Skip to main content

Usar o Explorador

Você pode executar consultas em dados reais do GitHub ao usar o explorador do GraphQL, um ambiente integrado de desenvolvimento no seu navegador que inclui documentação, destaque de sintaxe e erros de validação.

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

  1. Obtenha um token de acesso.
  2. Inicie o Altair.
  3. Na barra lateral esquerda, abaixo do logotipo da Altair, clique em Definir Cabeçalhos. Uma nova janela será aberta.
  4. No campo "Chave do cabeçalho", insira Authorization.
  5. No campo "Valor do cabeçalho", insira Bearer TOKEN, substituindo TOKEN pelo token da primeira etapa.
  6. Clique em Salvar no canto inferior direito da janela para salvar o cabeçalho de autorização.
  7. No campo "Ponto de Extremidade do GraphQL", insira http(s)://<em>HOSTNAME</em>/api/graphql.
  8. Para carregar o esquema do GraphQL GitHub, baixe o esquema público.
  9. No Altair, clique em Documentos no canto superior direito e, em seguida, nos três pontos e em Carregar Esquema...
  10. 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.