プログラムによるアクセスのパラダイム
この図は、新しいレポート テンプレートを作成し、カスタム レポートのスケジュールを設定して、エラー データを取得するために使用される API 呼び出しパターンを示しています。
図 1: API 呼び出しパターンの大まかなフロー
この一覧で、図 1 の詳細を説明します。
- クライアント アプリケーションでは、レポート クエリの作成 API を呼び出すことによって、カスタム レポート スキーマ/テンプレートを定義できます。 または、「パートナーの分析情報プログラムによるアクセスのためのシステム クエリの一覧」にあるレポート テンプレート ライブラリサンプルからレポート テンプレート (QueryId) を選択することもできます。
- 成功すると、レポート クエリの作成 API は QueryId を返します。
- 次に、クライアント アプリケーションは、QueryId とレポートの開始日、繰り返し間隔、繰り返し、およびオプションのコールバック URI を使用して、レポートの作成 API を呼び出す必要があります。
- 成功すると、レポート の作成 API から ReportId が返されます。
- クライアント アプリケーションでは、レポート データのダウンロード準備が完了するとすぐに、コールバック URI で通知を受け取ります。
- その後、クライアント アプリケーションは Get Report Executions API を使用して、レポート ID と日付範囲を使用してレポートの状態を照会します。
- 成功すると、レポートのダウンロード リンクが返され、アプリケーションでデータのダウンロードを開始できます。
レポート クエリ言語の仕様
レポートの作成 に使用できる システム クエリを提供しますが、ビジネス ニーズに基づいて独自のクエリを作成することもできます。 カスタム クエリの詳細については、「カスタム クエリの仕様」を参照してください。
レポート クエリの作成 API
この API では、列およびメトリックのエクスポート元となるデータセットを定義するカスタム クエリを作成できます。 この API は、ビジネス ニーズに基づいて新しいレポート テンプレートを作成するための柔軟性を提供します。
また、用意されているシステム クエリを使用することもできます。 カスタム レポート テンプレートが必要ない場合は、指定されたシステム クエリの QueryId を使用してレポート作成 API を直接呼び出すことができます。
次の例は、先月の売上で上位 10 人の顧客を取得するカスタム クエリを作成する方法を示しています。
要求の構文
| メソッド | 要求 URI |
|---|---|
| POST | https://api.partnercenter.microsoft.com/insights/v1/mpn/ScheduledQueries |
要求ヘッダー
| ヘッダー | 「」と入力します | 説明 |
|---|---|---|
| 承認 | 文字列 | 必須。 Microsoft Entra アクセス トークン。 形式は Bearer <token> です。 |
| Content-Type | 文字列 | Application/JSON |
パス パラメーター
なし
Query parameter (クエリ パラメーター)
なし
要求ペイロードのサンプル
{
"Name": "CustomersRevenueQuery",
"Description": "Query to get top 10 customers by revenue for last month",
"Query": "SELECT CustomerName, Product, BilledRevenueUSD FROM CustomersAndTenants ORDER BY BilledRevenueUSD LIMIT 10 TIMESPAN LAST_MONTH"
}
要求用語集
次の表では、要求ペイロードの要素の主な定義を示しています。
| パラメーター | 必須 | 説明 | 使用できる値 |
|---|---|---|---|
| 名前 | はい | クエリのフレンドリ名 | 文字列 |
| 説明 | なし | クエリから返される内容の説明 | 文字列 |
| クエリ | はい | レポート クエリ文字列 | データ型: string ビジネス ニーズに基づくカスタム クエリ |
Note
カスタム クエリのサンプルについては、「サンプル クエリの例」に関するページを参照してください。
サンプル応答
応答ペイロードは、次のように構成されます。
応答コード：200、400、401、403、500
応答ペイロードの例:
{
"value": [
{
"queryId": "ec8366a4-d96e-4194-8c37-d5dbc0639033",
"name": "CustomersRevenueQuery",
"description": "Query to get top 10 customers by revenue for last month",
"query": "SELECT CustomerName, Product, BilledRevenueUSD FROM CustomersAndTenants ORDER BY BilledRevenueUSD LIMIT 10 TIMESPAN LAST_MONTH",
"type": "userDefined",
"user": "GAUser@PITEST2.onmicrosoft.com",
"createdTime": "2021-03-30T12:52:39Z"
}
],
"nextLink": null,
"totalCount": 1,
"message": "Query created successfully",
"statusCode": 200,
"dataRedacted": false
}
応答用語集
次の表では、要求ペイロードの要素の主な定義を示しています。
| パラメーター | 説明 |
|---|---|
| QueryId | 作成したクエリの汎用一意識別子 (UUID) |
| 名前 | 要求ペイロード内のクエリに指定されたフレンドリ名 |
| 説明 | クエリの作成時に指定された説明 |
| クエリ | クエリの作成時に入力として渡されたレポート クエリ |
| 「」と入力します | userDefined に設定 |
| ユーザー | クエリの作成に使用されるユーザー ID |
| CreatedTime | クエリが作成された UTC 時刻の形式: yyyy-MM-ddTHH:mm:ssZ |
| TotalCount | Value 配列内のデータセットの数 |
| StatusCode | 結果コード 指定できる値は、200、400、401、403、500 です。 |
| message | API の実行からのステータス メッセージ |
レポートの作成 API
カスタム レポート テンプレートを正常に作成し、レポート作成クエリの応答の一部として QueryID を受け取った場合、この API を呼び出して、クエリが定期的に実行されるスケジュールを設定できます。 配信するレポートの頻度とスケジュールを設定できます。 用意されているシステム クエリの場合は、QueryId を使用してレポートの作成 API を呼び出すこともできます。
コールバック URL
レポート作成 API はコールバック URL を受け入れます。 この URL は、レポートの生成が成功した後に呼び出されます。 コールバック URL はパブリックに到達可能である必要があります。 URL に加えて、コールバックメソッドを指定することもできます。 コールバック メソッドには、次POSTの値のみを指定GETできます。 値が渡されない場合の既定のメソッドは .POST 生成が完了した reportId は、コールバック時に常に戻されます。
POST コールバック: 渡された URL がhttps://www.contosso.com/callbackの場合、呼び出された URL はhttps://www.contosso.com/callback/<reportID>になります。
GET コールバック: 渡された URL がhttps://www.contosso.com/callbackの場合、呼び出された URL はhttps://www.contosso.com/callback?reportId=<reportID>になります。
ExecuteNow レポート
スケジュールを指定せずにレポートを生成するための準備があります。 レポート作成 API ペイロードでは、パラメーターExecuteNowを受け取ることができます。これにより、API が呼び出されるとすぐに生成されるレポートがキューに入れられます。 true に設定すると ExecuteNow 、これらのレポートはスケジュールされていないため、フィールド : StartTime, RecurrenceCountは RecurrenceInterval 無視されます。
ExecuteNowが true の場合、QueryStartTimeとQueryEndTimeの2つの追加フィールドを渡すことができます。 この2つのフィールドは、クエリのTIMESPANフィールドよりも優先されます。 これらのフィールドは、変更されない一定の期間にわたってデータが継続的に生成されるため、スケジュールされたレポートには適用されません。
要求の構文
| メソッド | 要求 URI |
|---|---|
| POST | https://api.partnercenter.microsoft.com/insights/v1/mpn/ScheduledReport |
要求ヘッダー
| ヘッダー | 「」と入力します | 説明 |
|---|---|---|
| 承認 | 文字列 | 必須。 Microsoft Entra アクセス トークン。 形式は Bearer <token> です。 |
| Content-Type | 文字列 | Application/JSON |
パス パラメーター
なし
クエリ パラメーター
なし
要求ペイロードのサンプル
{
"ReportName": "Top10_CustomersReport",
"Description": "Top 10 customers by revenue for last month",
"QueryId": "ec8366a4-d96e-4194-8c37-d5dbc0639033",
"StartTime": "2021-03-31T18:41:00Z",
"ExecuteNow": false,
"QueryStartTime": null,
"QueryEndTime": null,
"RecurrenceInterval": 24,
"RecurrenceCount": 100,
"Format": "CSV",
"CallbackUrl": "https://<SampleCallbackUrl>",
"CallbackMethod": "GET"
}
用語集
要求ペイロード内の要素のキー定義は次のようになります。
| パラメーター | 必須 | 説明 | 使用できる値 |
|---|---|---|---|
| ReportName | はい | レポートに割り当てる名前 | 文字列 |
| 説明 | なし | 作成されたレポートの説明 | 文字列 |
| QueryId | はい | レポート クエリ ID | 文字列 |
| Starttime | はい | レポート生成が開始される UTC タイムスタンプ。 形式は yyyy-MM-ddTHH:mm:ssZ にする必要があります。 |
文字列 |
| ExecuteNow | なし | このパラメーターは、1 回だけ実行されるレポートを作成するために使用される必要があります。 true に設定されている場合StartTime、RecurrenceInterval、RecurrenceCountは無視されます。 レポートは非同期的に直ちに実行されます |
true/false |
| QueryStartTime | なし | 必要に応じて、データを抽出するクエリの開始時刻を指定します。 このパラメーターは、ExecuteNowがtrue に設定された1回限りの実行レポートにのみ適用できます。 このパラメーターを設定すると、TIMESPANのクエリでオーバーライドされます。 形式は yyyy-MM-ddTHH:mm:ssZ にする必要があります |
文字列としてのタイムスタンプ |
| QueryEndTime | なし | 必要に応じて、データを抽出するクエリの終了時刻を指定します。 このパラメーターは、ExecuteNowがtrue に設定された1回限りの実行レポートにのみ適用できます。 このパラメーターを設定すると、TIMESPANのクエリでオーバーライドされます。 形式は yyyy-MM-ddTHH:mm:ssZ にする必要があります |
文字列としてのタイムスタンプ |
| RecurrenceInterval | はい | レポートが生成される頻度 (時間単位)。 最小値は4で、最大値は2160です。 |
整数 |
| RecurrenceCount | なし | 生成されるレポートの数。 | 整数 |
| Format | なし | エクスポートされるファイルのファイル形式。 既定値は CSV です。 |
"CSV"/"TSV" |
| CallbackUrl | なし | 必要に応じてコールバック先として構成できるパブリックに到達可能な URL | 文字列 (http URL) |
| CallbackMethod | なし | コールバックに使用するメソッド | GET/POST |
サンプル応答
応答ペイロードは、次のように構成されます。
応答コード：200、400、401、403、500
応答ペイロードの例:
{
"value": [
{
"reportId": "d9548477-16d4-492a-bf9c-0cf91a9f69bf",
"reportName": "Top10_CustomersReport",
"description": "Top 10 customers by revenue for last month",
"queryId": "ec8366a4-d96e-4194-8c37-d5dbc0639033",
"query": "SELECT CustomerName, Product, BilledRevenueUSD FROM CustomersAndTenants ORDER BY BilledRevenueUSD LIMIT 10 TIMESPAN LAST_MONTH",
"user": "GAUser@PITEST2.onmicrosoft.com",
"createdTime": "2021-03-30T13:11:58Z",
"modifiedTime": null,
"executeNow": false,
"startTime": "2021-03-31T18:41:00Z",
"reportStatus": "Active",
"recurrenceInterval": 24,
"recurrenceCount": 100,
"callbackUrl": "https://<SampleCallbackUrl>",
"callbackMethod": "GET",
"format": "csv"
}
],
"nextLink": null,
"totalCount": 1,
"message": "Report created successfully",
"statusCode": 200,
"dataRedacted": false
}
用語集
要求ペイロード内の要素のキー定義は次のようになります。
| パラメーター | 説明 |
|---|---|
| ReportId | 作成したレポートの汎用一意識別子 (UUID) |
| ReportName | 要求ペイロード内のレポートに指定された名前 |
| 説明 | レポートの作成時に指定された説明 |
| QueryId | レポートの作成時に渡されたクエリ ID |
| クエリ | このレポートに対して実行されるクエリ テキスト |
| ユーザー | レポートの作成に使用されるユーザー ID |
| CreatedTime | レポートが作成された UTC 時刻の形式: yyyy-MM-ddTHH:mm:ssZ |
| ModifiedTime | レポートが最後に変更された UTC 時刻:yyyy-MM-ddTHH:mm:ssZ |
| ExecuteNow | ExecuteNow レポートの作成時に設定されたフラグ |
| Starttime | レポートの実行が開始される UTC 時刻:yyyy-MM-ddTHH:mm:ssZ |
| ReportStatus | レポート実行の状態。 使用可能な値は Paused、ActiveおよびInactiveです。 |
| RecurrenceInterval | レポートの作成時に指定された繰り返し間隔 |
| RecurrenceCount | レポートの作成中に指定された繰り返し回数。 |
| CallbackUrl | 要求で指定されたコールバック URL |
| CallbackMethod | 要求で提供されるコールバック メソッド |
| Format | レポート ファイルの形式。 設定できる値はCSVまたはTSVです。 |
| TotalCount | Value 配列内のレコードの数 |
| StatusCode | 結果コード |
| message | 設定できる値は次のとおりです。 API の実行からのステータス メッセージ |
レポート実行 API を取得する
このメソッドを使用すると、レポート作成 API から受信した ReportId を使用して、レポート実行の状態 を照会できます。 レポートをダウンロードする準備ができている場合、このメソッドでレポートのダウンロード リンクが返されます。 それ以外の場合は、メソッドから状態が返されます。 また、この API を使用して、特定のレポートで発生したすべての実行を取得することもできます。
重要
この API には、既定のクエリ パラメーターとして executionStatus=Completed および getLatestExecution=true が設定されています。 このため、レポート実行が最初に成功する前にこの API を呼び出すと、404 が返されます。 保留中の実行は、executionStatus=Pending を設定することによって取得できます。
要求の構文
| メソッド | 要求 URI |
|---|---|
| GET | https://api.partnercenter.microsoft.com/insights/v1/mpn/ScheduledReport/execution/{reportId}?executionId={executionId}&executionStatus={executionStatus}&getLatestExecution={getLatestExecution} |
要求ヘッダー
| ヘッダー | 「」と入力します | 説明 |
|---|---|---|
| 承認 | 文字列 | 必須。 Microsoft Entra アクセス トークン。 形式は Bearer <token> です。 |
| Content-Type | 文字列 | Application/JSON |
パス パラメーター
| パラメーター名 | 必須 | タイプ | 説明 |
|---|---|---|---|
| reportId | はい | string | フィルターを適用して、この引数で指定された reportId を持つレポートの実行の詳細のみを取得します。 複数の reportId を指定するには、セミコロン ";" で区切ります。 |
Query parameter (クエリ パラメーター)
| パラメーター名 | 必須 | タイプ | 説明 |
|---|---|---|---|
| executionId | いいえ | string | この引数で指定された executionId を持つレポートのみの詳細を取得するフィルター 複数の reportId は、セミコロン ";" で区切って指定できます。 |
| executionStatus | いいえ | String/enum | この引数で指定された executionStatus を持つレポートのみの詳細を取得するフィルター 有効な値は次のとおりです。 PendingRunningPausedCompleted 既定値は Completed です。 複数の状態を指定する場合は、セミコロン ";" で区切ります。 |
| getLatestExecution | いいえ | boolean | この API から最新のレポート実行の詳細が返されます。 既定では、このパラメーターは true に設定されます。 このパラメーターの値を false として渡すことを選択した場合、この API から最後の 90 日間の実行インスタンスが返されます。 |
要求ペイロードのサンプル
なし
サンプル応答
応答ペイロードは、次のように構成されます。
応答コード：200、400、401、403、500
応答ペイロードの例:
{
"value": [
{
"executionId": "906931dc-4f2f-4195-bbb2-d7295c7550d3",
"reportId": "d9548477-16d4-492a-bf9c-0cf91a9f69bf",
"recurrenceInterval": 24,
"recurrenceCount": 100,
"callbackUrl": null,
"callbackMethod": null,
"format": "csv",
"executionStatus": "Completed",
"reportLocation": null,
"reportAccessSecureLink": "https://<path to report for download>",
"reportExpiryTime": null,
"reportGeneratedTime": "2021-03-31T18:41:00Z"
}
],
"nextLink": null,
"totalCount": 1,
"message": null,
"statusCode": 200,
"dataRedacted": false
}
レポートの実行が完了すると、実行状態 Completed が表示されます。 reportAccessSecureLink で URL を選択して、レポートをダウンロードできます。
用語集
応答内の要素の主な定義。
| パラメーター | 説明 |
|---|---|
| ExecutionId | 実行インスタンスの汎用一意識別子 (UUID) |
| ReportId | 実行インスタンスに関連付けられているレポート ID |
| RecurrenceInterval | レポートの作成中に指定された繰り返し間隔 |
| RecurrenceCount | レポートの作成中に指定された繰り返し回数 |
| CallbackUrl | 実行インスタンスに関連付けられているコールバック URL |
| CallbackMethod | 実行インスタンスに関連付けられたコールバックメソッド |
| 形式 | 実行の終了時に生成されるファイルの形式 |
| ExecutionStatus | レポート実行インスタンスの状態。 有効な値は、 Pending、Running、Paused、Completed です |
| ReportAccessSecureLink | レポートに安全にアクセスできるリンク |
| ReportExpiryTime | レポート リンクの有効期限が切れる UTC 時刻で、形式は yyyy-MM-ddTHH:mm:ssZ |
| ReportGeneratedTime | レポートが生成された UTC 時刻で、形式は yyyy-MM-ddTHH:mm:ssZ |
| TotalCount | Value 配列内のデータセットの数 |
| StatusCode | 結果コード 200、400、401、403、404、500 の値になる可能性があります |
| メッセージ | API の実行からのステータス メッセージ |
次のステップ
- swagger API URL を使用して API を試す
- [最初の API 呼び出しを行う](insights-programmatic-first-api-call.md
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示