プログラムによるアクセスのパラダイム

この図は、新しいレポート テンプレートの作成、カスタム レポートのスケジュール設定、およびエラー データの取得に使用される API 呼び出しパターンを示しています。

高レベルのフロー 図 1: API 呼び出しパターンの高レベルのフロー

この一覧で、図 1 の詳細を説明します。

  1. クライアント アプリケーションでは、レポート クエリの作成 API を呼び出すことによって、カスタム レポート スキーマ/テンプレートを定義できます。 または、ここに一覧表示されているレポート テンプレート ライブラリのサンプルからレポート テンプレート (QueryId) を選択 することもできます。
  2. 成功すると、レポート クエリの作成 API は QueryId を返します。
  3. 次に、クライアント アプリケーションは、QueryId とレポートの開始日、繰り返し間隔、繰り返し、およびオプションのコールバック URI を使用して、レポートの作成 API を呼び出す必要があります。
  4. 成功すると、レポート の作成 API から ReportId が返されます。
  5. レポート データをダウンロードする準備が整った時点で、コールバック URL でクライアント アプリケーションに通知が送信されます。
  6. その後、クライアント アプリケーションは Get Report Executions API を使用して、レポート ID と日付範囲を使用してレポートの状態を照会します。
  7. 成功すると、レポートのダウンロード リンクが返され、アプリケーションでデータのダウンロードを開始できます。

レポート クエリ言語の仕様

レポートの作成 に使用できる システム クエリを提供しますが、ビジネス ニーズに基づいて独自のクエリを作成することもできます。 カスタム クエリの詳細については、「カスタム クエリの仕様 」を参照してください

レポート クエリの作成 API

この API は、列とメトリックをエクスポートする必要があるデータセットを定義するカスタム クエリを作成するのに役立ちます。 この API は、ビジネス ニーズに基づいて新しいレポート テンプレートを作成するための柔軟性を提供します。

また、用意されているシステム クエリを使用することもできます。 カスタム レポート テンプレートが不要な場合は、指定されたシステム クエリの QueryId を使用して、レポート 作成 API を直接呼び出します。

次の例は、先月の売上で上位 10 人の顧客を取得するカスタム クエリを作成する方法を示しています。

要求の構文

認証方法 要求 URI
POST https://api.partnercenter.microsoft.com/insights/v1/mpn/ScheduledQueries

要求ヘッダー

Header Type 説明
承認 string 必須。 Azure Active Directory (Azure AD) アクセス トークン。 形式は です  Bearer <token>
Content-Type string 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
説明 いいえ クエリが返すものの説明 string
クエリ はい レポート クエリ文字列 データ型: 文字列
ビジネス ニーズに基づくカスタム クエリ

注意

カスタム クエリのサンプルについては、「サンプル クエリの例」を参照してください。

応答のサンプル

応答ペイロードは、次のように構成されます。

応答コード: 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.ccsctp.net", 
      "createdTime": "2021-03-30T12:52:39Z" 
    }
  ], 
  "nextLink": null,
  "totalCount": 1,
  "message": "Query created successfully",
  "statusCode": 200,
  "dataRedacted": false
} 

用語集

次の表では、要求ペイロードの要素の主な定義を示しています。

パラメーター 説明
QueryId 作成したクエリの汎用一意識別子 (UUID)
名前 要求ペイロード内のクエリに指定されたフレンドリ名
説明 クエリの作成時に指定された説明
クエリ クエリの作成中に入力として渡されたレポート クエリ
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 を呼び出すこともできます。

コールバック URL

レポート作成 API はコールバック URL を受け入れる。 この URL は、レポートの生成が成功すると呼び出されます。 コールバック URL はパブリックに到達可能である必要があります。 URL に加えて、コールバック メソッドを指定することもできます。 コールバック メソッドには、"GET" または "POST" のみを指定できます。 値が渡された場合の既定のメソッドは "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 ペイロードは パラメーター を受け入れ、API が呼び出されるとすぐに生成されるレポート ExecuteNow をエンキューできます。 が ExecuteNow true に設定されている場合、フィールド 、、 は無視されます。これらの StartTime RecurrenceCount RecurrenceInterval レポートはスケジュールされません。

が true の場合、さらに 2 つの ExecuteNow フィールドを渡 QueryStartTime し、 と を渡す場合があります QueryEndTime 。 これら 2 つのフィールドは、クエリ TIMESPAN の フィールドをオーバーライドします。 これらのフィールドは、変更されない一定の期間、データが継続的に生成される予定レポートには適用されません。

要求の構文

認証方法 要求 URI
POST https://api.partnercenter.microsoft.com/insights/v1/mpn/ScheduledReport

要求ヘッダー

Header Type 説明
承認 string 必須。 Azure Active Directory (Azure AD) アクセス トークン。 形式は です  Bearer <token>
Content-Type string Application/JSON

Path パラメーター

なし

クエリ パラメーター

なし

サンプル要求ペイロード

{
  "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 はい レポートに割り当てられる名前 string
説明 いいえ 作成されたレポートの説明 string
QueryId はい レポート クエリ ID string
StartTime はい レポート生成が開始される UTC タイムスタンプ。
yyyy-MM-ddTHH:mm:ssZ の形式にする必要があります
string
ExecuteNow いいえ このパラメーターは、1 回だけ実行されるレポートを作成するために使用される必要があります。 StartTimeRecurrenceInterval RecurrenceCount true に設定されている場合、 と は無視されます。 レポートは非同期形式で直ちに実行されます true/false
QueryStartTime いいえ 必要に応じて、データを抽出するクエリの開始時刻を指定します。 このパラメーターは、true に設定された 1 回だけ実行 ExecuteNow レポートに適用されます。 このパラメーターを設定すると、クエリ TIMESPAN で指定されたオーバーライドがオーバーライドされます。 yyyy-MM-ddTHH:mm:ssZ の形式にする必要があります 文字列としてのタイムスタンプ
QueryEndTime いいえ 必要に応じて、データを抽出するクエリの終了時刻を指定します。 このパラメーターは、true に設定された 1 回だけ実行 ExecuteNow レポートに適用されます。 このパラメーターを設定すると、クエリ TIMESPAN で指定されたオーバーライドがオーバーライドされます。 yyyy-MM-ddTHH:mm:ssZ の形式にする必要があります 文字列としてのタイムスタンプ
RecurrenceInterval はい レポートが生成される頻度 (時間単位)。
最小値は 4、最大値は 2160 です。
整数 (integer)
RecurrenceCount いいえ 生成されるレポートの数。 整数 (integer)
Format いいえ エクスポートされるファイルのファイル形式。
既定値は CSV です。
"CSV"/"TSV"
CallbackUrl いいえ 必要に応じてコールバックの宛先として構成できる、パブリックに到達可能な URL 文字列 (http URL)
CallbackMethod いいえ コールバックに使用するメソッド GET/POST

応答のサンプル

応答ペイロードは、次のように構成されます。

応答コード: 200、400、401、403、404、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.ccsctp.net", 
      "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
クエリ このレポートに対して実行されるクエリ テキスト
User レポートの作成に使用するユーザー ID
CreatedTime レポートが作成された UTC 時刻で、形式は yyyy-MM-ddTHH:mm:ssZ
ModifiedTime レポートが最終更新された UTC 時刻で、形式は yyyy-MM-ddTHH:mm:ssZ
Execu ExecuteNow レポートの作成時に設定されたフラグ
StartTime レポート実行が開始する UTC 時刻で、形式は yyyy-MM-ddTHH:mm:ssZ
ReportStatus レポート実行のステータス。 指定できる値は Paused 、、 Active 、およびです。 Inactive
RecurrenceInterval レポートの作成中に指定された繰り返し間隔
RecurrenceCount レポートの作成中に指定された繰り返し回数。
CallbackUrl 要求で指定されたコールバック URL
"/" メソッド 要求に指定されたコールバックメソッド
フォーマット レポート ファイルの形式。 指定できる値は CSV または TSV です。
TotalCount 値配列内のレコードの数
StatusCode 結果コード
message 有効な値は、200、400、401、403、500です。 API の実行からのステータス メッセージ

レポート実行 API を取得する

この方法を使用すると、 Create REPORT 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}

要求ヘッダー

Header Type 説明
承認 string 必須。 Azure Active Directory (Azure AD) アクセス トークン。 形式は  Bearer <token> です。
Content-Type string Application/JSON

パス パラメーター

パラメーター名 必須 説明
reportId はい string この引数に指定された reportId を持つレポートのみの実行の詳細を取得するためにフィルター処理します。 複数の reportIds は、セミコロン ";" で区切ることによって指定できます。

Query parameter (クエリ パラメーター)

パラメーター名 必須 説明
executionId いいえ string この引数に指定された executionId を持つレポートのみの詳細を取得するためにフィルター処理します。 複数の executionIds は、セミコロン ";" で区切ることによって指定できます。
executionStatus いいえ String/enum この引数に指定された executionStatus を持つレポートのみの詳細を取得するためにフィルター処理します。
有効な値は Pending 、、 RunningPaused および Completed です。
既定値は Completed です。
複数の状態を指定するには、セミコロン ";" で区切ります。
getLatestExecution いいえ boolean API は、最新の実行の詳細を返します。 既定では、このパラメーターは true に設定されています。
このパラメーターの値を false として渡すことを選択した場合、API は最後の90日間の実行インスタンスを返します。

要求ペイロードのサンプル

なし

応答のサンプル

応答ペイロードは、次のように構成されます。

応答コード: 200、400、401、403、404、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
"/" メソッド 実行インスタンスに関連付けられたコールバックメソッド
フォーマット 実行の終了時に生成されるファイルの形式
ExecutionStatus レポート実行インスタンスの状態。
有効な値は、PendingRunningPausedCompleted です
ReportAccessSecureLink レポートに安全にアクセスできるリンク
ReportExpiryTime レポート リンクの有効期限が切れる UTC 時刻で、形式は yyyy-MM-ddTHH:mm:ssZ
Reportの時間 レポートが生成された UTC 時刻で、形式は yyyy-MM-ddTHH:mm:ssZ
TotalCount Value 配列内のデータセットの数
StatusCode 結果コード
200、400、401、403、404、500 の値になる可能性があります
message API の実行からのステータス メッセージ

次のステップ