記事のサマリー(TL;DR)
- Shopify Catalog APIのsearch_catalog、get_product、lookup_catalogが、製品のmedia配列に動画(video)および3Dモデル(model_3d)のアセットを返すようになりました。従来は画像(image)のみでした。
- search_catalogに新しいフィルタ
catalog.filters.mediaが追加され、image・video・model_3dを指定して検索結果を絞り込めます。このフィルタは任意(オプション)であり、既存のクエリは引き続き同じ製品を返します。 - 動画・3Dモデルのアセットを受け取るには、クライアントがエージェントプロファイルでShopifyのグローバルCatalog拡張機能(dev.shopify.catalog.global)のドラフト版を宣言する必要があります。
条件と制約
- 新しいメディア種別(動画・3Dモデル)を取得するには、エージェントプロファイルでdev.shopify.catalog.globalのdraft(ドラフト)版を宣言する必要があります。宣言はエージェントプロファイルの1行の変更で済みます。
- ドラフト版を宣言しない場合、mediaフィールドは引き続き画像のみを返します。
catalog.filters.mediaの各エントリはAND条件で組み合わされます。たとえばvideoとmodel_3dの両方を指定した場合、両方のメディアを持つ製品のみが返されます。- 認識されないメディア種別を指定してもリクエスト自体は失敗しません。APIはその種別を無視し、
result.messages[]内にコードnot_foundとして報告します。 - メディア種別によるフィルタリングはsearch_catalogに適用されます。アセットURL自体はget_productおよびlookup_catalogでも、フィルタを使わない場合でも返されます。
- stable(安定)版の拡張機能バージョンでフィルタを使用した場合、フィルタ自体は適用されますが、レスポンスに含まれるのは画像のみです。
- ドラフトスキーマは次回のUCPリリースでstable版に移行する予定です。
詳細
変更内容
search_catalog、get_product、lookup_catalogは、製品のmedia配列において動画・3Dモデルのアセットを返すようになりました。従来は画像のみを扱っていました。
Catalog API検索では新しいフィルタcatalog.filters.mediaを利用できます。各エントリはメディア種別(image、video、model_3dのいずれか)を指定します。条件に一致した製品は、レスポンス内にそれらのアセットへのリンクを含めて返されます。これにより、クライアントはメディア取得のための2回目のリクエストを行うことなく製品を描画できます。
従来は、製品をリクエストしたうえで各製品を個別に調べて使用可能なメディアの有無を確認し、メディアがない製品を除外するという手順が必要でした。新しいフィルタはこのパターンを置き換えるものです。
既存のフィルタに変更はなく、新しいエンドポイントの追加やマイグレーションも必要ありません。
影響を受ける対象
この変更は、Catalog APIを呼び出すアプリやツールのうち、以下に該当するものに影響します。
- search_catalogを使用し、画像・動画・3Dモデルのメディアで製品をフィルタリングしたい場合
- search_catalog、get_product、lookup_catalogのレスポンスに含まれる製品メディアのアセットURLに依存している場合
動画および3Dモデルのアセットを受け取るには、クライアントがエージェントプロファイルでShopifyのグローバルCatalog拡張機能(dev.shopify.catalog.global)のドラフト版を宣言する必要があります。宣言しない場合、mediaフィールドは引き続き画像のみを返します。
この変更の意義
提供元は、拡張現実(AR)の試着機能、3D製品ビューア、カメラ起点のショッピング体験を構築する場合、描画可能なアセットを持たない製品は利用できないと説明しています。クエリの時点で特定のメディアを持つ製品に絞り込むことで、取得・確認・除外というループが不要になり、またレスポンス内にアセットURLが含まれることで製品ごとの追加のラウンドトリップが不要になるとしています。
対応方法
カタログの検索結果に動画や3Dメディアが不要な場合、対応は必要ありません。既存のクエリは引き続き動作し、同じ製品を返します。
対応が必要な場合の手順は次のとおりです。
- エージェントプロファイルでdev.shopify.catalog.globalのドラフト版を宣言するか、Shopifyが公開しているドラフトプロファイルを参照する
- search_catalogリクエストに、必要なメディア種別を指定した
catalog.filters.mediaを追加する - レスポンスのmedia配列からアセットURLを取得する。動画および3Dのエントリには、ファイル形式ごとに1件のエントリを持つsources配列が含まれる
- 要求したメディアは存在するが、必要な形式が含まれていない製品への対応を行う
- 返された各製品が、要求した種別のアセットURLを少なくとも1つ含んでいることを確認して、動作を検証する
- 画像のみが返される場合は、プロファイルがまだstable版のままであることを意味する
関連ドキュメント
- Catalog APIリファレンス
- Agent profiles(エージェントプロファイル)