使用极狐GitLab GraphQL API

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

关于开发 API 本身的实施细节，请阅读 GraphQL API 风格指南。

运行示例

可以使用以下内容运行记录的示例：

命令行
GraphiQL
Rails console

命令行

在您的本地计算机中，您可以在命令行的 curl 请求中运行 GraphQL 查询。 GraphQL 请求可以作为对 /api/graphql 的 POST 请求发出，并将查询作为有效负载。您可以通过生成个人访问令牌授权您的请求，将其用作 Bearer 令牌。此令牌至少需要 read_api 范围。

示例：

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}}}}"}'
      # or "{\"query\": \"query {project(fullPath: \\\"<group>/<subgroup>/<project>\\\") {jobs {nodes {id duration}}}}\"}"

GraphiQL

GraphiQL 允许您通过语法高亮和自动完成功能直接针对服务器端点运行查询。还允许您探索架构和类型。

下面的例子：

可以直接针对极狐GitLab 运行。
无需任何进一步设置即可针对 JiHuLab.com 运行。确保您已登录并导航到 GraphiQL Explorer。

如果要在本地或私有化部署实例上运行查询，则必须：

使用名为 graphql-sandbox 的项目在其下创建 gitlab-org 群组，并在项目中创建几个议题。
或编辑查询，用您自己的群组和项目替换 gitlab-org/graphql-sandbox。

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

对于 12.0，请启用 graphql 功能标志。

Rails console

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

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

查询和 Mutation

极狐GitLab GraphQL API 可用于：

数据检索查询
创建、更新和删除数据的 Mutation

在极狐GitLab GraphQL API 中，id 指的是全局 ID，它是一个对象标识符，格式为 "gid://gitlab/Issue/123"。

示例：只获取 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
    }
  }
}

图遍历

检索子节点时使用：

edges { node { } } 语法
简短形式的 nodes { } 语法

在它下面是我们正在遍历的一个图，因此得名 GraphQL。

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

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

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

授权

授权使用与极狐GitLab 应用程序（和 JiHuLab.com）相同的引擎。如果您已登录极狐GitLab 并使用 GraphiQL，则所有查询都以您-经过身份验证的用户的身份进行操作。有关更多信息，请阅读极狐GitLab API 文档。

Mutation

Mutation 会改变数据。我们可以更新、删除或创建新记录。 Mutation 通常使用 InputTypes 和变量，这里都没有出现。

Mutation 拥有：

输入。例如参数，例如您想要给哪个对象奖励哪个表情符号。
返回报表。也就是说，成功时您想得到什么。
错误。经常询问是否一切正常，以防万一。

创建 Mutation

示例：将 :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
  }
}

更新 Mutation

当您看到您创建的备注的结果 id 时，请进行记录。

mutation {
  updateNote(input: { id: "gid://gitlab/Note/<note ID>",
      body: "*SIPS TEA*"
    }) {
    note {
      id
      body
    }
    errors
  }
}

删除 Mutation

删除评论。

mutation {
  destroyNote(input: { id: "gid://gitlab/Note/<note ID>" }) {
    note {
      id
      body
    }
    errors
  }
}

您会获取类似以下示例中的内容：

{
  "data": {
    "destroyNote": {
      "errors": [],
      "note": null
    }
  }
}

我们请求备注的详细信息，但是不存在，所以我们得到 null。

有关 Mutation 的详细信息，请参见 GraphQL 文档。

内省查询

客户端可以通过内省查询来查询 GraphQL 端点以获取有关其自身架构的信息。 GraphiQL 查询 Explorer 使用内省查询：

了解我们的 GraphQL 架构
实现自动完成
提供其交互式的 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
      }
    }
  }
}

分页

分页是一种只要求记录子集的方式，例如前十个。如果想要更多，我们可以从服务器再次请求十个，例如发送 please give me the next ten records。

默认情况下，极狐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 文档。