# Shopify GraphQL API ## 什么时候使用这个技能在以下情况下使用此技能： * 查询Shopify数据（产品、订单、客户） * 通过突变创建或更新资源 * 与 Shopify 商店建立集成 * 使用元字段和元对象 * 处理 API 响应中的分页 * 管理API身份验证和速率限制 ## API 类型 ### 管理API * 完整的商店访问权限（仅限后端） * 需要身份验证（OAuth 或 API 密钥） * 由应用程序和集成使用 ### 店面 API * 公共店面访问 * 使用公共访问令牌 * 前端/客户端安全 ## 开始使用 ### 管理 API 身份验证 // 使用@shopify/shopify-api 从“@shopify/shopify-api”导入{shopifyApi，LATEST_API_VERSION}； const shopify = shopifyApi({ apiKey: process.env.SHOPIFY_API_KEY, apiSecretKey：process.env.SHOPIFY_API_SECRET，范围：[“read_products”，“write_products”]，主机名：“your-app.com”， api版本：LATEST_API_VERSION， }); ### 提出请求 // 在 Remix 应用程序路径中从“../shopify.server”导入{验证}；导出异步函数加载器({ request }) { const { admin } = 等待authenticate.admin(请求); const 响应 = 等待 admin.graphql(` 查询{ 产品（第一：10）{ 节点{ 编号标题 } } } `); 返回response.json(); } ## 常见查询 ### 产品 # 获取具有变体的产品查询 GetProducts($first: Int!, $after: String) { 产品（第一：$第一，之后：$之后）{ 页面信息{ 有下一页结束光标 } 节点{ 编号标题手柄描述状态供应商产品类型标签精选图片{ 网址替代文本 } 变体（第一个：10）{ 节点{ 编号标题存货单元价格比较价格库存数量选定的选项 { 姓名值 } } } 价格范围{ 最小变量价格 { 金额货币代码 } 最大变量价格 { 金额货币代码 } } } } } # 根据ID获取单品查询 GetProduct($id: ID!) { 产品（id：$id）{ 编号标题描述变体（第一个：100）{ 节点{ 编号标题价格 } } } } # 通过句柄获取产品查询 GetProductByHandle($handle: String!) { 产品ByHandle（句柄：$句柄）{ 编号标题 } } ### 订单查询 GetOrders($first: Int!, $query: String) { 订单（第一个：$first，查询：$query）{ 节点{ 编号姓名电子邮件创建于显示财务状况显示履行状态总价格集 { 商店钱{ 金额货币代码 } } 客户{ 编号名字姓氏电子邮件 } 行项目（第一个：50）{ 节点{ 编号标题数量变体{ 编号存货单元 } 原始总计集 { 商店钱{ 金额 } } } } 送货地址{ 地址1 城市省份国家邮编 } } } } ### 客户查询 GetCustomers($first: Int!, $query: String) { 客户（第一个：$first，查询：$query）{ 节点{ 编号名字姓氏电子邮件电话订单数总花费{ 金额货币代码 } 地址（第一个：5）{ 地址1 城市省份国家邮编 } 标签创建于 } } } ### 收藏查询 GetCollection($handle: String!) { collectionByHandle（句柄：$句柄）{ 编号标题描述产品（第一：20）{ 节点{ 编号标题精选图片{ 网址 } } } } } ### 库存查询 GetInventory($locationId: ID!) { 位置（id：$locationId）{ 库存水平（第一：100）{ 节点{ 编号可用项目{ 编号变体{ 编号显示名称存货单元 } } } } } } ## 常见突变 ### 创建产品突变 CreateProduct($input: ProductInput!) { 产品创建（输入：$输入）{ 产品{ 编号标题手柄 } 用户错误{ 领域留言 } } } 变量： { “输入”：{ "title": "新产品", "descriptionHtml": "

产品描述

", "vendor": "我的商店", “产品类型”：“服装”， "tags": ["新", "精选"], “变体”：[ { “价格”：“29.99”， “sku”：“NEW-001”， "库存管理": "SHOPIFY", “库存政策”：“拒绝” } ] } } ### 更新产品突变 UpdateProduct($input: ProductInput!) { 产品更新（输入：$输入）{ 产品{ 编号标题 } 用户错误{ 领域留言 } } } 变量： { “输入”：{ "id": "gid://shopify/Product/123456", "title": "更新后的标题", "tags": ["促销", "精选"] } } ### 创建订单突变 CreateDraftOrder($input: DraftOrderInput!) { DraftOrderCreate（输入：$输入）{ 草稿订单 { 编号发票网址 } 用户错误{ 领域留言 } } } ### 更新库存突变AdjustInventory($input: InventoryAdjustQuantityInput!) { 库存调整数量（输入：$输入）{ 库存水平{ 可用 } 用户错误{ 领域留言 } } } 变量： { “输入”：{ "inventoryLevelId": "gid://shopify/InventoryLevel/123456", “可用增量”：10 } } ## 元字段 ### 读取元字段 # 产品元字段查询 GetProductMetafields($id: ID!) { 产品（id：$id）{ 元字段（第一个：20）{ 节点{ 编号名称空间钥匙值类型 } } # 特定元字段 careInstructions：元字段（命名空间：“自定义”，键：“care_instructions”）{ 值 } } } ### 写入元字段突变 SetMetafields($metafields: [MetafieldsSetInput!]!) { 元字段集（元字段：$元字段）{ 元字段 { 编号钥匙值 } 用户错误{ 领域留言 } } } 变量： { “元字段”：[ { "ownerId": "gid://shopify/Product/123456", “命名空间”：“自定义”， "key": "护理说明", "value": "冷水机洗", “类型”：“单行文本字段” }, { "ownerId": "gid://shopify/Product/123456", “命名空间”：“自定义”， “关键”：“尺寸”， "值": "{\"宽度\": 10, \"高度\": 20, \"深度\": 5}", “类型”：“json” } ] } ### 元字段类型类型 |描述 |示例值 ---|---|--- `单行文本字段` |短文| ``你好'` `多行文本字段` |长文| `“第 1 行\n第 2 行”` `number_integer` |整数 | `“42”` `数字小数` |十进制| `“19.99”` `布尔值` |对/错 | `“真实”` `日期` |日期 | `“2025-01-15”` `json` | JSON 对象 | `"{\"键\": \"值\"}"` `网址` |网址 | `“https://example.com”` `颜色` |颜色六角| `“#FF0000”` ## 分页 ### 基于光标的分页异步函数 getAllProducts(admin) { 让产品= []；让 hasNextPage = true; 让光标=空； while (有下一页) { const 响应 = 等待 admin.graphql( ` 查询 GetProducts($first: Int!, $after: String) { 产品（第一：$第一，之后：$之后）{ 页面信息{ 有下一页结束光标 } 节点{ 编号标题 } } } `, { 变量：{ 第一个：50，之后：光标 }， }, ）； const data =等待response.json(); 产品= [...产品，...data.data.products.nodes]； hasNextPage = data.data.products.pageInfo.hasNextPage; 光标 = data.data.products.pageInfo.endCursor; } 退回产品； } ## 速率限制 ### 了解成本查询{ 产品（第一：100）{ 节点{ 编号标题 } } } 回应包括： { “扩展”：{ “成本”：{ “请求的查询成本”：102， “实际查询成本”：52， “油门状态”：{ “最大可用”：2000， “当前可用”：1948， “恢复率”：100 } } } } ### 处理率限制异步函数 queryWithRetry(admin, 查询, 变量, maxRetries = 3) { for (让尝试 = 0;尝试 < maxRetries;尝试++) { 尝试{ const 响应 = 等待 admin.graphql(查询, { 变量 }); const data =等待response.json(); if (data.errors?.some((e) => e.extensions?.code === "THROTTLED")) { const waitTime = Math.pow(2, 尝试) * 1000; 等待新的 Promise((resolve) => setTimeout(resolve, waitTime)); 继续; } 返回数据； } 捕获（错误）{ if (attempt === maxRetries - 1) 抛出错误； } } } ## 店面API ### 身份验证 const storefrontClient = new StorefrontApiClient({ privateAccessToken：process.env.STOREFRONT_ACCESS_TOKEN， storeDomain：“your-store.myshopify.com”， api版本: "2025-01", }); ### 产品查询（店面）查询 GetProduct($handle: String!) { 产品（句柄：$句柄）{ 编号标题描述图片（第一张：5）{ 节点{ 网址替代文本 } } 变体（第一个：100）{ 节点{ 编号标题价格{ 金额货币代码 } 可供出售 } } } } ### 购物车操作（店面） # 创建购物车突变 CreateCart($lines: [CartLineInput!]!) { cartCreate(输入：{ 行数：$lines }) { 购物车{ 编号结帐网址行（第一行：10）{ 节点{ 编号数量商品{ ...在 ProductVariant { 标题 } } } } } } } # 添加到购物车突变 AddToCart($cartId: ID!, $lines: [CartLineInput!]!) { cartLinesAdd(cartId: $cartId,lines: $lines) { 购物车{ 编号行（第一行：10）{ 节点{ 编号数量 } } } } } ## 网络钩子 ### 订阅 Webhooks 突变 WebhookSubscriptionCreate( $topic：WebhookSubscriptionTopic！ $webhookSubscription：WebhookSubscriptionInput！）{ webhook订阅创建( 主题：$主题 webhook订阅：$webhook订阅）{ webhook订阅 { 编号主题端点{ ...在 WebhookHttpEndpoint { 回调地址 } } } 用户错误{ 领域留言 } } } 变量： { “主题”：“产品_创建”， “webhook订阅”：{ "callbackUrl": "https://your-app.com/webhooks", “格式”：“JSON” } } ### Webhook 主题主题 |描述 ---|--- `产品_创建` |产品已创建 `产品更新` |产品更新 `产品_删除` |产品已删除 `订单创建` |已下订单 `ORDERS_UPDATED` |订单修改 `订单已支付` |订单已付款 `CUSTOMERS_CREATE` |客户创建 `库存水平更新` |库存发生变化 ## 批量操作 ### 批量查询突变散装产品{ 批量操作运行查询（查询：“”” { 产品{ 边缘{ 节点{ 编号标题变体{ 边缘{ 节点{ 编号存货单元价格 } } } } } } } ”“” ）{ 批量操作{ 编号状态 } 用户错误{ 领域留言 } } } ### 轮询批量操作查询批量操作状态{ 当前批量操作{ 编号状态对象计数网址 } } ## 最佳实践 1. **仅请求所需的字段** \- 降低成本和响应大小 2. **使用片段** \- 重用公共字段选择 3. **处理错误** \- 检查突变中的 userErrors 4. **实现分页** \- 不要一次请求所有记录 5. **监控速率限制** \- 在响应中使用限制状态 6. **使用批量操作** \- 用于大数据导出 ## 资源 * [管理 API 参考]() * [店面 API 参考]() * [GraphQL 基础知识]() * [速率限制]() * [Webhooks 参考]() * [GraphiQL 浏览器]() 有关应用程序集成，请参阅 [app-development]() 技能。

API Graphql

包含技能