Microsoft コマーシャル マーケットプレースでの SaaS フルフィルメント操作 API v2
手記
SaaS Fulfillment Operations API を呼び出すことができるようにするには、正しいリソース ID を使用して発行元の承認トークンを作成する必要があります。発行元の承認トークン 取得する方法について説明
この記事では、SaaS フルフィルメント操作 API のバージョン 2 について説明します。
操作は、ChangePlan、ChangeQuantity、および Reinstate アクションの一部として webhook を経由するすべての要求に応答するのに役立ちます。 これにより、以下の API を使用して、Webhook 操作の成功または失敗に対するパッチによる要求を受け入れるか拒否する機会が提供されます。
これは、ACK を必要とする ChangePlan、ChangeQuantity、Reinstate などの Webhook イベントにのみ適用されます。 独立系ソフトウェア ベンダー (ISV) が通知のみのイベントであるため、イベントの更新、中断、登録解除に関するアクションは必要ありません。
未処理の操作を一覧表示する
指定した SaaS サブスクリプションの保留中の操作の一覧を取得します。 パブリッシャーは、Operation Patch APIを呼び出して、返された操作を確認する必要があります。
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 無効な要求: 検証エラー。
コード: 401 未承認。 承認トークンが無効であるか、有効期限が切れています。 要求は、認証トークンの作成に使用されたものとは異なる Microsoft Entra アプリ ID で発行されたオファーの SaaS サブスクリプションにアクセスしようとしています。
コード: 403 禁止。 承認トークンが無効であるか、指定されていないか、十分なアクセス許可が提供されていません。 有効な承認トークンを必ず指定してください。
このエラーは、多くの場合、SaaS 登録 正しく実行しない症状です。
コード: 404 見つかりません。
subscriptionId を含む SaaS サブスクリプションが見つかりません。
コード: 500 内部サーバー エラー。 API 呼び出しを再試行します。 エラーが解決しない場合は、Microsoft サポート にお問い合わせください。
操作の状態を取得する
この API を使用すると、パブリッシャーは指定した非同期操作の状態を追跡できます。登録解除、ChangePlan、または ChangeQuantity をします。
この API 呼び出しの operationId は、Operation-Location、保留中の Operations API 呼び出し、または webhook 呼び出しで受信した <id> パラメーター値によって返される値から取得できます。
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": ""
}
コード: 401 未承認。 承認トークンが無効であるか、有効期限が切れています。 要求は、認証トークンの作成に使用されたものとは異なる Microsoft Entra アプリ ID で発行されたオファーの SaaS サブスクリプションにアクセスしようとしています。
コード: 403 禁止。 承認トークンが無効であるか、指定されていないか、十分なアクセス許可が提供されていません。 有効な承認トークンを必ず指定してください。
このエラーは、多くの場合、SaaS 登録 正しく実行しない症状です。
コード: 404 見つかりません。
-
subscriptionIdを含むサブスクリプションが見つかりません。 -
operationIdを使用した操作が見つかりません。
コード: 500 内部サーバー エラー。 API 呼び出しを再試行します。 エラーが解決しない場合は、Microsoft サポート にお問い合わせください。
操作の状態を更新する
この API を使用して、保留中の操作の状態を更新して、パブリッシャー側で操作の成功または失敗を示します。
この API 呼び出しの operationId は、Operation-Location、保留中の Operations API 呼び出し、または webhook 呼び出しで受信した <id> パラメーター値によって返される値から取得できます。
パッチ 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 パートナー側での操作の完了を通知する呼び出し。 たとえば、この応答は、発行元側のシートまたはプランの変更の完了を通知できます。
コード: 401 未承認。 承認トークンが無効であるか、有効期限が切れています。 要求は、認証トークンの作成に使用されたものとは異なる Microsoft Entra アプリ ID で発行されたオファーの SaaS サブスクリプションにアクセスしようとしています。
コード: 403 禁止。 承認トークンが無効であるか、指定されていないか、十分なアクセス許可が提供されていません。 有効な承認トークンを必ず指定してください。
このエラーは、多くの場合、SaaS 登録 正しく実行しない症状です。
コード: 404 見つかりません。
-
subscriptionIdを含むサブスクリプションが見つかりません。 -
operationIdを使用した操作が見つかりません。
コード: 409 競合。 たとえば、新しい更新プログラムは既に満たされています。
コード: 500 内部サーバー エラー。 API 呼び出しを再試行します。 エラーが解決しない場合は、Microsoft サポート にお問い合わせください。
関連コンテンツ
- コマーシャル マーケットプレースでの SaaS オファーのその他のオプションについては、コマーシャル マーケットプレース使用状況測定サービス API を参照してください。
- のさまざまなプログラミング言語とサンプルのクライアントを確認して使用します。