GraphQL Admin API 参考​

使用 GraphQL Admin API 来扩展 SHOPLINE 的内置功能。 你可以使用这些 API 读取和修改商家数据并构建你的应用以扩展 SHOPLINE 的 Admin 功能。 本页介绍如何使用 GraphQL Admin API。

身份认证​

为了确保 SHOPLINE 平台上所有信息交互的安全性，所有应用在发送 GraphQL Admin API 请求时都需要访问令牌。

公共和自定义应用都使用 OAuth 2.0 进行身份验证，身份验证完成后你可以获取有效的访问令牌。关于如何使用 OAuth 2.0 获取访问令牌，请参阅 授权机制。

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

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

发送请求时需要将获取到的访问令牌添加到 HTTP 请求头的 Authorization 参数中，格式如下：

"Authorization":"Bearer {Your Token}"

接口地址​

所有 GraphQL Admin API 都使用 HTTP POST 方法发送请求到如下地址：

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

其中你需要替换如下变量的值：

• store_domain: 表示商家店铺的域名 handle。
• version: 表示你要使用的 API 版本。

版本管理​

GraphQL Admin API 基于产品能力的迭代提供了不同的 API 版本。更多关于 API 版本信息请参考 API 版本管理说明。

全局 ID​

全局 ID 是针对 GraphQL 对象的唯一标识 ID。 全局 ID 的结构为：gid://shopline/{object_name}/{id}，其中 object_name 为对象的名字。例如对象名词为 Customer 且 ID 值为 1 的全局 ID 为：gid://shopline/Customer/1。

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

查询限制​

限速​

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

HTTP status code: 429

{"errors":"Too many request"}

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

字段层级限制​

GraphQL Admin API 最多支持 13 层级的字段嵌套请求，如下样例代码所示。

query {
	 field1 {
		 field2 {
       field3 {
         ......
			     field13 {
         }
		   }
     }
   }
}

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

HTTP status code: 200

{
  "errors": [
    {
      "message": "maximum query depth exceeded 14 > 13",
      "extensions": {
        "classification": "ExecutionAborted"
      }
    }
  ]
}

状态码和错误码​

所有 GraphQL Admin API 都会返回 HTTP 类型的结果码，同时还可能会返回具体的业务错误码。

200​

接口调用成功时都会返回 200 的结果码。在一些请求中，因为服务端原因会导致一些预期内的错误，比如数据不存在，需要通过返回中的 errors.extensions.code 获取具体的错误信息。返回中的 errors.message 字段表示错误码的含义。代码样例如下： HTTP status: 200

{
  "errors": [
    {
      "message": "DATA_NOT_EXIST",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": [
        "field"
      ],
      "extensions": {
        "code": "DATA_NOT_EXIST"
      }
    }
  ],
  "data": {
    "api": null
  }
}

业务错误码​

常见的业务错误码及解释如下:

表 1. 常见业务错误码

公共错误码​

HTTP status: 200

表 2. 公共错误码

4XX and 5XX status codes​

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

HTTP status: 402

{
	"errors": "Store has been frozen or closed"
}

公共错误码​

更多 HTTP 状态码，请参考 HTTP 状态码。

API Explorer​

你可以使用 API Explorer 来探索 SHOPLINE GraphQL Admin API。API Explorer 提供了演示商店数据，你可以使用 API Explorer 执行以下操作：

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