dx-app-analytics-use

アプリ分析

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

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

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

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

• 標準の CRM SOQL クエリを実行する → querying-soql
• 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	時間範囲の終了時刻。時刻の境界に設定してください
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>