Microsoft コマーシャルマーケットプレースでの SaaS Fulfillment サブスクリプション API v2

[アーティクル]
11/08/2024

この記事では、SaaS Fulfillment サブスクリプション API のバージョン 2 について説明します。

Note

SaaS フルフィルメントサブスクリプション API を呼び出すことができるようにするには、正しいリソース ID を使用して発行元の承認トークンを作成する必要があります。発行元の承認トークン取得する方法について説明します

購入済みサブスクリプションを解決する

resolve エンドポイントを使用すると、公開元は、コマーシャルマーケットプレースからの購入識別トークン (「購入済みであるが、まだアクティブ化されていない」で "トークン" として言及) を、永続的な購入済み SaaS サブスクリプション ID とその詳細に交換できます。

顧客がパートナーのランディングページの URL にリダイレクトされると、この URL 呼び出しで、顧客識別トークンが token パラメーターとして渡されます。パートナーは、このトークンを使用すること、およびそれを解決するための要求を行うことを期待されています。 Resolve API 応答には、購入を一意に識別するための SaaS サブスクリプション ID とその他の詳細が含まれています。ランディングページの URL 呼び出しで提供される トークン は 24 時間有効です。受信した トークン の有効期限が切れている場合は、エンドユーザーに次のガイダンスを提供することをお勧めします。

"この購入を特定できませんでした。この SaaS サブスクリプションを Azure portal または Microsoft 365 管理 Center で再度開き、[アカウントの構成] または [アカウントの管理] をもう一度選択します。

Resolve API を呼び出すと、サポートされているすべての状態の SaaS サブスクリプションのサブスクリプションの詳細と状態が返されます。

Post`https://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 呼び出しを行っている発行者を識別する一意のアクセストークン。形式は、「 Microsoft Entra アプリに基づいてトークンを取得するで説明されているように、トークン値が発行元によって取得されるときに`"Bearer <access_token>"`されます。
`x-ms-marketplace-token`	解決する購入 ID token パラメーター。このトークンは、顧客が SaaS パートナーの Web サイトにリダイレクトされるときに、ランディングページの URL 呼び出しで渡されます (例: `https://contoso.com/signup?token=<token><authorization_token>`)。エンコードされる token 値はランディングページ URL の一部であるため、この API 呼び出しでパラメーターとして使用する前にデコードする必要があります。 URL 内のエンコードされた文字列の例は次のとおりです: `contoso.com/signup?token=ab%2Bcd%2Fef`。ここで、token は `ab%2Bcd%2Fef` です。デコードされる同じトークンは次のとおりです。 `Ab+cd/ef`

応答コード:

コード: 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 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 呼び出しが成功しない限り、顧客には課金されません。

Post`https://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 呼び出しを行っている発行者を識別する一意のアクセストークン。形式は、「 Microsoft Entra アプリに基づいてトークンを取得するで説明されているように、トークン値が発行元によって取得されるときに`"Bearer <access_token>"`されます。

応答コード:

コード: 200 サブスクリプションを更新し、"Subscribed" としてマークする要求が受信されます。独立系ソフトウェアベンダー (ISV) は、数分後にサブスクリプションの状態を確認できます (サブスクリプションの状態を確認するための Get 操作を読み取ります)。これにより、サブスクリプションが正常に更新されたかどうかを明確に示します。サブスクライブに失敗すると、"Unsubscribe" Webhook が自動的に送信されます。

この呼び出しには応答本文がありません。

コード: 400 無効な要求: 検証に失敗しました。

SaaS サブスクリプションは Suspended 状態です。

多くの場合、このエラーは、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 呼び出しを行っている公開元を識別する一意のアクセストークン。形式は、「 Microsoft Entra アプリに基づいてトークンを取得するで説明されているように、トークン値が発行元によって取得されるときに`"Bearer <access_token>"`されます。

応答コード:

コード: 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 呼び出しを行っている公開元を識別する一意のアクセストークン。形式は、「 Microsoft Entra アプリに基づいてトークンを取得するで説明されているように、トークン値が発行元によって取得されるときに`"Bearer <access_token>"`されます。

応答コード:

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

多くの場合、このエラーは、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 呼び出しを行っている公開元を識別する一意のアクセストークン。形式は、「 Microsoft Entra アプリに基づいてトークンを取得するで説明されているように、トークン値が発行元によって取得されるときに`"Bearer <access_token>"`されます。

応答コード:

コード: 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 呼び出しを行っている公開元を識別する一意のアクセストークン。形式は、「 Microsoft Entra アプリに基づいてトークンを取得するで説明されているように、トークン値が発行元によって取得されるときに`"Bearer <access_token>"`されます。

要求ペイロードの例:

{
  "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 サブスクリプションの状態が Subscribed ではありません。
更新される SaaS サブスクリプションは、クラウドソリューションプロバイダー (CSP) によって購入されます。このアクションを実行するには、CSP プロバイダーと協力する必要があります。

コード: 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 呼び出しを行っている公開元を識別する一意のアクセストークン。形式は、「 Microsoft Entra アプリに基づいてトークンを取得するで説明されているように、トークン値が発行元によって取得されるときに`"Bearer <access_token>"`されます。

要求ペイロードの例:

{
  "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 無効な要求: 検証エラー。

新しい数量が許容範囲内にありません。
新しい数量が見つからないか、0 です。
新しい数量は、現在の数量と同じです。
SaaS サブスクリプションの状態がサブスクライブ済みではありません。
更新される SaaS サブスクリプションは、クラウドソリューションプロバイダー (CSP) によって購入されます。このアクションを実行するには、CSP プロバイダーと協力する必要があります。

多くの場合、このエラーは、SaaS 登録を正しく実行していないことを表す症状です。

コード: 404 見つかりません。指定した subscriptionId を持つ SaaS サブスクリプションが見つかりません。

コード: 500 内部サーバーエラー。 API 呼び出しをやり直してください。エラーが解決しない場合は、Microsoft サポートにお問い合わせください。

Note

一度に変更できるのはプランまたは数量だけであり、両方ではありません。

この API は、変更についてエンドユーザーから明示的な承認を得た後にのみ呼び出すことができます。

サブスクリプションを取り消す

この API を使用して、指定した SaaS サブスクリプションの登録を解除します。公開元はこの API を使用する必要はありません。SaaS サブスクリプションを取り消すには、顧客をコマーシャルマーケットプレースに誘導することをお勧めします。

コマーシャルマーケットプレースで購入された SaaS サブスクリプションの取り消しを公開元側で実装する場合、公開元はこの API を呼び出す必要があります。この呼び出しが完了すると、サブスクリプションの状態は Microsoft 側で Unsubscribed になります。

購入から 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 呼び出しを行っている発行者を識別する一意のアクセストークン。形式は、「 Microsoft Entra アプリに基づいてトークンを取得するで説明されているように、トークン値が発行元によって取得されるときに`"Bearer <access_token>"`されます。

応答コード:

コード: 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 を参照してください。
さまざまなプログラミング言語とサンプルの clients を確認して使用する
テストガイダンスについては、「 SaaS サービスでの Webhook の実装」を参照してください。

次の方法で共有

Microsoft コマーシャルマーケットプレースでの SaaS Fulfillment サブスクリプション API v2

購入済みサブスクリプションを解決する

Post`https://marketplaceapi.microsoft.com/api/saas/subscriptions/resolve?api-version=<ApiVersion>`

サブスクリプションをアクティブ化する

Post`https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/activate?api-version=<ApiVersion>`

すべてのサブスクリプションの一覧を取得する

Get `https://marketplaceapi.microsoft.com/api/saas/subscriptions?api-version=<ApiVersion>`

サブスクリプションを取得する

Get `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>`

利用可能なプランを一覧表示する

Get `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/listAvailablePlans?api-version=<ApiVersion>&planId=<planId>`

サブスクリプションのプランを変更する

Patch `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>`

SaaS サブスクリプションのシート数を変更する

Patch `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>`

サブスクリプションを取り消す

Delete `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>`

フィードバック

その他のリソース

次の方法で共有

Microsoft コマーシャル マーケットプレースでの SaaS Fulfillment サブスクリプション API v2

購入済みサブスクリプションを解決する

Posthttps://marketplaceapi.microsoft.com/api/saas/subscriptions/resolve?api-version=<ApiVersion>

サブスクリプションをアクティブ化する

Posthttps://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/activate?api-version=<ApiVersion>

すべてのサブスクリプションの一覧を取得する

Get https://marketplaceapi.microsoft.com/api/saas/subscriptions?api-version=<ApiVersion>

サブスクリプションを取得する

Get https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>

利用可能なプランを一覧表示する

Get https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/listAvailablePlans?api-version=<ApiVersion>&planId=<planId>

サブスクリプションのプランを変更する

Patch https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>

SaaS サブスクリプションのシート数を変更する

Patch https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>

サブスクリプションを取り消す

Delete https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>

関連するコンテンツ

フィードバック

その他のリソース

Microsoft コマーシャルマーケットプレースでの SaaS Fulfillment サブスクリプション API v2

Post`https://marketplaceapi.microsoft.com/api/saas/subscriptions/resolve?api-version=<ApiVersion>`

Post`https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/activate?api-version=<ApiVersion>`

Get `https://marketplaceapi.microsoft.com/api/saas/subscriptions?api-version=<ApiVersion>`

Get `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>`

Get `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/listAvailablePlans?api-version=<ApiVersion>&planId=<planId>`

Patch `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>`

Patch `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>`

Delete `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>`