この記事では、SaaS フルフィルメント サブスクリプション API のバージョン 2 について説明します。
Note
SaaS フルフィルメント サブスクリプション API を呼び出すには、正しいリソース ID を使用してパブリッシャー承認トークンを作成します。 詳細については、「 発行元の承認トークンを取得する」を参照してください。
Note
CSP で購入したサブスクリプションの場合、受益者はこのフローでサブスクリプションを更新または削除できないため、許可される操作は 読み取りに制限されます。 その他のすべての購入では、[読み取り、更新、削除] のすべてのアクションが許可されます。
購入したサブスクリプションを解決する
解決エンドポイントを使用すると、パブリッシャーは、永続的に購入した SaaS サブスクリプション ID とその詳細について、Microsoft Marketplace から購入 ID トークン (購入済みでまだアクティブ化されていないトークンと呼ばれます) を交換できます。
Note
自動アクティブ化が有効になっているプランの場合、Resolve API は必要ありません。 Microsoftは、Subscribe webhook 通知を介してサブスクリプションの詳細をパブリッシャーに直接送信します。
顧客がパートナーのランディング ページ URL にリダイレクトされると、顧客識別トークンは、この URL 呼び出しで トークン パラメーターとして渡されます。 パートナーはこのトークンを使用して、それを解決するための要求を行います。 Resolve API 応答には、購入を一意に識別するための SaaS サブスクリプション ID とその他の詳細が含まれています。 ランディング ページの URL 呼び出しで提供 トークンは、24 時間有効です。 受信した トークン の有効期限が切れている場合は、エンド ユーザーに次のガイダンスを提供します。
「この購入を特定できませんでした。 Azure ポータルまたは Microsoft 365 管理 Center でこの SaaS サブスクリプションを再度開き、[アカウントの構成] または [アカウントの管理] をもう一度選択します。
Resolve API を呼び出すと、サポートされているすべての状態の SaaS サブスクリプションのサブスクリプションの詳細と状態が返されます。
https://marketplaceapi.microsoft.com/api/saas/subscriptions/resolve?api-version=<api-version> を投稿する
クエリ パラメーター:
| Parameter | Value |
|---|---|
api-version |
2018-08-31 を使用します。 |
要求ヘッダー:
応答コード:
コード: 200 提供された x-ms-marketplace-token に基づいて、一意の SaaS サブスクリプション識別子を返します。
応答本文の例:
{
"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 licenses, 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>", //for informational purposes, showing who is the beneficiary
"tenantId": "<guid>",
"puid": "<ID of the user>" //for informational purposes, showing who is the beneficiary
},
"purchaser": {
"emailId": "test@test.com",
"objectId": "<guid>", //for informational purposes, showing who made the purchase
"tenantId": "<guid>",
"puid": "<ID of the user>" //for informational purposes, showing who made the purchase
},
"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": ["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.
"sandboxType": "None",
"lastModified": "0001-01-01T00:00:00", //[Deprecated] Do not use.
"quantity": 5,
"sessionMode": "None"
}
}
コード: 400 無効な要求。
x-ms-marketplace-token が見つからない、形式が正しくない、無効、または期限切れです。
コード: 401 未承認。 承認トークンが無効であるか、有効期限が切れています。 要求は、認証トークンの作成に使用されたものとは異なる Microsoft Entra アプリ ID で発行されたオファーの SaaS サブスクリプションにアクセスしようとしています。
コード: 403 禁止。 承認トークンが無効であるか、指定されていないか、または十分なアクセス許可が提供されていません。 有効な承認トークンを指定します。
多くの場合、このエラーは 、SaaS 登録 が正しく実行されなかったことを示します。
コード: 500 内部サーバー エラー。 API 呼び出しを再試行します。 エラーが解決しない場合は、Microsoft サポート にお問い合わせください。
サブスクリプションをアクティブ化する
エンド ユーザーの SaaS アカウントを構成した後、パブリッシャーは、Microsoft側で Activate Subscription API を呼び出す必要があります。 この API 呼び出しが成功しない限り、顧客には課金されません。
Note
自動アクティブ化が有効になっているプランの場合、発行元は Activate API を呼び出す必要はありません。 Microsoft購入時にサブスクリプションが自動的にアクティブ化され、発行元は代わりに Subscribe webhook 通知を受け取ります。 詳細については、「 自動アクティブ化の構成」を参照してください。
https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/activate?api-version=<api-version> を投稿する
クエリ パラメーター:
| Parameter | Value |
|---|---|
api-version |
2018-08-31 を使用します。 |
subscriptionId |
購入した SaaS サブスクリプションの一意識別子。 この ID は、Resolve API を使用して Microsoft Marketplace 承認トークンを解決した後で取得します。 |
要求ヘッダー:
応答コード:
コード: 200 サブスクリプションを更新し、"Subscribed" としてマークする要求が受信されます。 独立系ソフトウェア ベンダー (ISV) は、数分後にサブスクリプションの状態を確認できます (サブスクリプションの状態を確認するには、Get 操作を読み取ります)。 この操作により、サブスクリプションが正常に更新されたかどうかの明確な回答が得られます。 サブスクライブに失敗すると、"Unsubscribe" Webhook が自動的に送信されます。
この呼び出しには応答本文がありません。
コード: 400 無効な要求: 検証に失敗しました。
- SaaS サブスクリプションが 中断 状態です。
コード: 401 未承認。 承認トークンが無効であるか、有効期限が切れています。 要求は、認証トークンの作成に使用されたものとは異なる Microsoft Entra アプリ ID で発行されたオファーの SaaS サブスクリプションにアクセスしようとしています。
コード: 403 禁止。 承認トークンが無効であるか、指定されていないか、または十分なアクセス許可が提供されていません。 有効な承認トークンを指定します。
多くの場合、このエラーは 、SaaS 登録 が正しく実行されなかったことを示します。
コード: 404 見つかりません。 SaaS サブスクリプションは、登録解除 状態です。
コード: 500 内部サーバー エラー。 API 呼び出しを再試行します。 エラーが解決しない場合は、Microsoft サポート にお問い合わせください。
すべてのサブスクリプションの一覧を取得する
この API は、パブリッシャーが Microsoft Marketplace で発行するすべてのオファーについて、購入したすべての SaaS サブスクリプションの一覧を取得します。 MICROSOFTはこの情報を削除しないため、登録解除されたサブスクリプションを含め、使用可能なすべての状態の SaaS サブスクリプションが返されます。
API は、ページ分割された結果を返します。 後続の結果を取得するには、continuationToken を渡す必要があります。
https://marketplaceapi.microsoft.com/api/saas/subscriptions?api-version=<api-version> を取得する
クエリ パラメーター:
| Parameter | Value |
|---|---|
api-version |
2018-08-31 を使用します。 |
continuationToken |
省略可能なパラメーターです。 結果の最初のページを取得するには、空のままにします。 パラメーターで返される値 @nextLink 使用して、次のページを取得します。 |
要求ヘッダー:
応答コード:
コード: 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 licenses, 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>", //for informational purposes, showing who is the beneficiary
"tenantId": "<guid>",
"puid": "<ID of the user>" //for informational purposes, showing who is the beneficiary
},
"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>", //for informational purposes, showing who made the purchase
"tenantId": "<guid>",
"puid": "<ID of the user>" //for informational purposes, showing who made the purchase
},
"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>", //for informational purposes, showing who is the beneficiary
"tenantId": "<guid>",
"puid": "<ID of the user>" //for informational purposes, showing who is the beneficiary
},
"purchaser": {
"emailId": "purchase@csp.com ",
"objectId": "<guid>", //for informational purposes, showing who made the purchase
"tenantId": "<guid>",
"puid": "<ID of the user>" //for informational purposes, showing who made the purchase
},
"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", "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",
"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 サブスクリプションが見つからない場合、応答本文は空です。
コード: 401 未承認。 承認トークンが無効であるか、有効期限が切れています。 要求は、認証トークンの作成に使用されたものとは異なる Microsoft Entra アプリ ID で発行されたオファーの SaaS サブスクリプションにアクセスしようとしています。
コード: 403 禁止。 承認トークンが無効であるか、指定されていないか、または十分なアクセス許可が提供されていません。 有効な承認トークンを指定します。
多くの場合、このエラーは 、SaaS 登録 が正しく実行されなかったことを示します。
コード: 500 内部サーバー エラー。 API 呼び出しを再試行します。 エラーが解決しない場合は、Microsoft サポート にお問い合わせください。
サブスクリプションを取得する
この API は、発行元が Microsoft Marketplace で発行する SaaS オファーに対して、購入した SaaS サブスクリプションを指定して取得します。 この呼び出しを使用して、すべてのサブスクリプションの一覧を取得するために使用される API を呼び出すのではなく、特定の SaaS サブスクリプションの使用可能なすべての情報を ID で取得します。
https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<api-version> を取得する
クエリ パラメーター:
| Parameter | Value |
|---|---|
api-version |
2018-08-31 を使用します。 |
subscriptionId |
購入した SaaS サブスクリプションの一意識別子。 この ID は、Resolve API を使用して Microsoft Marketplace 承認トークンを解決した後に取得します。 |
要求ヘッダー:
応答コード:
コード: 200 指定した subscriptionId に基づいて SaaS サブスクリプションの詳細を返します。
応答本文の例:
{
"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 licenses 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>", //for informational purposes, showing who is the beneficiary
"tenantId": "<guid>",
"puid": "<ID of the user>" //for informational purposes, showing who is the beneficiary
},
"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>", //for informational purposes, showing who made the purchase
"tenantId": "<guid>",
"puid": "<ID of the user>" //for informational purposes, showing who made the purchase
},
"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.
}
}
コード: 401 未承認。 承認トークンが無効であるか、有効期限が切れています。 要求は、認証トークンの作成に使用されたものとは異なる Microsoft Entra アプリ ID で発行されたオファーの SaaS サブスクリプションにアクセスしようとしています。
コード: 403 禁止。 承認トークンが無効であるか、指定されていないか、または十分なアクセス許可が提供されていません。 有効な承認トークンを指定します。
多くの場合、このエラーは 、SaaS 登録 が正しく実行されなかったことを示します。
コード: 404 見つかりません。 指定した subscriptionId を持つ SaaS サブスクリプションが見つかりません。
コード: 500 内部サーバー エラー。 API 呼び出しを再試行します。 エラーが解決しない場合は、Microsoft サポート にお問い合わせください。
利用可能なプランを一覧表示する
この API は、このオファーの特定の購入の subscriptionId によって識別される SaaS オファーのすべてのプランを取得します。 この呼び出しを使用して、SaaS サブスクリプションの受益者がサブスクリプションに対して更新できるすべてのプライベート プランとパブリック プランの一覧を取得します。 返されるプランは、既に購入したプランと同じ地域で利用できます。
この呼び出しでは、既に購入されているプランに加えて、その顧客が利用できるプランの一覧が返されます。 パブリッシャー サイトのエンド ユーザーにリストを表示できます。 エンド ユーザーは、返された一覧のプランのいずれかにサブスクリプション プランを変更できます。 一覧にないプランにプランを変更しても機能しません。
この API は、関連付けられているアクティブなプライベート オファー ID も取得します (planId フィルターを使用して API を呼び出す場合)。 planId フィルターを使用して API を呼び出すと、sourceOffers ノードの応答本文にアクティブなプライベート オファー ID GUID が表示されます。 フィルター パラメーターで渡される planId は、顧客が購入した planId と一致する必要があります。
https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/listAvailablePlans?api-version=<api-version>&planId=<planId> を取得する
クエリ パラメーター:
| Parameter | Value |
|---|---|
api-version |
2018-08-31 を使用します。 |
subscriptionId |
購入した SaaS サブスクリプションの一意識別子。 この ID は、Resolve API を使用して Microsoft Marketplace 承認トークンを解決した後に取得します。 |
planId (Optional) |
フェッチする特定のプランのプラン ID。 このパラメーターはオプションです。 省略すると、API はすべてのプランを返します。 |
要求ヘッダー:
応答コード:
コード: 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 が見つかりません。
コード: 401 未承認。 承認トークンが無効であるか、有効期限が切れています。 要求は、認証トークンの作成に使用されたものとは異なる Microsoft Entra アプリ ID で発行されたオファーの SaaS サブスクリプションにアクセスしようとしています。
コード: 403 禁止。 承認トークンが無効であるか、指定されていないか、または十分なアクセス許可が提供されていません。 有効な承認トークンを指定します。
多くの場合、このエラーは 、SaaS 登録 が正しく実行されなかったことを示します。
コード: 500 内部サーバー エラー。 API 呼び出しを再試行します。 エラーが解決しない場合は、Microsoft サポート にお問い合わせください。
サブスクリプションのプランを変更する
この API を使用して、SaaS サブスクリプション用に購入した既存のプランを新しいプラン (パブリックまたはプライベート) に更新します。 パブリッシャーは、Microsoft Marketplace で購入した SaaS サブスクリプションのプランをパブリッシャー側で変更するときに、この API を呼び出す必要があります。
この API は 、アクティブな サブスクリプションに対してのみ呼び出すことができます。 任意のプランを他の既存のプラン (パブリックまたはプライベート) に変更できますが、それ自体には変更できません。 プライベート プランの場合は、パートナー センターでプランの対象ユーザーの一部として顧客のテナントを定義する必要があります。
パッチ https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<api-version>
クエリ パラメーター:
| Parameter | Value |
|---|---|
api-version |
2018-08-31 を使用します。 |
subscriptionId |
購入した SaaS サブスクリプションの一意識別子。 この ID は、Resolve API を使用して Microsoft Marketplace 承認トークンを解決した後に取得します。 |
要求ヘッダー:
要求ペイロードの例:
{
"planId": "gold" // the ID of the new plan to be purchased
}
応答コード:
コード: 202 プランの変更要求が受け入れられ、非同期的に処理されます。 パートナー アプリは 、Operation-Location URL を ポーリングして、変更計画要求の成功または失敗を判断する必要があります。 操作の最後の状態が [失敗]、[ 成功]、または [競合 ] になるまで、数秒ごとにポーリングします。 最終的な操作の状態はすぐに戻りますが、場合によっては数分かかることがあります。
パートナー アプリは、Microsoft Marketplace でアクションを正常に完了する準備ができたら、webhook 通知も受け取ります。 パブリッシャー側でプランを変更する必要があるのは、その場合のみです。
応答ヘッダー:
| Parameter | Value |
|---|---|
Operation-Location |
操作の状態を取得する URL。 たとえば、https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31 |
コード: 400 無効な要求: 検証エラー。
- 要求されたプランが見つからないか、ユーザーがプランを使用できません。
- 要求されたプランは、サブスクライブされたプランと同じです。
- SaaS サブスクリプションの状態は、サブスクライブ されていません。
- 更新される SaaS サブスクリプションは、クラウド ソリューション プロバイダー (CSP) によって購入されます。 このアクションを実行するには、CSP プロバイダーと協力する必要があります。
- SaaS サブスクリプションは、譲渡後に更新されるまで管理できません。 この制限は更新日まで適用されます。
コード: 401 未承認。 承認トークンが無効であるか、有効期限が切れています。 要求は、認証トークンの作成に使用されたものとは異なる Microsoft Entra アプリ ID で発行されたオファーの SaaS サブスクリプションにアクセスしようとしています。
コード: 403 禁止。 承認トークンが無効であるか、指定されていないか、または十分なアクセス許可が提供されていません。 有効な承認トークンを指定します。
多くの場合、このエラーは 、SaaS 登録 が正しく実行されなかったことを示します。
コード: 404 見つかりません。 指定した subscriptionId を持つ SaaS サブスクリプションが見つかりません。
コード: 500 内部サーバー エラー。 API 呼び出しを再試行します。 エラーが解決しない場合は、Microsoft サポート にお問い合わせください。
Note
ライセンスのプランまたは数量は一度に変更できますが、両方を変更することはできません。
この API は、エンド ユーザーからの変更に対する明示的な承認を取得した後にのみ呼び出すことができます。
SaaS サブスクリプションのライセンス数を変更する
この API を使用して、SaaS サブスクリプションで購入したライセンスの数を更新 (増減) します。 パブリッシャーは、Microsoft Marketplace で作成された SaaS サブスクリプションのライセンス数がパブリッシャー側から変更された場合に、この API を呼び出す必要があります。
ライセンスの数量は、現在のプランで許可されている数量を超えることはできません。 この場合、発行元はライセンスの数量を変更する前にプランを変更する必要があります。
パッチ https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<api-version>
クエリ パラメーター:
| Parameter | Value |
|---|---|
api-version |
2018-08-31 を使用します。 |
subscriptionId |
購入した SaaS サブスクリプションの一意識別子。 この ID は、Resolve API を使用して Microsoft Marketplace 承認トークンを解決した後に取得します。 |
要求ヘッダー:
要求ペイロードの例:
{
"quantity": 5 // the new amount of licenses to be purchased
}
応答コード:
コード: 202 数量の変更要求が受け入れられ、非同期的に処理されます。 パートナーは、Operation-Location URL をポーリングして、変更数量要求の成功または失敗を判断する必要があります。 操作の最後の状態が [失敗]、[ 成功]、または [競合 ] になるまで、数秒ごとにポーリングします。 最終的な操作状態はすぐに戻りますが、場合によっては数分かかることがあります。
パートナーは、Microsoft Marketplace でアクションを正常に完了する準備ができたら、Webhook 通知も受け取ります。 パブリッシャー側で数量を変更する場合にのみ、パブリッシャー側で数量が変更されます。
応答ヘッダー:
| Parameter | Value |
|---|---|
Operation-Location |
リソースにリンクして、操作の状態を取得します。 たとえば、https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31します。 |
コード: 400 無効な要求: 検証エラー。
- 新しい数量が許容範囲内にありません。
- 新しい数量が見つからないか、0 です。
- 新しい数量は現在の数量と同じです。
- SaaS サブスクリプションの状態がサブスクライブされていません。
- 更新される SaaS サブスクリプションは、クラウド ソリューション プロバイダー (CSP) によって購入されます。 このアクションを実行するには、CSP プロバイダーと協力する必要があります。
- SaaS サブスクリプションは、譲渡後に更新されるまで管理できません。 この制限は更新日まで適用されます。
コード: 401 未承認。 承認トークンが無効であるか、有効期限が切れています。 要求は、認証トークンの作成に使用されたものとは異なる Microsoft Entra アプリ ID で発行されたオファーの SaaS サブスクリプションにアクセスしようとしています。
コード: 403 禁止。 承認トークンが無効であるか、指定されていないか、または十分なアクセス許可が提供されていません。 有効な承認トークンを指定します。
このエラーは、多くの場合、SaaS 登録 正しく実行しない症状です。
コード: 404 見つかりません。 指定した subscriptionId を持つ SaaS サブスクリプションが見つかりません。
コード: 500 内部サーバー エラー。 API 呼び出しを再試行します。 エラーが解決しない場合は、Microsoft サポート にお問い合わせください。
Note
一度に変更できるのはプランまたは数量のみです。両方を変更することはできません。
この API は、変更についてエンド ユーザーから明示的な承認を受けた後にのみ呼び出します。
サブスクリプションを取り消す
この API を使用して、指定した SaaS サブスクリプションのサブスクライブを解除します。 パブリッシャーはこの API を使用する必要はありません。 顧客を Microsoft Marketplace に誘導して SaaS サブスクリプションを取り消します。
パブリッシャー側で Microsoft Marketplace で購入した SaaS サブスクリプションのキャンセルを実装する場合は、この API を呼び出す必要があります。 この呼び出しが完了すると、サブスクリプションの状態が Microsoft 側 登録解除 になります。
購入から 72 時間以内にサブスクリプションが取り消された場合、顧客は課金されません。
前の猶予期間の後にサブスクリプションが取り消された場合、顧客は課金されます。 お客様は、取り消し直後に Microsoft 側の SaaS サブスクリプションにアクセスできなくなります。
https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<api-version> の削除
クエリ パラメーター:
| Parameter | Value |
|---|---|
api-version |
2018-08-31 を使用します。 |
subscriptionId |
購入した SaaS サブスクリプションの一意識別子。 この ID は、Resolve API を使用して Microsoft Marketplace 承認トークンを解決した後に取得します。 |
要求ヘッダー:
応答コード:
コード: 202 サブスクライブ解除の要求が受け入れられ、非同期的に処理されます。 パートナーは、Operation-Location URL をポーリングして、この要求の成功または失敗を判断する必要があります。 操作の最後の状態が [失敗]、[ 成功]、または [競合 ] になるまで、数秒ごとにポーリングします。 最終的な操作状態はすぐに戻りますが、場合によっては数分かかることがあります。
また、Microsoft Marketplace でアクションが正常に完了すると、パートナーは Webhook 通知を受け取ります。 パブリッシャー側でサブスクリプションを取り消す場合にのみ、パブリッシャー側でサブスクリプションを取り消します。
コード: 200 サブスクリプションは既にサブスクライブ解除状態です。
応答ヘッダー:
| Parameter | Value |
|---|---|
Operation-Location |
リソースにリンクして、操作の状態を取得します。 たとえば、https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31します。 |
コード: 400
- 要求が正しくありません。 削除は、この SaaS サブスクリプション
allowedCustomerOperations一覧に含まれません。 - SaaS サブスクリプションは、譲渡後に更新されるまで管理できません。 この制限は更新日まで適用されます。
コード: 401 未承認。 承認トークンが無効であるか、有効期限が切れています。 要求は、認証トークンの作成に使用されたものとは異なる Microsoft Entra アプリ ID で発行されたオファーの SaaS サブスクリプションにアクセスしようとしています。
コード: 403 禁止。 承認トークンが無効であるか、指定されていないか、または十分なアクセス許可が提供されていません。 有効な承認トークンを指定します。
多くの場合、このエラーは 、SaaS 登録 が正しく実行されなかったことを示します。
コード: 404 見つかりません。
subscriptionId を含む SaaS サブスクリプションが見つかりません。
コード: 409
保留中の操作によりサブスクリプションがロックされているため、削除を完了できません。
コード: 500 内部サーバー エラー。 API 呼び出しを再試行します。 エラーが解決しない場合は、Microsoft サポート にお問い合わせください。
無料試用版
顧客が試用版が有効なプランを購入すると、SaaS サブスクリプションを無料試用版にすることができます。 サブスクリプション API を使用して、試用版が有効なサブスクリプションをアクティブ化し、サブスクリプションが現在無料試用版に含まれているかどうかを特定し、無料試用版が構成されている利用可能なプランを特定し、顧客を無料試用版から有料プランに変更し、有料に変換する前に無料試用版を取り消します。
| API | 無料試用版の情報 |
|---|---|
| 購入したサブスクリプションを解決する | この API を使用して購入トークンを解決し、購入したサブスクリプションが現在無料試用版になっているかどうかを特定します。 入れ子になった subscription オブジェクトには、解決された購入が現在無料試用版に含まれている場合の isFreeTrial が含まれます。 |
| サブスクリプションをアクティブ化する | この API を使用して、顧客アカウントのセットアップが完了した後に、手動でアクティブ化された SaaS サブスクリプションをアクティブ化します。 購入したプランに無料試用版がある場合、ライセンス認証では、有料課金をすぐに開始するのではなく、無料試用期間が開始されます。 |
| すべてのサブスクリプションの一覧を取得する | この API を使用して、オファー全体の無料試用版サブスクリプションを特定します。 各サブスクリプション オブジェクトには isFreeTrialを含めることができるため、オファー全体でアクティブな無料試用版サブスクリプションを識別できます。 |
| サブスクリプションを取得する | この API を使用して、特定のサブスクリプションが現在無料試用版に含まれるかどうかを特定します。 サブスクリプションの応答には、指定したサブスクリプションの isFreeTrial を含めることができます。 |
| 利用可能なプランを一覧表示する | この API を使用して、プランに無料試用版が構成されているかどうかを確認します。 各プランには、 hasFreeTrialsを含めることができます。これは、そのプランに無料試用版が構成されているかどうかを示します。 |
| サブスクリプションのプランを変更する | 試用版が終了する前に顧客が無料試用版から有料プランにアップグレードするときや、お客様が試用版が有効なプランから別の試用版が有効なプランに変更された場合など、顧客がパブリッシャー側からプランを変更する場合は、この API を使用します。 |
| サブスクリプションを取り消す | パブリッシャー側から SaaS サブスクリプションを取り消すには、この API を使用します。 サブスクリプションが現在無料試用版の場合、キャンセルは試用版を終了し、サブスクリプションが有料に変換されないようにします。 |
isFreeTrialが true の場合、サブスクリプションはアクティブですが、試用版が終了するか、試用版が終了する前に顧客のアップグレードが支払われるまで、顧客はプランに対して課金されません。
無料試用版が終了するか、顧客が有料版にアップグレードすると、 isFreeTrial は false に設定されます。
関連コンテンツ
- Microsoft Marketplace の SaaS オファーのその他のオプションについては、Microsoft Marketplace の測定サービス API を参照してください。
- のさまざまなプログラミング言語とサンプルのクライアントを確認して使用します。
- テスト ガイダンスについては、 SaaS サービスでの Webhook の実装に関するページを参照してください。