Shopify セットアップ

ストアの Shopify CLI 認証と Admin API アクセスを機能させるようにセットアップします。商品およびコンテンツ管理に対応した、検証済みの API 接続を実現します。

ワークフロー

ステップ 1: 前提条件を確認

Shopify CLI がインストールされているか確認します:

shopify version

インストールされていない場合:

npm install -g @shopify/cli

ステップ 2: ストアで認証

shopify auth login --store mystore.myshopify.com

ブラウザで OAuth が開きます。ユーザーはストアのオーナーまたは適切な権限を持つスタッフメンバーである必要があります。

ログイン後、以下を確認します:

shopify store info

ステップ 3: API アクセス用のカスタムアプリを作成

カスタムアプリは安定した Admin API アクセストークンを提供します (有効期限が切れるような CLI セッショントークンとは異なります)。

カスタムアプリが既に存在するか確認: ユーザーがカスタムアプリを既にセットアップしているか確認してください。はいの場合は、ステップ 4 をスキップします。

カスタムアプリが存在しない場合, ブラウザでの作成をユーザーに案内します:

1. https://{store}.myshopify.com/admin/settings/apps/development にアクセス
2. Create an app をクリック
3. 名前を付ける (例: "Claude Code Integration")
4. Configure Admin API scopes をクリック
5. 以下のスコープを有効化 (詳細は references/api-scopes.md 参照):
   • read_products, write_products
   • read_content, write_content
   • read_product_listings
   • read_inventory, write_inventory
   • read_files, write_files
6. Save をクリックしてから Install app をクリック
7. Admin API access token をコピー (1 回限りの表示)

ユーザーが admin ナビゲートをサポートしてほしい場合は、ブラウザ自動化 (Chrome MCP または playwright-cli) を使用します。

ステップ 4: アクセストークンを保存

トークンは安全に保存してください。git にコミットしないでください。

プロジェクト使用の場合 — .dev.vars を作成:

SHOPIFY_STORE=mystore.myshopify.com
SHOPIFY_ACCESS_TOKEN=shpat_xxxxxxxxxxxxxxxxxxxxx

.dev.vars が .gitignore に含まれていることを確認してください。

複数プロジェクト使用の場合 — 任意のシークレットマネージャー (環境変数、1Password CLI など) に保存します。

ステップ 5: API アクセスを検証

シンプルな GraphQL クエリで接続をテストします:

curl -s https://{store}.myshopify.com/admin/api/2025-01/graphql.json \
  -H "Content-Type: application/json" \
  -H "X-Shopify-Access-Token: {token}" \
  -d '{"query": "{ shop { name primaryDomain { url } } }"}' | jq .

予想される応答にはストア名とドメインが含まれます。401 エラーが発生した場合、トークンが無効または有効期限が切れています。アプリを再作成してください。

ステップ 6: ストア設定を保存

他のスキルが参照できるように、プロジェクトルートに shopify.config.json を作成します:

{
  "store": "mystore.myshopify.com",
  "apiVersion": "2025-01",
  "tokenSource": ".dev.vars"
}

---

重要なパターン

API バージョン

常に明示的な API バージョンを指定します (例: 2025-01)。本番環境で unstable を使用すると予告なく破損します。Shopify は API バージョンを四半期ごとに廃止します。

トークンの種類

トークン	フォーマット	用途
Admin API アクセストークン	shpat_*	カスタムアプリ — 安定、長期有効
CLI セッショントークン	短期有効	Shopify CLI コマンドのみ
Storefront API トークン	shpca_*	パブリック ストアフロント クエリ

このスキルは Admin API アクセストークン をセットアップします。これは商品とコンテンツ管理に最適な選択肢です。

レート制限

Shopify はリーキーバケット レート リミッターを使用します:

• REST: 40 リクエスト/秒 バースト、2/秒 サステイン
• GraphQL: 1 秒あたり 1,000 コストポイント、クエリあたり最大 2,000 ポイント

バルク操作では、ループの代わりに bulkOperationRunQuery ミューテーションを使用します。

---

参考ファイル

• references/api-scopes.md — 商品およびコンテンツ管理に必要な Admin API スコープ