shopify-products

Shopify 产品

创建、更新并批量导入 Shopify 产品。通过 GraphQL Admin API 或 CSV 导入，在商店中创建实时产品。

前置条件

• Admin API 访问令牌（如果尚未配置，请使用 shopify-setup 技能）
• shopify.config.json 或 .dev.vars 中的商店 URL 和 API 版本

工作流

步骤 1：收集产品数据

确定用户想要创建或更新的内容：

• 产品基本信息：标题、描述（HTML）、产品类型、供应商、标签
• 变体：选项（尺码、颜色、材质）、价格、SKU、库存数量
• 图片：要上传的 URL 或本地文件
• SEO：页面标题、元描述、URL 句柄
• 组织信息：产品系列、产品类型、标签

接受以下来源的数据：

• 直接对话（用户描述产品）
• 电子表格/CSV 文件（用户提供文件）
• 网站抓取（用户提供要提取内容的 URL）

步骤 2：选择方法

场景	方法
1-5 个产品	GraphQL mutations
6-20 个产品	使用批处理的 GraphQL
20 个以上产品	通过管理后台导入 CSV
更新现有产品	GraphQL mutations
库存调整	inventorySetQuantities mutation

---

步骤 3a：通过 GraphQL 创建（推荐）

productCreate

mutation productCreate($product: ProductCreateInput!) {
  productCreate(product: $product) {
    product {
      id
      title
      handle
      status
      variants(first: 100) {
        edges {
          node { id title price sku inventoryQuantity }
        }
      }
    }
    userErrors { field message }
  }
}

变量：

{
  "product": {
    "title": "Example T-Shirt",
    "descriptionHtml": "<p>Premium cotton tee</p>",
    "vendor": "My Brand",
    "productType": "T-Shirts",
    "tags": ["summer", "cotton"],
    "status": "DRAFT",
    "options": ["Size", "Colour"],
    "variants": [
      {
        "optionValues": [
          {"optionName": "Size", "name": "S"},
          {"optionName": "Colour", "name": "Black"}
        ],
        "price": "29.95",
        "sku": "TSHIRT-S-BLK",
        "inventoryPolicy": "DENY",
        "inventoryItem": { "tracked": true }
      },
      {
        "optionValues": [
          {"optionName": "Size", "name": "M"},
          {"optionName": "Colour", "name": "Black"}
        ],
        "price": "29.95",
        "sku": "TSHIRT-M-BLK"
      },
      {
        "optionValues": [
          {"optionName": "Size", "name": "L"},
          {"optionName": "Colour", "name": "Black"}
        ],
        "price": "29.95",
        "sku": "TSHIRT-L-BLK"
      }
    ],
    "seo": {
      "title": "Example T-Shirt | My Brand",
      "description": "Premium cotton tee in multiple sizes"
    }
  }
}

Curl 示例：

curl -s https://{store}/admin/api/2025-01/graphql.json \
  -H "Content-Type: application/json" \
  -H "X-Shopify-Access-Token: {token}" \
  -d '{"query": "mutation productCreate($product: ProductCreateInput!) { productCreate(product: $product) { product { id title } userErrors { field message } } }", "variables": { ... }}'

批量创建多个产品：依次创建产品，并在每次创建之间短暂延迟，以遵守速率限制（每秒 1,000 个成本点）。

productUpdate

mutation productUpdate($input: ProductInput!) {
  productUpdate(input: $input) {
    product { id title }
    userErrors { field message }
  }
}

变量包括 id（必填）以及要更新的任意字段。

productDelete

mutation productDelete($input: ProductDeleteInput!) {
  productDelete(input: $input) {
    deletedProductId
    userErrors { field message }
  }
}

productVariantsBulkCreate

向现有产品添加变体：

mutation productVariantsBulkCreate($productId: ID!, $variants: [ProductVariantsBulkInput!]!) {
  productVariantsBulkCreate(productId: $productId, variants: $variants) {
    productVariants { id title price }
    userErrors { field message }
  }
}

productVariantsBulkUpdate

mutation productVariantsBulkUpdate($productId: ID!, $variants: [ProductVariantsBulkInput!]!) {
  productVariantsBulkUpdate(productId: $productId, variants: $variants) {
    productVariants { id title price }
    userErrors { field message }
  }
}

---

步骤 3b：通过 CSV 批量导入

对于 20 个以上的产品，生成 CSV 并通过 Shopify 管理后台导入。

CSV 列参考

必填列：

列	描述	示例
Handle	URL 别名（每个产品唯一）	classic-tshirt
Title	产品名称（每个产品的第一行）	Classic T-Shirt
Body (HTML)	HTML 格式的描述	<p>Premium cotton</p>
Vendor	品牌或制造商	My Brand
Product Category	Shopify 标准分类体系	Apparel & Accessories > Clothing > Shirts & Tops
Type	自定义产品类型	T-Shirts
Tags	以逗号分隔的标签	summer, cotton, casual
Published	产品是否可见	TRUE 或 FALSE

变体列：

列	描述	示例
Option1 Name	第一个选项名称	Size
Option1 Value	第一个选项值	Medium
Option2 Name	第二个选项名称	Colour
Option2 Value	第二个选项值	Black
Option3 Name	第三个选项名称	Material
Option3 Value	第三个选项值	Cotton
Variant SKU	库存单位	TSHIRT-M-BLK
Variant Grams	重量（克）	200
Variant Inventory Qty	库存数量	50
Variant Price	变体价格	29.95
Variant Compare At Price	原价（用于促销）	39.95
Variant Requires Shipping	是否为实体产品	TRUE
Variant Taxable	是否需要缴税	TRUE

图片列：

列	描述	示例
Image Src	图片 URL	https://example.com/img.jpg
Image Position	显示顺序（从 1 开始）	1
Image Alt Text	无障碍替代文本	Classic T-Shirt front view

SEO 列：

列	描述	示例
SEO Title	页面标题标签	`Classic T-Shirt
SEO Description	元描述	Premium cotton tee in 5 colours

多变体行格式

第一行包含产品标题和详细信息。同一产品的后续行仅包含 Handle 和变体专属列：

Handle,Title,Body (HTML),Vendor,Type,Tags,Published,Option1 Name,Option1 Value,Variant SKU,Variant Price,Variant Inventory Qty,Image Src
classic-tshirt,Classic T-Shirt,<p>Premium cotton</p>,My Brand,T-Shirts,"summer,cotton",TRUE,Size,Small,TSH-S,29.95,50,https://example.com/tshirt.jpg
classic-tshirt,,,,,,,,Medium,TSH-M,29.95,75,
classic-tshirt,,,,,,,,Large,TSH-L,29.95,60,

CSV 规则

• 必须使用 UTF-8 编码
• 文件大小上限为 50MB
• 每个产品的 Handle 必须唯一——重复的 Handle 会更新现有产品
• 对于不变的字段，在变体行中将对应列留空
• 图片可以放在任意行——系统会根据 Handle 将图片关联起来
• Published = TRUE 会使产品立即可见

导入步骤

1. 按照上述列格式生成 CSV
2. 如有模板，请使用 assets/product-csv-template.csv
3. 前往 https://{store}.myshopify.com/admin/products/import
4. 上传 CSV 文件
5. 检查预览并确认导入

如有需要，可使用浏览器自动化辅助上传。

---

第 4 步：上传产品图片

图片上传需要两个步骤——先暂存，再附加。

stagedUploadsCreate

mutation stagedUploadsCreate($input: [StagedUploadInput!]!) {
  stagedUploadsCreate(input: $input) {
    stagedTargets {
      url
      resourceUrl
      parameters { name value }
    }
    userErrors { field message }
  }
}

每个文件的输入：

{
  "filename": "product-image.jpg",
  "mimeType": "image/jpeg",
  "httpMethod": "POST",
  "resource": "IMAGE"
}

然后上传到暂存 URL，并使用 productCreateMedia 附加：

productCreateMedia

mutation productCreateMedia($productId: ID!, $media: [CreateMediaInput!]!) {
  productCreateMedia(productId: $productId, media: $media) {
    media { alt status }
    mediaUserErrors { field message }
  }
}

快捷方式：如果图片已托管在公开 URL 上，可在创建产品时直接传入 src：

{
  "images": [
    { "src": "https://example.com/image.jpg", "alt": "Product front view" }
  ]
}

---

第 5 步：分配到系列

collectionAddProducts

mutation collectionAddProducts($id: ID!, $productIds: [ID!]!) {
  collectionAddProducts(id: $id, productIds: $productIds) {
    collection { title productsCount }
    userErrors { field message }
  }
}

查找系列 ID：

{
  collections(first: 50) {
    edges {
      node { id title handle productsCount }
    }
  }
}

---

第 6 步：设置库存

inventorySetQuantities

mutation inventorySetQuantities($input: InventorySetQuantitiesInput!) {
  inventorySetQuantities(input: $input) {
    inventoryAdjustmentGroup { reason }
    userErrors { field message }
  }
}

输入：

{
  "reason": "correction",
  "name": "available",
  "quantities": [{
    "inventoryItemId": "gid://shopify/InventoryItem/123",
    "locationId": "gid://shopify/Location/456",
    "quantity": 50
  }]
}

查找位置 ID：

{
  locations(first: 10) {
    edges {
      node { id name isActive }
    }
  }
}

---

第 7 步：验证

查询已创建的产品以确认：

{
  products(first: 50) {
    edges {
      node {
        id title handle status productType vendor
        variants(first: 10) {
          edges { node { id title price sku inventoryQuantity } }
        }
        images(first: 3) { edges { node { url altText } } }
      }
    }
    pageInfo { hasNextPage endCursor }
  }
}

提供管理后台 URL，供用户查看：https://{store}.myshopify.com/admin/products

---

关键模式

产品状态

新产品的默认状态为 DRAFT。要使其可见：

{ "status": "ACTIVE" }

将状态设为 ACTIVE 前，务必先向用户确认。

变体数量限制

Shopify 每个产品最多允许 100 个变体和 3 个选项（例如 Size、Colour、Material）。如果需要更多，请拆分成多个产品。

价格格式

价格是字符串，而不是数字。务必加上引号："price": "29.95"，而不是 "price": 29.95。

HTML 描述

产品描述支持 HTML。保持简单——Shopify 编辑器可以处理基本标签：

• <p>、<strong>、<em>、<ul>、<ol>、<li>、<h2>-<h6>
• 用于链接的 <a href="...">
• <img> 会被移除——请改用产品图片

大批量导入操作

通过 API 导入 50 个或更多产品时，请使用 Shopify 的批量操作：

mutation {
  bulkOperationRunMutation(
    mutation: "mutation ($input: ProductInput!) { productCreate(input: $input) { product { id } userErrors { message } } }"
    stagedUploadPath: "tmp/bulk-products.jsonl"
  ) {
    bulkOperation { id status }
    userErrors { message }
  }
}

此操作接受一个 JSONL 文件，每行包含一个产品，并以异步方式处理。

---

资源文件

• assets/product-csv-template.csv -- 包含 Shopify 导入表头的空白 CSV 模板