---
title: "概述"

doc_type: static
doc_category: static
doc_version: v20270301
source_url:
  html: 'https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/graph-ql-admin-api/overview'
  md: 'https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/graph-ql-admin-api/overview.md'
---
<a name="dEMVz"></a>
# GraphQL Admin API 参考
使用 GraphQL Admin API 来扩展 SHOPLINE 的内置功能。 你可以使用这些 API 读取和修改商家数据并构建你的应用以扩展 SHOPLINE 的 Admin 功能。
本页介绍如何使用 GraphQL Admin API。


> **tip**
>
> 关于 GraphQL 的技术原理可以参考 GraphQL 的 [官方网站](https://spec.graphql.org/) 和 [官方教学文档](https://graphql.org/learn/queries/)。

<a name="h3xHp"></a>
## 身份认证
为了确保 SHOPLINE 平台上所有信息交互的安全性，所有应用在发送 GraphQL Admin API 请求时都需要访问令牌。

公共和自定义应用都使用 [OAuth 2.0](https://oauth.net/2/bearer-tokens/) 进行身份验证，身份验证完成后你可以获取有效的访问令牌。关于如何使用 OAuth 2.0 获取访问令牌，请参阅 [授权机制](https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/app-authorization.md?lang=zh-hans-cn)。

私有应用的访问令牌需要在 SHOPLINE Admin 的后台获取：找到 **应用** > **应用开发** > **编辑** > **API 凭据** > **后台 API 访问令牌**。


![image.png](https://s2cdn.myshopline.com/slfs/op-new/170913302849039/image.png)
<center>图 1. 私有应用的访问令牌</center>

私有应用的访问令牌有效期是 3 年。在即将过期前你的邮箱会收到访问令牌即将过期的提醒邮件，你需要去 SHOPLINE Admin 重新刷新访问令牌。令牌被刷新后，30 分钟后原访问令牌才会永久失效。如果想要把你的应用解除店铺的授权，你需要去 SHOPLINE Admin 删除应用后访问令牌才会失效。

发送请求时需要将获取到的访问令牌添加到 HTTP 请求头的 `Authorization` 参数中，格式如下：
```json
"Authorization":"Bearer {Your Token}"
```

<a name="iqVma"></a>
## 接口地址
所有 GraphQL Admin API 都使用 HTTP POST 方法发送请求到如下地址：


`POST https://{store_domain}.myshopline.com/admin/graph/{version}/graphql.json`

其中你需要替换如下变量的值：
- `store_domain`: 表示商家店铺的域名 handle。
- `version`: 表示你要使用的 API 版本。


<a name="nF9ty"></a>
## 版本管理 
GraphQL Admin API 基于产品能力的迭代提供了不同的 API 版本。更多关于 API 版本信息请参考 [API 版本管理说明](https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/api-versioning-guide.md)。

<a name="MBkmi"></a>
## 全局 ID
全局 ID 是针对 GraphQL 对象的唯一标识 ID。
全局 ID 的结构为：`gid://shopline/{object_name}/{id}`，其中 `object_name` 为对象的名字。例如对象名词为 [Customer](https://developer.shopline.com/zh-hans-cn/docs/admin-graph-ql-api/customers/objects/customer.md) 且 ID 值为 `1` 的全局 ID 为：`gid://shopline/Customer/1`。

你可以通过 GraphQL 查询来获取一个对象的全局 ID，并用于 GraphQL 的查询和变更中。

<a name="g1CQ6"></a>
## 查询限制

<a name="TJjYz"></a>

### 限速
GraphQL Admin API 根据请求成本点限制速率。每个请求的返回都会消耗特定数量的成本点，如果一个请求超过成本点限制，会返回状态码 `429`，并带有如下的错误提醒：

HTTP status code: `429`
```graphql
{"errors":"Too many request"}
```

简单的 GraphQL Admin API 请求消耗较少的成本点，因此同时间内可以进行多次请求。但如果你的请求过于复杂，很可能下一次请求需要等待较长的时间。

<a name="Sldt7"></a>
### 字段层级限制
GraphQL Admin API 最多支持 13 层级的字段嵌套请求，如下样例代码所示。
```graphql
query {
	 field1 {
		 field2 {
       field3 {
         ......
			     field13 {
         }
		   }
     }
   }
}
```

当你的请求中字段层级数超过了 13 层级的时候，将会返回 HTTP 结果码 `200` 以及一个系统错误码。假如你发送了一个 14 层级的字段嵌套请求，将会收到如下错误返回：

HTTP status code: `200`
```json
{
  "errors": [
    {
      "message": "maximum query depth exceeded 14 > 13",
      "extensions": {
        "classification": "ExecutionAborted"
      }
    }
  ]
}
```
<a name="YLBq3"></a>
## 状态码和错误码 {#status-and-error-codes}
所有 GraphQL Admin API 都会返回 HTTP 类型的结果码，同时还可能会返回具体的业务错误码。

<a name="eZsmz"></a>
### 200
接口调用成功时都会返回 `200` 的结果码。在一些请求中，因为服务端原因会导致一些预期内的错误，比如数据不存在，需要通过返回中的 `errors.extensions.code` 获取具体的错误信息。返回中的 `errors.message` 字段表示错误码的含义。代码样例如下：
HTTP status: `200`
```json
{
  "errors": [
    {
      "message": "DATA_NOT_EXIST",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": [
        "field"
      ],
      "extensions": {
        "code": "DATA_NOT_EXIST"
      }
    }
  ],
  "data": {
    "api": null
  }
}
```

<a name="xtT8b"></a>
#### 业务错误码
常见的业务错误码及解释如下:

| **错误码** | **描述** |
| --- | --- |
| REQUEST_LIMIT_EXCEEDED | 系统访问量超出限制，请稍后重试。 |
| PARAM_ILLEGAL | 参数非法，例如传参格式不对或参数类型不对，请检查参数重试。 |
| DATA_NOT_EXIST | 数据不存在。 |
| REMOTE_ERROR | 远程服务系统发生错误。 |
| SYSTEM_ERROR | 系统错误，建议稍后重试。 |

表 1. 常见业务错误码

#### 公共错误码
HTTP status: `200`

| 错误码    | 描述 |
| --------- | ----------- |
| TOO_MANY_REQUESTS    | 请求太多，请等待几分钟再重新请求。      |
| INNER_FAIL | 内部错误，请联系 SHOPLINE 处理。|

表 2. 公共错误码

<a name="G5qAO"></a>
### 4XX and 5XX status codes 
少数情况下可能会返回 4XX 和 5XX 类型的状态码。4XX 类的错误码一般表示客户端异常，而 5XX 错误码通常表示服务端异常。例如，当店铺被冻结时候，你将收到下面的响应:

HTTP status: `402`
```json
{
	"errors": "Store has been frozen or closed"
}
```

#### 公共错误码

| 错误码    | 描述 |
| --------- | ----------- |
| ACCESS_TOKEN_INVALID    | Access Token 无效，请检查 token 拼写是否正确。       |
| ACCESS_TOKEN_IS_EXPIRED | Access Token 过期，请刷新 token，可参考 [请求刷新 token ](https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/app-authorization.md)。|
| STORE_IS_FREZON | 店铺被冻结，被冻结的店铺请求会被限制。请检查店铺状态。|
| FAIL | 系统错误，请联系 SHOPLINE 处理。|



更多 HTTP 状态码，请参考 [HTTP 状态码](https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/http-status-code.md)。

<a name="g1ZUe"></a>
## API Explorer
你可以使用 [API Explorer](https://developer.shopline.com/graphql/admin) 来探索 SHOPLINE GraphQL Admin API。API Explorer 提供了演示商店数据，你可以使用 API Explorer 执行以下操作：

- 了解SHOPLINE提供的商店资源。
- 发出查询和变更请求以获取或修改演示商店数据。
- 探索不同版本的GraphQL API。