Sobre o explorador do GraphQL
O GraphiQL, também conhecido como GraphQL Explorer nesta documentação, é um "IDE gráfico interativo do GraphQL no navegador".
Usando o IDE do Cliente do Altair GraphQL
Há muitos IDEs do cliente de código aberto do GraphQL. Por exemplo, você pode usar o Altair para acessar a API do GraphQL GitHub. Para acessar a API do GraphQL com o Altair, baixe-a e instale-a de altair-graphql/altair. Em seguida, siga as etapas de configuração abaixo.
Configurando o Altair
- Obtenha um token de acesso.
- Inicie o Altair.
- Na barra lateral esquerda, abaixo do logotipo da Altair, clique em Definir Cabeçalhos. Uma nova janela será aberta.
- No campo "Chave do cabeçalho", insira
Authorization
. - No campo "Valor do cabeçalho", insira
Bearer TOKEN
, substituindoTOKEN
pelo token da primeira etapa. - Clique em Salvar no canto inferior direito da janela para salvar o cabeçalho de autorização.
- No campo "Ponto de Extremidade do GraphQL", insira
http(s)://<em>HOSTNAME</em>/api/graphql
. - Para carregar o esquema do GraphQL GitHub, baixe o esquema público.
- No Altair, clique em Documentos no canto superior direito e, em seguida, nos três pontos e em Carregar Esquema...
- Selecione o esquema público de arquivo que você baixou em uma etapa anterior.
Observação: para obter mais informações sobre o motivo de o POST
ser o método, confira "Realizar chamadas com o GraphQL".
Você pode testar seu acesso consultando você mesmo:
query {
viewer {
login
}
}
Se tudo funcionou corretamente, isto irá mostrar seu login. Você está pronto para começar a fazer consultas.
Acessar a documentação da barra lateral
Todos os tipos em um esquema do GraphQL incluem um campo description
compilado na documentação. O painel recolhível Documentação no lado direito da página do Explorer permite que você navegue pela documentação sobre o sistema de tipos. A documentação é atualizada automaticamente e eliminará os campos obsoletos.
A barra lateral da Documentação contém o mesmo conteúdo gerado automaticamente com base no esquema em "Documentação da API do Graph do GitHub", embora seja formatado de maneira diferente nos lugares.
Usar o painel de variáveis
Alguns exemplos de chamadas incluem variáveis escritas assim:
query($number_of_repos:Int!){
viewer {
name
repositories(last: $number_of_repos) {
nodes {
name
}
}
}
}
variables {
"number_of_repos": 3
}
Este é o formato correto para enviar a chamada usando uma solicitação POST
em um comando curl
(desde que você faça o escape das novas linhas).
Caso deseje executar a chamada no Explorer, insira o segmento query
no painel principal e as variáveis no painel Variáveis de Consulta abaixo dela. Omita a palavra variables
do Explorer:
{
"number_of_repos": 3
}
Solicitar suporte
Em caso de dúvidas, relatórios de bug e discussões sobre o GitHub Apps, o OAuth apps e o desenvolvimento de API, explore o Discussões sobre APIs e integrações na Comunidade do GitHub. As discussões são moderadas e mantidas pela equipe do GitHub, mas não é garantido que as perguntas publicadas no fórum recebam uma resposta da equipe do GitHub.
Considere a possibilidade de entrar em contato diretamente com o Suporte do GitHub usando o formulário de contato para:
- resposta garantida dos funcionários de GitHub Enterprise Server
- solicitações de suporte que envolvem dados confidenciais ou questões privadas
- solicitações de recursos
- feedback sobre produtos de GitHub Enterprise Server
Solucionando erros
Como o GraphQL é introspectivo, o Explorer dá suporte a:
- Preenchimento automático inteligente do esquema atual
- Pré-visualizações de erros durante a digitação
Se você inserir uma consulta que não esteja bem formada ou não seja aprovada na validação de esquema, um pop-up avisará sobre um erro. Se você executar a consulta, o erro será retornado no painel de resposta.
Uma resposta do GraphQL contém várias chaves: um hash data
e uma matriz errors
.
{
"data": null,
"errors": [
{
"message": "Objects must have selections (field 'nodes' returns Repository but has no selections)",
"locations": [
{
"line": 5,
"column": 8
}
]
}
]
}
É possível que você possa encontrar um erro inesperado que não esteja relacionado com o esquema. Se isso acontecer, a mensagem incluirá um código de referência que você poderá usar ao relatar o problema:
{
"data": null,
"errors": [
{
"message": "Something went wrong while executing your query. This is most likely a GitHub bug. Please include \"7571:3FF6:552G94B:69F45B7:5913BBEQ\" when reporting this issue."
}
]
}
Observação: o GitHub recomenda verificar se há erros antes de usar dados em um ambiente de produção. No GraphQL, a falha não é total: algumas partes de consultas do GraphQL podem ser bem-sucedidas enquanto outras falham.