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

  • このエントリーをはてなブックマークに追加
  • Pocket
  • LINEで送る
product-productvariant-collection-relationship

この記事の所要時間: 11分

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をだけを抜き出して、図示したものがこちらです。

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の主要なフィールド

titleString!商品のタイトル
handleString!商品のURLに使われる文字
productTypeString!マーチャントによって設定される商品のタイプ
onlineStoreUrlURL商品のURL。値がnullなら、公開されていないという意味になる。
descriptionHtmlHTML!HTMLフォーマットの商品説明
description
(オプションの引数としてIntをとる)
String!HTMLタグを取り除いた商品説明。
引数で与えられた文字数以降を切り捨てる。
statusProductStatus!商品の状態を表す列挙型
totalInventoryInt!商品の在庫数
totalVariantsInt!商品にひも付くProductVariantの数
vendorString!商品の販売者
mediaCountInt!商品にひも付くメディア(画像、動画、3Dモデルなど)の数
featuredImageImage優先して表示する画像
featuredMediaMedia優先して表示するメディア
inCollection
(引数としてIDを取る)
Boolean!商品がIDで指定されたCollectionに含まれるかどうか
publishedAtDateTime商品がショップに公開された日時

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フォーマットで保存されます。

ショップに表示される商品説明のデザインを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の主要なフィールド

productProduct!この商品バリエーション(ProductVariant)が属する商品(Product)
titleString!商品バリエーションのタイトル
displayNameString!商品バリエーションの表示名
priceMoney!商品バリエーションの価格
(ショップに設定された通貨単位に基づく)
weightFloat商品1つあたりの重さ。
単位はweightUnitフィールドで指定される。
imageImage優先して表示される商品バリエーションの画像
availableForSaleBoolean!商品バリエーションが販売可能かどうか
positionInt!商品バリエーションが表示される順番
inventoryItemInventoryItem!商品バリエーションの在庫情報
inventoryQuantityInt販売可能な数
deliveryProfileDeliveryProfile配送に関する情報
fulfillmentServiceFulfillmentService配送サービスに関する情報

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つの引数を持っています。

cropCropRegionCropRegionのBOTTOM、CENTER、LEFT、RIGHT、TOPの値に基づき、画像を切り抜く。
maxHeightIntピクセル単位で指定する画像の高さ。1~2048の範囲で指定できる。
maxWidthIntピクセル単位で指定する画像の幅。1~2048の範囲で指定できる。
scaleIntretinaディスプレイ向けに画像サイズを拡大する。1~3の範囲で指定できる。

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

Positionフィールド

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

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

Positionは、1つの商品と結びつく複数の商品バリエーションに、順番を指定できます。商品ページのドロップダウンメニューで商品バリエーションを選択する時などに表示の順番が変わります。

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の主要なフィールド

titleString!コレクションのタイトル
handleString!コレクションのURLに使われる文字列
descriptionHtmlHTML!HTMLフォーマットのコレクションの説明
description
(オプションの引数としてIntをとる)
String!HTMLタグを取り除いたコレクションの説明。
引数で与えられた文字数以降を切り捨てる。
imageImageコレクションにひも付いた画像
hasProduct
(引数としてProductのIDをとる)
Boolean!コレクションがIDで指定された商品を含むかどうか
productsCountInt!コレクションに含まれる商品の数
ruleSetCollectionRuleSetコレクションに追加される商品の条件。smart collectionの場合にのみ適用される。

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

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

Automated collectionとManual collectionです。

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

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

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

最後に

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

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

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

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

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

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

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

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

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

  • このエントリーをはてなブックマークに追加
  • Pocket
  • LINEで送る

SNSでもご購読できます。