目次
Shopifyは2026年11月13日、Storefront 2027-01からMarket.metafieldsのキー照合で大文字・小文字を区別しなくなると発表しました。マーケットごとの案内文などをまとめて取得するアプリは、これまでnullだった項目に値が返る可能性があります。API版を上げる前に、単一取得と複数取得の結果、値がない場合の表示を比較してください。
本稿は2026年11月14日に確認した公式資料に基づく移行解説です。2027-01は確認時点でリリース候補版であり、2026-10以前の動作を同時に変更する発表ではありません。掲載クエリーは未実行例です。比較表、移行順序、の確認は本サイトの提案で、実ストアでの検証結果ではありません。
スポンサーリンク
対象はMarketの複数取得で使うキー
Shopify公式の変更告知は、Localization.marketまたはCountry.marketから得たMarketオブジェクトのmetafieldsを対象としています。保存されたキーと要求するキーの表記が違う場合や、購入者に関わるマーケット間でキーの大小文字がそろっていない場合に、取得結果を確認する必要があります。
今回変わるのはキーの照合です。保存済みのキーが自動で小文字へ書き換わる、namespaceやvalueの照合も同じように変わる、といった内容は発表されていません。アプリ内であらゆる文字列を小文字化する修正へ広げず、Marketの複数取得を行う箇所に対象を絞ります。
単一取得のMarket.metafieldは、すでに大小文字を区別しない照合を行います。公式は、現在利用している版で同じnamespaceとkeyを両方のフィールドへ渡し、差を比較する方法を示しています。版の切り替えだけで結果を推測する前に、現行環境で差分を見つけられる点が実務上の入口です。
nullが値へ変わると表示の分岐も変わる
説明用に、customというnamespaceにdelivery_noteというキーを保存し、アプリがDelivery_Noteを要求している構成を考えます。大小文字が一致しないので、従来の複数取得で値がなかった箇所が、新しい版では取得対象になります。これが必ず画面の改善になるとは限らず、アプリがnullにどんな意味を持たせていたかを確認する必要があります。
例えば、nullなら共通の配送案内を表示し、値があれば地域別の案内を表示する設計では、アップグレード後に見える文面が切り替わる可能性があります。この配送案内は本稿の仮想例であり、Shopifyが特定の案内文を自動生成する機能ではありません。読者自身のストアで、データと画面の分岐を対応付けてください。
データが存在しない状態と、大小文字が違って取得できなかった状態を、従来は同じnullとして扱っていたかもしれません。前者のテストだけを通しても、後者の変化は検出できません。利用者の国を変えたときに、どの案内や表示条件が変わるべきかを、運用担当者と先に決めておきます。
スポンサーリンク
現行版で単一取得と複数取得を並べる
Marketオブジェクトのリファレンスでは、metafieldsはnamespaceとkeyの識別子リストを受け取ります。次は要求キーを一つに絞り、応答をsingleとbatchという別名で見分ける比較例です。国、namespace、keyは実際に確認する組み合わせへ置き換えます。
query AuditMarketKey($country: CountryCode!, $key: String!)
@inContext(country: $country) {
localization {
market {
id
handle
single: metafield(namespace: "custom", key: $key) {
namespace
key
type
value
}
batch: metafields(identifiers: [{namespace: "custom", key: $key}]) {
namespace
key
type
value
}
}
}
}
変数の例はcountryを、keyをDelivery_Noteとする組み合わせです。同じストア、同じ取得権限、同じ国の文脈で両方を読み、返ったキーの表記、型、値を比較します。Marketのidとhandleも記録すると、別の対象を見ていたために差が出たのかを調べやすくなります。
Localizationの現行リファレンスではmarketフィールドに非推奨の表示があります。本稿は公式告知と同じ既存経路を、変更の影響を調べるために使っています。新規設計へこの経路を無条件に勧めるものではありません。キー照合の修正と取得経路の見直しを同時に行う場合も、それぞれの差分を分けて記録します。
値だけでなく型と要求の文脈を記録する
Metafieldの公式仕様は、valueを文字列として返し、typeで解釈の種類を示します。表示上同じ文字に見えても、型を無視して比較すると問題を見逃します。文字列の案内、数値、参照型などを同じ整形処理へ流していないかを確認し、業務で必要な比較項目を決めます。
一方、取得結果がnullなら、保存データがないと直ちに断定しません。対象マーケット、要求したnamespace、キー表記、アクセス条件を確認します。Storefront APIでのメタフィールド取得ガイドは、公開設定と取得を別の工程として扱っています。今回の照合変更を理由に、確認せず公開範囲を広げる必要はありません。
国の文脈は比較条件の一つです。Localizationの資料は@inContextで有効な国を変えられると説明しています。画面で選んだ国とAPIへ渡した国が一致しているかも記録します。APIが正しい値を返していても、表示側が前の国のデータを保持していれば、キーの問題と取り違えやすくなります。
スポンサーリンク
大小文字の不一致を含む検証表を用意する
まずキーが完全一致するケースを基準にします。次に大小文字だけ違う要求、値を持たないケース、複数マーケットで表記が違うケースを用意します。すべてを本番データで作り替えるのではなく、検証用ストアや限定した試験データで、現在の表示と期待する表示を確認します。
| 試験条件 | 比較して残すもの |
|---|---|
| 保存キーと要求キーが完全一致 | 現行版の基準値と画面表示 |
| 大小文字だけ異なる要求 | singleとbatchの差およびnull時の分岐 |
| 値を用意していないキー | 未設定時の表示とエラーの有無 |
| マーケットごとに表記が異なる | 国の文脈と実際に返るキー・型・値 |
| 国を連続して切り替える | 古いキャッシュや遅い応答が残らないか |
| API版を変えて同じ要求を送る | 要求版と応答版および表示の差 |
複数取得の戻り値は、リストそのものが返っても、要素を無条件に有効なメタフィールドとして扱わないようにします。取得できない要素と有効な要素がある前提で、実装のnull処理を確認します。値が増えた結果、これまで通らなかった描画や変換のコードへ進むことも試験に含めます。
キャッシュと表示条件を国別に再確認する
ここからはアプリ側の設計上の確認です。比較クエリーを直接実行した結果と、キャッシュを経由した画面の結果を分けます。現行版で保存したnullが残っていれば、新しい版で取得できても画面が変わらない場合があります。逆に国の文脈を混同したキャッシュなら、別の購入者向けの値を表示するおそれがあります。
キャッシュの識別条件に、対象ストア、国や必要な購入者文脈、要求内容、API版の違いをどう反映するかを確認します。これはShopifyが自動でアプリのキャッシュを変更するという話ではありません。版を変えた後の再取得、古い結果の失効、国を切り替えた後の描画を、利用している基盤で検証します。
また、要求するキーを小文字へ直すだけで保存データの表記まで統一されたと扱わないでください。複数の連携アプリや管理画面が同じデータを読む構成では、書き込み側の命名規則と読み取り側の要求を別に調べます。コードの検索では、固定文字列だけでなく、設定ファイルや外部サービスから組み立てるキーも対象にします。
データを整える変更は取得の検証と分ける
公式は、キーの大小文字に依存しないよう、要求と保存データの表記を整える方法を示しています。ただし既存データを一括で削除・再作成することを本稿の手順にはしません。最初に利用箇所と所有者、現在値を把握し、必要な変更と影響をレビューします。比較のための読み取り段階では、保存データを変えずに差を記録できます。
Storefront APIはメタフィールドを作成・更新・削除するためのAPIではなく、公式取得ガイドは書き込みにGraphQL Admin APIを案内しています。移行でデータ変更が必要になった場合は、管理側の適切な手順を別に設計します。API版の切り替えとデータの書き換えを一度に実施せず、どちらで結果が変わったかを追える順序にします。
nullを意図的な制御フラグとして使っていた場合は、その意図を明示的な設定へ移せるか検討します。キーの大文字・小文字がたまたま合わない状態を、地域別表示のオン・オフとして使い続けると、今回のような照合変更で意味が変わります。業務上の条件と、APIが値を見つけられたかという条件を分けて扱う方が保守しやすくなります。
版を上げる前に差分と切り戻し条件をそろえる
ShopifyのAPIバージョニング資料では、現在の安定版とリリース候補版の用途を分けています。2027-01は本番向けに推奨される段階ではないため、まず現行版で比較とコード修正を進め、検証環境で候補版との差を確認します。リクエストURLや設定だけでなく、応答のX-Shopify-API-Versionも確認し、意図した版で比較できたかを記録します。
リリース判定には、対象キーの一覧、国別の差、値がない場合の画面、キャッシュを含む結果、変更前へ戻す条件を残します。差がある項目すべてを問題とせず、業務上期待する表示と一致するかで判断します。該当するキーを読まないアプリや、すべて一致している構成に、不要なデータ変更を加える必要はありません。
採用の完了条件は、クエリーが成功することだけではありません。対象の国で意図したデータを取得し、型に合った解釈を行い、未設定時の表示も保たれ、利用者の画面まで一致することです。現行版で単一取得と複数取得を並べる確認を入口に、データ、取得、キャッシュ、描画の順で変化を追ってください。
スポンサーリンク
関連記事
Shopifyの顧客ページ遷移とAPI版更新の解説は、同じアプリで顧客アカウント拡張も保守する場合の別の確認項目を扱っています。Storefront APIのキー照合とは独立した変更なので、拡張側の版と試験結果を分けて管理してください。
参考資料
Shopify:Market.metafieldsのキー照合変更(2026年11月13日)
Shopify Storefront API:Market(2027-01リリース候補版)
Shopify Storefront API:Metafield
Shopify Storefront API:Localization
Shopify:Storefront APIでのメタフィールド取得
Shopify:APIバージョニング







