运行 GraphQL API 查询和变更
- 层级：免费、高级、旗舰
- 提供方式：GitLab.com、GitLab 自管版、GitLab 专属版
本指南演示了 GitLab GraphQL API 的基本用法。
运行示例
此处记录的示例可以通过以下方式运行：
GraphiQL
GraphiQL（发音为"graphical"）允许您交互式地对 API 运行真实的 GraphQL 查询。 它通过提供具有语法高亮和自动补全功能的 UI，使探索模式变得更加容易。
对于大多数人来说，使用 GraphiQL 将是探索 GitLab GraphQL API 的最简单方式。
您可以通过以下方式使用 GraphiQL：
- 在 GitLab.com 上。
- 在 GitLab 自管版上，地址为
https://<your-gitlab-site.com>/-/graphql-explorer。
首先登录 GitLab，以便使用您的 GitLab 账户对请求进行身份验证。
要开始使用，请参考示例查询和变更。
命令行
您可以在本地计算机的命令行上通过 curl 请求运行 GraphQL 查询。
这些请求以查询作为载荷 POST 到 /api/graphql。
您可以通过生成个人访问令牌来授权您的请求，将其用作 bearer token。
了解更多关于 GraphQL 身份验证 的信息。
示例：
GRAPHQL_TOKEN=<your-token>
curl --request POST \
--url "https://gitlab.com/api/graphql" \
--header "Authorization: Bearer $GRAPHQL_TOKEN" \
--header "Content-Type: application/json" \
--data "{\"query\": \"query {currentUser {name}}\"}"要在查询字符串中嵌套字符串，请将数据用单引号括起来或使用 \ 转义字符串：
curl --request POST \
--url "https://gitlab.com/api/graphql" \
--header "Authorization: Bearer $GRAPHQL_TOKEN" \
--header "Content-Type: application/json" \
--data '{"query": "query {project(fullPath: \"<group>/<subgroup>/<project>\") {jobs {nodes {id duration}}}}"}'
# or "{\"query\": \"query {project(fullPath: \\"<group>/<subgroup>/<project>\\") {jobs {nodes {id duration}}}}\"}"Rails 控制台
- 层级：免费、高级、旗舰
- 提供方式：GitLab 自管版、GitLab 专属版
GraphQL 查询可以在 Rails 控制台会话中运行。例如，搜索项目：
current_user = User.find_by_id(1)
query = <<~EOQ
query securityGetProjects($search: String!) {
projects(search: $search) {
nodes {
path
}
}
}
EOQ
variables = { "search": "gitlab" }
result = GitlabSchema.execute(query, variables: variables, context: { current_user: current_user })
result.to_h查询和变更
GitLab GraphQL API 可用于执行：
- 用于数据检索的查询。
- 用于创建、更新和删除数据的变更。
GitLab GraphQL 模式概述了哪些对象和字段可供客户端查询及其相应的数据类型。
示例：获取当前认证用户在 gitlab-org 组中可以访问的所有项目的名称（有限制）。
query {
group(fullPath: "gitlab-org") {
id
name
projects {
nodes {
name
}
}
}
}示例：获取特定项目和 Issue #2 的标题。
query {
project(fullPath: "gitlab-org/graphql-sandbox") {
name
issue(iid: "2") {
title
}
}
}图遍历
检索子节点时使用：
edges { node { } }语法。- 简短形式
nodes { }语法。
所有这些之下是我们正在遍历的图，因此得名 GraphQL。
示例：获取项目的名称及其所有问题的标题。
query {
project(fullPath: "gitlab-org/graphql-sandbox") {
name
issues {
nodes {
title
description
}
}
}
}更多关于查询的信息：GraphQL 文档
授权
如果您已登录 GitLab 并使用 GraphiQL，所有查询都将作为您（认证用户）执行。更多信息，请阅读关于 GraphQL 身份验证 的内容。
变更
变更会对数据进行修改。我们可以更新、删除或创建新记录。 变更通常使用 InputTypes 和变量，这两者在此处均未出现。
变更具有：
- 输入。例如，参数，如您想要添加哪个表情符号反应，以及添加到哪个对象。
- 返回语句。即成功时您希望返回的内容。
- 错误。总是询问出了什么问题，以防万一。
创建变更
示例：让我们喝杯茶 - 向问题添加 :tea: 反应表情符号。
mutation {
awardEmojiAdd(input: { awardableId: "gid://gitlab/Issue/27039960",
name: "tea"
}) {
awardEmoji {
name
description
unicode
emoji
unicodeVersion
user {
name
}
}
errors
}
}示例：向问题添加评论。在此示例中，我们使用 GitLab.com 问题的 ID。如果您使用的是本地实例，则必须获取您可以写入的问题的 ID。
mutation {
createNote(input: { noteableId: "gid://gitlab/Issue/27039960",
body: "*sips tea*"
}) {
note {
id
body
discussion {
id
}
}
errors
}
}更新变更
当您看到创建的注释的结果 id 时，请记下它。让我们编辑它以更快地啜饮。
mutation {
updateNote(input: { id: "gid://gitlab/Note/<note ID>",
body: "*SIPS TEA*"
}) {
note {
id
body
}
errors
}
}删除变更
让我们删除评论，因为我们的茶已经喝完了。
mutation {
destroyNote(input: { id: "gid://gitlab/Note/<note ID>" }) {
note {
id
body
}
errors
}
}您应该得到类似以下的输出：
{
"data": {
"destroyNote": {
"errors": [],
"note": null
}
}
}我们请求了注释的详细信息，但它已不存在，因此我们得到 null。
更多关于变更的信息：GraphQL 文档。
更新项目设置
您可以在单个 GraphQL 变更中更新多个项目设置。
此示例是针对 CI_JOB_TOKEN 范围行为中的重大变更的解决方法。
mutation DisableCI_JOB_TOKENscope {
projectCiCdSettingsUpdate(input:{fullPath: "<namespace>/<project-name>", inboundJobTokenScopeEnabled: false}) {
ciCdSettings {
inboundJobTokenScopeEnabled
}
errors
}
}内省查询
客户端可以通过进行内省查询来查询 GraphQL 端点以获取有关其模式的信息。
GraphiQL 查询资源管理器使用内省查询来：
- 获取有关 GitLab GraphQL 模式的知识。
- 进行自动补全。
- 提供其交互式
Docs选项卡。
示例：获取模式中的所有类型名称。
{
__schema {
types {
name
}
}
}示例：获取与 Issue 关联的所有字段。kind 告诉我们类型的枚举值，如 OBJECT、SCALAR 或 INTERFACE。
query IssueTypes {
__type(name: "Issue") {
kind
name
fields {
name
description
type {
name
}
}
}
}更多关于内省的信息：GraphQL 文档
查询复杂度
通过查询 queryComplexity，可以向客户端揭示查询的计算复杂度分数和限制。
query {
queryComplexity {
score
limit
}
project(fullPath: "gitlab-org/graphql-sandbox") {
name
}
}排序
某些 GitLab GraphQL 端点允许您指定如何对对象集合进行排序。 您只能按照模式允许的方式进行排序。
示例：问题可以按创建日期排序：
query {
project(fullPath: "gitlab-org/graphql-sandbox") {
name
issues(sort: created_asc) {
nodes {
title
createdAt
}
}
}
}分页
分页是一种只请求记录子集（例如前十条）的方法。
如果我们想要更多记录，可以向服务器发出另一个请求，请求接下来的十条记录，形式类似于 给我接下来的十条记录。
默认情况下，GitLab GraphQL API 每页返回 100 条记录。
要更改此行为，请使用 first 或 last 参数。
两个参数都接受一个值，因此 first: 10 返回前十条记录，而 last: 10 返回最后十条记录。
每页返回的记录数有限制，通常为 100。
示例：仅检索前两个问题（切片）。cursor 字段为我们提供了一个位置，我们可以从该位置检索相对于该记录的更多记录。
query {
project(fullPath: "gitlab-org/graphql-sandbox") {
name
issues(first: 2) {
edges {
node {
title
}
}
pageInfo {
endCursor
hasNextPage
}
}
}
}示例：检索接下来的三个问题。（游标值 eyJpZCI6IjI3MDM4OTMzIiwiY3JlYXRlZF9hdCI6IjIwMTktMTEtMTQgMDU6NTY6NDQgVVRDIn0 可能不同，但它是上面返回的第二个问题返回的 cursor 值。）
query {
project(fullPath: "gitlab-org/graphql-sandbox") {
name
issues(first: 3, after: "eyJpZCI6IjI3MDM4OTMzIiwiY3JlYXRlZF9hdCI6IjIwMTktMTEtMTQgMDU6NTY6NDQgVVRDIn0") {
edges {
node {
title
}
cursor
}
pageInfo {
endCursor
hasNextPage
}
}
}
}更多关于分页和游标的信息：GraphQL 文档
更改查询 URL
有时，需要将 GraphQL 请求发送到不同的 URL。例如，GeoNode 查询只对辅助 Geo 站点 URL 有效。
要在 GraphiQL 资源管理器中更改 GraphQL 请求的 URL，请在 GraphiQL 的 Header 区域（左下角区域，Variables 旁边）设置自定义标头：
{
"REQUEST_PATH": "<the URL to make the graphQL request against>"
}