Microsoft コマーシャル マーケットプレースでの SaaS Fulfillment サブスクリプション API v2
この記事では、SaaS Fulfillment サブスクリプション API のバージョン 2 について説明します。
購入済みサブスクリプションを解決する
resolve エンドポイントを使用すると、公開元は、コマーシャル マーケットプレースからの購入識別トークン (「購入済みであるが、まだアクティブ化されていない」で "トークン" として言及) を、永続的な購入済み SaaS サブスクリプション ID とその詳細に交換できます。
顧客がパートナーのランディング ページの URL にリダイレクトされると、この URL 呼び出しで、顧客識別トークンが token パラメーターとして渡されます。 パートナーは、このトークンを使用すること、およびそれを解決するための要求を行うことを期待されています。 Resolve API 応答には、購入を一意に識別するための SaaS サブスクリプション ID とその他の詳細が含まれています。 ランディング ページの URL 呼び出しで提供されるトークンは、24 時間有効です。 受信したトークンの有効期限が切れている場合は、エンド ユーザーに次のガイダンスを提供することをお勧めします。
"この購入を特定できませんでした。 この SaaS サブスクリプションを Azure portal または Microsoft 365 管理 Center で再度開き、[アカウントの構成] または [アカウントの管理] をもう一度選択します。
Resolve API を呼び出すと、サポートされているすべての状態の SaaS サブスクリプションのサブスクリプションの詳細と状態が返されます。
Posthttps://marketplaceapi.microsoft.com/api/saas/subscriptions/resolve?api-version=<ApiVersion>
クエリ パラメーター:
| パラメーター | 値 |
|---|---|
ApiVersion |
2018-08-31 を使用します。 |
要求ヘッダー:
| パラメーター | 値 |
|---|---|
content-type |
application/json |
x-ms-requestid |
クライアントからの要求を追跡するための一意の文字列値 (GUID を推奨)。 この値が指定されていない場合は、1 つが生成され、応答ヘッダーに指定されます。 |
x-ms-correlationid |
クライアントでの操作に対する一意の文字列値。 このパラメーターによって、クライアント操作からのすべてのイベントがサーバー側のイベントに関連付けられます。 この値が指定されていない場合は、1 つが生成され、応答ヘッダーに指定されます |
authorization |
この API 呼び出しを行っている発行者を識別する一意のアクセス トークン。 形式は、「 "Bearer <access_token>" Microsoft Entra アプリに基づくトークンを取得する」で 説明されているように、発行元がトークン値を取得する場合です。 |
x-ms-marketplace-token |
解決する購入 ID token パラメーター。 このトークンは、顧客が SaaS パートナーの Web サイトにリダイレクトされるときに、ランディング ページの URL 呼び出しで渡されます (例: https://contoso.com/signup?token=<token><authorization_token>)。 エンコードされるトークン値はランディング ページ URL の一部であるため、この API 呼び出しでパラメーターとして使用する前にデコードする必要があります。 URL 内のエンコードされた文字列の例は次のとおりです: contoso.com/signup?token=ab%2Bcd%2Fef。ここで、token は ab%2Bcd%2Fef です。 デコードされる同じトークンは次のとおりです。 Ab+cd/ef |
応答コード:
コード: 200 指定された内容に基づいて一意の SaaS サブスクリプション識別子を x-ms-marketplace-token 返します。
応答本文の例:
{
"id": "<guid>", // purchased SaaS subscription ID
"subscriptionName": "Contoso Cloud Solution", // SaaS subscription name
"offerId": "offer1", // purchased offer ID
"planId": "silver", // purchased offer's plan ID
"quantity": 20, // number of purchased seats, might be empty if the plan is not per seat
"subscription": { // full SaaS subscription details, see Get Subscription APIs response body for full description
"id": "<guid>",
"publisherId": "contoso",
"offerId": "offer1",
"name": "Contoso Cloud Solution",
"saasSubscriptionStatus": " PendingFulfillmentStart ",
"beneficiary": {
"emailId": "test@test.com",
"objectId": "<guid>",
"tenantId": "<guid>",
"puid": "<ID of the user>"
},
"purchaser": {
"emailId": "test@test.com",
"objectId": "<guid>",
"tenantId": "<guid>",
"puid": "<ID of the user>"
},
"planId": "silver",
"term": {
"termUnit": "P1M",
"startDate": "2022-03-07T00:00:00Z", //This field is only available after the saas subscription is active.
"endDate": "2022-04-06T00:00:00Z" //This field is only available after the saas subscription is active.
},
"autoRenew": true/false,
"isTest": true/false,
"isFreeTrial": false,
"allowedCustomerOperations": <CSP purchases>["Read"] <All Others> ["Delete", "Update", "Read"],
"sandboxType": "None",
"lastModified": "0001-01-01T00:00:00", //[Deprecated] Do not use.
"quantity": 5,
"sessionMode": "None"
}
}
コード: 400 無効な要求。 x-ms-marketplace-token が見つからないか、形式が正しくありません。または、有効期限が切れています。
コード: 403 禁止。 認証トークンが無効であるか、期限切れであるか、指定されませんでした。 要求は、承認トークンの作成に使用されたものとは異なる Microsoft Entra アプリ ID で発行されたオファーの SaaS サブスクリプションにアクセスしようとしています。
多くの場合、このエラーは、SaaS 登録を正しく実行していないことを表す症状です。
コード: 500 内部サーバー エラー。 API 呼び出しをやり直してください。 エラーが解決しない場合は、Microsoft サポートにお問い合わせください。
サブスクリプションをアクティブ化する
SaaS アカウントがエンド ユーザー向けに構成されたら、公開元は Microsoft 側で Activate Subscription API を呼び出す必要があります。 この API 呼び出しが成功しない限り、顧客には課金されません。
Posthttps://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/activate?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 |
この API 呼び出しを行っている発行者を識別する一意のアクセス トークン。 形式は、「 "Bearer <access_token>" Microsoft Entra アプリに基づくトークンを取得する」で 説明されているように、発行元がトークン値を取得する場合です。 |
応答コード:
コード: 200 サブスクリプションを更新し、"Subscribed" としてマークする要求が受信されます。 独立系ソフトウェア ベンダー (ISV) は、数分後にサブスクリプションの状態をチェックできます (サブスクリプションの状態をチェックするには、Get 操作を読み取ります)。 これにより、サブスクリプションが正常に更新されたかどうかを明確に示します。 サブスクライブに失敗すると、"Unsubscribe" Webhook が自動的に送信されます。
この呼び出しには応答本文がありません。
コード: 400 無効な要求: 検証に失敗しました。
- SaaS サブスクリプションが中断状態です。
コード: 403 禁止。 認証トークンが無効であるか、期限切れであるか、指定されませんでした。 要求は、承認トークンの作成に使用されたものとは異なる Microsoft Entra アプリ ID で発行されたオファーの SaaS サブスクリプションにアクセスしようとしています。
多くの場合、このエラーは、SaaS 登録を正しく実行していないことを表す症状です。
コード: 404 見つかりません。 SaaS サブスクリプションは Unsubscribed 状態です。
コード: 500 内部サーバー エラー。 API 呼び出しをやり直してください。 エラーが解決しない場合は、Microsoft サポートにお問い合わせください。
すべてのサブスクリプションの一覧を取得する
この API は、公開元がコマーシャル マーケットプレースに公開しているすべてのオファーのすべての購入済み SaaS サブスクリプションの一覧を取得します。 可能なすべての状態の SaaS サブスクリプションが返されます。 サブスクリプションを解除した SaaS サブスクリプションも返されます。この情報は Microsoft 側では削除されないためです。
この API では、1 ページあたり 100 件のページ分割された結果が返されます。
Get https://marketplaceapi.microsoft.com/api/saas/subscriptions?api-version=<ApiVersion>
クエリ パラメーター:
| パラメーター | 値 |
|---|---|
ApiVersion |
2018-08-31 を使用します。 |
continuationToken |
省略可能な 型のパラメーターです。 結果の最初のページを取得するには、空のままにします。 次のページを取得するには、@nextLink パラメーターで返された値を使用します。 |
要求ヘッダー:
| パラメーター | 値 |
|---|---|
content-type |
application/json |
x-ms-requestid |
クライアントからの要求を追跡するための一意の文字列値 (GUID を推奨)。 この値が指定されていない場合は、1 つが生成され、応答ヘッダーに指定されます。 |
x-ms-correlationid |
クライアントでの操作に対する一意の文字列値。 このパラメーターによって、クライアント操作からのすべてのイベントがサーバー側のイベントに関連付けられます。 この値が指定されていない場合は、1 つが生成され、応答ヘッダーに指定されます。 |
authorization |
この API 呼び出しを行っている公開元を識別する一意のアクセス トークン。 形式は、「 "Bearer <access_token>" Microsoft Entra アプリに基づくトークンを取得する」で 説明されているように、発行元がトークン値を取得する場合です。 |
応答コード:
コード: 200 発行元の承認トークンに基づいて、この発行元によって行われたすべてのオファーのすべての既存のサブスクリプションの一覧を返します。
応答本文の例:
{
"subscriptions": [
{
"id": "<guid>", // purchased SaaS subscription ID
"name": "Contoso Cloud Solution", // SaaS subscription name
"publisherId": "contoso", // publisher ID
"offerId": "offer1", // purchased offer ID
"planId": "silver", // purchased plan ID
"quantity": 10, // purchased amount of seats, is empty if plan is not per seat
"beneficiary": { // email address, user ID and tenant ID for which SaaS subscription was purchased.
"emailId": " test@contoso.com",
"objectId": "<guid>",
"tenantId": "<guid>",
"puid": "<ID of the user>"
},
"purchaser": { // email address, user ID and tenant ID that purchased the SaaS subscription. These could be different from beneficiary information for reseller (CSP) purchase
"emailId": " test@contoso.com",
"objectId": "<guid>",
"tenantId": "<guid>",
"puid": "<ID of the user>"
},
"term": { // The period for which the subscription was purchased.
"startDate": "2022-03-04T00:00:00Z", //format: YYYY-MM-DD. This is the date when the subscription was activated by the ISV and the billing started. This field is only available after the saas subscription is active.
"endDate": "2022-04-03T00:00:00Z", // This is the last day the subscription is valid. Unless stated otherwise, the automatic renew happens the next day. This field is only available after the saas subscription is active.
"termUnit": "P1M" // where P1M is monthly and P1Y is yearly. Also reflected in the startDate and endDate values
},
"autoRenew": true,
"allowedCustomerOperations": ["Read", "Update", "Delete"], // Indicates operations allowed on the SaaS subscription for beneficiary. For CSP-initiated purchases, this is always "Read" because the customer cannot update or delete subscription in this flow. Purchaser can perform all operations on the subscription.
"sessionMode": "None", // not relevant
"isFreeTrial": true, // true - the customer subscription is currently in free trial, false - the customer subscription is not currently in free trial. (Optional field -– if not returned, the value is false.)
"isTest": false, // not relevant
"sandboxType": "None", // not relevant
"saasSubscriptionStatus": "Subscribed" // Indicates the status of the operation. Can be one of the following: PendingFulfillmentStart, Subscribed, Suspended or Unsubscribed.
},
// next SaaS subscription details, might be a different offer
{
"id": "<guid1>",
"name": "Contoso Cloud Solution1",
"publisherId": "contoso",
"offerId": "offer2",
"planId": "gold",
"quantity": "",
"beneficiary": {
"emailId": " test@contoso.com",
"objectId": "<guid>",
"tenantId": "<guid>",
"puid": "<ID of the user>"
},
"purchaser": {
"emailId": "purchase@csp.com ",
"objectId": "<guid>",
"tenantId": "<guid>",
"puid": "<ID of the user>"
},
"term": {
"startDate": "2019-05-31", /This field is only available after the saas subscription is active.
"endDate": "2020-04-30", //This field is only available after the saas subscription is active.
"termUnit": "P1Y"
},
"autoRenew": false,
"allowedCustomerOperations": ["Read"],
"sessionMode": "None",
"isFreeTrial": false,
"isTest": false,
"sandboxType": "None",
"saasSubscriptionStatus": "Suspended"
}
],
"@nextLink": "https:// https://marketplaceapi.microsoft.com/api/saas/subscriptions/?continuationToken=%5b%7b%22token%22%3a%22%2bRID%3a%7eYeUDAIahsn22AAAAAAAAAA%3d%3d%23RT%3a1%23TRC%3a2%23ISV%3a1%23FPC%3aAgEAAAAQALEAwP8zQP9%2fFwD%2b%2f2FC%2fwc%3d%22%2c%22range%22%3a%7b%22min%22%3a%22%22%2c%22max%22%3a%2205C1C9CD673398%22%7d%7d%5d&api-version=2018-08-31" // url that contains continuation token to retrieve next page of the SaaS subscriptions list, if empty or absent, this is the last page. ISV can use this url as is to retrieve the next page or extract the value of continuation token from this url.
}
この発行者について購入済み SaaS サブスクリプションが見つからない場合は、空の応答本文が返されます。
コード: 403 禁止。 認証トークンが使用できないか、無効であるか、有効期限が切れています。
多くの場合、このエラーは、SaaS 登録を正しく実行していないことを表す症状です。
コード: 500 内部サーバー エラー。 API 呼び出しをやり直してください。 エラーが解決しない場合は、Microsoft サポートにお問い合わせください。
サブスクリプションを取得する
この API は、公開元がコマーシャル マーケットプレースに公開している SaaS オファーの、指定された購入済み SaaS サブスクリプションを取得します。 この呼び出しを使用して (すべてのサブスクリプションの一覧を取得するために API を呼び出すのではなく)、特定の SaaS サブスクリプションに関して入手できるすべての情報をその ID で取得します。
Get https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?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 |
この API 呼び出しを行っている公開元を識別する一意のアクセス トークン。 形式は、「 "Bearer <access_token>" Microsoft Entra アプリに基づくトークンを取得する」で 説明されているように、発行元がトークン値を取得する場合です。 |
応答コード:
コード: 200 提供された内容に基づいて SaaS サブスクリプションの詳細を subscriptionId 返します。
応答本文の例:
{
"id": "<guid>", // purchased SaaS subscription ID
"name": "Contoso Cloud Solution", // SaaS subscription name
"publisherId": "contoso", // publisher ID
"offerId": "offer1", // purchased offer ID
"planId": "silver", // purchased plan ID
"quantity": 10, // purchased amount of seats is empty if plan is not per seat
"beneficiary": { // email address, user ID and tenant ID for which SaaS subscription is purchased.
"emailId": "test@contoso.com",
"objectId": "<guid>",
"tenantId": "<guid>",
"puid": "<ID of the user>"
},
"purchaser": { // email address ,user ID and tenant ID that purchased the SaaS subscription. These could be different from beneficiary information for reseller (CSP) scenario
"emailId": "test@test.com",
"objectId": "<guid>",
"tenantId": "<guid>",
"puid": "<ID of the user>"
},
"allowedCustomerOperations": ["Read", "Update", "Delete"], // Indicates operations allowed on the SaaS subscription for beneficiary. For CSP-initiated purchases, this is always "Read" because the customer cannot update or delete subscription in this flow. Purchaser can perform all operations on the subscription.
"sessionMode": "None", // not relevant
"isFreeTrial": false, // true - the customer subscription is currently in free trial, false - the customer subscription is not currently in free trial. Optional field – if not returned the value is false.
"autoRenew": true,
"isTest": false, // not relevant
"sandboxType": "None", // not relevant
"created": "2022-03-01T22:59:45.5468572Z",
"lastModified": "0001-01-01T00:00:00", //[Deprecated] Do not use.
"saasSubscriptionStatus": " Subscribed ", // Indicates the status of the operation: PendingFulfillmentStart, Subscribed, Suspended or Unsubscribed.
"term": { // the period for which the subscription was purchased
"startDate": "2022-03-04T00:00:00Z", //format: YYYY-MM-DD. This is the date when the subscription was activated by the ISV and the billing started. This field is only available after the saas subscription is active.
"endDate": "2022-04-03T00:00:00Z", // This is the last day the subscription is valid. Unless stated otherwise, the automatic renew happens the next day. This field is only available after the saas subscription is active.
"termUnit": "P1M" //where P1M is monthly and P1Y is yearly. Also reflected in the startDate and endDate values.
}
}
コード: 403 禁止。 認証トークンが無効であるか、期限切れであるか、指定されませんでした。 要求は、承認トークンの作成に使用されたものとは異なる Microsoft Entra アプリ ID で発行されたオファーの SaaS サブスクリプションにアクセスしようとしています。
多くの場合、このエラーは、SaaS 登録を正しく実行していないことを表す症状です。
コード: 404 見つかりません。 指定された subscriptionId の SaaS サブスクリプションが見つかりません。
コード: 500 内部サーバー エラー。 API 呼び出しをやり直してください。 エラーが解決しない場合は、Microsoft サポートにお問い合わせください。
利用可能なプランを一覧表示する
この API は、このオファーの特定の購入の subscriptionId によって識別される SaaS オファーのすべてのプランを取得します。 この呼び出しを使用して、SaaS サブスクリプションの利用者がサブスクリプションで更新できるすべてのプライベートおよびパブリック プランの一覧を取得します。 返されるプランは、既に購入したプランと同じ地域で利用できます。
この呼び出しからは、既に購入済みのものに加えて、その顧客が使用可能なプランの一覧が返されます。 その一覧は、公開元のサイト上でエンド ユーザーに表示できます。 エンド ユーザーはサブスクリプション プランを、返された一覧にあるいずれかのプランに変更できます。 一覧にないプランにプランを変更しても機能しません。
この API は、関連付けられているアクティブなプライベート オファー ID も取得します (planId フィルターを使用して API を呼び出す場合)。 planId フィルターを使用して API を呼び出すと、sourceOffers ノードの応答本文にアクティブなプライベート オファー ID GUID が表示されます。 フィルター パラメーターで渡される planId は、顧客が購入した planId と一致する必要があります。
Get https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/listAvailablePlans?api-version=<ApiVersion>&planId=<planId>
クエリ パラメーター:
| パラメーター | 値 |
|---|---|
ApiVersion |
2018-08-31 を使用します。 |
subscriptionId |
購入済み SaaS サブスクリプションの一意識別子。 この ID は、Resolve API を使用してコマーシャル マーケットプレース認証トークンを解決した後に取得されます。 |
planId (Optional) |
フェッチする特定のプランのプラン ID。 これは省略可能であり、無視するとすべてのプランが返されます。 |
要求ヘッダー:
| パラメーター | 値 |
|---|---|
content-type |
application/json |
x-ms-requestid |
クライアントからの要求を追跡するための一意の文字列値 (GUID を推奨)。 この値が指定されていない場合は、1 つが生成され、応答ヘッダーに指定されます。 |
x-ms-correlationid |
クライアントでの操作に対する一意の文字列値。 このパラメーターによって、クライアント操作からのすべてのイベントがサーバー側のイベントに関連付けられます。 この値が指定されていない場合は、1 つが生成され、応答ヘッダーに指定されます。 |
authorization |
この API 呼び出しを行っている公開元を識別する一意のアクセス トークン。 形式は、「 "Bearer <access_token>" Microsoft Entra アプリに基づくトークンを取得する」で 説明されているように、発行元がトークン値を取得する場合です。 |
応答コード:
コード: 200 既に購入済みの SaaS サブスクリプションを含む、既存の SaaS サブスクリプションで使用可能なすべてのプランの一覧を返します。
無効な (省略可能) planId を渡すと、プランの空の一覧が返されます。
応答本文の例:
{
"plans": [
{
"planId": "Platinum001",
"displayName": "plan display name",
"isPrivate": true, //returns true for private plans and customized plans created within a private offer.
"description": "plan description",
"minQuantity": 5,
"maxQuantity": 100,
"hasFreeTrials": false,
"isPricePerSeat": true,
"isStopSell": false,
"market": "US",
"planComponents": {
"recurrentBillingTerms": [
{
"currency": "USD",
"price": 1,
"termUnit": "P1M",
"termDescription": "term description",
"meteredQuantityIncluded": [
{
"dimensionId": "Dimension001",
"units": "Unit001"
}
]
}
],
"meteringDimensions": [
{
"id": "MeteringDimension001",
"currency": "USD",
"pricePerUnit": 1,
"unitOfMeasure": "unitOfMeasure001",
"displayName": "unit of measure display name"
}
]
},
"sourceOffers": [ //sourceOffers is returned when planId is passed as filter parameter (note that this is the plan that customer has purchased).
{
"externalId": "<guid>" //private offer id, returned when purchase is made through private offer.
}
]
}
]
}
コード:404 見つかりません。
subscriptionId が見つかりません。
コード: 403 禁止。 認証トークンが無効であるか、期限切れであるか、指定されませんでした。 要求は、承認トークンの作成に使用されたものとは異なる Microsoft Entra アプリ ID でサブスクライブ解除または発行されたオファーの SaaS サブスクリプションにアクセスしようとしている可能性があります。
多くの場合、このエラーは、SaaS 登録を正しく実行していないことを表す症状です。
コード: 500 内部サーバー エラー。 API 呼び出しをやり直してください。 エラーが解決しない場合は、Microsoft サポートにお問い合わせください。
サブスクリプションのプランを変更する
この API を使用して、SaaS サブスクリプションで購入済みの既存のプランを新しいプラン (パブリックまたはプライベート) に更新します。 公開元は、コマーシャル マーケットプレースで購入された SaaS サブスクリプションについて公開元側でプランが変更されるときに、この API を呼び出す必要があります。
この API は、"アクティブ" なサブスクリプションに対してのみ呼び出すことができます。 どのプランも他の既存のプラン (パブリックまたはプライベート) に変更できますが、それ自体には変更できません。 プライベート プランの場合、顧客のテナントは、パートナー センターでプランの対象ユーザーの一部として定義されている必要があります。
Patch https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?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 |
この API 呼び出しを行っている公開元を識別する一意のアクセス トークン。 形式は、「 "Bearer <access_token>" Microsoft Entra アプリに基づくトークンを取得する」で 説明されているように、発行元がトークン値を取得する場合です。 |
要求ペイロードの例:
{
"planId": "gold" // the ID of the new plan to be purchased
}
応答コード:
コード: 202 プランの変更要求が受け入れられ、非同期的に処理されました。 パートナーは、プラン変更要求の成功または失敗を判断するために Operation-Location の URL をポーリングする必要があります。 操作の最終状態として "失敗"、"成功"、または "競合" を受け取るまで数秒ごとにポーリングを行います。 最終的な操作の状態は迅速に返されますが、場合によっては数分かかることがあります。
パートナーは、コマーシャル マーケットプレース側でアクションを正常に完了する準備ができたら、webhook 通知も受け取ります。 その段階でようやく、公開元側でプランの変更を行います。
応答ヘッダー:
| パラメーター | 値 |
|---|---|
Operation-Location |
操作の状態を取得するための URL。 たとえば、https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31 のように指定します。 |
コード: 400 無効な要求: 検証エラー。
- 新しいプランが存在しないか、この特定の SaaS サブスクリプションでは使用できません。
- 新しいプランは、現在のプランと同じです。
- SaaS サブスクリプションの状態が Subscribed ではありません。
- SaaS サブスクリプションの更新操作が
allowedCustomerOperationsに含まれていません。
コード: 403 禁止。 認証トークンが無効であるか、期限切れであるか、指定されませんでした。 要求は、承認トークンの作成に使用されたものとは異なる Microsoft Entra アプリ ID で発行されたオファーの SaaS サブスクリプションにアクセスしようとしています。
多くの場合、このエラーは、SaaS 登録を正しく実行していないことを表す症状です。
コード: 404 見つかりません。 subscriptionId を持つ SaaS サブスクリプションが見つかりません。
コード: 500 内部サーバー エラー。 API 呼び出しをやり直してください。 エラーが解決しない場合は、Microsoft サポートにお問い合わせください。
Note
一度に変更できるのは、プランまたはシート数のいずれかであり、両方ではありません。
この API は、エンド ユーザーから変更の明示的な承認を得た後にのみ呼び出すことができます。
SaaS サブスクリプションのシート数を変更する
この API を使用して、SaaS サブスクリプションのために購入されたシートの数を更新 (増減) します。 公開元は、コマーシャル マーケットプレースで作成された SaaS サブスクリプションのシート数が公開元側から変更されるときに、この API を呼び出す必要があります。
シートの数量は、現在のプランで許可されている数量を超えることはできません。 この場合、公開元は、シート数を変更する前にプランを変更する必要があります。
Patch https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?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 |
この API 呼び出しを行っている公開元を識別する一意のアクセス トークン。 形式は、「 "Bearer <access_token>" Microsoft Entra アプリに基づくトークンを取得する」で 説明されているように、発行元がトークン値を取得する場合です。 |
要求ペイロードの例:
{
"quantity": 5 // the new amount of seats to be purchased
}
応答コード:
コード: 202 数量の変更要求が受け入れられ、非同期的に処理されました。 パートナーは、数量変更要求の成功または失敗を判断するために Operation-Location の URL をポーリングする必要があります。 操作の最終状態として "失敗"、"成功"、または "競合" を受け取るまで数秒ごとにポーリングを行います。 最終的な操作の状態は迅速に返されますが、場合によっては数分かかることがあります。
パートナーは、コマーシャル マーケットプレース側でアクションを正常に完了する準備ができたら、webhook 通知も受け取ります。 その段階でようやく、公開元側で数量の変更を行います。
応答ヘッダー:
| パラメーター | 値 |
|---|---|
Operation-Location |
操作状態を取得するリソースへのリンク。 たとえば、https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31 のようにします。 |
コード: 400 無効な要求: 検証エラー。
- 新しい数量が現在のプランの制限を上回っているか下回っています。
- 新しい数量がありません。
- 新しい数量は、現在の数量と同じです。
- SaaS サブスクリプションの状態がサブスクライブ済みではありません。
- SaaS サブスクリプションの更新操作が
allowedCustomerOperationsに含まれていません。
コード: 403 禁止。 認証トークンが無効であるか、期限切れであるか、指定されませんでした。 要求で、現在の発行者に属していないサブスクリプションにアクセスしようとしています。
多くの場合、このエラーは、SaaS 登録を正しく実行していないことを表す症状です。
コード: 404 見つかりません。 subscriptionId を持つ SaaS サブスクリプションが見つかりません。
コード: 500 内部サーバー エラー。 API 呼び出しをやり直してください。 エラーが解決しない場合は、Microsoft サポートにお問い合わせください。
Note
一度に変更できるのはプランまたは数量だけであり、両方ではありません。
この API は、変更についてエンド ユーザーから明示的な承認を得た後にのみ呼び出すことができます。
サブスクリプションを取り消す
この API を使用して、指定した SaaS サブスクリプションの登録を解除します。 公開元はこの API を使用する必要はありません。SaaS サブスクリプションを取り消すには、顧客をコマーシャル マーケットプレースに誘導することをお勧めします。
コマーシャル マーケットプレースで購入された SaaS サブスクリプションの取り消しを公開元側で実装する場合、公開元はこの API を呼び出す必要があります。 この呼び出しが完了すると、サブスクリプションの状態は Microsoft 側でサブスクライブ解除されます。
購入から 72 時間以内にサブスクリプションが取り消された場合、顧客は課金されません。
前の猶予期間の後にサブスクリプションが取り消された場合、顧客は課金されます。 お客様は、取り消し直後に Microsoft 側の SaaS サブスクリプションにアクセスできなくなります。
Delete https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?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 |
この API 呼び出しを行っている発行者を識別する一意のアクセス トークン。 形式は、「 "Bearer <access_token>" Microsoft Entra アプリに基づくトークンを取得する」で 説明されているように、発行元がトークン値を取得する場合です。 |
応答コード:
コード: 202 サブスクライブ解除の要求が受け入れられ、非同期的に処理されました。 パートナーは、この要求の成功または失敗を判断するために Operation-Location の URL をポーリングする必要があります。 操作の最終状態として "失敗"、"成功"、または "競合" を受け取るまで数秒ごとにポーリングを行います。 最終的な操作の状態は迅速に返されますが、場合によっては数分かかることがあります。
また、コマーシャル マーケットプレース側でアクションが正常に完了すると、パートナーは Webhook 通知を受け取ります。 その段階でようやく、公開元側でサブスクリプションを取り消します。
コード: 200 サブスクリプションは既にサブスクライブ解除状態です。
応答ヘッダー:
| パラメーター | 値 |
|---|---|
Operation-Location |
操作状態を取得するリソースへのリンク。 たとえば、https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31 のようにします。 |
コード: 400 無効な要求。 削除は、この SaaS サブスクリプションの allowedCustomerOperations 一覧に含まれていません。
コード: 403 禁止。 認証トークンが無効であるか、期限切れであるか、使用できません。
多くの場合、このエラーは、SaaS 登録を正しく実行していないことを表す症状です。
コード: 404 見つかりません。 subscriptionId を持つ SaaS サブスクリプションが見つかりません。
コード: 409
保留中の操作によりサブスクリプションがロックされているため、削除を完了できません。
コード: 500 内部サーバー エラー。 API 呼び出しをやり直してください。 エラーが解決しない場合は、Microsoft サポートにお問い合わせください。
次のステップ
- コマーシャル マーケットプレースでの SaaS オファーのその他のオプションについては、コマーシャル マーケットプレースの測定サービス API を参照してください
- さまざまなプログラミング言語とサンプルの クライアントを確認して使用する
- テスト ガイダンスについては、SaaS サービスでの Webhook の実装に関するページを参照してください 。
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示