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

2025-05-11

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

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

この一覧では、図 1 について詳しく説明します。

クライアントアプリケーションは、 Create Report Query API を呼び出すことで、カスタムレポートスキーマ/テンプレートを定義できます。または、パートナー分析情報のプログラムによるアクセスのシステムクエリの一覧に関するレポートテンプレートライブラリのサンプルから、レポートテンプレート (QueryId) を選択することもできます。
成功すると、Create Report Query API は QueryId を返します。
その後、クライアントアプリケーションは、QueryId を使用して、レポートの開始日、繰り返し間隔、繰り返し、およびオプションのコールバック URI を使用して、レポート作成 API を呼び出す必要があります。
成功すると、 Create Report API は ReportId を返します。
クライアントアプリケーションは、レポートデータをダウンロードする準備が整うとすぐに、コールバック URL で通知を受け取ります。
その後、クライアントアプリケーションは Get Report Executions API を使用して、レポート ID と日付範囲を使用してレポートの状態をクエリします。
成功すると、レポートのダウンロードリンクが返され、アプリケーションはデータのダウンロードを開始できます。

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

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

レポートクエリ API の作成

この API は、列とメトリクスのエクスポート元となるデータセットを定義するカスタムクエリを作成するのに役立ちます。この API は、ビジネスニーズに基づいて新しいレポートテンプレートを柔軟に作成できます。

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

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

リクエスト構文

メソッド	URI リクエスト
投稿	`https://api.partnercenter.microsoft.com/insights/v1/mpn/ScheduledQueries`

リクエストヘッダー

ヘッダ	タイプ	説明
認証	ひも	必須。 Microsoft Entra アクセストークン。形式は `Bearer <token>`です。
コンテンツタイプ	ひも	`Application/JSON`

Path パラメーター

無し

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"
}

要求用語集

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

パラメーター	必須	説明	使用できる値
名前	イエス	クエリのフレンドリ名	ひも
説明	いいえ	クエリが返す内容の説明	ひも
クエリ	イエス	レポートクエリ文字列	データ型: 文字列ビジネスニーズに基づくカスタムクエリ

注

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

サンプル応答

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

応答コード: 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
}

応答用語集

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

パラメーター	説明
クエリ ID	作成したクエリの汎用一意識別子 (UUID)
名前	要求ペイロード内のクエリに付けられたフレンドリ名
説明	クエリの作成時に指定された説明
クエリ	クエリ作成時に入力として渡されるレポートクエリ
タイプ	`userDefined` に設定
ユーザー	クエリの作成に使用されたユーザー ID
CreatedTime	クエリが作成された UTC 時刻 (yyyy-MM-ddTHH:mm:ssZ の形式)
トータルカウント	Value 配列内のデータセットの数
ステータスコード	結果コード指定できる値は、200、400、401、403、500 です。
メッセージ	API の実行からのステータスメッセージ

レポート作成 API

カスタムレポートテンプレートを正常に作成し、 Create Report Query 応答の一部として QueryID を受け取ると、この API を呼び出して、クエリが定期的に実行されるようにスケジュールできます。レポートを配信する頻度とスケジュールを設定できます。 Microsoft が提供するシステムクエリの場合、Create Report API は QueryId を使用して呼び出すこともできます。

コールバック 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 の各フィールドはスケジュールされていないため、無視されます。

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

リクエスト構文

メソッド	URI リクエスト
投稿	`https://api.partnercenter.microsoft.com/insights/v1/mpn/ScheduledReport`

リクエストヘッダー

ヘッダ	タイプ	説明
認証	ひも	必須。 Microsoft Entra アクセストークン。形式は `Bearer <token>`です。
コンテンツタイプ	ひも	`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"
}

用語集

リクエストペイロード内の要素の主な定義は、以下のとおりです。

パラメーター	必須	説明	使用できる値
レポート名	イエス	レポートに割り当てる名前	ひも
説明	いいえ	作成されたレポートの説明	ひも
クエリ ID	イエス	レポートクエリ ID	ひも
開始時間	イエス	UTC レポートの生成が開始されるタイムスタンプ。形式は yyyy-MM-ddTHH:mm:ssZ です。	ひも
今すぐ実行	いいえ	このパラメーターは、一度だけ実行されるレポートを作成するために使用する必要があります。 `StartTime`これが true に設定されている場合、 `RecurrenceInterval`、および `RecurrenceCount` は無視されます。レポートは非同期ですぐに実行されます	真/偽
クエリ開始時間	いいえ	オプションで、データを抽出するクエリの開始時刻を指定します。このパラメータは、 `ExecuteNow` が true に設定されている 1 回限りの実行レポートにのみ適用されます。このパラメータを設定すると、クエリで指定 `TIMESPAN` が上書きされます。形式は yyyy-MM-ddTHH:mm:ssZ である必要があります。	文字列としてのタイムスタンプ
クエリ終了時間	いいえ	オプションで、データを抽出するクエリの終了時刻を指定します。このパラメータは、 `ExecuteNow` が true に設定されている 1 回限りの実行レポートにのみ適用されます。このパラメータを設定すると、クエリで指定 `TIMESPAN` が上書きされます。形式は yyyy-MM-ddTHH:mm:ssZ である必要があります。	文字列としてのタイムスタンプ
RecurrenceInterval (繰り返し間隔)	イエス	レポートを生成する頻度 (時間単位)。最小値は 4 で、最大値は 2160 です。	整数 (integer)
RecurrenceCount (繰り返しカウント)	いいえ	生成されるレポートの数。	整数 (integer)
フォーマット	いいえ	エクスポートされたファイルのファイル形式。デフォルトは CSV です。	「CSV」/「TSV」
コールバックURL	いいえ	コールバックの宛先としてオプションで設定できる、パブリックに到達可能なURL	文字列 (http URL)
コールバックメソッド	いいえ	コールバックに使用するメソッド	取得/投稿

サンプル応答

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

応答コード: 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.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
}

用語集

応答の要素の主な定義は、以下に明確化されています。

パラメーター	説明
レポートID	作成したレポートの汎用一意識別子 (UUID)
レポート名	要求ペイロード内のレポートに指定された名前
説明	レポートの作成時に指定された説明
クエリ ID	レポートの作成時に渡されたクエリ ID
クエリ	このレポートに対して実行されるクエリテキスト
ユーザー	レポートの作成に使用されるユーザー ID
CreatedTime	レポートが作成された UTC 時刻 yyyy-MM-ddTHH:mm:ssZ
変更時刻	レポートが最後に変更された UTC 時刻 (yyyy-MM-ddTHH:mm:ssZ の形式)
今すぐ実行	`ExecuteNow` レポートの作成時に設定されたフラグ
開始時間	レポートの実行が次の形式で開始される UTC 時刻: yyyy-MM-ddTHH:mm:ssZ
レポートステータス	レポート実行の状態。指定できる値は、 `Paused`、 `Active`、および `Inactive`
RecurrenceInterval (繰り返し間隔)	レポートの作成時に指定された繰り返し間隔
RecurrenceCount (繰り返しカウント)	レポート作成時に提供される繰り返しカウント。
コールバックURL	要求で指定されたコールバック URL
コールバックメソッド	要求で提供されるコールバックメソッド
フォーマット	レポートファイルの形式。使用可能な値は、 `CSV` または `TSV`です。
トータルカウント	Value 配列のレコード数
ステータスコード	結果コード
メッセージ	可能な値は、200、400、401、403、500 です。 API の実行からのステータスメッセージ

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

このメソッドを使用すると、 Create Report API から受信した ReportId を使用して、レポート実行の状態を照会できます。このメソッドは、レポートをダウンロードする準備ができている場合に、レポートのダウンロードリンクを返します。それ以外の場合、メソッドはステータスを返します。また、この API を使用して、特定のレポートで発生したすべての実行を取得することもできます。

Von Bedeutung

この API には、 executionStatus=Completed と getLatestExecution=true の既定のクエリパラメーターが設定されています。したがって、レポートの最初の正常な実行の前に API を呼び出すと、404 が返されます。保留中の実行は、 executionStatus=Pendingを設定することで取得できます。

リクエスト構文

メソッド	URI リクエスト
取得する	`https://api.partnercenter.microsoft.com/insights/v1/mpn/ScheduledReport/execution/{reportId}?executionId={executionId}&executionStatus={executionStatus}&getLatestExecution={getLatestExecution}`

リクエストヘッダー

ヘッダ	タイプ	説明
認証	ひも	必須。 Microsoft Entra アクセストークン。形式は `Bearer <token>`です。
コンテンツタイプ	ひも	`Application/JSON`

Path パラメーター

パラメーター名	必須	タイプ	説明
レポートID	イエス	ひも	この引数で指定された reportId を持つレポートのみの実行詳細を取得するようにフィルター処理します。複数の reportId を指定するには、セミコロン ";" で区切ります。

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

パラメーター名	必須	タイプ	説明
実行ID	いいえ	ひも	この引数で指定された executionId を持つレポートのみの詳細を取得するようにフィルター処理します。複数の executionId を指定するには、セミコロン ";" で区切ります。
executionステータス	いいえ	文字列/列挙型	この引数で指定された executionStatus を持つレポートのみの詳細を取得するようにフィルター処理します。有効な値は、 `Pending`、 `Running`、 `Paused`、 `Completed` です。既定値は `Completed` です。複数のステータスを指定するには、セミコロン ";" で区切ります。
getLatestExecution (英語)	いいえ	ブーリアン	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 を選択します。

用語集

応答内の要素の主要な定義。

パラメーター	説明
実行ID	実行インスタンスの汎用一意識別子 (UUID)
レポートID	実行インスタンスに関連付けられたレポート ID
RecurrenceInterval (繰り返し間隔)	レポートの作成時に指定された繰り返し間隔
RecurrenceCount (繰り返しカウント)	レポートの作成時に指定された繰り返し数
コールバックURL	実行インスタンスに関連付けられたコールバック URL
コールバックメソッド	実行インスタンスに関連付けられたコールバックメソッド
フォーマット	実行終了時に生成されるファイルの形式
実行ステータス	レポート実行インスタンスのステータス。有効な値は、 `Pending`、 `Running`、 `Paused`、および `Completed`
レポートアクセスセキュアリンク	レポートに安全にアクセスできるリンク
レポート有効期限	UTC 時間この形式でレポートリンクの有効期限が切れます: yyyy-MM-ddTHH:mm:ssZ
レポート生成時間	レポートが生成された UTC 時刻 (yyyy-MM-ddTHH:mm:ssZ の形式)
トータルカウント	Value 配列内のデータセットの数
ステータスコード	結果コード可能な値は、200、400、401、403、404、および 500 です
メッセージ	API の実行からのステータスメッセージ

Swagger API URL を使用して API を試してみてください

最初の API 呼び出しを行います。

次の方法で共有

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

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

レポート クエリ API の作成

リクエスト構文

リクエストヘッダー

Path パラメーター

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

サンプル要求ペイロード

要求用語集

サンプル応答

応答用語集

レポート作成 API

コールバック URL

ExecuteNow レポート

リクエスト構文

リクエストヘッダー

パスパラメータ

クエリ パラメーター

サンプル要求ペイロード

用語集

サンプル応答

用語集

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

リクエスト構文

リクエストヘッダー

Path パラメーター

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

サンプルリクエストペイロード

応答の例

用語集

関連コンテンツ

フィードバック

その他のリソース

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

レポートクエリ API の作成

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

クエリパラメーター

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