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 ミューテーション
6～20 製品	バッチ処理を使用した GraphQL
20 製品以上	管理画面から CSV をインポート
既存製品の更新	GraphQL ミューテーション
在庫調整	inventorySetQuantities ミューテーション

---

ステップ 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	1 番目のオプション名	Size
Option1 Value	1 番目のオプション値	Medium
Option2 Name	2 番目のオプション名	Colour
Option2 Value	2 番目のオプション値	Black
Option3 Name	3 番目のオプション名	Material
Option3 Value	3 番目のオプション値	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 です
• ハンドルは商品ごとに一意である必要があります。同じハンドルがある場合、既存の商品が更新されます
• 変更されないフィールドは、バリエーション行のバリエーション列を空欄にしてください
• 画像はどの行に記載してもかまいません。ハンドルで関連付けられます
• Published = TRUE にすると、商品がすぐに公開されます

インポート手順

1. 上記の列形式を使って CSV を生成します
2. 利用可能な場合は、assets/product-csv-template.csv のテンプレートを使います
3. https://{store}.myshopify.com/admin/products/import に移動します
4. CSV ファイルをアップロードします
5. プレビューを確認し、インポートを確定します

必要に応じて、ブラウザー自動化を使ってアップロードを補助してください。

---

Step 4：商品画像をアップロードする

画像のアップロードには、ステージングアップロードしてから添付する 2 段階の処理が必要です。

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" }
  ]
}

---

Step 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 }
    }
  }
}

---

Step 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 }
    }
  }
}

---

Step 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 つのオプション（例：サイズ、色、素材）を設定できます。それ以上必要な場合は、商品を分けてください。

価格の形式

価格は数値ではなく文字列です。必ず引用符で囲んでください。例："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 }
  }
}

この操作では、1 行につき 1 商品を記載した JSONL ファイルを受け付け、非同期で処理します。

---

アセットファイル

• assets/product-csv-template.csv -- Shopify のインポート用ヘッダーが含まれる空の CSV テンプレート