Shopify 开发者文档实操：版本、权限与最小商品查询

Shopify 开发者文档的学习可以从一次最小请求开始：在已授权的测试应用中确认商品读取权限，再取得最多两条商品的标识、标题和状态，并解释成功、空结果与错误的差别。本篇的交付物是同一请求的版本、权限和响应记录，供开发者检查自己是否真正用对了参考文档。

本练习需要一个已安装并完成授权的测试应用，以及可访问的测试店铺。请求示例依据 2026 年 10 月 4 日核对的官方 schema 拟定，未连接店铺执行；返回条数、标题和错误必须由执行者记录。示例不会创建或修改商品。

先选 API 与版本，再读资源页

在 shopify.dev 的 API references 中选择 GraphQL Admin API。本例读取商家后台商品；不要把 Storefront API 的顾客端字段和凭证复制进来。两类 API 的认证方式不同，Admin API 请求使用 X-Shopify-Access-Token，见API 认证说明。

在参考页的 Choose a version 中选择要验收的受支持稳定版本，把版本同时写入请求配置。本次复核时，官方版本时间表将 2026-10 标为最新稳定版本，因此下面用它举例。复用时重新核对支持状态，不把 latest、release candidate 或 unstable 当成固定的生产版本。

1. 打开 products 查询页，在版本选择器确认 2026-10，查 Arguments 中的 first 和返回的 ProductConnection。本例的 first: 2 只取一个小样本，不是完整商品导出。
2. 顺着返回类型读 nodes 与 Product 对象。本次版本中，id 是 ID!，title 是 String!，status 是 ProductStatus!；同时记下资源页要求的 read_products。
3. 把页面 URL、页面显示版本、所选字段与类型、权限要求和复核日期写在请求旁。链接到 latest 的页面会随最新版本变化；后来打开链接时仍要把版本选择器切回本次请求版本，或明确开始新的升级测试。

用当前应用查已授予权限

配置里声明过 scope，不等于这个店铺已经授予。只读练习通常需要 read_products；如果当前应用已经具有 write_products，其读取能力也覆盖商品，不必为了示例再申请写权限。权限继承与声明、授权之间的区别见访问范围管理。

用待验收应用的凭证运行下面的查询。currentAppInstallation返回当前认证应用的安装信息；accessScopes 是实际授予列表，不是配置文件的复制件。

query DocumentScopes {
  currentAppInstallation {
    accessScopes {
      handle
    }
  }
}

记录实际返回的 handle。缺少所需读取能力时，先按应用类型修正配置和授权：CLI 应用在配置 TOML 的 [access_scopes] 中声明并部署；Dev Dashboard 创建的应用在应用版本中配置并发布；自行实现授权码流程的应用更新授权请求。范围必须获店铺批准后才能使用；组织内应用与商家安装应用的批准流程有差别。具体分支见scope 配置与更新步骤。完成后再查授予列表，不能用“已经部署”替代权限证据。

已有 Shopify CLI 测试项目时，运行应用的开发命令 shopify app dev，按 g 打开本地 GraphiQL；它以你的应用连接店铺，使用同一组 scope。官方GraphiQL 探索指南也列出单独安装的 GraphiQL 应用和演示环境。演示数据或另一款 GraphiQL 应用能查到商品，不能证明待验收应用获得了权限。

提交最小商品查询并保留完整响应

在编辑器中逐项对应参考页，使用下面的命名操作。先检查拼写、括号和字段是否存在，再提交。

query DocumentProducts {
  products(first: 2) {
    nodes {
      id
      title
      status
    }
  }
}

以已授权应用的服务端 API 客户端发出请求时，使用下面的 HTTP 结构。替换测试店铺域名和凭证；凭证不要写入公开教程、浏览器页面或交接截图。endpoint 与 JSON 格式见products 的请求示例，认证头见Admin API 认证。

POST https://YOUR-TEST-STORE.myshopify.com/admin/api/2026-10/graphql.json
Content-Type: application/json
X-Shopify-Access-Token: YOUR-AUTHORIZED-APP-TOKEN

{
  "query": "query DocumentProducts { products(first: 2) { nodes { id title status } } }"
}

DocumentScopes 也通过同一 endpoint 和认证头提交，把 JSON 的 query 值换成对应查询即可。记录客户端实际发出的 URL、操作名、请求时间，以及响应的 HTTP 状态、X-Shopify-API-Version 头和完整 JSON；这些记录不包含 token。如果使用的 GraphiQL 视图没有展示响应头，就用待验收应用的 API 客户端补做同一请求，不能靠编辑器的页面标题证明服务器执行版本。

Shopify 的版本说明要求以响应头确认实际版本；访问已不可用的版本可能被服务端自动转到仍可访问的稳定版本。响应与错误说明指出，GraphQL 在 HTTP 200 中也可能返回操作错误。空数组、部分数据和顶层错误要分别记录。

让错误处理也有一次可观察的练习

在测试副本里故意把 title 改成不存在的 notAProductField。先观察编辑器的 schema 校验；如由测试客户端发送，则保存实际返回的错误结构。预期这条错误查询不能被计为成功读取。记录 message，以及响应实际提供的 path 和 extensions.code，再恢复 title 重跑正确查询。以实际响应为准，不要求每个错误都同时提供这几个字段。

遇到 ACCESS_DENIED 时，重新检查当前凭证所属应用和实际授予 scope；权限看似齐全仍失败时，再核对在线 token 对应用户的权限与资源页附加条件。遇到 HTTP 401 时先查认证，不靠重复请求修复凭证。若返回 THROTTLED，记录限制状态并采用官方支持的节流处理，不在此练习中循环发送。以上分类分别见scope 故障表和响应错误说明。

升级时重跑同一请求

每次更换版本，先阅读目标版本的 release notes、资源页弃用提示和 developer changelog，再在测试环境重跑权限查询、正确商品查询及错误处理练习。比较字段、类型、响应头和实际结果，把受影响代码、负责人、测试记录和上线条件写清楚。GraphiQL 的弃用警告及 Dev Dashboard 的应用提醒也是复核线索，见版本与弃用治理说明。

本次验收完成的条件是：选定资源和版本、实际 scope 有证据、正确查询及错误查询均能解释、真实执行版本已确认。它证明这一个只读请求可以被维护；完整数据同步、写操作和生产部署还需要各自的验收范围。

常见问题

GraphiQL 示例能运行，为什么应用仍然提示无权限？

先确认 GraphiQL 是否以待验收应用连接，而不是演示数据或单独安装的 GraphiQL 应用。再用该应用查 currentAppInstallation.accessScopes，并检查当前用户权限。不同探索环境的范围差异见GraphiQL 使用说明。

请求版本已写在 URL 中，还需要记录响应头吗？

需要。版本文档说明，X-Shopify-API-Version 表示实际处理请求的版本。请求过期而被自动转到其他版本时，只保留 URL 无法证明代码按预定 schema 执行。