記事のサマリー（TL;DR）
- GraphQL Admin API version 2027-01から、metaobject定義に対して analyticsQueryable 機能の読み取りと設定ができるようになりました。
- 対象は、metaobject定義を作成・更新・参照するアプリです。アプリがmetaobject定義を分析でクエリ可能にするかどうかを制御したい場合以外、対応は不要です。
- この機能によりmetaobject定義はmetafield定義と同様の扱いとなり、カスタムデータ型を分析に表示するかどうかを一貫して制御できるようになります。
対象アプリと対応要否
この変更は、GraphQL Admin API version 2027-01以降を使用してmetaobject定義を作成・更新・参照するアプリに適用されます。それより前のバージョンを使用しているアプリでは、analyticsQueryableフィールド、入力、enum値、エラーコードのいずれも表示されません。既存のアプリは、metaobject定義の分析クエリ可能性に対応したい場合を除き、変更の必要はありません。
詳細
変更内容
GraphQL Admin APIは、metaobject定義向けにanalytics queryable機能を新たに公開しました。MetaobjectCapabilities.analyticsQueryable を読み取ることができ、これには以下が含まれます。
eligible：metaobject定義がこの機能を使用できるかどうか。定義内の少なくとも1つのフィールドが分析互換の型を使用している場合に対象となります。enabled：この機能が現在有効になっているかどうか。
また、metaobject定義の作成・更新時に、以下を使って機能を設定することもできます。
MetaobjectCapabilityCreateInput.analyticsQueryableMetaobjectCapabilityUpdateInput.analyticsQueryableMetaobjectCapabilityAnalyticsQueryableInput.enabled
MetaobjectCapabilityType enumには ANALYTICS_QUERYABLE が追加され、MetaobjectUserErrorCode には、機能を有効化できない定義向けに CAPABILITY_NOT_ELIGIBLE が追加されました。
この変更が重要な理由
これにより、あるmetaobject定義が分析でクエリ可能な対象かどうかを判断し、公開されているGraphQL Admin APIを通じてその機能を有効化できるようになります。これはmetaobject定義をmetafield定義と同等の扱いに揃えるもので、どのカスタムデータ型を分析に表示するかについて一貫した制御が可能になります。
対応方法
対応は必須ではありません。この機能を利用したい場合は、以下の手順を行います。
- アプリをGraphQL Admin API version 2027-01以降に更新する。
- metaobject定義のクエリまたはミューテーションを更新し、analyticsQueryableを含める。例えば、metaobject定義の機能を読み取る場合は次のように記述します。
capabilities {
analyticsQueryable {
eligible
enabled
}
}
- metaobject定義を作成・更新する際は、機能の入力で
analyticsQueryable.enabledを設定する。 - まず
eligibleを確認し、ミューテーションのユーザーエラーでCAPABILITY_NOT_ELIGIBLEを処理する。この方法を使って、定義がこの機能に対応しているかを確認し、対応していない場合は明確なフィードバックを返すようにします。
関連ドキュメント
- GraphQL Admin API reference
- Metaobjects in Shopify apps