[分享] 如何使用GraphQL

使用GraphQL

1.简介

官方文档:GraphQL API | GitLab

GraphQL语法文档:https://graphql.org/learn

GraphQL是Gitlab的一种api查询语句,它能实现REST API的所有功能,并且在官方预期是最优先使用GraphQL。

2.开始使用GraphQL

使用GraphQL有两种方式Command lineGraphiQL,即命令行和图形化。

2.1使用Command line

需要先为用户创建access token,请求示例:

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}}”}”

2.2使用GraphiQL

GraphiQL是一个图形化的web console,web url为:https://<gitlab_url>/-/graphql-explorer

3.GraphQL的两种模式

GraphQL有两种工作模式–Queries and mutations:

  • Queries:用于数据检索
  • mutations:用于创建,更新,删除数据

GraphQL所有参数的文档:GraphQL API Resources | GitLab

3.1这个文档应该怎么看?

这里以group这个方法为例:

GraphQL的写法模式我总结为:

操作模式类型 {
  需要请求的资源(参数: "值") {
    field1
    field2
  }
}

field即为期望被查询资源所要返回的数据条目。

最后得到GraphQL为:

query {
  group(fullPath: "policy") {
    id
    name
    projects {
      nodes {
        name
      }
    }
  }
}

这条GraphQL的意思为:查询“policy”这个组,返回结果包括这个组的id,组名,和下面的项目名。

效果如下:

3.2怎么查看一个资源有哪些field?

这里以vulnerabilityCreate为例,因为这个资源涉及到的属性比较多,可以用作典型。

查询一个资源必须先获取它的id,GraphQL中使用的资源id是global id,global id的组成是:gid://gitlab/<resource_type>/<id_num>需要注意这里的resource_type名称首字母为大写。

比如一个id为4的组的global id就为gid://gitlab/Group/4

一个id为1的vulnerability的global id就为:gid://gitlab/Vulnerability/1

假设现在要查询id为1的vulnerability,我们首先需要在graphql reference中找到创建对应资源的方法这里对应的就是vulnerabilityCreate

Arguments就可以作为查询的field,但是有些filed是由子field组成的,所以在查询时还必须填写需要查询的子field,要查询一个field的子field,可以直接点击type下面对应的字段连接即可,比如这里要查询confidence的子field,直接点击后面的VulnerabilityConfidence即可,就会进入下面的界面:


然后在GraphQL中以field{subfield}的形式组合即可。

GraphQL示例:

query {
  vulnerability(id: "gid://gitlab/Vulnerability/1") {
    id
    description
   	severity
    identifiers {
      name
      url
    }
    scanner {
      name
    }
    project {
      id
    }
  }
}