• 运行示例
  • GraphiQL
  • 命令行
  • Rails 控制台
• 查询和变更
  • 图遍历
  • 授权
  • 变更
    • 创建变更
    • 更新变更
    • 删除变更
  • 更新项目设置
  • 内省查询
  • 查询复杂性
• 排序
• 分页
• 更改查询 URL

{{< details >}}

• Tier: 基础版, 专业版, 旗舰版
• Offering: JihuLab.com, 私有化部署

{{< /details >}}

本指南演示了极狐GitLab GraphQL API 的基本用法。

阅读 GraphQL API 风格指南 以获取面向希望开发 API 本身的开发人员的实现细节。

运行示例

此处记录的示例可以使用以下方式运行：

1. GraphiQL。
2. 命令行。
3. Rails 控制台。

GraphiQL

GraphiQL（发音为 “graphical”）允许您以交互方式对 API 运行真实的 GraphQL 查询。它通过提供带有语法高亮和自动完成的 UI，使探索模式变得更加容易。

对于大多数人来说，使用 GraphiQL 将是探索极狐GitLab GraphQL API 的最简单方法。

您可以使用 GraphiQL：

1. 在 JihuLab.com 上。
2. 在极狐GitLab 私有化部署上，网址为 https://<your-gitlab-site.com>/-/graphql-explorer。

首先登录极狐GitLab 以使用您的极狐GitLab 账户验证请求。

要开始使用，请参考 示例查询和变更。

命令行

您可以在本地计算机上的命令行中通过 curl 请求运行 GraphQL 查询。请求将 POST 到 /api/graphql，查询为有效负载。您可以生成个人访问令牌作为承载令牌来授权您的请求。阅读更多关于 GraphQL 认证 的信息。

示例：

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

在查询字符串中嵌套字符串时， 将数据用单引号包裹，或使用 \\ 转义字符串：

curl "https://gitlab.com/api/graphql" --header "Authorization: Bearer $GRAPHQL_TOKEN" \
    --header "Content-Type: application/json" --request POST \
    --data '{"query": "query {project(fullPath: \"<group>/<subgroup>/<project>\") {jobs {nodes {id duration}}}}"}'
      # 或 "{\"query\": \"query {project(fullPath: \\\"<group>/<subgroup>/<project>\\\") {jobs {nodes {id duration}}}}\"}"

Rails 控制台

{{< details >}}

• Tier: Free, Premium, Ultimate
• Offering: GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

可以在 Rails 控制台会话 中运行 GraphQL 查询。例如，搜索项目：

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 可用于执行：

1. 数据检索查询。
2. 用于创建、更新和删除数据的 变更。

{{< alert type=”note” >}}

在极狐GitLab GraphQL API 中，id 指的是一个全局 ID，这是一个格式为 "gid://gitlab/Issue/123" 的对象标识符。有关更多信息，请参见 全局 ID。

{{< /alert >}}

极狐GitLab GraphQL 模式 概述了客户端可以查询的对象和字段及其对应的数据类型。

示例：仅获取当前身份验证用户可以访问的所有项目的名称（最多限制）在群组 gitlab-org 中。

query {
  group(fullPath: "gitlab-org") {
    id
    name
    projects {
      nodes {
        name
      }
    }
  }
}

示例：获取特定项目和议题 #2 的标题。

query {
  project(fullPath: "gitlab-org/graphql-sandbox") {
    name
    issue(iid: "2") {
      title
    }
  }
}

图遍历

检索子节点时使用：

1. edges { node { } } 语法。
2. 简写形式 nodes { } 语法。

本质上，我们正在遍历一个图，因此得名 GraphQL。

示例：获取项目的名称及其所有议题的标题。

query {
  project(fullPath: "gitlab-org/graphql-sandbox") {
    name
    issues {
      nodes {
        title
        description
      }
    }
  }
}

更多关于查询的信息： GraphQL 文档

授权

如果您已登录极狐GitLab 并使用 GraphiQL，则所有查询都将以您，即经过身份验证的用户身份执行。有关更多信息，请阅读GraphQL 认证。

变更

变更会对数据进行更改。我们可以更新、删除或创建新记录。 变更通常使用 InputTypes 和变量，这些都不会出现在这里。

变更包括：

1. 输入。例如，参数，如您希望添加的表情符号反应 以及要添加到哪个对象。
2. 返回语句。也就是当成功时您希望返回的内容。
3. 错误。总是询问出错的原因，以防万一。

创建变更

示例：让我们喝些茶 - 向议题添加一个 :tea: 表情符号反应。

mutation {
  awardEmojiAdd(input: { awardableId: "gid://gitlab/Issue/27039960",
      name: "tea"
    }) {
    awardEmoji {
      name
      description
      unicode
      emoji
      unicodeVersion
      user {
        name
      }
    }
    errors
  }
}

示例：向议题添加评论。在此示例中，我们使用 JihuLab.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 查询浏览器 使用内省查询来：

1. 获取关于极狐GitLab GraphQL 模式的信息。
2. 进行自动完成。
3. 提供其交互式 Docs 选项卡。

示例：获取模式中的所有类型名称。

{
  __schema {
    types {
      name
    }
  }
}

示例：获取与议题相关的所有字段。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 区域设置自定义 header（左下区域，Variables 所在位置的右边）：

{
  "REQUEST_PATH": "<the URL to make the graphQL request against>"
}