Admin GraphQL API：认证、版本与限流

Admin GraphQL API 是应用读写店铺后台数据（商品、订单、客户、库存、metafield 等）的主要接口，官方写作“构建扩展和增强 Shopify admin 的应用与集成”。本文说明它的认证、版本、限流和分页这些跨资源的通用规则；不列具体资源的字段，也不覆盖面向顾客的 Storefront API。Admin GraphQL API 参考

本库哪些内容依赖它

• OAuth 回调指南：如何在授权后拿到访问令牌；本文负责令牌拿到之后怎么用；
• Shopify App 的三种形态：分发方式决定令牌来源，遗留的后台自建应用令牌见该文；
• 原生配置、应用与开发、店铺、组织与权限：扩展位置与人员权限，与应用的 access scopes 是两套授权；
• 自定义数据、隐私与同意、应用用量计费、评价的数据结构：这些文章里提到的 metafield、同意状态、订阅变更和评价汇总 metafield，都经本 API 读写；
• Webhooks：事件推送与本 API 的拉取互为补充；
• 环境隔离、共享后端：令牌属于具体应用与店铺的安装关系。

本文是 Admin API 通用机制的权威来源，其他文章只写各自页面语境下的用法。

核心对象与概念

在哪里配置

• scopes：写在应用配置文件 shopify.app.toml 的 [access_scopes]，推送后由 Shopify 处理商家批准（Shopify managed installation）；可声明商家在安装后另行批准的可选 scopes，所以“已授予的”可能不同于“配置里写的”。
• 实际授予了什么：查询 currentAppInstallation { accessScopes { handle } }，返回该安装实际授予的每个 scope。
• 安装与令牌方式：官方总览列出 Shopify managed installation（CLI 应用默认）、token exchange（嵌入式应用）、authorization code grant（非嵌入应用）和 client credentials grant（仅组织内自有应用，无商家批准步骤）四种。前两种与本库分发方式、OAuth 回调一致；client credentials 一项是本次读到的新增内容，本库上述两篇未涉及，适用条件以官方页为准。

与主题、Liquid 和 API 的连接

• Admin API 与 Liquid 是两个方向：Liquid 在主题里渲染店面，读取对象由主题决定；应用在服务端用 Admin API 写入数据（如 metafield），主题再经 Liquid 读取。不要在浏览器端调用 Admin API：令牌是服务端凭据。
• REST 现状：REST Admin API 页写明“自 2024 年 10 月 1 日起是遗留 API；自 2025 年 4 月 1 日起，所有新的公共应用必须仅用 GraphQL Admin API 构建”。GraphQL 参考页本身未提 REST。新集成默认用 GraphQL。
• 与 webhook 的形状差：Webhook 投递体是“完整的 REST 资源”，而 Events（开发者预览）才允许自定义 GraphQL 载荷，见Webhooks。因此“拉取用 GraphQL、推送是 REST 形”并不矛盾。
• 无代码替代：不想自建服务时，先看 Flow 能否在后台内完成同类自动化。
• Headless：面向顾客的数据读取走 Storefront API，见 Headless。

最小查询与变更示例（虚构字段值；语法与字段已用 Admin schema 校验器检查）：

query Products($first: Int!, $after: String) {
  products(first: $first, after: $after) {
    nodes { id title }
    pageInfo { hasNextPage endCursor }
  }
}

mutation UpdateTitle($product: ProductUpdateInput!) {
  productUpdate(product: $product) {
    product { id }
    userErrors { field message }
  }
}

校验器提示旧写法 productUpdate(input: ProductInput!) 的 input 参数已弃用，应使用 product 参数，示例采用后者。

限制、数值与易错点

核验于 2026-09-29，逐条标来源；数值会变，使用前重读来源页。

1. 版本节奏。 版本字符串是日期形式，如 2026-04；每三个月在季度首日 17:00 UTC 发布新版本；每个稳定版至少支持 12 个月，相邻版本至少重叠 9 个月；另有 release candidate 与 unstable。版本页读到的状态：2025-01、2025-04、2025-07 为 Unsupported；2025-10、2026-01、2026-04 为 Stable；2026-07 为最新稳定；2026-10 为 release candidate。请求指向不可用版本时，Shopify“向前落到最老的可用稳定版”，可能悄悄改变返回结构，所以要固定并按季度升级。API versioning
2. 弃用通知渠道。 版本页列出 Dev Dashboard 提醒、GraphiQL 等客户端工具、开发者 changelog、API 参考更新与紧急联系通知；响应头 X-Shopify-Api-Version 用于确认实际使用的版本。
3. 限流是成本模型。 Admin GraphQL 按计算出的查询成本限流，采用漏桶：请求往桶里加“弹珠”，桶持续漏出。各套餐的恢复速率：Standard 100、Advanced Shopify 200、Shopify Plus 1000、面向企业的 Commerce Components 2000 点/秒；单个查询成本上限 1000，与套餐无关。字段成本：标量与枚举 0，对象 1，连接按 first/last 计，变更 10，接口与联合取可能选择中的最大值；Shopify 保留手动设定字段成本的权利。执行完成后桶会退还“请求成本”与“实际成本”之差。GraphQL Admin API rate limits。该页未给出桶容量，实际值从响应 extensions.cost.throttleStatus 的 maximumAvailable、currentlyAvailable、restoreRate 读取；超限返回错误码 THROTTLED，语义类似 429。Admin API 参考
4. 变体创建的额外限制。 limits 页写明：变体总数超过 500,000 的店铺，每天最多创建 10,000 个新变体；rate-limits 页写超限收到 429 Too Many Requests。API limits
5. 输入与分页。 接受数组的输入参数最多 250 项；游标分页一次最多取 250 条；分页数组对象总量限制为 25,000，超出时计数返回 25,001。pageInfo 含 hasNextPage、endCursor、hasPreviousPage、startCursor。分页
6. Bulk operations 绕开逐条限流。 官方写明它们没有单个查询的最大成本与限流。查询侧：bulkOperationRunQuery 异步执行，结果为 JSONL，下载 URL 一周后过期，10 天内必须完成，最多五个连接且嵌套最多两层，完成通知可订阅 bulk_operations/finish webhook。变更侧：先 stagedUploadsCreate 取上传位置，上传变量 JSONL（不得超过 100MB），再 bulkOperationRunMutation，须 24 小时内完成；除这两个 bulk 变更本身外任何 Admin 变更都可以传入，部分失败可用 partialDataUrl。并发数因版本而异：2026-01 起每个应用每店可同时运行最多五个 bulk 查询或五个 bulk 变更，更早版本每类只能一个；查询状态 2026-01 起用 bulkOperation(id:)，更早版本用已弃用的 currentBulkOperation。查询；变更
7. HTTP 200 不代表成功。 官方写明许多在 REST 里是 4xx/5xx 的错误，GraphQL 用 HTTP 200 加 errors 数组返回，每条含 message 与带 code 的 extensions。变更的业务错误在 userErrors，且必须在选择集里显式请求，没请求就看不到。所以成功判据是：无顶层 errors、userErrors 为空、返回对象是预期值。GraphQL 变更基础
8. 默认只能读近 60 天订单。 access scopes 页写明，默认应用只能访问最近 60 天内创建的订单，更早需向 Shopify 申请 read_all_orders 并获批准；受保护客户数据在配置并获批准前不可访问。Access scopes
9. 令牌寿命。 access tokens 页读到：在线令牌 24 小时或员工退出 Shopify admin 时失效（取先到者）；expiring 离线令牌 expires_in 为 3600 秒，refresh token 签发时为 90 天；non-expiring 离线令牌在应用被卸载或 client secret 被撤销前有效。商家卸载或撤销 client secret 会终止令牌的全部访问。哪种方式适用于哪类应用，以官方页为准，本文未逐一核实。
10. 令牌不属于域名。 令牌属于“某应用 + 某店铺”的安装关系，多应用共用后端时必须分别存放，见共享后端。

验证一次

1. 在开发店查询 currentAppInstallation，把返回的 scope 与配置文件逐项对照，确认有无缺失或多余；
2. 用最小查询分页两次，确认使用 endCursor 后不重复不遗漏，并记录响应里的 extensions.cost；
3. 故意省略必填字段发一次变更：一次不请求 userErrors，一次请求，对比“看不到错误”与“看到错误”的差异，并核对 HTTP 状态码；
4. 固定版本发一次请求，再把版本改为已标 Unsupported 的版本，观察响应头 X-Shopify-Api-Version，确认向前落版行为；
5. 需要大批量数据时，先跑一个 bulk 查询，核对状态、JSONL 结果与 bulk_operations/finish 通知是否一致。

待继续完善

• 令牌交换与授权码流的接口细节、delegate access token、client credentials 的适用条件；
• 限流桶容量的官方数值（本文未取得）与 REST 的请求制限流细节；
• 受保护客户数据的申请路径；
• 各版本间的破坏性变更清单，需按 changelog 逐季整理。