GraphiQL App活用：GraphQLで商品・コレクション作成

Shopify

Shopify アカデミー「Shopify Development Fundamentals」ラーニングパスで学んできたGraphQLの実装チャレンジとして、新しいコレクションの作成から、商品登録、メタフィールドの活用、ページ反映の確認までを一通り実践しました。

この記事では実装の流れとつまずきやすいポイントなど、これからShopifyアプリ開発に挑戦する方にもわかりやすく記録します。

今回実現したいこと

今回のタスクには以下の要件が含まれています：

  • 「Spring Collection」という新しいコレクションを作成する
  • コレクションに含める複数の商品を作成
  • 作成した情報が、商品ページで正しく表示されることを確認

これは単なる「データを作って終わり」ではありません。GraphQLで登録した構造化データが、実際にフロントにどう反映されるかまでを含む、Shopifyならではの実装フローとなっています。

GraphQL実装前の準備：GraphiQL Appのインストール

GraphQLを使ってShopifyのデータを操作するには、GraphiQL Appという専用の開発ツールのインストールが必要です。

これは、Shopifyが提供しているストアのデータと直接やり取りできるブラウザベースのGraphQLクライアントで、管理画面内でクエリの実行・検証ができます。

インストール方法（開発ストアで作業しています）

  1. Shopifyアプリストアにアクセスし、GraphiQL Appを検索
  2. 開発ストアにインストール
  3. 管理画面から Apps > GraphiQL App に移動し、起動

GraphiQL Appでできること

  • クエリの試行と修正：リクエストをすぐに実行してレスポンスを確認
  • ドキュメント参照機能：GraphQLスキーマに基づいて利用可能なフィールドを確認
  • Mutation・Queryの雛形作成支援：補完機能やクエリ構造のヒントが充実

本記事で紹介する実装チャレンジは、このGraphiQL Appを使ってすべてのGraphQL操作を行っています。

これからGraphQLの実装に挑戦する方は、まずはこのアプリをインストールして、開発環境を整えることから始めましょう。

GraphiQL for the Admin API
Browse Shopify’s GraphQL Admin API resources using GraphiQL.
shopify.dev

ステップ1：Spring Collectionの作成

まずはGraphQLを使って、新しいコレクション「Spring Collection」を作成します。

GraphQLのcollectionCreate mutationを使い、以下のようなクエリを送信しました。

mutation collectionCreate($input: CollectionInput!) {
  collectionCreate(input: $input) {
    collection {
      id
     	title
      handle
      descriptionHtml
    }
    userErrors {
      field
      message
    }
  }
}
{
  "input": {
    "descriptionHtml": "Embrace the essence of renewal and blooming beauty with our captivating spring collection. From delicate pastel hues to vibrant floral patterns, our pieces embody the spirit of the season, bringing a fresh, joyful touch to your wardrobe.",
    "handle": "spring-2025",
    "title": "Spring Collection"
  }
}
productCreate - GraphQL Admin
Creates a (with attributes such as title, description, vendor, and media.The `productCreate` mutation helps you create m...
shopify.dev

ステップ2：MetafieldとMetaobjectの登録内容をGraphQLで確認

商品データをGraphQLで作成する際、事前に登録したMetafieldやMetaobjectの定義（Definition）を把握しておくことが重要です。これにより、正しいnamespace・key・type・IDなどを把握し、エラーなくMutationを送信できます。

Metafield情報の確認クエリ

query MetafieldDefinitions($ownerType: MetafieldOwnerType!, $first: Int) {
  metafieldDefinitions(ownerType: $ownerType, first: $first) {
    nodes {
      id
      name
      namespace
      key
      type {
        name
      }
    }
  }
}
{
  "ownerType": "PRODUCT",
  "first": 2
}
metafieldDefinitions - GraphQL Admin
Returns a list of metafield definitions.
shopify.dev

Metaobject情報の確認クエリ

query metaobjectDefinitions {
  metaobjectDefinitions (first: 10) {
    nodes {
      name
      id
      metaobjects(first: 3) {
        nodes {
          id
          handle
          type
        }
      }
    }
  }
}
metaobjectDefinitions - GraphQL Admin
All metaobject definitions.
shopify.dev

商品を作成する前のフィールド確認作業は、後続ステップの成功を左右する重要な準備です。とくに複数の商品を一括で登録するような場合、スキーマの誤りは全ての登録失敗につながるため、この工程はしっかり行うことが大切です。

ステップ3：GraphQLのMutationを使って商品を作成する

MetafieldやMetaobjectの情報を確認できたら、GraphQLを使って商品を作成していきます。ここでは、productCreate Mutationを使用します。

商品には、以下の情報を登録します：

  • タイトル（title）
  • 商品の説明（bodyHtml）
  • 商品タイプ（productType）
  • コレクションへの関連付け（collectionsToJoin）
    • ステップ1でコレクションを作成した際のレスポンスでGIDを確認できます
  • Metafield・Metaobjectのカスタム情報（metafields）
    • namespace、key、typeは、ステップ２で確認したMetafield定義と一致させる必要があります
    • Metaobjectは、IDを直接指定して登録します
mutation productionCreateMutation {
  productCreate(product: 
    {title: "Spring Blossom Maxi Dress", 
    	productType: "Dress"
      collectionsToJoin: "gid://shopify/Collection/000000000"
    	metafields:[{
        namespace: "custom"
        key: "wearing_size"
        value: "Small"
      },
      {
        namespace: "custom"
        key: "model_info"
        value: "gid://shopify/Metaobject/0000000000"
        }
      ]
    
    }){
    product {
      id
    }
    userErrors {
      field
      message
    }
  }
}
productCreate - GraphQL Admin
Creates a (with attributes such as title, description, vendor, and media.The `productCreate` mutation helps you create m...
shopify.dev

ステップ4：商品ページに反映されているか確認

GraphQLで商品作成のmutationを実行した後は、Shopifyの管理画面（Admin）で実際に商品が登録されているかどうかを確認しました。

手順は以下の通りです：

  1. Shopify管理画面メニューの「商品」→「すべての商品」へ移動
  2. 作成した商品が一覧に表示されているか確認
  3. 対象商品をクリックし、詳細ページにてタイトルやメタフィールドの情報が反映されているかをチェック

今回は、商品名・価格・コレクションの割り当て・メタオブジェクトの内容などがすべて正常に反映されていることを確認できました。

これにより、GraphQLを使った商品作成と関連データの紐づけが正しく行われていることが証明でき、データ操作とフロントエンドの連携の第一歩を実感できました。

つまずきやすいポイントと補足解説

GID（グローバルID）の取得は必須

ShopifyのGraphQLでは、metaobject や collection、product などを他のエンティティと関連付ける際に、GID（グローバルID） を明示的に指定する必要があります。

今回はまずコレクションを作成したので、そのレスポンスに含まれる id を控えておけば、後から商品に割り当てる際に再度クエリを発行せずに済みます。最初のmutationの返り値も見逃さず活用すると、開発の効率が上がります。

GraphiQLではタブを分けて作業するのが便利

Shopifyが提供する GraphiQL アプリでは、複数のクエリやミューテーションをタブで並行管理できます。たとえば以下のようにタブを分けて作業すると、コピペやIDの参照が非常にスムーズになります：

  • タブ1：collectionCreate
  • タブ2：productCreate
  • タブ3：GIDを確認するためのクエリmetafieldDefinitions
  • タブ4：GIDを確認するためのクエリmetaobjectDefinitions

特にIDをまたいで使う操作が多い今回のようなケースでは、一括で見比べながら作業できる構成がとても効率的です。

GraphQL独自の構文に慣れる必要がある

GraphQLのクエリは、見た目はJSONに似ていますが、クオーテーション（”　”）を使わない独自の構文です。たとえば次のような記述になります：


{
  shop{
    name
    primaryDomain{
      url
  	}
 }
}

初めて扱うと、うっかりキーや値に " を付けてしまうなど、細かい構文ミスでエラーが出やすくなります。JSONっぽいけどJSONではないという前提を理解しておくと、混乱を防ぎやすくなります。

クエリとレスポンスで記法が異なることに注意

GraphQLでは、クエリは独自言語で書きますが、レスポンスはJSON形式で返ってきます。この差異に慣れていないと戸惑いやすいポイントです。

例：

  • クエリは product { title } のように記述（クオーテーションなし）
  • レスポンスは { "product": { "title": "商品名" } } のようにJSONで返ってくる

このように、出力と記述形式の違いを意識して使い分けることが重要です。

userErrors をmutationに含めると原因特定に役立つ

GraphQLのmutationは、失敗してもHTTPエラーを返さず、成功したかのようにレスポンスを返すことがあります。そのため、mutationの返り値に userErrors を含めておくとエラーの情報を表示することができます。

userErrors {
  field
  message
}

この指定をしておくことで、たとえば「必須フィールドが抜けている」「メタフィールドの型が一致していない」などのエラーをメッセージ付きで受け取ることができ、開発時のデバッグが格段に楽になります。

まとめ：GraphQLで拡張するShopifyのデータ操作

今回の実装チャレンジでは単なるAPI操作にとどまらず、metaobjectやmetafieldの実用例、GraphQLのMutationによる商品作成や紐づけ、そして最終的なストア反映まで実践的な一連の流れを体験できました。

「データを構造的に扱いそれをストア上で適切に表示させる。」この一連のプロセスを習得することこそがShopifyにおける「実装力」の基礎となると実感しています。

タイトルとURLをコピーしました