# Getting started with GitLab GraphQL API

> 原文：[https://docs.gitlab.com/ee/api/graphql/getting_started.html](https://docs.gitlab.com/ee/api/graphql/getting_started.html)

*   [Running examples](#running-examples)
    *   [Command line](#command-line)
    *   [GraphiQL](#graphiql)
*   [Queries and mutations](#queries-and-mutations)
    *   [Graph traversal](#graph-traversal)
    *   [Authorization](#authorization)
    *   [Mutations](#mutations)
        *   [Creation mutations](#creation-mutations)
        *   [Update mutations](#update-mutations)
        *   [Deletion mutations](#deletion-mutations)
    *   [Introspective queries](#introspective-queries)
*   [Sorting](#sorting)
*   [Pagination](#pagination)

# Getting started with GitLab GraphQL API[](#getting-started-with-gitlab-graphql-api "Permalink")

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

请参见[GraphQL API 样式指南，](../../development/api_graphql_styleguide.html)以了解针对希望开发 API 本身的开发人员的实现细节.

## Running examples[](#running-examples "Permalink")

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

*   命令行.
*   GraphiQL.

### Command line[](#command-line "Permalink")

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

Example:

```
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}}\"}" 
```

### GraphiQL[](#graphiql "Permalink")

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

下面的例子：

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

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

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

有关更多信息，请参考[运行 GraphiQL](index.html#graphiql) .

**注意：**如果您正在运行 GitLab 11.0 到 12.0，请启用`graphql` [功能标记](../features.html#set-or-create-a-feature) .

## Queries and mutations[](#queries-and-mutations "Permalink")

GitLab GraphQL API 可用于执行：

*   数据检索查询.
*   用于创建，更新和删除数据的[突变](#mutations) .

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

[GitLab 的 GraphQL Schema](reference/index.html)概述了哪些对象和字段可供客户端查询以及它们对应的数据类型.

示例：在`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  }  }  } 
```

### Graph traversal[](#graph-traversal "Permalink")

检索子节点时，请使用：

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

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

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

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

有关查询的更多信息： [GraphQL 文档](https://s0graphql0org.icopy.site/learn/queries/)

### Authorization[](#authorization "Permalink")

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

### Mutations[](#mutations "Permalink")

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

变异有：

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

#### Creation mutations[](#creation-mutations "Permalink")

示例：让我们喝点茶-在问题中添加`: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  }  } 
```

#### Update mutations[](#update-mutations "Permalink")

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

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

#### Deletion mutations[](#deletion-mutations "Permalink")

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

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

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

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

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

有关突变的更多信息： [GraphQL Docs](https://s0graphql0org.icopy.site/learn/queries/) .

### Introspective queries[](#introspective-queries "Permalink")

客户端可以查询 GraphQL 端点以获取有关其自身架构的信息. 通过进行[内省性查询](https://s0graphql0org.icopy.site/learn/introspection/) .

通过自省查询， [GraphiQL 查询资源管理器](https://gitlab.com/-/graphql-explorer)获得了有关我们的 GraphQL 模式的所有知识，以执行自动补全并提供其交互式`Docs`选项卡.

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

```
{  __schema  {  types  {  name  }  }  } 
```

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

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

有关自省的更多信息： [GraphQL 文档](https://s0graphql0org.icopy.site/learn/introspection/)

## Sorting[](#sorting "Permalink")

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

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

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

## Pagination[](#pagination "Permalink")

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

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

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

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

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

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

有关分页和游标的更多信息： [GraphQL 文档](https://s0graphql0org.icopy.site/learn/pagination/)