コマーシャルマーケットプレースのプログラムによるアクセスパラダイム

[アーティクル]
06/14/2024

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

図 1: API 呼び出しパターンの大まかなフロー

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

クライアントアプリケーションでは、レポートクエリの作成 API を呼び出すことによって、カスタムレポートスキーマ/テンプレートを定義できます。または、システムクエリの一覧からレポートテンプレート (QueryId) を使用することもできます。
成功した場合、レポートテンプレートの作成 API から QueryId が返されます。
その後、クライアントアプリケーションでは、QueryID と共にレポートの開始日、繰り返し間隔、繰り返し回数、およびオプションのコールバック URI を使用して、レポートの作成 API を呼び出します。
成功した場合、レポートの作成 API から ReportID が返されます。
クライアントアプリケーションでは、レポートデータのダウンロード準備が完了するとすぐに、コールバック URI で通知を受け取ります。
その後、クライアントアプリケーションでレポート実行状態の取得 API を使用し、Report ID と日付範囲を指定してレポートの状態のクエリを実行します。
成功すると、レポートのダウンロードリンクが返され、アプリケーションでデータのダウンロードを開始できます。

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

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

レポートクエリの作成 API

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

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

次の例では、過去 1 か月間の ISVUsage データセットから有料 SKU の正規化された使用と推定料金を取得するカスタムクエリを作成する方法を示します。

要求構文

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

要求ヘッダー

Header	型	説明
承認	string	必須。 Microsoft Entra アクセストークン。形式は `Bearer <token>` です。
コンテンツタイプ	`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`、 `RecurrenceInterval`、 `RecurrenceCount`、および `EndTime` は無視されます。 `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 または RecurrenceInterval と RecurrenceCount の組み合わせが必須です。

サンプル応答

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

応答コード: 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`	レポートの作成時に要求ペイロードに指定されたクエリの開始時刻。これは、 `ExecuteNow` が "True" に設定されている場合にのみ適用されます
`queryEndTime`	レポートの作成時に要求ペイロードに指定されたクエリの終了時刻。これは、 `ExecuteNow` が "True" に設定されている場合にのみ適用されます
`StartTime`	レポートの作成中に要求ペイロードに指定された開始時刻
`ReportStatus`	レポート実行の状態。有効な値は、Paused、Active、および Inactive です。
`RecurrenceInterval`	レポートの作成中に要求ペイロードに指定された繰り返し間隔
`RecurrenceCount`	レポートの残りの繰り返し数
`CallbackUrl`	レポートの作成時に要求ペイロードに指定されたコールバック URL
`CallbackMethod`	レポートの作成時に要求ペイロードで提供されるコールバックメソッド
`Format`	レポートの作成時に要求ペイロードに指定されたレポートファイルの形式
`EndTime`	レポートの作成中に要求ペイロードに指定された終了時刻。これは、 `ExecuteNow` が "True" に設定されている場合にのみ適用されます
`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`	レポートの作成中に要求ペイロードに指定された終了時刻。これは、 `ExecuteNow` が "True" に設定されている場合にのみ適用されます
`TotalRecurrenceCount`	`RecurrenceCount` レポートの作成時に要求ペイロードに指定された
`nextExecutionStartTime`	次のレポートの実行が開始される UTC タイムスタンプ
`TotalCount`	Value 配列内のデータセットの数
`StatusCode`	結果コード 200、400、401、403、404、500 の値になる可能性があります
`message`	API の実行からのステータスメッセージ

Swagger API URLを使用して API を試すことができます。

Marketplace Insights レポートの最初の API 呼び出しを行う

次の方法で共有

コマーシャルマーケットプレースのプログラムによるアクセスパラダイム

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

レポートクエリの作成 API

レポートの作成 API

レポート実行の取得 API

フィードバック

その他のリソース

次の方法で共有

コマーシャル マーケットプレースのプログラムによるアクセス パラダイム

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

レポート クエリの作成 API

レポートの作成 API

レポート実行の取得 API

関連するコンテンツ

フィードバック

その他のリソース

コマーシャルマーケットプレースのプログラムによるアクセスパラダイム

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

レポートクエリの作成 API