【Shopify GraphQL API徹底解説】商品を管理するための3つのオブジェクト

この記事の所要時間： 10分

Graph APIは最初から全てを理解することが困難なので、範囲を決めて少しずつ理解していく必要があります。

【Shopify GraphQL API徹底解説】シリーズでは、Shopify GraphQL APIの仕様から、主要なオブジェクトを少しずつ読み解いていきます。

説明は記事内で完結しているので、シリーズの他の記事を参照しなくても理解できるようにしています。

今回解説するのはProductとProductVariantとCollectionです。

密接な関係がある、これらのオブジェクトを読み解くことで、Shopify GraphQL APIの見通しが良くなります。

InventoryItemやfulfillmentなどの重要なオブジェクトも関わってきますが、それらについては、関係性の高いオブジェクトとまとめて、別の記事で解説します。

最初に、ProductとProductVariantとCollectionの関係性(Connection)を把握します。

そのあとに、それぞれのオブジェクトの詳細を見ていきます。

ProductとProductVariantとCollectionの関係性

Productは商品を表し、ProductVariantはサイズや色などの商品バリエーションを表し、Collectionは商品をカテゴリーとしてまとめます。

この3つのオブジェクトには密接な関係があります。

Shopify GraphQL APIにおいては、オブジェクト同士の関係は、Connectionで表現されます。

今回紹介する3オブジェクト間のConnectionだけを抜き出して、図示したものがこちらです。

文章として表現すると、

• 商品(Product)は商品バリエーション(ProductVariation)と結びついています。
• 商品(Product)はコレクション(Collection)に含まれます。
• コレクション(Collection)は、商品(Product)を含みます。

またConnection先の数も重要です。

• 1つの商品(Product)に結びつく商品バリエーション(ProductVariation)数は、1か複数です。
• 1つの商品(Product)が含まれるコレクション(Collection)数は、0か1か複数です。
• 1つのコレクション(Collection)に含まれる商品(Product)数は、0か1か複数です。

それでは、それぞれのオブジェクトの詳細を見ていきます。

Product

Productはショップに登録された商品の情報です。

注目してほしいのは、色やサイズ、価格などの情報が含まれないことです。

赤いSサイズのジャケットも、青いLサイズのジャケットも、1つのProductとして表現されます。

Productのイメージをつかんでもらうために、主要なフィールドを紹介します。

全てを理解する必要はありません。

Productの主要なフィールド

titleフールド、handleフィールド、onlineStoreURLフィールドの関係性

titleは商品のタイトルです。商品タイトルとしてショップに表示されます。

handleは商品ページのURLに使われる商品名です。

onlineStoreUrlがhandleを含んだ、URL全体になります。

例えば、titleに「wonderfull T-shirt」を設定すると、handleは自動で「wanderfull-t-shirt」となり、onlineStoreUrlは「https://yourstore.com/products/wanderfull-t-shirt」となります。

yourstore.comの部分はストアのドメイン名によって変わります。

featuredImageフィールドが返すImageオブジェクト

featuredImageには優先して表示する画像がImageオブジェクトとして返されます。

Imageオブジェクトを返すフィールドは、以降で紹介するProductVariantとCollectionでも出てきます。

Imageオブジェクトは、アップロードされた画像を表し、heightやwidth、altTextといったフィールドを持ちます。

ImageオブジェクトのtransformedSrcフィールドでは、cropやmaxHeightといった引数を指定することで、フロントエンドに最適化された画像のURLを取得できます。

statusフィールド

statusは商品の状態を表す列挙型です。

以下のいずれかの値を取ります。

• ACTIVE・・・商品が販売される準備ができている状態。商品はショップで公開される。
• ARCHIVED・・・商品がこれから販売される見込みがない状態。今後商品がショップで公開されることはない。
• DRAFT・・・商品が販売される準備ができてない下書きの状態。商品はショップで公開されない。

descriptionHtmlフィールドとdescriptionフィールド

ショップに表示される商品説明のデザインをdescriptionHtmlで制御できます。

ストア管理画面で以下のように編集した場合は、descriptionHtmlにHTMLフォーマットで保存されます。

一方、descriptionにはdescriptionHtmlの値からHTMLタグが除外された値が保存されます。

例えば、以下のようになります。

{
  "data": {
    "product": {
      "descriptionHtml": "<meta charset=\"utf-8\">\n<h1 data-mce-fragment=\"1\"><strong data-mce-fragment=\"1\">人気ナンバーワンのシャツシリーズです！</strong></h1>\n<h3 data-mce-fragment=\"1\">特徴</h3>\n<ul data-mce-fragment=\"1\">\n<li data-mce-fragment=\"1\"><strong data-mce-fragment=\"1\">シンプル</strong></li>\n<li data-mce-fragment=\"1\"><strong data-mce-fragment=\"1\">質感が気持ち良い</strong></li>\n<li data-mce-fragment=\"1\"><strong data-mce-fragment=\"1\">早く乾く</strong></li>\n</ul>",
      "description": "人気ナンバーワンのシャツシリーズです！ 特徴 シンプル 質感が気持ち良い 早く乾く"
    }
  },
  # 省略
}

ProductVariant

ProductVariantは、商品バリエーションと訳されます。

商品の色やサイズ、価格などの情報を含みます。

ひとつのProductが複数のProductVariantとむすび付いています。

先ほどの例でいうと、赤いSサイズのジャケットと、青いLサイズのジャケットは、それぞれProductVariantです。

ProductVariantの主要なフィールド

titleフィールドとdisplayNameフィールド

titleは商品バリエーション(ProductVariant)自体のタイトルです。

先ほど紹介した商品(Product)にもtitleフィールドがありました。

「商品のtitle + 商品バリエーションのタイトル」が商品バリエーションのdisplayNameとなります。

下の例だと、商品のtitleが「Tシャツ」で、2つの商品バリエーションのtitleがそれぞれ「S」と「L」です。

すなわち、商品バリエーションのタイトルは、「Tシャツ – S」と「Tシャツ – L」となっています。

{
  "data": {
    "product": {
      "title": "Tシャツ",
      "variants": {
        "edges": [
          {
            "node": {
              "title": "S",
              "displayName": "Tシャツ - S"
            }
          },
          {
            "node": {
              "title": "L",
              "displayName": "Tシャツ - L"
            }
          }
        ]
      }
    }
  },
  # 省略
}

imageフィールド

imageフィールドはImageオブジェクトを返しますが、ProductのfeaturedImageフィールドとは違い、4つの引数を持っています。

この4つの引数を指定して、商品バリエーションに設定された画像をクライアントによって最適化できます。

Positionフィールド

Positionは、１つの商品と結びつく複数の商品バリエーションに、順番を指定できます。

商品ページのドロップダウンメニューで商品バリエーションを選択する時などに表示の順番が変わります。

Collection

Shopifyには商品を束ねるコレクション(Collection)という機能があります。

関連する商品(Product)をコレクション(Collection)として束ねて、商品カテゴリとして利用します。

この例では、「white T-shirt」と「wonderful T-shirt」という商品(Product)が「シャツ」というコレクション(Collection)に束ねられています。

{
  "data": {
    "collection": {
      "title": "シャツ",
      "productsCount": 2,
      "products": {
        "edges": [
          {
            "node": {
              "title": "white T-shirt"
            }
          },
          {
            "node": {
              "title": "wonderful T-shirt"
            }
          }
        ]
      }
    }
  },
  # 省略
}

Collectionの主要なフィールド

2種類のCollectionとruleSetフィールド

コレクションには2種類あります。

Automated collectionとManual collectionです。

Manual collectionは名前の通り、GUI操作、もしくはAPI経由でコレクションに商品を追加します。

Automated collectionは、コレクションに含める商品の条件(CollectionRule)のリストを設定することで、商品が自動でコレクションに分類されます。

CollectionのruleSetフィールドにCollectionRuleのリストを含む、CollectionRuleSetというオブジェクトを設定します。

最後に

Productは商品を表し、ProductVariantはサイズや色などの商品バリエーションを表し、Collectionは商品をカテゴリーとしてまとめます。

最初に示した図を再掲するので、頭の中で整理してみてください。

Shopify GraphQL APIにおいて中心的な役割を果たしている、ProductとProductVariantとCollectionについて解説しました。

理解を容易にするために、全てのフィールドは紹介しておりませんし、フィールドに登場したオブジェクトも一部しか解説していません。

また、ProductとProductVariantとCollectionは、この3つのオブジェクト間に限らず、他へのConnectionも持っています。

Graph APIは最初から全てを理解することが困難なので、今回のように、範囲を決めて少しずつ理解していく必要があります。

【Shopify GraphQL API徹底解説】シリーズでは、次回以降も、密接に関係するオブジェクトをまとめて紹介していきます。

シリーズを通して、主要なオブジェクトと、その関係性を理解すれば、Shopify GraphQL APIの強力さを体感できるはずです。