Microsoft コマーシャル マーケットプレースの SaaS Fulfillment 操作 API v2

この記事では、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>

クエリ パラメーター:

要求ヘッダー:

応答コード:

コード: 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 見つかりません。 SaaS サブスクリプションが subscriptionId 見つかりません。

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

クエリ パラメーター:

要求ヘッダー:

応答コード:

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

クエリ パラメーター:

要求ヘッダー:

要求ペイロードの例:

{
  "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 を参照してください。
• さまざまなプログラミング言語のクライアントを確認して、サンプルを使用します。