速報

ジェトロのサイトで情報漏えい|追加9,413件の内訳と暫定再開の範囲

CATEGORY

Shopifyのファイル参照で外部動画を扱う|型別の描画と代替導線を検証する

※本ページのリンクにはプロモーションが含まれています。

商品ページに関連する二つの外部動画と補足説明のカードを照合する開発者の概念イラスト

目次

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へ入れる設計にはしません。

描画方針の例を次の表に示します。これはサイト側の実装を整理するための提案です。各行の表示部品はアプリが用意し、利用するプレーヤーやブラウザーで検証してください。種別が増えたときにも、既定処理で画面全体が落ちないことを重視します。

参照先取得値の使い分け表示できない場合
MediaImageimageのURLと代替テキスト補足説明を残す
VideosourcesとMIME型に対応する動画部品再生不可を案内する
ExternalVideo埋め込みはembedUrl、元ページへの導線はoriginUrl元ページのリンクと説明
GenericFileurlと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

この記事を書いた人

Ryohei

Webエンジニア / アプリ開発者 / 技術ブログ運営者

福岡のWeb制作会社に勤務するWebエンジニアです。10年以上にわたりWeb制作・開発に携わり、ヒアリングや進行管理から、コーディング、CMSの構築、システム開発、サーバーの構築・保守・運用まで、Webサイト制作の工程を幅広く担当しています。Webサイトは、これまでに100以上の構築・保守を手がけてきました。

個人でもWebサイトの制作・改修やWebアプリの開発・運用を行い、AIを活用した開発にも取り組んでいます。近年はWebセキュリティにも注力しています。

2015年から技術メディア「Into the Program」を運営し、実務や開発で得た知識をもとに、プログラミングの実装方法やWebサイトの運用・セキュリティ情報を発信しています。

主な分野
Webサイト構築・保守・運用 / HTML/CSS / JavaScript / PHP / WordPress / サーバー構築・保守・運用 / アプリ開発 / セキュリティ対策
資格・試験合格
情報セキュリティマネジメント試験
基本情報技術者試験
AWS認定ソリューションアーキテクト アソシエイト
PHP8技術者認定ウィザード
メディア運営
2015年〜

記事の作成・更新について

セキュリティ記事は、ベンダーの公式アドバイザリやCVE・JVNなどの一次情報を参照し、出典と情報確認日を記載します。実環境での検証を行った場合は、その環境と確認範囲を明示します。重要な追加情報や誤りを把握した場合は、内容を確認して追記・訂正します。

関連する記事

おすすめの書籍

キーワードから探す

スポンサーリンク

キャッシュ

一度取得したデータを一時的に保存しておき、次に使うときに再利用して処理を速くする仕組み。

詳しく見る

HTTP

ブラウザとWebサーバーがやりとりするための決まりごと(プロトコル)。暗号化したものはHTTPSと呼ぶ。

詳しく見る

スキーマ

データの構造や型、決まりごとを定義したもの。データベースのテーブルの設計や、JSONの形式の定義などに使う。

詳しく見る

認証

アクセスしてきた相手が本人であることを確かめる仕組み。パスワードや生体情報、電子証明書などを使う。

詳しく見る

検証環境

本番環境に反映する前に、変更や更新が問題なく動くかを試すための環境。本番と同じ構成にできるほど確認の精度が上がる。

詳しく見る

API

ソフトウェアやサービスの機能を、ほかのプログラムから決まった方法で呼び出して使えるようにした窓口。

詳しく見る