メタオブジェクトのアナリティクス分析対応がAdmin APIで設定可能に

10月 25, 2026

ADMIN API

メタオブジェクトのアナリティクス分析対応がAdmin APIで設定可能に

GraphQL Admin API 2027-01から、カスタムデータ型をアナリティクスクエリ対象に指定できる新ケイパビリティが追加

GraphQL Admin API バージョン 2027-01以降、メタオブジェクト定義に対してanalyticsQueryableケイパビリティの読み取りと設定が可能になりました。アプリ開発者は、カスタムデータ定義がアナリティクスでクエリ対象になるかどうかをAPIで制御できます。既存アプリへの影響はなく、この機能を利用したい場合のみ対応が必要です。

1変更内容の図解：Before / After

2業務に活かせる具体ユースケース

課題: 独自の「素材スペック」メタオブジェクトをShopifyアナリティクスで集計したいが、APIから対応状況を確認する手段がなかった
打ち手: MetaobjectCapabilities.analyticsQueryable.eligible をクエリして対象定義の適格性を確認し、MetaobjectCapabilityUpdateInput.analyticsQueryable でenabledをtrueに設定する
効果: カスタムデータをアナリティクスのクエリ対象に組み込み、素材軸での売上分析や在庫最適化レポートが構築できる
技術メモ: eligibleがtrueであることを必ず先に確認する。少なくとも1フィールドがアナリティクス互換型である必要がある

課題: 複数のメタオブジェクト定義を管理するアプリで、アナリティクス対応の有無をユーザーに一覧表示したい
打ち手: 定義一覧取得クエリに capabilities { analyticsQueryable { eligible enabled } } を追加し、管理画面でバッジ表示する
効果: 店舗オーナーがどのカスタムデータ型がアナリティクス対応済みかを一目で把握でき、設定変更のセルフサービス化が進む
技術メモ: API 2027-01以前のバージョンではフィールドが存在しないため、バージョン分岐処理を実装する必要がある

課題: メタオブジェクト作成フロー内でアナリティクス対応を設定しようとしたが、非対応定義への誤設定でエラーが発生しクライアント体験を損なう
打ち手: ミューテーション実行後のuserErrorsで CAPABILITY_NOT_ELIGIBLE を明示的にハンドリングし、「この定義はアナリティクス対応できません」と具体的なメッセージをUIに表示する
効果: 設定ミスによるサポート問い合わせを削減し、エラー理由が明確になることで開発者の調査コストも低減できる
技術メモ: MetaobjectUserErrorCode.CAPABILITY_NOT_ELIGIBLE が2027-01で新たに追加されたエラーコード。旧バージョンでは返らない

3技術者目線のポイント

🗓 対象APIバージョン

GraphQL Admin API 2027-01以降が必須。それ以前のバージョンでは analyticsQueryable フィールド・入力・列挙値・エラーコードのいずれも返されない。

📖 新規追加フィールド（読み取り）

MetaobjectCapabilities.analyticsQueryable
├ eligible: 定義がケイパビリティを利用できるか
└ enabled: 現在有効化されているか

✏️ 新規追加入力（書き込み）

Create時: MetaobjectCapabilityCreateInput.analyticsQueryable
Update時: MetaobjectCapabilityUpdateInput.analyticsQueryable
共通入力型: MetaobjectCapabilityAnalyticsQueryableInput.enabled

🔢 列挙値・エラーコードの追加

MetaobjectCapabilityType に ANALYTICS_QUERYABLE が追加。MetaobjectUserErrorCode に CAPABILITY_NOT_ELIGIBLE が追加（非対応定義への有効化試行時に返る）。

⚠️ eligibleの条件

定義のフィールドのうち少なくとも1つがアナリティクス互換型である必要がある。互換型の詳細は公式ドキュメントを参照（本記事では記載なし）。

🔄 既存アプリへの影響

既存アプリへの破壊的変更はなし。古いAPIバージョンを使い続ける場合は何もしなくてよい。メタフィールド定義と同等の制御体験がメタオブジェクトにも提供される形。

4APIクエリ例（構造早見表）

操作	使用するフィールド / 入力型	用途
読み取り	`MetaobjectCapabilities.analyticsQueryable { eligible enabled }`	定義の対応状況確認
作成時設定	`MetaobjectCapabilityCreateInput.analyticsQueryable`	定義作成と同時に有効化
更新時設定	`MetaobjectCapabilityUpdateInput.analyticsQueryable`	既存定義を後から有効化
有効化トグル	`MetaobjectCapabilityAnalyticsQueryableInput.enabled`	true / false で切り替え
エラーハンドリング	`MetaobjectUserErrorCode.CAPABILITY_NOT_ELIGIBLE`	非対応定義への設定をユーザーに通知