shopify-category-taxonomy

Shopify カテゴリタクソノミー

連続して行う2つの作業です。まず商品の Standard Product Taxonomy カテゴリを割り当て（パート1）、次に、そのカテゴリで公開されるカテゴリメタフィールドを入力します（パート2）。パート1が完了するまで、パート2には進めません。商品をカテゴリに割り当てると初めて、「Category metafields」パネルが表示されるためです。CSVによる一括データ処理には、関連プロジェクトの shopify-matrixify を使用します。Matrixifyでできないのは、パート2で必要な予約値のメタオブジェクトを作成することだけです。それが、このスキルが存在する理由です。

ストアへのアクセス

レーンA：カスタムアプリのトークン（スクリプトで実行可能）。 Shopify admin → Settings → Apps and sales channels → Develop apps → アプリを作成 → 以下の4つのスコープを付与 → インストール → Admin API access token をコピーします。環境変数に設定し、ディスクには書き込まないでください。

export SHOPIFY_STORE="your-store.myshopify.com"
export SHOPIFY_ACCESS_TOKEN="<your Admin API access token>"   # env, not disk
curl -s "https://$SHOPIFY_STORE/admin/api/2025-07/graphql.json" \
  -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" -d '{"query":"{ shop { name } }"}'

必要な最小スコープ：read_products、write_products、read_metaobjects、write_metaobjects。 メタオブジェクトの2つのスコープは必須です（null の落とし穴を参照）。

レーンB：Shopify CLI の OAuth（トークンを保存しない方式）。 shopify store auth --store $SHOPIFY_STORE --scopes read_products,write_products,read_metaobjects,write_metaobjects を実行してから、shopify store execute を実行します。ストアオーナーが対話形式でログインする、トークンレスのストアに適しています。

ツールキットの事前確認。 レーンBは Shopify CLI を使用します。まず shopify version を実行し、未インストールの場合はインストールしてください。Admin GraphQL スキーマ全体と検証済みの実行を利用するには、このスキルを Shopify 公式の AI ツールキットプラグインと組み合わせてください。Claude Code では claude plugin list を確認し、表示されない場合は次を実行します。

claude plugin marketplace add Shopify/Shopify-AI-Toolkit
claude plugin install shopify-plugin@shopify-ai-toolkit

推奨ですが、必須ではありません。レーンAでは curl とトークンだけが必要です。ツールキットはエージェントに API を提供し、このスキルは手順を提供します。

スクリプトではなくレシピ

すべての GraphQL ブロックは、エージェントが新たに作成して実行し、その後破棄する、コピーして応用するためのレシピとして扱ってください。安全を保つため、次の2つのルールに従ってください。

1. 変更前にプレビューする。 書き込みの前に、対象カテゴリの商品数を読み取り専用で集計し、妥当性を確認してください。想定を大幅に超える場合は、作業を止めて対象範囲を見直してください。
2. デフォルトでは非破壊的に処理する。 未入力の値のみを補完してください。metafieldsSet の空値はメタフィールドを削除するため、空でない値のみを出力してください。最初のバッチで userErrors が発生したら、実行を中止してください。

ストアフロントではなく Admin API を使って、実際のデータと照合してください（CDN キャッシュにより、最新の状態が反映されないことがあります）。トークンを表示したり、コミットしたりしないでください。

パート1：カテゴリを割り当てる

productUpdate（または一括読み込みの場合は Matrixify の Category 列）を使って、各商品の category フィールドに Standard Product Taxonomy のカテゴリを設定します。

重要：すべてのカテゴリ ID を公式タクソノミーソースで確認してください。IDを推測してはいけません。 推測したタクソノミー ID は、誤ったカテゴリや削除済みのノードに解決されますが、エラーは表面化しません。商品はカテゴリに分類されたように見えても、下流の属性、フィルター、フィードのマッピングがすべて誤った状態になります。推測した ID によって、実際の商品フィードに問題が起きた例もあります。taxonomy { categories } に対する search: で ID を特定するか（クエリはパート2の手順1を参照）、Provenance にリンクされている公式タクソノミーリポジトリで確認してください。

分類に使う情報の優先順位（確信度の高い順）： タグ（カテゴリ別にタグ付けしているストアでは最も有力です。「Mango」ティーに black-tea タグが付いていれば、果物のインフュージョンではなくフレーバー付きのブラックティーです。商品名から誤解しやすい場合も、タグが示しています）> 商品タイプ（ストアで入力されていれば有用ですが、入力していないストアも多くあります）> 商品名／販売元（語句から判断する代替手段です。単一ラインの販売元ならカテゴリを特定できますが、複数ラインを扱う販売元では特定できません）> 説明（最後の手段です。冗長で、フレーバーの語句に引きずられて誤分類しやすいためです）。

商品ごとに確信度フラグを付け、カタログを確信度の高いものと、判断が曖昧なもの（バンドル、サンプラー、複数カテゴリにまたがる商品）に分けてください。確信度の高い商品は処理し、判断が曖昧な商品は推測せず、人による確認用シートに回してください。以下の SOP の「取得してから分類する」手順を参照してください。

# preview (read-only): how many products your classifier targets, before any write
query { productsCount(query: "tag:black-tea status:active") { count } }

# then, per high-confidence product, assign the category
mutation Assign($id: ID!, $cat: ID!) {
  productUpdate(product: {id: $id, category: $cat}) {
    product { id category { id fullName } }
    userErrors { field message }
  }
}

パート 2：カテゴリメタフィールドを入力する

カテゴリメタフィールドは、単純なテキスト値や選択値ではありません。予約済みの shopify 名前空間に属する、型が list.metaobject_reference のメタフィールドであり、その値は Metaobject GID の JSON 配列です。各メタオブジェクトは、label と、グローバルな TaxonomyValue を指す taxonomy_reference を持つ、予約済みのタクソノミー値（type: "shopify--<attribute>"）です。このつながりは次のとおりです。

Product
  └─ metafield  shopify.<attribute>  (list.metaobject_reference)
       └─ value: ["gid://shopify/Metaobject/…"]
            └─ Metaobject  type: shopify--<attribute>   label: "Decaf"
                 └─ taxonomy_reference ─▶ TaxonomyValue/26137  (global)

これらの値のメタオブジェクトは必要に応じて作成されます。ストアが保持するのは、実際に使用した値のメタオブジェクトだけです。新しい値を参照するには、先に作成する必要があります。この作成してから参照する手順を Matrixify では実行できません。

特に注意すべき点トップ 5（詳しくはリファレンスを参照）：

1. null／スコープの落とし穴。 read_metaobjects がないと、値のメタオブジェクトは node()、references、metaobjectDefinitions から null を返し、機能全体が読み取り専用のように見えます。このスコープがあれば解決できます。作成には write_metaobjects が必要です。
2. 書き込み時に TaxonomyValue GID は受け付けられません。 metafieldsSet が要求するのは Metaobject GID であり、タクソノミー値の GID ではありません（そうでない場合は「Value require that you select a metaobject」と表示されます）。TaxonomyValue GID を渡すのは、メタオブジェクトの作成時に指定する taxonomy_reference としてのみです。
3. **製品はすでにそのカテゴリに属している必要があります。**そうでないと、そのメタフィールドはカテゴリメタフィールドとして表示されません。スコープの対象は product.category であり、製品タイプやタイトルではありません。
4. **GID はストアごとに異なります。**あるストアで作成したメタオブジェクトの GID は別のストアでは使えません。ストアごとに作成し直してください。
5. **Matrixify ではこれらを作成できません。**予約済みのメタオブジェクトを作成できず、値の名前も解決しません。信頼できる方法は Admin API のみです。

SOP

1. カテゴリ、その属性、許可されている値を確認します。

query {
  taxonomy {
    categories(first: 1, search: "Tea & Infusions > Tea") {
      nodes {
        id fullName
        attributes(first: 50) {
          nodes {
            ... on TaxonomyChoiceListAttribute {
              id name
              values(first: 50) { nodes { id name } }   # id = TaxonomyValue GID
            }
            ... on TaxonomyMeasurementAttribute { id name }
          }
        }
      }
    }
  }
}

属性ごとに、メタフィールドキー（属性ハンドルを小文字にしてハイフン区切りにしたもの。手順 6 で設定済みの製品を読み取り、確認します。Color 属性のキーは color ではなく color-pattern です）と、値の名前 → TaxonomyValue GID の対応表を記録します。

**2. 対象カテゴリにスコープを絞ってカタログを取得します。**分類を推測だけで行わず、まず候補となるすべての製品をページングして、分類器が読み取るシグナルを収集してください。

query($cursor: String) {
  products(first: 100, after: $cursor, query: "status:active") {
    pageInfo { hasNextPage endCursor }
    nodes {
      id handle title vendor productType tags
      category { id fullName }
      options { name optionValues { name } }
      metafields(namespace: "shopify", first: 25) { nodes { key jsonValue } }
    }
  }
}

カタログが大規模な場合は、ライブでページングする代わりに、bulkOperationRunQuery のダンプとして実行してください。このダンプは書き込み前のバックアップにもなります。

**3. 信頼度の高いものと曖昧なものに分類します。**シグナルの優先順位（まずタグ）を適用します。製品ごとに信頼度フラグを出力し、信頼度の高い行は適用します。曖昧なもの（セット商品、詰め合わせ、複数カテゴリにまたがるもの、タイトルの情報が少ないもの）は、書き込み前に人が修正するレビュー用スプレッドシートに回します。この分類により、あるお茶の小売業者は、推測で進める代わりに、717 製品のうち 583 製品を高信頼度として適用し、残り 134 製品をレビューに回すことができました。まず高信頼度の行にカテゴリ（パート 1）を割り当ててから、以下の作成と設定に進みます。

4. 不足している値のメタオブジェクトを作成します（ストアごとに 1 回）。label がすでに一致するメタオブジェクトがあれば再利用し、本当に存在しない場合にのみ作成します。

mutation M($m: MetaobjectCreateInput!) {
  metaobjectCreate(metaobject: $m) {
    metaobject { id displayName } userErrors { field message code }
  }
}
# variables:
# {"m":{"type":"shopify--caffeine-content","handle":"decaf",
#   "fields":[{"key":"label","value":"Decaf"},
#             {"key":"taxonomy_reference","value":"gid://shopify/TaxonomyValue/26137"}]}}

結果と既存のエントリーから、値の名前 → Metaobject GID の対応表を作成します。

5. metafieldsSet で適用します。1 回の呼び出しにつき、メタフィールドは最大 25 個です。

mutation S($m: [MetafieldsSetInput!]!) {
  metafieldsSet(metafields: $m) {
    metafields { id } userErrors { field message code }
  }
}
# each entry: {ownerId, namespace:"shopify", key:"tea-variety",
#   type:"list.metaobject_reference",
#   value:"[\"gid://shopify/Metaobject/…\"]"}

空白でない値のみを出力します。最初のバッチでエラーが発生したら中止してください。

6. 書き込み時の userErrors: [] を信頼するのではなく、解決後のラベルを読み取って確認します。

query { product(id: "gid://shopify/Product/…") {
  metafields(namespace: "shopify", first: 10) { nodes {
    key references(first: 5) { nodes { ... on Metaobject { displayName } } } } } } }

複数の製品を抜き取り確認し、すべての名前が意図したとおりに解決されることを確かめます。

リファレンス

• references/gotchas-and-scoping.md： 注意点 6～10（自由入力ラベル、タイプごとの作成フィールド、複数カテゴリのスコープ）、 各属性が反映される場所（Google フィード、Search & Discovery、JSON-LD）、 実数を使った 2 つの例。

出典とメンテナンス

最終確認日：2026-07-05。GraphQL は Admin API 2025-07 に固定されています。Shopify は四半期ごとのローリングスケジュールでバージョンを非推奨にするため、バージョン固有の記述を信頼する前に、shopify.dev およびメタフィールド／メタオブジェクトのドキュメントでフィールドの形式を確認してください。カテゴリ ID とタクソノミーの値は Shopify の 標準商品タクソノミー に基づいています。ID を確認する際は、必ず正規の情報源を参照してください。推測してはいけません。

第三者が実行できる読み取り専用の再確認（書き込みなし）：

# 1. token reaches the store and reads a product's assigned category
curl -s "https://$SHOPIFY_STORE/admin/api/2025-07/graphql.json" \
  -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ products(first:1){ nodes{ category { id name } } } }"}'

# 2. taxonomy discovery resolves (confirms the taxonomy API + your read scope)
curl -s "https://$SHOPIFY_STORE/admin/api/2025-07/graphql.json" \
  -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ taxonomy { categories(first:1, search:\"Tea\"){ nodes{ id fullName } } } }"}'

これらのスキルには、ドキュメントにはない運用上の知見が記されています。リファレンスの代わりにはなりません。