Getting started with GitLab GraphQL API

原文：https://docs.gitlab.com/ee/api/graphql/getting_started.html

Getting started with GitLab GraphQL API

本指南演示了 GitLab 的 GraphQL API 的基本用法.

请参见GraphQL API 样式指南，以了解针对希望开发 API 本身的开发人员的实现细节.

Running examples

此处记录的示例可以使用以下命令运行：

  • 命令行.
  • GraphiQL.

Command line

您可以在本地计算机上的命令行中的curl请求中运行 GraphQL 查询. 可以将 GraphQL 请求作为对/api/graphql的POST请求，并将查询作为有效负载. 您可以通过生成个人访问令牌以用作承载令牌来授权您的请求.

Example:

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

GraphiQL

GraphiQL（发音为”图形”）允许您使用语法突出显示和自动完成功能直接针对服务器端点运行查询. 它还允许您探索模式和类型.

下面的例子：

  • 可以直接在 GitLab 11.0 或更高版本上运行，尽管某些类型和字段在较早的版本中可能不受支持.
  • 无需任何进一步设置即可在 GitLab.com 上运行. 确保您已登录并导航到GraphiQL Explorer .

如果要在本地或在自管实例上运行查询，则需要执行以下任一操作：

  • 创建gitlab-org组，并在其下创建一个名为graphql-sandbox的项目. 在项目中创建多个问题.
  • 编辑查询以将gitlab-org/graphql-sandbox替换为您自己的组和项目.

有关更多信息，请参考运行 GraphiQL .

注意：如果您正在运行 GitLab 11.0 到 12.0，请启用graphql 功能标记 .

Queries and mutations

GitLab GraphQL API 可用于执行：

  • 数据检索查询.
  • 用于创建，更新和删除数据的突变 .

注意：在 GitLab GraphQL API 中， id通常是指全局 ID，它是对象标识符，格式为gid://gitlab/Issue/123 .

GitLab 的 GraphQL Schema概述了哪些对象和字段可供客户端查询以及它们对应的数据类型.

示例：在gitlab-org组中，仅获取当前登录用户可以访问的所有项目的名称（最大限制，稍后再介绍）.

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

示例：获得一个特定的项目和标题＃2.

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

Graph traversal

检索子节点时，请使用：

  • the edges { node { } } syntax.
  • 缩写形式nodes { }语法.

在它的下面是一个我们正在遍历的图，因此命名为 GraphQL.

示例：获得一个项目（仅名称）及其所有期刊的标题.

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

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

Authorization

授权使用与 GitLab 应用程序（和 GitLab.com）相同的引擎. 因此，如果您已经登录到 GitLab 并使用 GraphiQL，则所有查询都将以您（登录用户）的身份执行. 有关更多信息，请参见GitLab API 文档 .

Mutations

变异会改变数据. 我们可以更新，删除或创建新记录. 变异通常使用 InputTypes 和变量，在此都不会出现.

变异有：

  • 输入. 例如，参数，例如您想要授予的表情符号以及对象.
  • 返回语句. 也就是说，成功后您希望获得什么.
  • 错误. 总是问出什么问题了，以防万一.

Creation mutations

示例：让我们喝点茶-在问题中添加:tea:反应表情符号.

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

示例：在问题上添加评论（我们使用的是GitLab.com问题的 ID，但是如果您使用的是本地实例，则需要获取可以写入的问题的 ID）.

  1. mutation  {  createNote(input:  {  noteableId:  "gid://gitlab/Issue/27039960",  body:  "*sips tea*"  })  {  note  {  id  body  discussion  {  id  }  }  errors  }  }

Update mutations

当您看到创建的注释的结果id时，请记下它. 现在，让我们对其进行编辑以更快地 ip 饮！

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

Deletion mutations

让我们删除评论，因为我们的茶都没了.

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

您应该得到类似以下输出的内容：

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

我们已经要求提供注释的详细信息，但是它不再存在，因此我们得到null .

有关突变的更多信息： GraphQL Docs .

Introspective queries

客户端可以查询 GraphQL 端点以获取有关其自身架构的信息. 通过进行内省性查询 .

通过自省查询， GraphiQL 查询资源管理器获得了有关我们的 GraphQL 模式的所有知识，以执行自动补全并提供其交互式Docs选项卡.

示例：获取架构中的所有类型名称.

  1. {  __schema  {  types  {  name  }  }  }

示例：获取与 Issue 相关的所有字段. kind告诉我们该类型的枚举值，例如OBJECT ， SCALAR或INTERFACE .

  1. query  IssueTypes  {  __type(name:  "Issue")  {  kind  name  fields  {  name  description  type  {  name  }  }  }  }

有关自省的更多信息： GraphQL 文档

Sorting

GitLab 的一些 GraphQL 端点允许您指定想要对对象集合进行排序的方式. 您只能按架构允许的排序.

示例：可以按创建日期对问题进行排序：

  1. query  {  project(fullPath:  "gitlab-org/graphql-sandbox")  {  name  issues(sort:  created_asc)  {  nodes  {  title  createdAt  }  }  }  }

Pagination

分页是仅询问记录子集（例如前 10 个）的一种方法. 如果我们想要更多，我们可以从服务器再次请求下 10 条记录（例如”请给我下 10 条记录”）.

默认情况下，GitLab 的 GraphQL API 将仅返回任何集合的前 100 条记录. 可以使用first或last参数来更改. 这两个参数都有一个值，因此first: 10将返回前 10 条记录， last: 10将最后 10 条记录.

示例：仅检索前两个问题（切片）. cursor字段为我们提供了一个位置，从中可以检索相对于该位置的其他记录.

  1. query  {  project(fullPath:  "gitlab-org/graphql-sandbox")  {  name  issues(first:  2)  {  edges  {  node  {  title  }  }  pageInfo  {  endCursor  hasNextPage  }  }  }  }

示例：检索下一个 3.（游标值eyJpZCI6IjI3MDM4OTMzIiwiY3JlYXRlZF9hdCI6IjIwMTktMTEtMTQgMDU6NTY6NDQgVVRDIn0可能有所不同，但它是上面返回的第二个问题返回的cursor值.）

  1. query  {  project(fullPath:  "gitlab-org/graphql-sandbox")  {  name  issues(first:  3,  after:  "eyJpZCI6IjI3MDM4OTMzIiwiY3JlYXRlZF9hdCI6IjIwMTktMTEtMTQgMDU6NTY6NDQgVVRDIn0")  {  edges  {  node  {  title  }  cursor  }  pageInfo  {  endCursor  hasNextPage  }  }  }  }

有关分页和游标的更多信息： GraphQL 文档