コマーシャル マーケットプレースのプログラムによるアクセス パラダイム
この図は、新しいレポート テンプレートを作成し、カスタム レポートのスケジュールを設定して、エラー データを取得するために使用される API 呼び出しパターンを示しています。
図 1: API 呼び出しパターンの大まかなフロー
この一覧で、図 1 の詳細を説明します。
- クライアント アプリケーションでは、レポート クエリの作成 API を呼び出すことによって、カスタム レポート スキーマ/テンプレートを定義できます。 または、システム クエリの一覧からレポート テンプレート (
QueryId) を使用することもできます。 - 成功した場合、レポート テンプレートの作成 API から
QueryIdが返されます。 - その後、クライアント アプリケーションでは、
QueryIDと共にレポートの開始日、繰り返し間隔、繰り返し回数、およびオプションのコールバック URI を使用して、レポートの作成 API を呼び出します。 - 成功した場合、レポートの作成 API から
ReportIDが返されます。 - クライアント アプリケーションでは、レポート データのダウンロード準備が完了するとすぐに、コールバック URI で通知を受け取ります。
- その後、クライアント アプリケーションで レポート実行状態の取得 API を使用し、
Report IDと日付範囲を指定してレポートの状態のクエリを実行します。 - 成功すると、レポートのダウンロード リンクが返され、アプリケーションでデータのダウンロードを開始できます。
レポート クエリ言語の仕様
レポートの作成に使用できるシステム クエリが用意されていますが、ビジネス ニーズに基づいて独自のクエリを作成することもできます。 カスタム クエリの詳細については、「カスタム クエリの仕様」を参照してください。
レポート クエリの作成 API
この API では、列およびメトリックのエクスポート元となるデータセットを定義するカスタム クエリを作成できます。 この API は、ビジネス ニーズに基づいて新しいレポート テンプレートを作成するための柔軟性を提供します。
また、用意されているシステム クエリを使用することもできます。 カスタム レポート テンプレートが必要ない場合は、提供するシステム クエリの QueryId を使用して、レポートの作成 API を直接呼び出すことができます。
次の例では、過去 1 か月間の ISVUsage データセットから有料 SKU の正規化された使用と推定料金を取得するカスタム クエリを作成する方法を示します。
要求構文
| 認証方法 | 要求 URI |
|---|---|
| POST | https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledQueries |
要求ヘッダー
| Header | 型 | 説明 |
|---|---|---|
| 承認 | string | 必須。 Microsoft Entra アクセス トークン。 形式は Bearer <token> です。 |
| Content-Type | string |
application/JSON |
パス パラメーター
なし
クエリ パラメーター
なし
要求ペイロードの例
{
"Name": "ISVUsageQuery",
"Description": "Normalized Usage and Estimated Financial Charges for PAID SKUs",
"Query": "SELECT UsageDate, NormalizedUsage, EstimatedExtendedChargePC FROM ISVUsage WHERE SKUBillingType = 'Paid' ORDER BY UsageDate DESC TIMESPAN LAST_MONTH"
}
用語集
次の表では、要求ペイロードの要素の主な定義を示しています。
| パラメーター | 必須 | 説明 | 使用できる値 |
|---|---|---|---|
Name |
はい | クエリのわかりやすい名前 | string |
Description |
いいえ | 作成されたクエリの説明 | string |
Query |
はい | ビジネス ニーズに基づいて文字列をクエリする | string |
Note
カスタム クエリの例については、サンプル クエリを参照してください。
サンプル応答
応答ペイロードは、次のように構成されます。
応答コード: 200、400、401、403、500
応答ペイロードの例:
{
"value": [
{
"queryId": "78be43f2-e35f-491a-8cd5-78fe14194f9c",
"name": " ISVUsageQuery",
"description": "Normalized Usage and Estimated Financial Charges for PAID SKUs",
"query": " SELECT UsageDate, NormalizedUsage, EstimatedExtendedChargePC FROM ISVUsage WHERE SKUBillingType = 'Paid' ORDER BY UsageDate DESC TIMESPAN LAST_MONTH",
"type": "userDefined",
"user": "142344300",
"createdTime": "2024-01-06T05:38:34Z"
}
],
"totalCount": 1,
"message": "Query created successfully",
"statusCode": 200
}
用語集
次の表では、応答の要素の主な定義を示しています。
| パラメーター | 説明 |
|---|---|
QueryId |
作成されたクエリの汎用一意識別子 (UUID) |
Name |
クエリの作成時に要求ペイロードに指定された名前 |
Description |
クエリの作成時に要求ペイロードで指定された説明 |
Query |
クエリの作成時に要求ペイロードで提供されるカスタム レポート クエリ |
Type |
手動で作成されたクエリに対して設定するuserDefined |
User |
クエリの作成に使用するユーザー ID |
CreatedTime |
クエリが作成された UTC 時刻。 形式: yyyy-MM-ddTHH:mm:ssZ |
TotalCount |
Value 配列内のレコードの数 |
StatusCode |
結果コード 200、400、401、403、500 の値になる可能性があります |
message |
API の実行からのステータス メッセージ |
レポートの作成 API
カスタム レポート テンプレートを正常に作成し、QueryID を レポート クエリの作成応答の一部として受け取ると、この API を呼び出して一定の間隔でクエリを実行するようにスケジュールを設定できます。 配信するレポートの頻度とスケジュールを設定できます。 用意されているシステム クエリの場合は、QueryId を使用してレポートの作成 API を呼び出すこともできます。
要求構文
| 認証方法 | 要求 URI |
|---|---|
| POST | https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledReport |
要求ヘッダー
| Header | 型 | 説明 |
|---|---|---|
| 承認 | string | 必須。 Microsoft Entra アクセス トークン。 形式は Bearer <token> です。 |
| Content Type | string | application/JSON |
パス パラメーター
なし
クエリ パラメーター
なし
要求ペイロードの例
{
"ReportName": "ISVUsageReport",
"Description": "Normalized Usage and Estimated Financial Charges for PAID SKUs",
"QueryId": "78be43f2-e35f-491a-8cd5-78fe14194f9c ",
"StartTime": "2021-01-06T19:00:00Z ",
"executeNow": false,
"RecurrenceInterval": 48,
"RecurrenceCount": 20,
"Format": "csv",
"CallbackUrl": "https://<SampleCallbackUrl>"
"callbackMethod": "GET",
}
用語集
次の表では、要求ペイロードの要素の主な定義を示しています。
| パラメーター | 必須 | 説明 | 使用できる値 |
|---|---|---|---|
ReportName |
はい | レポートに割り当てられたわかりやすい名前 | String |
Description |
いいえ | 作成されたレポートの説明 | String |
QueryId |
はい | レポート生成に使用する必要があるクエリ ID | String |
StartTime |
はい | レポート生成が開始される UTC タイムスタンプ。 yyyy-MM-ddTHH:mm:ssZ の形式にする必要があります | String |
ExecuteNow |
いいえ | このパラメーターは、1 回だけ実行されるレポートを作成するために使用する必要があります。 StartTimeにRecurrenceIntervalRecurrenceCountEndTime設定されている場合は無視されます。true |
Boolean |
QueryStartTime |
いいえ | 必要に応じて、データを抽出するクエリの開始時刻を指定します。 このパラメーターは、ExecuteNow が true に設定されている 1 回限りの実行レポートにのみ適用されます。 yyyy-MM-ddTHH:mm:ssZ の形式にする必要があります |
文字列としてのタイムスタンプ |
QueryEndTime |
いいえ | 必要に応じて、データを抽出するクエリの終了時刻を指定します。 このパラメーターは、ExecuteNow が true に設定されている 1 回限りの実行レポートにのみ適用されます。 yyyy-MM-ddTHH:mm:ssZ の形式にする必要があります |
文字列としてのタイムスタンプ |
RecurrenceInterval |
はい | レポートが生成される頻度 (時間単位)。 最小値は 1、最大値は 17520 です | Integer |
RecurrenceCount |
はい | 生成されるレポートの数。 制限は繰り返し間隔によって異なります | Integer |
Format |
いいえ | エクスポートされるファイルのファイル形式。 既定の形式は CSV です | CSV/TSV |
CallbackUrl |
いいえ | 必要に応じてコールバック先として構成できるパブリックにアクセス可能な URL | String |
CallbackMethod |
いいえ | コールバック URL で構成できる Get/Post メソッド | GET/POST |
EndTime |
はい | レポート生成が終了する UTC タイムスタンプ。 yyyy-MM-ddTHH:mm:ssZ の形式にする必要があります | String |
Note
レポートの作成時に、いずれかEndTimeまたは組み合わせRecurrenceCountRecurrenceIntervalが必須です。
サンプル応答
応答ペイロードは、次のように構成されます。
応答コード: 200、400、401、403、404、500
応答ペイロード:
{
"Value": [
{
"reportId": "72fa95ab-35f5-4d44-a1ee-503abbc88003",
"reportName": "ISVUsageReport",
"description": "Normalized Usage and Estimated Financial Charges for PAID SKUs",
"queryId": "78be43f2-e35f-491a-8cd5-78fe14194f9c",
"query": "SELECT UsageDate, NormalizedUsage, EstimatedExtendedChargePC FROM ISVUsage WHERE SKUBillingType = 'Paid' ORDER BY UsageDate DESC TIMESPAN LAST_MONTH",
"user": "142344300",
"createdTime": "2024-01-06T05:46:00Z",
"modifiedTime": null,
"startTime": "2024-01-06T19:00:00Z",
"reportStatus": "Active",
"recurrenceInterval": 48,
"recurrenceCount": 20,
"callbackUrl": "https://<SampleCallbackUrl>",
"callbackMethod": "GET",
"format": "csv"
}
],
"TotalCount": 1,
"Message": "Report created successfully",
"StatusCode": 200
}
用語集
次の表では、応答の要素の主な定義を示しています。
| パラメーター | 説明 |
|---|---|
ReportId |
作成したレポートの汎用一意識別子 (UUID) |
ReportName |
レポートの作成時に要求ペイロードに指定された名前 |
Description |
レポートの作成時に要求ペイロードに指定された説明 |
QueryId |
レポートの作成時に要求ペイロードに指定されたクエリ ID |
Query |
このレポートに対して実行されるクエリ テキスト |
User |
レポートの作成に使用するユーザー ID |
CreatedTime |
レポートが作成された UTC 時刻で、形式は yyyy-MM-ddTHH:mm:ssZ |
ModifiedTime |
レポートが最終更新された UTC 時刻で、形式は yyyy-MM-ddTHH:mm:ssZ |
ExecuteNow |
レポートの作成時に要求ペイロードに指定された ExecuteNow パラメーター |
queryStartTime |
レポートの作成時に要求ペイロードに指定されたクエリの開始時刻。 これは、"True" に設定されている場合 ExecuteNow にのみ適用されます。 |
queryEndTime |
レポートの作成時に要求ペイロードに指定されたクエリの終了時刻。 これは、"True" に設定されている場合 ExecuteNow にのみ適用されます。 |
StartTime |
レポートの作成中に要求ペイロードに指定された開始時刻 |
ReportStatus |
レポート実行の状態。 有効な値は、Paused、Active、および Inactive です。 |
RecurrenceInterval |
レポートの作成中に要求ペイロードに指定された繰り返し間隔 |
RecurrenceCount |
レポートの繰り返し数をメインする |
CallbackUrl |
レポートの作成時に要求ペイロードに指定されたコールバック URL |
CallbackMethod |
レポートの作成時に要求ペイロードで提供されるコールバック メソッド |
Format |
レポートの作成時に要求ペイロードに指定されたレポート ファイルの形式 |
EndTime |
レポートの作成中に要求ペイロードに指定された終了時刻。 これは、"True" に設定されている場合 ExecuteNow にのみ適用されます。 |
TotalRecurrenceCount |
RecurrenceCount レポートの作成時に要求ペイロードに指定された |
nextExecutionStartTime |
次のレポートの実行が開始される UTC タイムスタンプ |
TotalCount |
Value 配列内のレコードの数 |
StatusCode |
結果コード。 200、400、401、403、500 の値になる可能性があります |
message |
API の実行からのステータス メッセージ |
レポート実行の取得 API
このメソッドを使用すると、レポートの作成 API から受信した ReportId を使用して、レポート実行状態のクエリを実行できます。 レポートをダウンロードする準備ができている場合、このメソッドでレポートのダウンロード リンクが返されます。 それ以外の場合は、メソッドから状態が返されます。 また、この API を使用して、特定のレポートで発生したすべての実行を取得することもできます。
重要
この API には、既定のクエリ パラメーターとして executionStatus=Completed および getLatestExecution=true が設定されています。 このため、レポート実行が最初に成功する前にこの API を呼び出すと、404 が返されます。 保留中の実行は、executionStatus=Pending を設定することによって取得できます。
要求構文
| 認証方法 | 要求 URI |
|---|---|
| Yammer の入手 | https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledReport/execution/{reportId}?executionId={executionId}&executionStatus={executionStatus}&getLatestExecution={getLatestExecution} |
要求ヘッダー
| Header | 型 | 説明 |
|---|---|---|
| 承認 | string | 必須。 Microsoft Entra アクセス トークン。 形式は Bearer <token> です。 |
| コンテンツ タイプ | string | application/json |
パス パラメーター
なし
クエリ パラメーター
| パラメーター名 | 必須 | タイプ | 説明 |
|---|---|---|---|
reportId |
イエス | string | この引数で指定された reportId を持つレポートのみの実行の詳細を取得するフィルター。 |
executionId |
いいえ | string | この引数で指定された executionId を持つレポートのみの詳細を取得するフィルター。 複数 executionIds を指定するには、セミコロン ";" で区切ります。 |
executionStatus |
いいえ | string/enum | この引数で指定された executionStatus を持つレポートのみの詳細を取得するフィルター。有効な値は、 Pending、Running、Paused、Completed です 既定値は Completed です。 |
getLatestExecution |
いいえ | boolean | この API から最新のレポート実行の詳細が返されます。 既定では、このパラメーターは true に設定されます。 このパラメーターの値を false として渡すことを選択した場合、この API から最後の 90 日間の実行インスタンスが返されます。 |
要求ペイロード
なし
サンプル応答
応答ペイロードは、次のように構成されます。
応答コード: 200、400、401、403、404、500
応答ペイロードの例:
{
"value": [
{
"executionId": "a0bd78ad-1a05-40fa-8847-8968b718d00f",
"reportId": "72fa95ab-35f5-4d44-a1ee-503abbc88003",
"recurrenceInterval": 4,
"recurrenceCount": 10,
"callbackUrl": null,
"format": "csv",
"executionStatus": "Completed",
"reportAccessSecureLink": "https://<path to report for download>",
"reportExpiryTime": null,
"reportGeneratedTime": "2021-01-13T14:40:46Z"
}
],
"totalCount": 1,
"message": null,
"statusCode": 200
}
レポートの実行が完了すると、実行状態 Completed が表示されます。 reportAccessSecureLink で URL を選択して、レポートをダウンロードできます。
用語集
応答内の要素の主な定義。
| パラメーター | 説明 |
|---|---|
ExecutionId |
実行インスタンスの汎用一意識別子 (UUID) |
ReportId |
実行インスタンスに関連付けられているレポート ID |
RecurrenceInterval |
レポートの作成中に指定された繰り返し間隔 |
RecurrenceCount |
レポートの作成中に指定された繰り返し回数 |
CallbackUrl |
実行インスタンスに関連付けられているコールバック URL |
CallbackMethod |
レポートの作成時に要求ペイロードで提供されるコールバック メソッド |
Format |
実行の終了時に生成されるファイルの形式 |
ExecutionStatus |
レポート実行インスタンスの状態。 有効な値は、 Pending、Running、Paused、Completed です |
ReportLocation |
レポートがダウンロードされる場所。 |
ReportAccessSecureLink |
レポートに安全にアクセスできるリンク |
ReportExpiryTime |
レポート リンクの有効期限が切れる UTC 時刻で、形式は yyyy-MM-ddTHH:mm:ssZ |
ReportGeneratedTime |
レポートが生成された UTC 時刻で、形式は yyyy-MM-ddTHH:mm:ssZ |
EndTime |
レポートの作成中に要求ペイロードに指定された終了時刻。 これは、"True" に設定されている場合 ExecuteNow にのみ適用されます。 |
TotalRecurrenceCount |
RecurrenceCount レポートの作成時に要求ペイロードに指定された |
nextExecutionStartTime |
次のレポートの実行が開始される UTC タイムスタンプ |
TotalCount |
Value 配列内のデータセットの数 |
StatusCode |
結果コード 200、400、401、403、404、500 の値になる可能性があります |
message |
API の実行からのステータス メッセージ |
次のステップ
- Swagger API URL を使用して API を試すことができます
- Marketplace インサイト レポートの最初の API 呼び出しを行う
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示