目次
Shopifyは2026年11月20日、 2027-01からファイル参照メタフィールドでYouTubeとVimeoの外部動画を扱えると案内しました。商品に補足資料を付けるヘッドレスストアでは、参照先を画像やShopify内の動画と決め付けた描画処理を確認する必要があります。取得クエリーだけでなく、動画を表示できない場合に何を残すかも設計してください。
本稿は11月22日に確認したShopify開発者向け変更一覧と公式仕様に基づく導入解説です。2027-01は現在リリース候補版です。以下はその版を検証するための未実行例であり、全ストアの本番表示がすでに変わったという意味ではありません。対象はStorefront APIで商品メタフィールドを読み、独自の画面へ描画する開発者です。
スポンサーリンク
file_referenceの名前だけで描画先を決めない
メタフィールドの型一覧によると、file_referenceは既定で全ファイル種別を許可し、検証規則で対象を制限できます。2027-01では、全種別を許可する場合、またはVideoを許可する場合に、YouTubeやVimeoのExternalVideoも参照できます。画像だけに絞った定義まで、同じ条件と解釈しないでください。
大切なのは、メタフィールドの型名と参照先オブジェクトの型を分けることです。file_referenceという型名だけでは、画像用のURLを読むべきか、動画の再生候補を読むべきかは決まりません。既存コードで「ファイルならurlを使う」「動画ならsourcesがある」と仮定している場所を探します。
MetafieldReferenceのリファレンスでは、参照先は複数の型を持つunionです。ExternalVideo、Video、MediaImage、GenericFileは別の型として扱われています。GraphQLで__typenameを取得し、その結果に応じて必要なフィールドと表示部品を選ぶ構成が検証の入口になります。
定義と公開設定を確認してからデータを読む
検証用に、商品へ付けるcustom.product_guideという単一のファイル参照を想定します。実際には自社のnamespaceとkeyへ置き換え、定義が許可する種別と利用箇所を記録してください。画像専用の既存フィールドへ動画を入れるためだけに、全商品の検証規則を一括で広げる手順にはしません。
Storefront APIでのメタフィールド取得ガイドは、公開する定義にaccess.storefrontのPUBLIC_READを設定する方法を案内しています。管理画面で値を確認できることと、Storefront APIから取得できることは別です。公開してよい補足資料だけを対象に、定義とアクセス条件を確認します。
また、Storefront APIはメタフィールドの作成・更新・削除用ではありません。書き込みが必要なら管理側の適切な手順を別に用意します。今回の検証では、まず読み取りと描画の対応を調べ、値の移行や定義の変更は別の差分としてレビューできる状態にします。
スポンサーリンク
参照先の型を取得するクエリー例
Metafieldの公式仕様では、単一参照はreference、参照リストはreferencesから取得します。valueは文字列なので、動画の埋め込みURLそのものとして使わず、参照オブジェクトを読みます。次は2027-01を指定したで、既存の主要なファイル型と外部動画を区別する例です。
query ProductGuide($handle: String!) {
product(handle: $handle) {
id
guide: metafield(namespace: "custom", key: "product_guide") {
type
reference {
__typename
... on MediaImage {
image { url altText }
}
... on Video {
alt
sources { url mimeType }
}
... on ExternalVideo {
alt
host
embedUrl
originUrl
}
... on GenericFile {
alt
url
mimeType
}
}
}
}
}
handleには検証商品を指定します。利用中のStorefront APIのとアクセス条件が整っていることが前提です。このクエリーは参照を作成せず、プレーヤーも生成しません。商品が取得できない場合、guideがない場合、referenceがない場合を、それぞれ有効なデータと混同しないように扱います。
リスト型を使うアプリでは、この単一参照の例へそのままデータを当てはめず、referencesの接続とページ送りに合わせて変更します。取得した項目の順序と型の混在も確認対象です。最初は単一の検証フィールドで一つずつ型を確かめると、データと画面の不一致を追いやすくなります。
VideoとExternalVideoでは使うURLが違う
Videoの仕様では、Shopify上の動画はsourcesに再生用データを持ちます。一方、ExternalVideoの仕様では、embedUrlはホストに応じた埋め込み用URL、originUrlは元の動画ページのURLです。外部動画のembedUrlを通常のvideo要素のsrcへ入れる設計にはしません。
描画方針の例を次の表に示します。これはサイト側の実装を整理するための提案です。各行の表示部品はアプリが用意し、利用するプレーヤーやブラウザーで検証してください。種別が増えたときにも、既定処理で画面全体が落ちないことを重視します。
| 参照先 | 取得値の使い分け | 表示できない場合 |
|---|---|---|
| MediaImage | imageのURLと代替テキスト | 補足説明を残す |
| Video | sourcesとMIME型に対応する動画部品 | 再生不可を案内する |
| ExternalVideo | 埋め込みはembedUrl、元ページへの導線はoriginUrl | 元ページのリンクと説明 |
| GenericFile | urlとmimeTypeを確認した資料リンク | リンクを出さず説明を残す |
| 未対応型・参照なし | 既定の表示へ戻す | 商品本文と購入導線を保つ |
画像はMediaImageのimageフィールド、一般ファイルはGenericFileのurlとmimeTypeを使うため、同じプロパティを全型へ読み出す処理を避けます。外部動画への対応を足した結果、既存のPDFリンクや画像表示が壊れていないことも回帰試験に含めます。
UI側では__typenameで分岐してから、その型の値を読むようにします。TypeScriptなどで型を生成しているなら、2027-01のとクエリーへ合わせて生成物を更新します。型エラーを強制変換で消すだけにせず、新しい分岐と既定分岐の両方がレビュー対象になるようにします。
スポンサーリンク
最初は元ページへのリンクで表示を成立させる
外部動画を扱う最小の対応として、originUrlへのリンクと説明文を出す方法を提案します。埋め込みプレーヤーはその後の段階です。動画を見るための導線を一つ確保しておくと、プレーヤーの読み込みや外部サービスの都合で表示できない場合も、商品説明そのものを失わずに済みます。
リンクの文言は「動画」だけにせず、何を説明する動画かと、外部サイトへ移動することが分かる内容にします。altが空なら、運用担当者が用意した案内文を使えるようにしてください。元ページが非公開になった場合は、リンクも解決策にならないため、商品の使い方など重要な情報は本文や別の資料でも伝えます。
埋め込む場合は、APIが返すembedUrlを利用する表示部品を用意し、タイトル、縦横比、キーボードでの移動、再生前の状態を確認します。任意の入力文字列をHTMLへ連結する方式を避け、利用しているフレームワークの属性設定を使います。自動再生を導入の前提にはしません。
さらに、外部プレーヤーをいつ読み込むかをストアの方針として決めます。必要に応じて利用者の操作や同意を待つ画面にし、待機中にも説明と代替導線を出します。この方針は今回のAPI変更が自動で決めるものではありません。データの取得成功と、外部コンテンツの表示条件を分けて試験します。
nullと再生失敗を別々に切り分ける
APIから値が返らない場合は、商品、namespace、key、定義、公開設定、要求版を順に照合します。新しい型の表示が空白だからといって、直ちにファイルを削除・再登録する必要はありません。まず生の取得結果で、メタフィールドがないのか、参照がないのか、参照型に対応していないのかを調べます。
一方、ExternalVideoとURLが取得できているなら、次は描画部品や外部ホストの再生条件を調べます。ネットワークが遅い場合、埋め込みが許可されない動画、公開状態が変わった動画も試験候補です。APIの応答だけで完了とせず、利用者が実際に見られる内容まで確認してください。
ログには、検証した商品とメタフィールド、要求版、__typename、どの表示分岐を通ったかを残すと原因を追いやすくなります。動画の成功・失敗だけを一つの件数へまとめると、取得の問題とプレーヤーの問題が混ざります。調査に不要なレスポンス全体を保存せず、必要な識別情報へ絞ります。
版を固定して混在データの回帰試験を行う
ShopifyのAPIバージョニング方針では、リリース候補版は本番用途に推奨されません。2027-01の検証用設定を現行の本番設定と分け、要求した版と応答のX-Shopify-API-Versionを記録します。正式提供時には、候補版で確認した仕様が維持されているかを再確認します。
試験データには、画像、Shopify上の動画、YouTube、Vimeo、一般ファイル、未設定をそろえます。各種別について取得値、型分岐、画面、代替導線を一組で記録します。新しい型だけ成功しても、従来の資料が読めなくなっていれば採用完了にはしません。
や静的生成を使う構成では、APIを直接読んだ結果と、配信ページの結果を比較します。前の型や未設定状態を保持していれば、クエリーを直しても表示が変わらない場合があります。キャッシュの更新、再生成、古い画面からの移動を含め、参照先を変えた後の反映手順も確認します。
適用は検証フィールドと少数の商品から始め、戻す表示部品と設定を残します。外部動画の登録を広げる前に、旧実装がそのデータを読んだ場合の振る舞いも調べてください。保存データ、取得するAPI版、表示コードを同時に戻せるとは限らないため、変更の順序と停止条件を先に決めます。
今回の価値は、補足コンテンツをファイル参照として扱う選択肢が広がる点です。その利点を生かすには、参照先の型を読み、型に合った表示を選び、利用できない場合にも商品の理解を助ける情報を残す必要があります。まず取得とリンク表示を成立させ、その上にプレーヤーを追加する順序なら、運用担当者とも確認点を共有しやすくなります。
関連記事
ShopifyのMarketメタフィールドとキー照合の検証は、同じStorefront API更新で別途確認する取得条件を扱っています。外部動画の参照型とは独立した変更なので、対象と試験結果を分けて管理してください。
スポンサーリンク
参考資料
Shopify:開発者向け変更一覧(2026年11月20日のファイル参照変更)
Shopify:メタフィールドの型一覧
Storefront API 2027-01:MetafieldReference
Storefront API 2027-01:ExternalVideo
Storefront API 2027-01:Metafield
Storefront API 2027-01:Video
Shopify:Storefront APIでのメタフィールド取得
Shopify:APIバージョニング
Storefront API 2027-01:MediaImage
Storefront API 2027-01:GenericFile









