我们经常发布文档更新,此页面的翻译可能仍在进行中。有关最新信息,请访问英文文档。如果此页面上的翻译有问题,请告诉我们

此版本的 GitHub Enterprise 已停止服务 2020-11-12. 即使针对重大安全问题,也不会发布补丁。 要获得更好的性能、改进的安全性和新功能,请升级到 GitHub Enterprise 的最新版本。 如需升级方面的帮助,请联系 GitHub Enterprise 支持

使用 Explorer

GraphQL Explorer 是浏览器中的集成开发环境,包含文档、语法重点和验证错误,可用于查询实际的 GitHub 数据。

本文内容

关于 GraphQL Explorer

GraphiQL 在本文档中也称为 GraphQL Explorer,是“浏览器内的图形交互式 GraphQL IDE”。

使用 GraphiQL

要使用 GraphiQL 应用程序,请从 https://github.com/skevy/graphiql-app 下载并安装。

配置 GraphiQL

  1. 获取 OAuth 令牌
  2. 启动 GraphiQL。
  3. 在 GraphiQL 的右上角,单击 Edit HTTP Headers(编辑 HTTP 标头)
  4. Key(密钥)字段中,输入 Authorization。 在 Value(值)字段中,输入 Bearer <token>,其中 <token> 是您生成的 OAuth 令牌。
    graphiql 标头
  5. 单击令牌右侧的复选标记将其保存。
  6. 要返回到编辑器,请单击 Edit HTTP Headers(编辑 HTTP 标头)模态框外部。
  7. GraphQL Endpoint(GraphQL 端点)字段中,输入 http(s)://<em>[hostname]</em>/api/graphql
  8. Method(方法)下拉菜单中,选择 POST

:有关为何选择 POST 作为方法的更多信息,请参阅“与 GraphQL 通信”。

您可以通过自我查询来测试您的访问:

query {
  viewer {
    login
  }
}

如果一切运行正常,将会显示您的登录信息。 您已设置完成,可以开始查询。

访问边栏文档

GraphQL 架构中的所有类型都包含一个编译到文档中的 description 字段。 Explorer 页面右侧可折叠的 Docs(文档)窗格可用于浏览有关类型系统的文档。 文档将自动更新,并删除已弃用的字段。

Docs(文档)边栏包含的内容,与“引用”下的架构自动生成的内容相同,但有些地方的格式不同。

使用变量窗格

包含变量的一些示例调用可能写作:

query($number_of_repos:Int!){
  viewer {
    name
     repositories(last: $number_of_repos) {
       nodes {
         name
       }
     }
   }
}
variables {
   "number_of_repos": 3
}

这是通过 cURL POST 提交调用的正确格式(但要避免使用换行符)。

如果要在 Explorer 中运行调用,请在主窗格中输入 query 字段,并在其下方的 Query Variables(查询变量)窗格中输入变量。 在 Explorer 中省略 variables 一词:

{
   "number_of_repos": 3
}

请求支持

有关 GitHub 应用程序、OAuth 应用程序 和 API 开发的问题、漏洞报告和讨论,请访问 GitHub API 开发和支持论坛。 该论坛由 GitHub 工作人员管理和维护,但不能保证发布到论坛的问题都会得到 GitHub 工作人员的回复。

对于以下问题,请考虑使用联系表直接联系 GitHub Support

  • 要保证得到 GitHub Enterprise Server 工作人员的回应
  • 涉及敏感数据或私人问题的支持请求
  • 功能请求
  • 关于 GitHub Enterprise Server 产品的反馈

排查错误

由于 GraphQL 可以自省,因此 Explorer 支持:

  • 基于当前架构的智能输入提示
  • 键入时预提示验证错误

如果您输入的查询格式不正确或未通过架构验证,则会弹出错误警示窗口。 如果您运行查询,错误将返回响应窗格中。

GraphQL 响应中包含多个密钥:data 哈希和 errors 数组。

{
  "data": null,
  "errors": [
    {
      "message": "Objects must have selections (field 'nodes' returns Repository but has no selections)",
      "locations": [
        {
          "line": 5,
          "column": 8
        }
      ]
    }
  ]
}

您可能会遇到与架构无关的意外错误。 如果发生这种情况,该消息将包含一个参考代码,供您在报告问题时使用:

{
  "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."
    }
  ]
}

注: GitHub 建议,在数据用于生产环境之前,先检查其是否有错误。 在 GraphQL 中,失败并不意味着全部错误:在一些 GraphQL 查询失败的同时,另一些查询可能成功。