Criando uma query persistente
Uma query persistente é uma combinação das APIs GraphQL e REST: é uma query GraphQL normal, publicada no site e acessada por meio de seu próprio URL, semelhante a um endpoint REST.
Por exemplo, podemos expor dados de um site por meio das seguintes queries persistentes:
/graphql-query/homepage-posts/graphql-query/user-widget/graphql-query/post-contente executá-la passando o ID do post:?post=1/graphql-query/post-content/espara traduzir o conteúdo do post para o espanhol- Outras
Executando a query persistente
Após a publicação da query persistente, podemos executá-la por meio de seu permalink.
A query persistente pode ser executada diretamente no navegador, pois é acessada via GET, e obteremos os dados solicitados no formato JSON:
Executando a query persistente em uma aplicação
Siga as instruções do guia Conectando-se ao servidor GraphQL a partir de um cliente.
Acessando todas as queries persistentes
Ao clicar em "Persisted Queries" no menu do plugin, é exibida a lista de todas as queries persistentes criadas:
Criando uma nova query persistente
Clique no botão "Add New GraphQL persisted query" para abrir o editor do WordPress:
Dê um título e certifique-se de que o permalink seja o esperado, insira a query GraphQL, selecione a configuração de schema e ajuste as opções. Quando estiver pronto, clique no botão Publicar, e o permalink se torna o endpoint da query persistente.
O link para o endpoint (e para a fonte) é exibido no painel lateral "Persisted Query Endpoint Overview":
Por padrão, o endpoint da query persistente tem o caminho /graphql-query/, e esse valor é configurável por meio das Configurações:
Editor de queries
O cliente GraphiQL no editor é onde se insere a query GraphQL persistente:
O editor vem com o complemento Explorer, que permite compor a query clicando nos campos no painel lateral esquerdo. Clicar no botão "Run" executa a query para visualizar a resposta:
Configuração de schema
A definição de quem pode acessar os campos solicitados na query persistente é definida na configuração de schema.
Portanto, devemos criar uma configuração de schema, e então selecioná-la no menu suspenso (ou não usar nenhuma, ou usar a padrão):
Queries persistentes privadas
Ao definir o status da query persistente como privado, o endpoint só pode ser acessado pelo usuário administrador. Isso evita que nossos dados sejam compartilhados involuntariamente com usuários que não deveriam ter acesso a eles.
Por exemplo, podemos criar queries persistentes privadas que ajudam a gerenciar a aplicação, como recuperar dados para criar relatórios com nossas métricas.
Queries persistentes protegidas por senha
Se criarmos uma query persistente para um cliente específico, podemos atribuir uma senha a ela, para fornecer um nível adicional de segurança garantindo que apenas aquele cliente acesse o endpoint.
Ao acessar pela primeira vez uma query persistente protegida por senha, encontramos uma tela solicitando a senha:
Uma vez que a senha seja fornecida e validada, somente então o usuário acessará o endpoint pretendido.
Tornando a query persistente dinâmica via parâmetros de URL
O valor de cada variável pode ser definido por meio de um parâmetro de URL (com o nome da variável) ao executar a query persistente. Se a opção "Do URL params override variables?" estiver habilitada, o parâmetro de URL terá prioridade. Caso contrário, o valor definido no dicionário de variáveis terá prioridade (se houver).
Por exemplo, nesta query, o número de resultados é controlado pela variável $limit, com um valor padrão de 3:
Ao executar esta query persistente, passar ?limit=5 executará a query retornando 5 resultados:
Criando uma hierarquia de queries persistentes
Leia as instruções em criando uma hierarquia de API.
Desabilitando a query persistente
Nas opções, defina "Enabled" como false para desabilitar a query persistente.
Esse recurso pode ser útil quando a query persistente faz parte de uma hierarquia de API, para fornecer um comportamento comum às suas queries persistentes filhas, sem precisar ela mesma ser executada.
Descrevendo a query persistente
Use o campo "Excerpt", no painel de configurações do documento, para dar uma descrição à query persistente.
Encontre mais informações no guia Adicionando uma descrição à API.
Testando a query persistente antes de publicar online
Uma query persistente com status rascunho ou pendente está disponível apenas para os usuários editores de schema.
Assim, podemos criar uma query persistente, atribuir uma Configuração de Schema, publicá-la como rascunho ou pendente, e testá-la (por exemplo: verificando se suas regras de Controle de Acesso são apropriadas).
Após a aprovação, somente então definimos seu status como publicado, tornando a query persistente disponível para todos.
Visualizando a fonte
Ao acrescentar ?view=source ao endpoint, será exibida a configuração da query persistente (desde que o usuário esteja autenticado e que sua função tenha acesso a ela):
Configuração no editor do WordPress
Estes são os campos no corpo do editor:
| Campo | Descrição |
|---|---|
| Título | Título da query persistente |
| Cliente GraphiQL | Editor para escrever e executar a query GraphQL:
GraphiQL Explorer estiver habilitado) permite clicar nos campos, que são automaticamente adicionados à query |
| Configuração de schema | No menu suspenso, selecione a configuração de schema aplicável à query persistente, ou uma destas opções:
|
| Opções | Personalizar o comportamento da query persistente:
|
Estes são os campos nas configurações do documento:
| Campo | Descrição |
|---|---|
| Permalink | O endpoint sob o qual a query persistente estará disponível |
| Categorias | Permite categorizar a query persistente. Ex.: mobile, app, etc. |
| Excerpt | Fornece uma descrição para a query persistente. Este campo está disponível quando o módulo Excerpt as Description está habilitado |
| Atributos de página | Selecionar uma query persistente pai. Este campo está disponível quando o módulo API Hierarchy está habilitado |