Microsoft コマーシャル マーケットプレースの SaaS Fulfillment 操作 API v2
Note
SaaS Fulfillment Operations API を呼び出すことができるようにするには、正しいリソース ID を使用して発行元の承認トークンを作成する必要があります。発行元の承認トークン 取得する方法について説明します
この記事では、SaaS Fulfillment 操作 API のバージョン 2 について説明します。
操作は、ChangePlan、ChangeQuantity、および Reinstate アクションの一部として webhook を経由するすべての要求に応答するのに役立ちます。 これにより、以下の API を使用して当該 Webhook 操作について成功または失敗を示すパッチを送信することで、要求を受諾または拒否できます。
これは、ACK を必要とする ChangePlan、ChangeQuantity、Reinstate などの Webhook イベントにのみ適用されます。 独立系ソフトウェア ベンダー (ISV) が通知のみのイベントであるため、イベントの更新、中断、登録解除に関するアクションは必要ありません。
未処理の操作を一覧表示する
指定した SaaS サブスクリプションの保留中の操作の一覧を取得します。 公開元は、Operation patch API を呼び出すことによって、返された操作を確認する必要があります。
Get https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations?api-version=<ApiVersion>
クエリ パラメーター:
| パラメーター | 値 |
|---|---|
ApiVersion |
2018-08-31 を使用します。 |
subscriptionId |
購入済み SaaS サブスクリプションの一意識別子。 この ID は、Resolve API を使用してコマーシャル マーケットプレース認証トークンを解決した後に取得されます。 |
要求ヘッダー:
| パラメーター | 値 |
|---|---|
content-type |
application/json |
x-ms-requestid |
クライアントからの要求を追跡するための一意の文字列値 (GUID を推奨)。 この値が指定されていない場合は、1 つが生成され、応答ヘッダーに指定されます。 |
x-ms-correlationid |
クライアントでの操作に対する一意の文字列値。 このパラメーターによって、クライアント操作からのすべてのイベントがサーバー側のイベントに関連付けられます。 この値が指定されていない場合は、1 つが生成され、応答ヘッダーに指定されます。 |
authorization |
形式は、「 Microsoft Entra アプリに基づいてトークンを取得するで説明されているように、トークン値が発行元によって取得されるときに"Bearer <access_token>"されます。 |
応答コード:
コード: 200 指定された SaaS サブスクリプションで保留中の操作を返します。
応答ペイロードの例:
{
"operations": [
{
"id": "<guid>", //Operation ID, should be provided in the operations patch API call
"activityId": "<guid>", //not relevant
"subscriptionId": "<guid>", // subscriptionId of the SaaS subscription that is being reinstated
"offerId": "offer1", // purchased offer ID
"publisherId": "contoso",
"planId": "silver", // purchased plan ID
"quantity": 20, // purchased amount of seats, will be empty is not relevant
"action": "Reinstate",
"timeStamp": "2018-12-01T00:00:00", // UTC
"status": "InProgress" // the only status that can be returned in this case
}
]
}
保留中の操作がない場合は、空の json を返します。
コード: 400 無効な要求: 検証エラー。
コード: 403 禁止。 認証トークンが無効であるか、期限切れであるか、指定されませんでした。 要求は、承認トークンの作成に使用されたものとは異なる Microsoft Entra アプリ ID で発行されたオファーの SaaS サブスクリプションにアクセスしようとしています。
多くの場合、このエラーは、SaaS 登録を正しく実行していないことを表す症状です。
コード: 404 見つかりません。 subscriptionIdを含む SaaS サブスクリプションが見つかりません。
コード: 500 内部サーバー エラー。 API 呼び出しをやり直してください。 エラーが解決しない場合は、Microsoft サポートにお問い合わせください。
操作状態を取得する
この API を使うと、発行者は、指定した非同期操作 (Unsubscribe、ChangePlan、または ChangeQuantity) の状態を追跡できます。
この API 呼び出しの operationId は、Operation-Location によって返される値、保留中の Operations API の取得の呼び出し、または Webhook 呼び出しで受け取った <id> パラメーター値から取得できます。
Get https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=<ApiVersion>
クエリ パラメーター:
| パラメーター | 値 |
|---|---|
ApiVersion |
2018-08-31 を使用します。 |
subscriptionId |
購入済み SaaS サブスクリプションの一意識別子。 この ID は、Resolve API を使用してコマーシャル マーケットプレース認証トークンを解決した後に取得されます。 |
operationId |
取得する対象である操作を表す一意識別子。 |
要求ヘッダー:
| パラメーター | 値 |
|---|---|
content-type |
application/json |
x-ms-requestid |
クライアントからの要求を追跡するための一意の文字列値 (GUID を推奨)。 この値が指定されていない場合は、1 つが生成され、応答ヘッダーに指定されます。 |
x-ms-correlationid |
クライアントでの操作に対する一意の文字列値。 このパラメーターによって、クライアント操作からのすべてのイベントがサーバー側のイベントに関連付けられます。 この値が指定されていない場合は、1 つが生成され、応答ヘッダーに指定されます。 |
authorization |
この API 呼び出しを行っている発行者を識別する一意のアクセス トークン。 形式は、「 Microsoft Entra アプリに基づいてトークンを取得するで説明されているように、トークン値が発行元によって取得されるときに"Bearer <access_token>"されます。 |
応答コード:
コード: 200 指定された SaaS 操作の詳細を取得します。
応答ペイロードの例:
Response body:
{
"id ": "<guid>", //Operation ID, should be provided in the patch operation API call
"activityId": "<guid>", //not relevant
"subscriptionId": "<guid>", // subscriptionId of the SaaS subscription for which this operation is relevant
"offerId": "offer1", // purchased offer ID
"publisherId": "contoso",
"planId": "silver", // purchased plan ID
"quantity": 20, // purchased amount of seats
"action": "ChangePlan", // Can be ChangePlan, ChangeQuantity or Reinstate
"timeStamp": "2018-12-01T00:00:00", // UTC
"status": "InProgress", // Possible values: NotStarted, InProgress, Failed, Succeeded, Conflict (new quantity / plan is the same as existing)
"errorStatusCode": "",
"errorMessage": ""
}
コード: 403 禁止。 認証トークンが無効であるか、期限切れであるか、指定されませんでした。 要求は、承認トークンの作成に使用されたものとは異なる Microsoft Entra アプリ ID で発行されたオファーの SaaS サブスクリプションにアクセスしようとしています。
多くの場合、このエラーは、SaaS 登録を正しく実行していないことを表す症状です。
コード: 404 見つかりません。
subscriptionIdを含むサブスクリプションが見つかりません。operationIdを使用した操作が見つかりません。
コード: 500 内部サーバー エラー。 API 呼び出しをやり直してください。 エラーが解決しない場合は、Microsoft サポートにお問い合わせください。
操作の状態を更新する
この API を使用して、保留中の操作の状態を更新し、公開元側で操作が成功したか失敗したかを示します。
この API 呼び出しの operationId は、Operation-Location によって返される値、保留中の Operations API の取得の呼び出し、または Webhook 呼び出しで受け取った <id> パラメーター値から取得できます。
Patch https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=<ApiVersion>
クエリ パラメーター:
| パラメーター | 値 |
|---|---|
ApiVersion |
2018-08-31 を使用します。 |
subscriptionId |
購入済み SaaS サブスクリプションの一意識別子。 この ID は、Resolve API を使用してコマーシャル マーケットプレース認証トークンを解決した後に取得されます。 |
operationId |
完了する対象である操作の一意識別子。 |
要求ヘッダー:
| パラメーター | 値 |
|---|---|
content-type |
application/json |
x-ms-requestid |
クライアントからの要求を追跡するための一意の文字列値 (GUID を推奨)。 この値が指定されていない場合は、1 つが生成され、応答ヘッダーに指定されます。 |
x-ms-correlationid |
クライアントでの操作に対する一意の文字列値。 このパラメーターによって、クライアント操作からのすべてのイベントがサーバー側のイベントに関連付けられます。 この値が指定されていない場合は、1 つが生成され、応答ヘッダーに指定されます。 |
authorization |
この API 呼び出しを行っている公開元を識別する一意のアクセス トークン。 形式は、「 Microsoft Entra アプリに基づいてトークンを取得するで説明されているように、トークン値が発行元によって取得されるときに"Bearer <access_token>"されます。 |
要求ペイロードの例:
{
"status": "Success" // Allowed Values: Success/Failure. Indicates the status of the operation on ISV side.
}
応答コード:
コード: 200 パートナー側での操作の完了を通知する呼び出し。 たとえば、この応答によって発行者側でのシートまたはプランの変更を通知できます。
コード: 403
- Forbidden. 承認トークンが使用できない、無効、または期限切れです。 要求が、現在の発行元に属していないサブスクリプションにアクセスしようとしている可能性があります。
- Forbidden. 認証トークンが無効であるか、期限切れであるか、指定されませんでした。 要求は、承認トークンの作成に使用されたものとは異なる Microsoft Entra アプリ ID で発行されたオファーの SaaS サブスクリプションにアクセスしようとしています。
多くの場合、このエラーは、SaaS 登録を正しく実行していないことを表す症状です。
コード: 404 見つかりません。
subscriptionIdを含むサブスクリプションが見つかりません。operationIdを使用した操作が見つかりません。
コード: 409 競合。 たとえば、より新しい更新が既に履行されています。
コード: 500 内部サーバー エラー。 API 呼び出しをやり直してください。 エラーが解決しない場合は、Microsoft サポートにお問い合わせください。
関連するコンテンツ
- コマーシャル マーケットプレースでの SaaS オファーのその他のオプションについては、コマーシャル マーケットプレースの測定サービス API を参照してください。
- さまざまなプログラミング言語のクライアントを確認して、サンプルを使用します。