关于 GraphQL Explorer
GraphiQL,在本文档中也称为 GraphQL 浏览器,是“浏览器内的图形交互式 GraphQL IDE”。
查询自动完成
可以使用查询自动完成来帮助生成查询。 在主窗格中,大括号内的查询中使用 Control+空格或 Shift+空格,显示自动完成菜单。
访问边栏文档
GraphQL 架构中的所有类型都包含一个编译到文档中的 description
字段。 该浏览器页面右侧可折叠的“文档”窗格可用于浏览有关类型系统的文档。 文档将自动更新,并删除已弃用的字段。
“文档”边栏包含的内容与“GitHub GraphQL API 文档”下的架构自动生成的内容相同,但有些地方的格式不同。
使用变量窗格
一些示例调用包括如下编写的变量:
query($number_of_repos:Int!){
viewer {
name
repositories(last: $number_of_repos) {
nodes {
name
}
}
}
}
variables {
"number_of_repos": 3
}
这是使用 curl
命令中 POST
请求提交呼叫的正确格式(但要避免使用换行符)。
如果要在浏览器中运行调用,请在主窗格中输入 query
字段,并在其下方的“查询变量”窗格中输入变量。 在浏览器中省略 variables
一词:
{
"number_of_repos": 3
}
使用 Altair GraphQL 客户端 IDE
有许多开放源代码 GraphQL 客户端 IDE。 例如,可以使用 Altair 访问 GitHub 的 GraphQL API。 若要使用 Altair 访问 GraphQL API,请从 altair-graphql/altair 下载并安装它。 然后,按照下面的配置步骤进行操作。
配置 Altair
- 获取访问令牌。
- 启动 Altair。
- 在左侧边栏中的 Altair 徽标下方,单击“设置标头”。 此时将打开一个新的窗口。
- 在“标头密钥”字段中,输入
Authorization
。 - 在“标头值”字段中,输入
Bearer TOKEN
,将TOKEN
替换为第一步中的令牌。 - 单击窗口右下角的“保存”以保存授权标头。
- 在“GraphQL 终结点”字段中,输入
http(s)://HOSTNAME/api/graphql
。 - 若要加载 GitHub GraphQL 架构,请下载公共架构。
- 在 Altair 中,单击右上角的“Docs”,然后单击三个点和“加载架构...”
- 选择在前面步骤中下载的文件公共架构。
注意:有关为何选择 POST
作为方法的详细信息,请参阅“使用 GraphQL 建立调用”。
您可以通过自我查询来测试您的访问:
query {
viewer {
login
}
}
如果一切运行正常,将会显示您的登录信息。 您已设置完成,可以开始查询。
请求支持
有关 GitHub Apps、OAuth apps 和 API 开发的问题、漏洞报告和讨论,请访问 GitHub 社区讨论中的 API 和 Webhook 类别。 讨论由 GitHub 工作人员审查和维护,由 GitHub 社区回答。
请考虑使用联系人表单直接联系 GitHub 支持:
- 要保证得到 GitHub Enterprise Server 工作人员的回应
- 涉及敏感数据或私人问题的支持请求
- 功能请求
- 关于 GitHub Enterprise Server 产品的反馈
排查错误
由于 GraphQL 可以自省,因此浏览器支持:
- 基于当前架构的智能输入提示
- 键入时预提示验证错误
如果输入的查询格式不正确或未通过架构验证,则会弹出错误警示窗口。 如果您运行查询,错误将返回响应窗格中。
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 查询失败的同时,另一些查询可能成功。