Metaobject APIがシンプルに。valuesで一括取得・更新

8月 09, 2026

API CHANGE

Metaobject API が刷新
values で全フィールドを一発操作

シリアライズ処理をAPIに任せ、JSONオブジェクトのまま読み書きできる新プロパティ登場

2026年6月11日より、Shopify GraphQL APIのメタオブジェクトに values プロパティが追加されました。アプリ側でフィールドのデシリアライズ処理を書かずとも、JSONオブジェクトとして全フィールドを一括取得・一括更新できます。既存の fields プロパティは引き続き利用可能で、移行は任意です。

OVERVIEW

01何が変わったのか — values プロパティの全貌

従来の fields では各フィールドの value が文字列で返るため、アプリ側でデシリアライズ処理が必要でした。新しい values プロパティはAPI側がシリアライズ/デシリアライズを担い、JSONオブジェクトをそのまま返します。書き込み時も同様に、フィールドキーと値をJSONスタイルで渡すだけで完了します。

省略フィールドはクリアされる点に注意： values で更新する際、メタオブジェクト定義に存在するフィールドを省略すると、そのフィールドはクリア（削除）されます。特定フィールドのみを変更するパッチ的な挙動が必要な場合は、引き続き fields / field を使用してください。

USE CASES

02業務で活かせる具体ユースケース3選

課題: 外部CMSからShopifyへコンテンツを一括インポートするバッチ処理で、フィールドごとに型判定とシリアライズを書く手間がかかっていた
打ち手: 外部CMSのJSONレスポンスをそのまま values に渡してメタオブジェクトを作成・更新するよう実装を変更
効果: フィールド変換ロジックが不要になりコードが大幅に削減。スキーマ変更時の修正コストも低下
技術メモ: CMSのフィールドキーとShopifyメタオブジェクト定義のフィールドキーを揃えておくと、マッピングコードをほぼゼロにできる

課題: 商品カタログ管理ツールでメタオブジェクトの全フィールドを表示する際、複数の fields エントリをループ処理してUIにバインドするコードが複雑になっていた
打ち手: values で取得したJSONオブジェクトをそのままフォームの defaultValues に渡すことでバインディングを簡素化
効果: フロントエンドの状態管理コードが簡潔になり、新フィールド追加時の対応工数がゼロに近づく
技術メモ: フィールドの型情報が必要な場合（バリデーション等）は fields { type } を併用することで対応可能

課題: 在庫・価格・説明文などを格納したメタオブジェクトを全件書き換えるバルク更新処理で、各フィールドをキー/バリュー形式で構築するボイラープレートが多かった
打ち手: 更新用のJSONオブジェクトを values 引数に渡す形式に移行し、全フィールドを一括置換
効果: API呼び出しのペイロード構築コードが簡潔化し、バルク処理の実装・メンテナンスコストが削減
技術メモ: 全フィールドを毎回まとめて渡す設計なので、省略フィールドはクリアされる仕様と相性が良い。パーシャル更新には fields を使い分けること

DEVELOPER NOTES

03技術者が押さえるべき5つのポイント

#	ポイント	詳細
1	values は読み取り専用ではない	クエリ（取得）だけでなく、作成 (metaobjectCreate) ・更新 (metaobjectUpdate) のミューテーションでも使用可能
2	省略フィールドはクリアされる	values でミューテーション時に定義済みフィールドを省略すると null / 空にリセットされる。意図しないデータ消失に注意
3	fields との共存・使い分け	field / fields は廃止されない。型情報の取得やパッチ的な部分更新には引き続き fields を使用できる
4	API バージョン	元記事に具体的なバージョン番号の記載なし。利用前に公式ドキュメントで対応バージョンを確認のこと
5	Liquid / アプリへの影響	元記事に Liquid テンプレートやアプリ拡張への言及なし。GraphQL Admin API を使うカスタムアプリが主な対象とみられる