Events にメタフィールドトリガー と新トピックが追加

図解 ： Shopify Events にメタフィールドトリガーと新トピックが追加 Developer Changelog / Events（開発者プレビュー） Events にメタフィールドトリガー と新トピックが追加 Order / Collection / InventoryItem / InventoryShipment / Location が購読可能に。さらに Product・Order・Customer・Collection・Location の メタフィールド変更そのもの を namespace と key 単位で購読できるようになった。「全更新を受けて自前で差分を取る」handler が要らなくなる。 このページの構成 30 秒で理解 ： 何ができるようになったか 追加された対応リソース一覧 仕組み図解 ： メタフィールド変更が handler に届くまで 設定例 ： shopify.app.toml 受け取るペイロードの構造 トリガーの粒度 ： 3 パターン 制約と注意点 技術者が押さえるべき5つのポイント 業務に活かせる3つのユースケース 提案で使える1行サマリ 1 30 秒で理解 ： 何ができるようになったか Events の購読対象が Order / Collection / InventoryItem / InventoryShipment / Location に広がり、 さらに メタフィールドの値が変わったこと自体 を、namespace と key を指定して購読できるようになった。 これまで ： 全部受けて自分で diff 「この 1 つのメタフィールドが変わったときだけ動きたい」場合でも、リソースの update をまるごと購読し、handler 側でペイロードを差分比較する必要があった。 これから ： 欲しいフィールドだけ狙い撃ち triggers に対象のメタフィールドを書けば、その値が変わったときだけイベントが飛ぶ。変わったリソースを自分で query して、必要なデータだけ受け取れる。 公式の表現では ： アプリは「トリガーで対象フィールドを狙い撃ちし、変更されたリソースを query し、 ペイロードを差分比較するためだけに全リソース更新を購読することを避けられる 」。 つまり 通知量の削減 と handler の単純化 の 2 つが同時に効く変更。 2 追加された対応リソース一覧 新たにイベント購読できるトピック Order 注文 Collection コレクション InventoryItem 在庫アイテム InventoryShipment 在庫の出荷 Location ロケーション メタフィールド変更を購読できるリソース リソース メタフィールド購読 備考 Product 対応 ProductVariant のメタフィールドも Product トピック経由 でサポート Order 対応 — Customer 対応 — Collection 対応 — Location 対応 — 上記以外 未対応 未対応トピックは引き続き webhooks を併用する（同じ shopify.app.toml 内で共存可） $app メタフィールドも通常のメタフィールドも、どちらもサポート対象。 アプリ予約の namespace と、マーチャントが定義した custom 等の namespace を同じ subscription で並べて指定できる。 3 仕組み図解 ： メタフィールド変更が handler に届くまで ポイントは ③ の query_variables 。「どのメタフィールドが変わったか」が変数としてクエリに渡るので、 1 つのクエリ定義で複数のメタフィールドを使い回せる 。トリガーごとにクエリを書き分ける必要がない。 4 設定例 ： shopify.app.toml 公式が示している「Product の 2 つのメタフィールドを狙い撃ちし、実際に変わった方を query_variables で取得する」例。 [events] api_version = "unstable" [[events.subscription]] handle = "product_material_sync" topic = "Product" actions = [ "update" ] triggers = [ "product.metafield(namespace: 'custom', key: 'material').value" , "product.metafield(namespace: '$app', key: 'sourcing_status').value" ] uri = "/events/product" query = """ query ProductMetafieldSync( $productId: ID! $metafieldNamespace: String! $metafieldKey: String! ) { product(id: $productId) { id title metafield(namespace: $metafieldNamespace, key: $metafieldKey) { namespace key value type } } } """ triggers フィールドパス式で指定 product.metafield(namespace: …, key: …).value という形。 custom のような通常の namespace と $app を同じ配列に並べられる。 query 受け取る形を自分で設計 GraphQL クエリを toml 内に書いて、ペイロードの形をアプリ側で決める。namespace / key を変数化しておけば複数トリガーで共用できる。 actions update を指定 この例では actions = ["update"] 。 handle はペイロードにもそのまま入るので、ルーティングの識別子として使える。 5 受け取るペイロードの構造 上記の設定で custom.material が変わったときに届くペイロード。 { "topic" : "Product" , "action" : "update" , "handle" : "product_material_sync" , "data" : { "product" : { "id" : "gid://shopify/Product/1234567890" , "title" : "Canvas Tote" , "metafield" : { "namespace" : "custom" , "key" : "material" , "value" : "Cotton" , "type" : "single_line_text_field" } } }, "fields_changed" : [ "product.metafield(namespace: 'custom', key: 'material').value" ], "query_variables" : { "productId" : "gid://shopify/Product/1234567890" , "metafieldNamespace" : "custom" , "metafieldKey" : "material" } } キー 中身 handler での使いどころ topic / action Product / update 大枠の振り分け handle subscription の handle どの購読設定由来かの識別 data toml に書いた query の結果 そのまま業務処理に投入できる fields_changed 実際に変わったフィールドパスの配列 複数トリガーを 1 subscription に束ねたときの分岐 query_variables クエリに渡された変数の実値 ログ・冪等キー・再取得時の入力として再利用 6 トリガーの粒度 ： 3 パターン A triggers を書かない 対応リソースのメタフィールド変更イベントも 受け取るようになる 。取りこぼしは無いが通知量は最大。 B 親トリガー（例 ： product） 親を指定した場合も、同様にメタフィールド変更イベントが届く。既存の購読設定のまま範囲が広がる形。 C ターゲット指定 namespace と key を明示した metafield トリガーを追加すると、 その変更だけ を受け取る。通知量は最小。 既存アプリは A / B に該当する可能性がある。 triggers 無し・親トリガーの購読は、この変更以降メタフィールド変更でも発火するようになる。想定外の呼び出し増を避けたいなら、C のターゲット指定へ書き換えるのが安全。 7 制約と注意点 アクセス制御はそのまま効く アプリが そのメタフィールドへのアクセス権を持っていること が、購読とデータ受信の条件。権限が無ければ購読もクエリ結果の受け取りもできない。 開発者プレビュー / unstable のみ Events は開発者プレビュー中で、 unstable API バージョンでのみ利用可能 。安定版での提供時期は記載なし。 未対応トピックは webhook 併用 まだ Events が対応していないトピックは、これまで通り webhooks を使う。 同じ shopify.app.toml の中で Events と webhooks を並記する のが公式の案内。 ProductVariant は Product 経由 バリアントのメタフィールドに独立したトピックがあるわけではなく、 Product トピックを通じてサポート される。購読設定は Product 側に書く。 レート制限・配信保証・リトライ・イベントの順序保証については、この告知には 記載なし 。本番運用の前提条件にする場合は Events のドキュメント側で確認すること。 8 技術者が押さえるべき5つのポイント 1. 「差分検出を handler に持たせない」設計に変わる これまで handler 内にあった「前回値をどこかに保持して比較する」ロジックが不要になる。 状態を持つ受信側から、状態を持たない受信側へ 。KVS への前回値キャッシュを撤去できる余地がある。 2. query_variables でクエリを共通化できる namespace / key を変数として受け取れるので、複数のメタフィールドトリガーを 1 つのクエリ定義 でさばける。トリガーが増えても toml が線形に膨らまない。 3. $app と通常 namespace を混在できる アプリ専用の $app メタフィールドと、マーチャント側の custom を同じ triggers 配列に書ける。「アプリの内部状態」と「マーチャントの入力」を同じ経路で拾える。 4. 権限設計がイベント設計に直結する アクセス権が無いメタフィールドは購読もデータ取得もできない。 スコープ／メタフィールドアクセスの申請漏れが「イベントが飛んでこない」という形で表面化する ので、切り分け時はまず権限を疑う。 5. 既存購読の「発火量が勝手に増える」側面に注意 triggers 無し、あるいは product のような親トリガーで購読しているアプリは、今回の変更で メタフィールド変更でも呼ばれるようになる 。エンドポイントの呼び出し回数・課金・ジョブキューの流入量が想定より増える可能性があるため、リリース後は受信量をモニタし、必要ならターゲット指定に絞り込む。 9 業務に活かせる3つのユースケース USE CASE 1 PIM / 基幹連携を「変わった属性だけ」同期する 課題 商品マスタ連携アプリが product/update を全部受け、handler 内で前回値と比較して「素材」「原産国」などの属性が変わったかを判定している。比較用の前回値ストアの保守と、無駄な受信の処理コストが重い。 打ち手 連携対象のメタフィールドだけを triggers にターゲット指定し、 query で変更されたメタフィールドの値と型だけを取得。 fields_changed で連携先のどのカラムを更新するか分岐する。 効果 受信イベント数の削減、前回値キャッシュの撤去、handler の単純化。連携ジョブの実行回数そのものが減る。 技術メモ ProductVariant のメタフィールドは Product トピック経由。バリアント属性の同期も同じ subscription に寄せられる。 USE CASE 2 注文のカスタム属性をトリガーに後続業務を起動する 課題 「配送指定」「ギフト設定」「審査ステータス」などを注文メタフィールドで管理しているが、値が入ったことを検知する手段がなく、ポーリングやバッチで拾っている。反映が遅い。 打ち手 Order のメタフィールド変更を購読し、対象の namespace / key に絞ってイベント駆動化。 $app メタフィールドを使えばアプリ自身が書いたステータス遷移も同じ仕組みで拾える。 効果 バッチ待ちの解消によるリードタイム短縮、ポーリング用の API コール削減、業務フローのイベント駆動化。 技術メモ アクセス権が無いメタフィールドは購読できない。アプリのメタフィールドアクセス設定を先に確認する。Order 以外に Customer / Collection / Location も同様に使える。 USE CASE 3 在庫・ロケーション連携を Events に寄せて webhook を整理する 課題 在庫・出荷・拠点まわりの連携を webhook で組んでおり、購読設定が散らばっている。必要なデータを得るために受信後に追加の API コールを重ねている。 打ち手 今回対応した InventoryItem / InventoryShipment / Location / Order / Collection を Events 側へ移し、 query で必要な項目を最初から取得する形に置き換える。未対応トピックは webhooks を同じ shopify.app.toml に残して併用する。 効果 受信後の追加 API コール削減、購読定義の集約、ペイロード形状をアプリ側で設計できることによる handler の簡素化。 技術メモ Events は開発者プレビュー中で unstable のみ。本番切り替えの前提にはせず、 検証環境で並走させて挙動と受信量を比較 する段取りが現実的。 10 提案で使える1行サマリ 「Shopify Events が Order・Collection・在庫・ロケーションに対応し、 メタフィールドの変更そのものを namespace / key 単位で購読できるようになった。 『全更新を受けて自分で差分を取る』handler を捨てて、必要なフィールドだけをイベント駆動で拾える。 ただし現時点では unstable の開発者プレビュー、未対応トピックは webhook 併用。」 + 関連ドキュメント Events shopify.dev/docs/apps/build/events Order shopify.dev/docs/api/events/latest/order Collection shopify.dev/docs/api/events/latest/collection InventoryItem shopify.dev/docs/api/events/latest/intentory-item ※ 原文記載のままの URL（原文に intentory-item という表記あり） InventoryShipment shopify.dev/docs/api/events/latest/inventory-shipment Location shopify.dev/docs/api/events/latest/location source ： shopify.dev / changelog / metafield-triggers-and-additional-topics-are-now-available-for-events published 2026-07-21