dx-app-analytics-query

アプリ分析

このスキルがタスクを担当する場合

次の作業には dx-app-analytics-query を使用します。

• REST／sObject API を介した AppAnalyticsQueryRequest レコードの作成
• Metadata API を介した AppAnalyticsSettings の設定（シミュレーションモード、オプトアウト）
• クエリのライフサイクルの把握：New → Pending → Complete → Expired → Failed
• dataType 値の選択：PackageUsageSummary、PackageUsageLog、SubscriberSnapshot
• 分析データのダウンロードに関するファイル形式と圧縮オプション
• startTime、endTime、availableSince による時間範囲のフィルタリング
• 失敗または期限切れになった分析クエリのトラブルシューティング

次の場合は、ほかのスキルに委任します。

• 標準的な CRM SOQL クエリの実行 → platform-soql-query
• Data Cloud SQL または DMO の操作 → retrieving-datacloud
• 標準オブジェクトに関するレポート／ダッシュボードの作成 → reporting skills
• 汎用のメタデータ XML のデプロイまたは取得 → deploying-metadata / retrieving-metadata

---

利用可能な型

AppAnalyticsQueryRequest（REST／sObject API）

ISV パートナーが、管理パッケージの使用状況分析データを ISV Intelligence Data Lake から取得するために使用する非同期クエリリクエストです。レコードは POST /services/data/vXX.0/sobjects/AppAnalyticsQueryRequest で作成し、GET /services/data/vXX.0/sobjects/AppAnalyticsQueryRequest/<id> でポーリングします。システムがクエリを処理し、完了すると署名付きダウンロード URL を提供します。

フィールド（14 プロパティ）：

フィールド	型	説明
DataType	string（フィルタリング可能）	分析データの種類。値：PackageUsageSummary、PackageUsageLog、SubscriberSnapshot
RequestState	string（フィルタリング可能）	処理状況。値：New、Pending、Complete、Expired、Failed、NoData、Delivered
StartTime	string	リクエストしたデータの時間範囲の開始時刻
EndTime	string	時間範囲の終了時刻。時刻がちょうど 1 時間になるように設定してください
AvailableSince	string	この時刻以降（時刻を含む）にインデックスされたデータにクエリを限定します。増分取得に使用します
PackageIds	string	管理パッケージ ID（033 プレフィックス）のカンマ区切りリスト
OrganizationIds	string	結果を絞り込むための購読者組織 ID のカンマ区切りリスト
DownloadUrl	string	結果をダウンロードするための署名付き URL。RequestState が Complete になると設定されます
DownloadSize	long	結果データファイルのサイズ（バイト単位）
DownloadExpirationTime	string	ダウンロード URL の有効期限
FileType	string（フィルタリング可能）	出力形式。値：csv、parquet
FileCompression	string（フィルタリング可能）	圧縮方式。値：none、gzip、snappy
QuerySubmittedTime	string	Data Lake にクエリが送信された時刻
ErrorMessage	string	クエリ失敗時の診断メッセージ

AppAnalyticsSettings（Metadata API）

シミュレーションモードとオプトアウトの動作を制御する ISV App Analytics の設定です。Metadata API（sf project deploy）または Tooling API を介してデプロイします。

フィールド（2 プロパティ）：

フィールド	型	説明
enableSimulationMode	boolean（フィルタリング可能）	true の場合、実際の購読者データを使わず、統合テスト用のサンプル使用状況ログをクエリできます
enableAppAnalyticsOptOut	boolean（フィルタリング可能）	true の場合、この購読者組織は AppExchange App Analytics のデータ収集をオプトアウトします

---

リクエストのライフサイクル

New → Pending → Complete → (download within expiration window)
                         → Expired (download URL no longer valid)
                         → Delivered (download confirmed received)
         → Failed (check errorMessage)
         → NoData (no matching records for the criteria)

---

よくあるパターン

Package Usage Summary のクエリ（過去 7 日間）

REST API を介してレコードを作成します。

POST /services/data/v60.0/sobjects/AppAnalyticsQueryRequest
Content-Type: application/json

{
  "DataType": "PackageUsageSummary",
  "StartTime": "<7-days-ago>T00:00:00Z",
  "EndTime": "<today-on-hour-boundary>T00:00:00Z",
  "PackageIds": "033XXXXXXXXXXXX",
  "FileType": "csv",
  "FileCompression": "gzip"
}

RequestState が Complete になるまで GET でレコードをポーリングし、その後 DownloadUrl からダウンロードします。

増分データ取得

すでに取得したデータを再ダウンロードしないよう、最後にクエリが正常に完了した時刻を AvailableSince に設定します。

テスト用のシミュレーションモードを有効化

Metadata API を介して enableSimulationMode: true を指定した AppAnalyticsSettings をデプロイすると、実際の購読者を使わずにサンプルデータをクエリできます。

---

注意すべき重要なポイント

• AppAnalyticsQueryRequest はsObjectです。レコードの作成とポーリングには、REST Data API（/sobjects/AppAnalyticsQueryRequest）を使用してください。Metadata API XML デプロイメントは使用しないでください。
• AppAnalyticsQueryRequest には Apex トリガーがなく、カスタムオブジェクトやフローを経由することもありません。
• ダウンロード URL は有効期限が切れます。ダウンロードを試みる前に、必ず DownloadExpirationTime を確認してください。
• 一貫した結果を得るには、EndTime を毎時の境界に設定してください。
• AvailableSince は開始時刻を含みます。正確にそのタイムスタンプでインデックスされたデータも含まれます。
• PackageIds には 04t（パッケージバージョン）ID ではなく、033 で始まる ID を使用します。
• データは ISV Intelligence Data Lake インフラストラクチャによって非同期で処理されます。同期クエリのオプションはありません。
• 大規模なデータセットでは、FileType: parquet と FileCompression: snappy の組み合わせが最適なパフォーマンスを実現します。

---

出力形式

Analytics task: <query / configure / troubleshoot>
Data type: <PackageUsageSummary / PackageUsageLog / SubscriberSnapshot>
Package IDs: <033-prefixed IDs>
Time range: <startTime> to <endTime>
File format: <csv|parquet> / <none|gzip|snappy>
Request state: <current state>
Next step: <poll for completion / download / investigate failure>