GraphQL API

GraphQL 是一种用于 API 的查询语言。您可以使用它来请求您所需的确切数据，从而限制所需的请求数量。

GraphQL 数据按类型排列，因此您的客户端可以使用 客户端 GraphQL 库 来消费 API 并避免手动解析。

GraphQL API 是无版本的。

入门指南

如果您是 GitLab GraphQL API 的新用户，请参阅 GitLab GraphQL API 入门指南。

您可以在 GraphQL API 参考 中查看可用资源。

GitLab GraphQL API 端点位于 /api/graphql。

交互式 GraphQL 资源管理器

使用交互式 GraphQL 资源管理器探索 GraphQL API，可以选择：

• 在 GitLab.com 上。
• 在 GitLab 自管理实例上，地址为 https://<your-gitlab-site.com>/-/graphql-explorer。

更多信息，请参阅 GraphiQL。

查看 GraphQL 示例

您可以使用从 GitLab.com 上的公共项目中提取数据的示例查询：

• 创建审计报告
• 识别问题看板
• 查询用户
• 使用自定义表情符号

入门指南页面包含了自定义 GraphQL 查询的不同方法。

身份验证

您可以在不进行身份验证的情况下访问某些查询，但其他查询需要身份验证。变更操作始终需要身份验证。

您可以使用以下任一方式进行身份验证：

• 令牌
• 会话 cookie

如果身份验证信息无效，GitLab 会返回状态码为 401 的错误消息：

{"errors":[{"message":"Invalid token"}]}

令牌身份验证

使用以下任一令牌向 GraphQL API 进行身份验证：

• OAuth 2.0 令牌
• 个人访问令牌
• 项目访问令牌
• 群组访问令牌

通过在请求头中传递令牌或作为参数来使用令牌进行身份验证。

令牌需要正确的权限范围。

请求头身份验证

使用 Authorization: Bearer <token> 请求头进行令牌身份验证的示例：

curl --request POST \
  --url "https://gitlab.com/api/graphql" \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --data "{\"query\": \"query {currentUser {name}}\"}"

参数身份验证

在 access_token 参数中使用 OAuth 2.0 令牌的示例：

curl --request POST \
  --url "https://gitlab.com/api/graphql?access_token=<oauth_token>" \
  --header "Content-Type: application/json" \
  --data "{\"query\": \"query {currentUser {name}}\"}"

您可以使用 private_token 参数传递个人、项目或群组访问令牌：

curl --request POST \
  --url "https://gitlab.com/api/graphql?private_token=<access_token>" \
  --header "Content-Type: application/json" \
  --data "{\"query\": \"query {currentUser {name}}\"}"

令牌权限范围

令牌必须具有正确的权限范围才能访问 GraphQL API，可以是：

会话 cookie 身份验证

登录主 GitLab 应用程序会设置一个 _gitlab_session 会话 cookie。

交互式 GraphQL 资源管理器和 GitLab 本身的 Web 前端都使用这种身份验证方法。

对象标识符

GitLab GraphQL API 使用混合标识符。

全局 ID、完整路径和内部 ID (IID) 都在 GitLab GraphQL API 中用作参数，但通常 schema 的特定部分不会同时接受所有这些标识符。

虽然 GitLab GraphQL API 历史上在这方面并不一致，但通常您可以预期：

• 如果对象是项目、群组或命名空间，您使用对象的完整路径。
• 如果对象有 IID，您使用完整路径和 IID 的组合。
• 对于其他对象，您使用全局 ID。

例如，通过完整路径 "gitlab-org/gitlab" 查找项目：

{
  project(fullPath: "gitlab-org/gitlab") {
    id
    fullPath
  }
}

另一个示例，通过项目的完整路径 "gitlab-org/gitlab" 和问题的 IID "1" 锁定问题：

mutation {
  issueSetLocked(input: { projectPath: "gitlab-org/gitlab", iid: "1", locked: true }) {
    issue {
      id
      iid
    }
  }
}

通过其全局 ID 查找 CI 运行器的示例：

{
  runner(id: "gid://gitlab/Ci::Runner/1") {
    id
  }
}

历史上，GitLab GraphQL API 在完整路径和 IID 字段及参数的类型方面一直不一致，但通常：

• 完整路径字段和参数是 GraphQL ID 类型。
• IID 字段和参数是 GraphQL String 类型。

全局 ID

在 GitLab GraphQL API 中，名为 id 的字段或参数几乎总是全局 ID，而绝不是数据库主键 ID。GitLab GraphQL API 中的全局 ID 以 "gid://gitlab/" 开头。例如，"gid://gitlab/Issue/123"。

全局 ID 是某些客户端库中用于缓存和获取的约定。

GitLab 全局 ID 可能会发生变化。如果发生变化，将旧的全局 ID 用作参数将被弃用，并根据弃用和重大变更流程提供支持。您不应期望缓存的全局 ID 在 GitLab GraphQL 弃用周期之后仍然有效。

可用的顶级查询

所有查询的顶级入口点在 GraphQL 参考中的 Query 类型中定义。

多路复用查询

GitLab 支持将查询批处理为单个请求。更多信息，请参阅 多路复用。

重大变更

GitLab GraphQL API 是无版本的，对 API 的更改主要是向后兼容的。

但是，GitLab 有时会以不向后兼容的方式更改 GraphQL API。这些更改被视为重大变更，可能包括删除或重命名字段、参数或 schema 的其他部分。在进行重大变更时，GitLab 遵循弃用和移除流程。

为避免重大变更影响您的集成，您应该：

• 熟悉弃用和移除流程。
• 经常根据未来的重大变更 schema 验证您的 API 调用。

对于 GitLab 自管理实例，降级从 EE 实例到 CE 会导致重大变更。

重大变更豁免

在 GraphQL API 参考中标记为实验的 schema 项目不受弃用流程的限制。这些项目可以随时被移除或更改，恕不另行通知。

位于功能标志后且默认禁用的字段不遵循弃用和移除流程。这些字段可以随时被移除，恕不另行通知。

根据未来的重大变更 schema 进行验证

您可以调用 GraphQL API，就好像所有已弃用的项目都已被移除一样。这样，您可以在项目实际从 schema 中移除之前，提前验证 API 调用以应对重大变更发布。

要进行这些调用，请在 GraphQL API 端点中添加 remove_deprecated=true 查询参数。例如， 对于 GitLab.com 上的 GraphQL，使用 https://gitlab.com/api/graphql?remove_deprecated=true。

弃用和移除流程

标记为从 GitLab GraphQL API 中移除的 schema 部分首先被弃用，但仍可在至少六个版本中使用。然后，它们将在下一个 XX.0 主要版本中被完全移除。

项目在以下位置被标记为已弃用：

• Schema。
• GraphQL API 参考。
• 弃用功能移除时间表，该时间表从发布帖子中链接。
• GraphQL API 的内省查询。

弃用消息为已弃用的 schema 项目提供了替代方案（如果适用）。

为避免遇到重大变更，您应尽快从 GraphQL API 调用中移除已弃用的 schema。您应该根据不包含已弃用 schema 项目的 schema 验证您的 API 调用。

弃用示例

以下字段在不同的次要版本中被弃用，但都在 GitLab 17.0 中被移除：

已移除项目列表

查看在先前版本中移除的项目列表。

限制

以下限制适用于 GitLab GraphQL API。

最大查询复杂度

GitLab GraphQL API 对查询的复杂度进行评分。通常，较大的查询具有较高的复杂度分数。此限制旨在保护 API 免于执行可能对其整体性能产生负面影响的查询。

您可以查询查询的复杂度分数和请求的限制。

如果查询超过复杂度限制，将返回错误消息响应。

通常，查询中的每个字段都会将复杂度分数增加 1，但对于特定字段，这个值可能更高或更低。有时，添加某些参数也可能增加查询的复杂度。

解决被检测为垃圾邮件的变更操作

GraphQL 变更操作可能被检测为垃圾邮件。如果变更操作被检测为垃圾邮件并且：

• 未配置 CAPTCHA 服务，则会引发 GraphQL 顶级错误。例如：

  {
    "errors": [
      {
        "message": "Request denied. Spam detected",
        "locations": [ { "line": 6, "column": 7 } ],
        "path": [ "updateSnippet" ],
        "extensions": {
          "spam": true
        }
      }
    ],
    "data": {
      "updateSnippet": {
        "snippet": null
      }
    }
  }

• 配置了 CAPTCHA 服务，您会收到包含以下内容的响应：

  • needsCaptchaResponse 设置为 true。
  • 设置了 spamLogId 和 captchaSiteKey 字段。

  例如：

  {
    "errors": [
      {
        "message": "Request denied. Solve CAPTCHA challenge and retry",
        "locations": [ { "line": 6, "column": 7 } ],
        "path": [ "updateSnippet" ],
        "extensions": {
          "needsCaptchaResponse": true,
          "captchaSiteKey": "6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI",
          "spamLogId": 67
        }
      }
    ],
    "data": {
      "updateSnippet": {
        "snippet": null,
      }
    }
  }

• 使用 captchaSiteKey 通过适当的 CAPTCHA API 获取 CAPTCHA 响应值。 仅支持 Google reCAPTCHA v2。

• 使用设置的 X-GitLab-Captcha-Response 和 X-GitLab-Spam-Log-Id 请求头重新提交请求。

export CAPTCHA_RESPONSE="<CAPTCHA response obtained from CAPTCHA service>"
export SPAM_LOG_ID="<spam_log_id obtained from initial REST response>"
curl --request POST \
  --header "Authorization: Bearer $PRIVATE_TOKEN" \
  --header "Content-Type: application/json" \
  --header "X-GitLab-Captcha-Response: $CAPTCHA_RESPONSE" \
  --header "X-GitLab-Spam-Log-Id: $SPAM_LOG_ID" \
  --data-binary '{"query": "mutation {createSnippet(input: {title: \"Title\" visibilityLevel: public blobActions: [ { action: create filePath: \"BlobPath\" content: \"BlobContent\" } ] }) { snippet { id title } errors }}"}' "https://gitlab.example.com/api/graphql"