Analytics metric targets が GraphQL Admin API で読み書き可能に
原題: Analytics metric targets now available in the GraphQL Admin API
図解 ： Analytics metric targets が GraphQL Admin API に対応 Admin GraphQL API / 新機能 Analytics metric targets が GraphQL Admin API で読み書き可能に 「今四半期で総売上 $50K」のような数値目標（メトリクス目標）を、4 つの新オペレーションでアプリから作成・取得・更新・削除できるようになった。管理画面のマーチャントが見るのと同じ目標を、同じ API・同じルール・同じバリデーションで扱える。 このページの構成 30秒で理解 ： 何ができるようになったのか 仕組み図解 ： アプリ ↔ Shopify Analytics の流れ 4 つのオペレーション（CRUD） 押さえるべき仕様（Scope / 重複 / ステータス / フィルタ） ステータスは自動計算される 関連 ： ColumnDataType に追加された 2 つの enum 技術者が押さえるべき5つのポイント 業務に活かせる3つのユースケース 提案で使える1行サマリ 1 30秒で理解 ： 何ができるようになったのか マーチャントは Analytics で「今四半期で総売上 $50K」のような 数値目標（metric target） を設定し、ゲージで進捗を見られる。 今回、その目標を GraphQL Admin API の 4 オペレーションでアプリから作成・取得・更新・削除 できるようになった。管理画面の Targets を支えているのと同じ基盤を、アプリも使える。 これまで ： 管理画面の中だけ 目標の設定・進捗確認は Shopify 管理画面の Analytics 内で完結。外部の目標設定ツールや BI ツールからは触れなかった。 これから ： API で双方向 アプリが目標を読み書きでき、アプリが作った目標もマーチャントが作った目標と並んで管理画面・ダッシュボードのゲージに表示される。 2 仕組み図解 ： アプリ ↔ Shopify Analytics の流れ アプリが作った目標は、マーチャントが手で作った目標と 区別なく 、Targets 一覧ページの専用ゲージや各ダッシュボードに表示される。出自に関係なく、マーチャントは一貫して管理できる。 3 4 つのオペレーション（CRUD） Create analyticsTargetCreate メトリクス・目標値・期間・任意のフィルタ（例 ： 特定の販売チャネルや商品に限定）を指定して作成。 Read analyticsTargets ショップの目標を取得。ページネーションに対応。 Update analyticsTargetUpdate メトリクス・名前・目標値・期間・フィルタを変更できる。 Delete analyticsTargetsDelete 目標を削除。 削除した目標は復元できない。 analyticsTargetsDelete は名前が複数形（targets）。削除は不可逆なので、UI 上で確認ステップを挟む実装が安全。 4 押さえるべき仕様 項目 内容 スコープ read_reports と write_reports の権限が必要。 重複排除 目標は メトリクス・期間（date range）・フィルタ の組み合わせで一意に識別される。重複作成を試みると、必要な変更を案内する userError が返る。 ステータス計算 クエリ時点の期間と現在のメトリクス値から、 status フィールド（In progress / Achieved / Not achieved / Upcoming）を API が自動で導出 する。 フィルタ 各目標は ShopifyQL の WHERE 句に ディメンションベースのフィルタを 1 つ 持てる。演算子は = または IN 。 重複判定キーが「メトリクス × 期間 × フィルタ」と明確なので、 べき等な同期処理 を作りやすい。同じ 3 要素なら作成ではなく更新に倒す設計が定石。 5 ステータスは自動計算される status は保存値ではなく、クエリ時点の「期間」と「現在のメトリクス値」から毎回導出される。アプリ側でステータスを計算・保持する必要はない。 6 関連 ： ColumnDataType に追加された 2 つの enum API バージョン 2026-04 で、 ShopifyqlTableDataColumn の ColumnDataType に 2 つの値が追加された。これまで FLOAT を返していたメトリクスが対象。 2026-04 より前のバージョンを使う呼び出し元には影響しない。 新 enum UNITLESS_SCALAR 単位を持たない無次元のスコア値。Web パフォーマンス指標に適用 ： p50_cls / p75_cls / p90_cls / p99_cls （Cumulative Layout Shift のパーセンタイル）。 新 enum MULTIPLIER 比率・倍率を表す値（例 ： 3.2x）。 shop_campaign_return_on_ad_spend （広告費用対効果 / ROAS）に適用。 これらの指標を FLOAT 前提でパースしているコードは、2026-04 へ上げる際に UNITLESS_SCALAR / MULTIPLIER のハンドリング追加が必要。表示フォーマット（"3.2x" 等）も合わせて見直す。 7 技術者が押さえるべき5つのポイント 1. 必須スコープは 2 つ 読み取りでも read_reports 、作成・更新・削除には write_reports が要る。アプリのアクセススコープ申請に忘れず含める。 2. 一意キーは 3 要素 「メトリクス × 期間 × フィルタ」で重複判定。同一キーの作成は userError 。同期処理は「無ければ作る／有れば更新」に倒すと衝突しない。 3. status は読むだけ In progress / Achieved / Not achieved / Upcoming はクエリ時に自動導出。自前で計算・保存しない。期間や値が動けば自然に切り替わる。 4. フィルタは 1 つ・演算子は = / IN ShopifyQL の WHERE に持てるディメンションフィルタは 1 つだけ。複数条件の AND は不可。販売チャネル別や商品別の目標は、目標を分けて作る。 5. アプリ製の目標とマーチャント製の目標は同じ土俵 アプリが作った目標も Targets 一覧・ダッシュボードに同じゲージで出て、マーチャントが直接編集・削除できる。 アプリ外で勝手に上書きされうる前提 で、同期は冪等かつ差分検出できる設計にしておく。 analyticsTargets はページネーション対応なので全件走査も可能。 8 業務に活かせる3つのユースケース USE CASE 1 目標設定アプリ ： 過去実績やベンチマークから「賢い初期値」を提案 課題 マーチャントが目標値をゼロから決めるのは難しく、勘で置いた目標は形骸化しやすい。 打ち手 過去パフォーマンスや業界ベンチマークを基に、 analyticsTargetCreate でスマートな初期目標を自動作成。期間・メトリクスもまとめて提案。 効果 マーチャントは設定の手間なく、根拠のある目標を持てる。作った目標は管理画面のゲージにそのまま表示される。 技術メモ 「メトリクス × 期間 × フィルタ」が重複キー。再提案時は作成ではなく analyticsTargetUpdate に倒し、 userError を避ける。 USE CASE 2 レポーティング / BI ツール ： 自社の可視化に「Shopify と一致した目標」を重ねる 課題 BI ダッシュボードに独自の目標線を引くと、Shopify 管理画面の数字と食い違い、マーチャントが混乱する。 打ち手 analyticsTargets でマーチャントの目標を読み取り、自社グラフに進捗・達成状況を重ねて表示。 効果 Shopify と完全に一致した目標・進捗を見せられ、ツール間の数字のズレをなくせる。 技術メモ status は API が自動導出するので、自前計算せずそのまま使う。件数が多い店舗はページネーションで全件取得。 USE CASE 3 代理店ダッシュボード ： 複数クライアント店舗の目標を一括で設定・監視 課題 複数のクライアント店舗の目標管理を、各店の管理画面に個別ログインして手作業でやっている。 打ち手 4 オペレーションでプログラム的に目標を作成・更新・監視。 analyticsTargets を横断で取得し、未達（Not achieved）の店舗を集約表示。 効果 店舗横断で目標の設定・進捗追跡を自動化。アラートや週次レポートにも転用できる。 技術メモ 各店舗で read_reports / write_reports の付与が前提。削除は不可逆なので、店舗横断の一括 analyticsTargetsDelete は確認フローを必須に。 9 提案で使える1行サマリ 「マーチャントが Analytics で設定する 数値目標 を、GraphQL Admin API の 4 オペレーションで アプリから読み書き できるように。 目標設定 / BI / プランニング / 代理店ツールが、管理画面と 完全に一致した目標とゲージ を、同じ API・ルール・バリデーションで扱える。」 source ： shopify.dev / changelog / analytics-metric-targets-now-available-in-the-graphql-admin-api generated 2026-05-24 --- ファイル書き込みとAskは許可されなかったので、生成HTMLをそのまま出力しました。リポジトリに取り込む場合の想定情報も置いておきます（許可いただければ私が実行します）: - **保存先**: `site/public/raw/260429_analytics-metric-targets-now-available-in-the-graphql-admin-api.html`（公開日 2026-04-29 UTC → `260429_` + URL スラッグ） - **`content/index.json` 追記エントリ案**: - `source`: `"developer"` / `sourceLabel`: `"Developer Changelog"` / `tag`: `"Developer Changelog"` - `tags`: `["Admin GraphQL API","Analytics","Metric Targets","ShopifyQL","ColumnDataType","ROAS","Core Web Vitals","API 2026-04"]` - `categories`: `["analytics","admin-api"]` 「書き込みに進めて」と言っていただければ、ファイル作成と `index.json` への登録（上記メタ）まで行います。