Uso do GraphiQL IDE

Última atualização em 2023-12-05

Uma implementação do GraphiQL IDE padrão está disponível para uso com a API GraphQL do Adobe Experience Manager (AEM) as a Cloud Service.

OBSERVAÇÃO

O GraphiQL é incluído em todos os ambientes do AEM (mas só se torna acessível/visível quando você configura os pontos de acesso).

Em versões anteriores, era necessário um pacote para instalar o GraphiQL IDE. Se você o instalou, agora é possível removê-lo.

OBSERVAÇÃO

Você deve configurar os endpoints no navegador de configuração antes de usar o GraphiQL IDE.

A variável GraphiQL A ferramenta permite testar e depurar as consultas do GraphQL, possibilitando:

  • selecionar o endpoint apropriado à configuração de Sites que deseja usar para as consultas
  • inserir diretamente novas consultas
  • criar e acessar consultas persistentes
  • executar as consultas para ver os resultados imediatamente
  • gerenciar variáveis de consulta
  • salvar e gerenciar consultas persistentes
  • publicar ou desfazer a publicação de consultas persistentes no serviço de Publicação ou Visualização; por exemplo, para/de dev-publish
  • consultar o histórico de consultas anteriores
  • usar o Explorador de documentação para acessar a documentação; ajudando você a conhecer e entender quais métodos estão disponíveis.

É possível acessar o editor de consultas por meio de:

  • Ferramentas > Geral > Editor de consultas GraphQL
  • diretamente; por exemplo, http://localhost:4502/aem/graphiql.html
Interface GraphiQL

Você pode usar o GraphiQL no sistema para que as consultas possam ser solicitadas pelo aplicativo cliente usando solicitações GET e para publicar consultas. Para o uso em produção, é possível mover as consultas para o ambiente de produção. Inicialmente ao autor de produção para validação do conteúdo recém-criado com as consultas e, finalmente, à produção de publicação para consumo em tempo real.

Seleção do endpoint

Como primeira etapa, é preciso selecionar o endpoint que deseja usar para as consultas. O endpoint é apropriado para a configuração dos Sites que você deseja usar para as consultas.

Isso está disponível na lista suspensa na parte superior direita.

Criação e persistência de uma nova consulta

Você pode inserir a nova consulta no editor, que está no painel central esquerdo, diretamente sob o logotipo do GraphiQL.

OBSERVAÇÃO

Se você tiver uma consulta persistente já selecionada que está sendo exibida no painel do editor, selecione + (ao lado de Consultas persistentes) para esvaziar o editor para sua nova consulta.

Basta começar a digitar. O editor também:

  • mostra informações adicionais sobre os elementos ao passar o mouse sobre eles
  • fornece recursos como realce de sintaxe, preenchimento automático, sugestão automática
OBSERVAÇÃO

As consultas de GraphQL normalmente começam com um caractere {.

Linhas que começam com # são ignoradas.

Use a opção Salvar como para criar uma consulta persistente.

Atualização da consulta persistente

Selecione a consulta que deseja atualizar na lista do painel Consultas persistentes (lado esquerdo).

A consulta será exibida no painel do editor. Faça as alterações necessárias e use a opção Salvar para confirmar as atualizações da consulta persistente.

Execução de consultas

Você pode executar uma nova consulta imediatamente ou pode carregar e executar uma consulta persistente. Para carregar uma consulta persistente, selecione-a na lista; a consulta será exibida no painel do editor.

Em ambos os casos, a consulta exibida no painel do editor é a que será executada quando você:

  • selecione no Executar consulta ícone
  • usar a combinação de teclado Control-Enter

Variáveis de consulta

O GraphiQL IDE também permite gerenciar os Variáveis de consulta.

Por exemplo:

Variáveis GraphQL

Gerenciamento do cache para suas consultas persistentes

Consultas persistentes são recomendadas, pois elas podem ser armazenadas em cache nas camadas do Dispatcher e CDN, melhorando o desempenho do aplicativo cliente solicitante. Por padrão, o AEM invalidará o cache da rede de entrega de conteúdo (CDN) com base em um TTL (Time To Live) padrão.

OBSERVAÇÃO

As regras de regravação personalizadas no Dispatcher podem substituir as configurações de publicação padrão do AEM.

Caso esteja enviando cabeçalhos de controle de cache com base em TTL do dispatcher, com base em um padrão de correspondência de local, se necessário, você poderá excluir /graphql/execute.json/* dos jogos.

Ao usar o GraphQL, é possível configurar os cabeçalhos de cache HTTP para controlar esses parâmetros para sua consulta persistente individual.

  1. A opção Cabeçalhos também é acessível por meio dos três pontos verticais à direita do nome da consulta persistente (painel à esquerda):

    Cabeçalhos de cache HTTP de consulta persistente
  2. Selecionar isso abre o Configuração de cache caixa de diálogo:

    Configurações do cabeçalho de cache HTTP de consulta persistente
  3. Selecione o parâmetro apropriado e ajuste o valor conforme necessário:

    • cache-control - max-age
      Os caches podem armazenar esse conteúdo por um número especificado de segundos. Normalmente, esse é o TTL (Time To Live) do navegador.
    • surrogate-control - s-maxage
      Igual a max-age, mas aplica-se especificamente a caches de proxy.
    • surrogate-control - stale-while-revalidate
      Os caches podem continuar a servir uma resposta em cache depois que ela se tornar obsoleta, por um número especificado de segundos.
    • surrogate-control - stale-if-error
      Os caches podem continuar a servir uma resposta em cache em caso de erro de origem, por um número especificado de segundos.
  4. Selecione Salvar para confirmar as alterações.

Publicação e visualização de consultas persistentes

Depois de selecionar a consulta persistente na lista (painel esquerdo), você pode usar a ação Publicar.

Essa ação ativa a consulta no ambiente selecionado. Você pode escolher o ambiente de Publicação (por exemplo, dev-publish) ou o ambiente de Visualização para facilitar o acesso através de seus aplicativos durante os testes.

GraphiQL - Consulta persistente publicada
OBSERVAÇÃO

A definição do cache da consulta persistente Time To Live {"cache-control":"parameter":value} tem um valor padrão de 2 horas (7200 segundos).

Desfazer a publicação de consultas persistentes

Assim como ocorre na publicação, depois de selecionar a consulta persistente na lista (painel esquerdo), você pode usar a ação Desfazer publicação.

Essa ação desativa a consulta no ambiente selecionado, seja o ambiente de Publicação ou de Visualização.

OBSERVAÇÃO

Você também deve verificar se fez as alterações necessárias no aplicativo cliente para evitar possíveis problemas.

Copiar o URL para acessar a consulta diretamente

A variável Copiar URL permite simular uma consulta copiando o URL usado para acessar diretamente a consulta persistente e ver os resultados. Essa opção pode ser usada para testes; por exemplo, acessando em um navegador:

Por exemplo:

http://localhost:4502/graphql/execute.json/global/article-list-01

Ao usar esse URL em um navegador, é possível confirmar os resultados:

GraphiQL - Copiar URL

A opção Copiar URL é acessível por meio dos três pontos verticais à direita do nome da consulta persistente (painel à esquerda):

GraphiQL - Copiar URL

Exclusão de consultas persistentes

A opção Excluir também é acessível por meio dos três pontos verticais à direita do nome da consulta persistente (painel à esquerda).

Instalação da consulta persistente na produção

Depois de desenvolver e testar a consulta persistente com o GraphiQL, o objetivo final é transferi-la para o ambiente de produção para que os aplicativos possam usá-la.

Atalhos de teclado

Há uma série de atalhos de teclado que fornecem acesso direto aos ícones de ação no IDE:

  • Adornar a consulta: Shift-Control-P
  • Mesclar consulta: Shift-Control-M
  • Executar consulta: Control-Enter
  • Preenchimento automático: Control-Space
OBSERVAÇÃO

Em alguns teclados, a tecla Control é rotulada como Ctrl.

Nesta página