Como definir o Query Builder para itens da API REST

Vamos começar entendendo quais tipos de dados podem ser consultados com quais operadores na consulta personalizada do tipo API REST.

Na pasta do plugin JetEngine, você pode encontrar um arquivo que lista os tipos de dados e operadores seguindo este caminho:

“\jet-engine\includes\modules\custom-content-types\inc\query-dialog.php”.

Compreender os tipos de dados ajuda a escrever o tipo de dados e o operador apropriados na cláusula de consulta, para que os valores sejam convertidos, se necessário, e ao fazer uma consulta ao banco de dados, convertidos para um tipo especificado.

Estes são os tipos de dados:

• sem conversão:
  • ‘inteiro’ — um número não decimal;
  • ‘float’ — um número com ponto decimal;
  • ‘char’ — valores de string.
• com conversão:
  • ‘timestamp’ — número de segundos entre uma data específica e a Época Unix, que começa em 1º de janeiro de 1970 em UTC; os valores inseridos serão convertidos para carimbo de data/hora UNIX. Por exemplo, ‘13.07.2023’ será convertido para 1689199200 antes de fazer uma chamada REST API, ‘today’ será convertido para a data de hoje no carimbo de data/hora;
  • ‘date’ — é uma data no formato MySQL DATETIME; a data será convertida para ela; por exemplo, ‘13.07.2023’ será convertido para ‘13.07.2023 00:00:00’.

Aqui estão também os operadores. Eles definem uma condição pela qual o valor inserido na cláusula de consulta é comparado com os valores nos itens:

• Igual;
• Não igual;
• Maior que;
• Maior ou igual;
• Menor que;
• Igual ou menor;
• Como;
• Não parece;
• Em;
• Não em;
• Entre;
• Não entre.

Na guia WordPress Dashboard > JetEngine > REST API Endpoints , crie uma conexão com um endpoint com os itens CCT de outro site.

Vá para WordPress Dashboard > JetEngine > Query Builder e crie uma consulta personalizada pressionando o botão “ Adicionar novo ”.

Selecione “REST API Query” como Query Type e escolha um endpoint previamente conectado na API REST do JetEngine no campo  From Endpoint .

Recomendamos ativar Visualizar resultados na parte superior da página para ver os resultados da consulta instantaneamente no lado direito.

Adicione um novo item à consulta e ‘_filters’ como Key .

Adicionamos essa chave exata porque na pasta do plugin JetEngine (no arquivo “\jet-engine\includes\modules\custom-content-types\inc\rest-api\public-controller.php”), você pode encontrar um parâmetro ‘_filters’ que permite consultar os itens do CCT.

Inteiro

Verifique o primeiro exemplo com o campo ‘f2’ que armazena um valor do tipo de dados “inteiro”.

Neste caso, o valor da cláusula de consulta deve ser escrito no seguinte formato:

[{"field":"f2","operator":"=","value":"12","type":"INTEGER"}]

Isso significa que queremos extrair os itens com valor ’12’ no campo ‘f2’. Também especificamos que o valor é um número inteiro. Com esta cláusula de consulta, obtemos instantaneamente um item na janela Visualizar resultados que corresponde à nossa solicitação.

Número flutuante

O segundo exemplo é uma cláusula de consulta baseada em um valor de “número flutuante”.

Escrevemos o seguinte valor:

 [{"field":"num2","operator":">","value":"67.50","type":"FLOATING"}] 

Como resultado, obteve-se um item CCT com valor superior a 67,50.

Corda

O exemplo a seguir é uma cláusula de consulta baseada no valor do campo de item CCT, que armazena um valor de “string”.

É um valor para a cláusula de consulta:

[{"field":"cct_status","operator":"=","value":"publish","type":"CHAR"}]

Com esta solicitação, obtivemos três itens CCT com status ‘publicado’.

” alt=”valor da string na consulta” data-src=”https://crocoblock.com/knowledge-base/wp-content/uploads/2023/07/Screenshot_45.png” />

Campo de caixa de seleção

Prossigamos com o exemplo de consulta pelo campo checkbox. A caixa de seleção armazena itens em um array serializado no banco de dados, portanto usaremos o tipo CHAR.

A caixa de seleção em nosso campo de exemplo tem duas opções – ‘um’ e ‘dois’. Verificaremos como a consulta deve ser escrita em diferentes casos.

Para mostrar os itens que possuem pelo menos a opção ‘um’ marcada, usamos este valor na cláusula de consulta:

[{"field":"check1","operator":"LIKE","value":"one","type":"CHAR"}]

Neste caso, recebemos itens com a opção ‘um’ marcada e outras opções.

” alt=”valor da caixa de seleção na consulta com uma opção marcada” data-src=”https://crocoblock.com/knowledge-base/wp-content/uploads/2023/07/Screenshot_47.png” />Para mostrar os itens onde apenas um item específico está marcado, é necessário este valor na cláusula de consulta:

 [{"field":"check1","operator":"REGEXP","value":"a:1:.*one","type":"CHAR"}]

O resultado exibe o item com apenas a opção ‘um’ marcada. Outros itens com as opções ‘um’ e ‘dois’ marcadas são ignorados.

Vejamos também como podemos mostrar os itens do CCT que possuem apenas as duas opções específicas marcadas simultaneamente, e não apenas uma. Em outras palavras, os itens devem ser consultados com um operador relacional ‘AND’. Criamos o seguinte valor para a cláusula de consulta:

[{"field":"check1","operator":"LIKE","value":"one","type":"CHAR"},
{"field":"check1","operator":"LIKE","value":"two","type":"CHAR"}]

Agora o resultado exibe os itens que possuem apenas as duas opções marcadas ao mesmo tempo.

Outro caso de consulta por campo checkbox é mostrar itens com pelo menos um valor marcado na lista. Isso significa que um operador relacional ‘OR’ é usado.

[
{ "relation":"OR",
"0":{"field":"f2","operator":"=","value":"12","type":"CHAR"},
"1":{"field":"f1","operator":"=","value":"1","type":"CHAR"}
}
]

Os resultados mostrarão itens com a opção ‘um’ marcada, apenas a opção ‘dois’ marcada ou ambas simultaneamente.

E por último, mas não menos importante, o caso de consulta por campo de caixa de seleção é a criação de uma cláusula de consulta com dois operadores relacionais – ‘OR’ e ‘AND’. Significa que a consulta deve apresentar os itens com a opção ‘um’ marcada ou as opções ‘um’ e ‘dois’ marcadas simultaneamente.

Você pode ver o valor da cláusula de consulta para esse caso abaixo. Você também pode comparar valores de outros campos, não apenas de um, para criar uma consulta mais avançada.

[
  {
    "relation":"OR",
    "0" : {
            "relation" : "AND",
            "0" : {
                    "field" : "check1",
                    "operator" : "LIKE",
                    "value" : "one",
                    "type" : "CHAR"
                   },
            "1" : {
                    "field" : "check1",
                    "operator" : "LIKE",
                    "value" : "two",
                    "type"  : "CHAR"}
           },
    "1" : {
            "field" : "check1",
            "operator" : "LIKE",
            "value" : "one",
            "type" : "CHAR"
           }
  }
]

Aqui está um item nos resultados com apenas a opção ‘um’ marcada.

Dois outros itens nos resultados têm as opções ‘um’ e ‘dois’ marcadas conforme a consulta.

Por fim, vamos consultar os itens do CCT pelos campos que armazenam datas nos formatos de data ou carimbo de data/hora.

Data

Temos um campo ‘cct_created’ que armazena uma data em formato de data.

Portanto, podemos usar a seguinte expressão para consultar por este campo:

[{"field":"cct_created","operator":"BETWEEN","value":"2023-01-01,2023-04-22","type":"DATE"}]

Como resultado, temos um item que foi criado entre as datas inseridas em 21 de abril de 2023.

Carimbo de data e hora

Uma solicitação frequente é mostrar itens com data maior ou igual a ‘hoje’ com base no carimbo de data / hora.

Como você pode ver, ‘date1’ tem uma data salva como timestamp, então precisamos usar o tipo ‘TIMESTAMP’ na cláusula de consulta.

Aqui está como a consulta deve ser escrita neste caso:

[{"field":"date1","operator":">=","value":"today","type":"TIMESTAMP"}]

Nesse caso, obtemos uma postagem com data maior que ‘hoje’ porque o carimbo de data / hora ‘1698624000’ é ‘segunda-feira, 30 de outubro de 2023’ em GMT.