• 愿景
• 使用 GraphQL
  • GraphiQL
  • 查看 GraphQL 示例
• 重大更改
  • 针对未来重大更改架构进行验证
  • 废弃和移除流程
    • 废弃示例
  • 移除条目列表
• 可用查询
  • 多路查询
• 限制
  • 最大查询复杂度
• 解决检测为垃圾邮件的 Mutation

GraphQL API

启用并广泛可用于极狐GitLab 12.1。功能标志 graphql 已移除。

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

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

愿景

我们希望 GraphQL API 成为与极狐GitLab 以编程方式交互的主要方式。 为了实现这一点，需要全面覆盖 - REST API 中的东西也应该存在于 GraphQL API。

为了帮助我们实现这一愿景，与 REST API 相比，前端应该优先使用 GraphQL 进行新功能开发。

我们没有计划废弃 REST API。为了减轻同时支持两个 API 的技术负担，它们应该尽可能多地分担。

使用 GraphQL

如果您不熟悉极狐GitLab GraphQL API，请参阅了解极狐GitLab GraphQL API。

该引用是从极狐GitLab GraphQL 架构自动生成的，并且写入 Markdown 文件。

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

GraphiQL

使用交互式 GraphiQL Explorer 或在您 https://<your-gitlab-site.com>/-/graphql-explorer 上的私有化部署的极狐GitLab 实例上探索 GraphQL API。

有关详细信息，请参阅 GraphiQL。

查看 GraphQL 示例

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

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

了解页面包含自定义 GraphQL 查询的不同方法。

重大更改

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

但是，极狐GitLab 有时会以不向后兼容的方式更改 GraphQL API。这些更改被视为重大更改，并且可以包括移除或重命名字段、参数或架构的其他部分。 创建重大更改时，极狐GitLab 遵循废弃和移除流程。

为避免重大更改影响您的集成，您应该熟悉废弃和移除流程并经常 针对未来的重大更改架构验证您的 API 调用。

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

针对未来重大更改架构进行验证

引入于极狐GitLab 15.6。

您可以对 GraphQL API 进行调用，就好像所有已弃用的项目都已经被移除一样。 这样，您可以在项目实际从架构中删除之前，在重大更改发布之前验证 API 调用。

要进行这些调用，请向极狐GitLab GraphQL API 端点（例如，适用于极狐GitLab SaaS GraphQL 的 https://gitlab.com/api/graphql?remove_deprecated=true ） 添加一个 remove_deprecated=true 查询参数。

废弃和移除流程

极狐GitLab GraphQL API 的废弃和移除流程与更广泛的极狐GitLab 废弃流程保持一致。

标记为从极狐GitLab GraphQL API 中移除的部分结构已废弃， 但仍可用于至少六个版本。然后将其完全移除于下一个 XX.0 的主要版本中。

您应该在没有弃用的架构项的情况下，针对架构验证您的 API 调用。

废弃示例

以下字段在不同的小版本发布中都已废弃，但都移除于 14.0。

移除条目列表

请查看先前发布中的移除条目列表。

可用查询

GraphQL API 包括根级别的以下查询：

新的关联和根级别的对象会定期添加。 <!–See the GraphQL API Reference for up-to-date information.

Root-level queries are defined in app/graphql/types/query_type.rb.–>

多路查询

极狐GitLab 支持使用 @apollo/client/link/batch-http 将查询批处理到单个请求中。 有关多路查询的信息也可用于极狐GitLab 在后端使用的库，即 GraphQL Ruby。

限制

极狐GitLab GraphQL API 有以下限制：

最大查询复杂度

极狐GitLab GraphQL API 对查询的复杂度进行评分。一般来说，较大的查询具有更高的复杂度分数。 此限制旨在保护 API 执行可能对其整体性能产生负面影响的查询。

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

如果查询超出复杂性限制，则会返回错误消息响应。

通常情况下，查询中的每个字段都会在复杂度得分上加 1，尽管对于特定领域会更高或更低。有时，添加某些参数也可能增加查询的复杂性。

解决检测为垃圾邮件的 Mutation

引入于极狐GitLab 13.11。

GraphQL Mutation 可能会被检测为垃圾邮件。如果其被检测为垃圾邮件并且：

• 未配置 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,
      }
    }
  }
  

• 使用合适的 CAPTCHA API 通过 captchaSiteKey 获取 CAPTCHA 响应值。 仅支持 Google reCAPTCHA v2。
• 设置 X-GitLab-Captcha-Response 和 X-GitLab-Spam-Log-Id Header，重新提交请求。

export CAPTCHA_RESPONSE="<CAPTCHA response obtained from CAPTCHA service>"
export SPAM_LOG_ID="<spam_log_id obtained from initial REST response>"
curl --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" --request POST --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"