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

[アーティクル]
01/31/2025

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

手記

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

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

解決エンドポイントを使用すると、パブリッシャーはコマーシャルマーケットプレースから購入 ID トークン (購入済みトークンと呼ばれますが、まだアクティブ化されていない) を永続的に購入した SaaS サブスクリプション ID とその詳細に交換できます。

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

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

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

`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 トークンパラメーター。顧客が SaaS パートナーの Web サイト (例: `https://contoso.com/signup?token=<token><authorization_token>`) にリダイレクトされると、トークンはランディングページ URL 呼び出しで渡されます。エンコードされるトークン値はランディングページ URL の一部であるため、この API 呼び出しでパラメーターとして使用する前にデコードする必要があります。 URL にエンコードされた文字列の例を次に示します。`contoso.com/signup?token=ab%2Bcd%2Fef`。トークン `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 が見つからない、形式が正しくない、無効、または期限切れです。

コード: 401 未承認。承認トークンが無効であるか、有効期限が切れています。要求は、認証トークンの作成に使用されたものとは異なる Microsoft Entra アプリ ID で発行されたオファーの SaaS サブスクリプションにアクセスしようとしています。

コード: 403 禁止。承認トークンが無効であるか、指定されていないか、十分なアクセス許可が提供されていません。有効な承認トークンを必ず指定してください。

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

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

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

SaaS アカウントがエンドユーザー用に構成されたら、発行元は Microsoft 側で Activate Subscription API を呼び出す必要があります。この API 呼び出しが成功しない限り、顧客には課金されません。

`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 サブスクリプションが中断状態です。

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

コード: 404 見つかりません。 SaaS サブスクリプションは、登録解除 状態です。

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

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

この API は、パブリッシャーがコマーシャルマーケットプレースで発行するすべてのオファーについて、購入したすべての SaaS サブスクリプションの一覧を取得します。可能なすべての状態の SaaS サブスクリプションが返されます。サブスクリプションを解除した SaaS サブスクリプションも返されます。この情報は Microsoft 側では削除されないためです。

API はページ分割された結果を返します。後続の結果を取得するには continuationToken を渡す必要があります。

`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 サブスクリプションが見つからない場合は、空の応答本文が返されます。

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

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

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

この API は、パブリッシャーがコマーシャルマーケットプレースで発行する SaaS オファーに対して、指定された購入済み SaaS サブスクリプションを取得します。この呼び出しを使用して、すべてのサブスクリプションの一覧を取得するために使用される API を呼び出すのではなく、特定の SaaS サブスクリプションの使用可能なすべての情報を ID で取得します。

`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 と一致する必要があります。

`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 が見つかりません。

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

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

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

この API を使用して、SaaS サブスクリプション用に購入した既存のプランを新しいプラン (パブリックまたはプライベート) に更新します。コマーシャルマーケットプレースで購入した SaaS サブスクリプションのプランがパブリッシャー側で変更された場合、パブリッシャーはこの API を呼び出す必要があります。

この API は、Active サブスクリプションに対してのみ呼び出すことができます。任意のプランを他の既存のプラン (パブリックまたはプライベート) に変更できますが、それ自体には変更できません。プライベートプランの場合、顧客のテナントはパートナーセンターでプランの対象ユーザーの一部として定義する必要があります。

パッチ `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 をポーリングして、変更計画要求の成功または失敗を判断する必要があります。ポーリングは、Failed、Succeed、または Conflict の最終状態を受け取るまで、数秒ごとに実行する必要があります。最終的な操作の状態はすぐに返されますが、場合によっては数分かかることがあります。

パートナーは、コマーシャルマーケットプレース側でアクションを正常に完了する準備ができたら、webhook 通知も受け取ります。パブリッシャー側でプランを変更する必要があるのは、その場合のみです。

応答ヘッダー:

パラメーター	価値
`Operation-Location`	操作の状態を取得する URL。たとえば、`https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31`

コード: 400 無効な要求: 検証エラー。

要求されたプランが見つからないか、ユーザーがプランを使用できません。
要求されたプランは、サブスクライブされたプランと同じです。
SaaS サブスクリプションの状態は、サブスクライブされていません。
更新される SaaS サブスクリプションは、クラウドソリューションプロバイダー (CSP) によって購入されます。このアクションを実行するには、CSP プロバイダーと協力する必要があります。

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

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

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

手記

プランまたはシート数は、両方ではなく一度に変更できます。

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

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

この API を使用して、SaaS サブスクリプションで購入したシートの数を更新 (増減) します。コマーシャルマーケットプレースで作成された SaaS サブスクリプションのシート数がパブリッシャー側から変更された場合、パブリッシャーはこの API を呼び出す必要があります。

シートの数量は、現在のプランで許可されている数量を超えることはできません。この場合、パブリッシャーはシートの数量を変更する前にプランを変更する必要があります。

パッチ `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 をポーリングして、変更数量要求の成功または失敗を判断する必要があります。ポーリングは、Failed、Succeed、または Conflict の最終状態を受け取るまで、数秒ごとに実行する必要があります。最終的な操作状態はすぐに返される必要がありますが、場合によっては数分かかることがあります。

パートナーは、コマーシャルマーケットプレース側でアクションを正常に完了する準備ができたら、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 サポートにお問い合わせください。

手記

一度に変更できるのはプランまたは数量のみです。両方を変更することはできません。

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

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

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

パブリッシャー側のコマーシャルマーケットプレースで購入した SaaS サブスクリプションのキャンセルをパブリッシャーが実装する場合は、この API を呼び出す必要があります。この呼び出しが完了すると、サブスクリプションの状態が Microsoft 側 登録解除 になります。

購入から 72 時間以内にサブスクリプションが取り消された場合、顧客は課金されません。

前の猶予期間の後にサブスクリプションが取り消された場合、顧客は課金されます。お客様は、取り消し直後に Microsoft 側の SaaS サブスクリプションにアクセスできなくなります。

`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 をポーリングして、この要求の成功または失敗を判断する必要があります。ポーリングは、Failed、Succeed、または Conflict の最終状態を受け取るまで、数秒ごとに実行する必要があります。最終的な操作状態はすぐに返される必要がありますが、場合によっては数分かかることがあります。

また、コマーシャルマーケットプレース側でアクションが正常に完了すると、パートナーは Webhook 通知を受け取ります。パブリッシャー側でサブスクリプションを取り消す場合にのみ、パブリッシャー側でサブスクリプションを取り消します。

コード: 200 サブスクリプションは既にサブスクライブ解除状態です。

応答ヘッダー:

パラメーター	価値
`Operation-Location`	リソースにリンクして、操作の状態を取得します。たとえば、`https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31`します。

コード: 400 無効な要求。削除は、この SaaS サブスクリプション allowedCustomerOperations 一覧に含まれていません。

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

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

コード: 409

保留中の操作によりサブスクリプションがロックされているため、削除を完了できません。

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

コマーシャルマーケットプレースでの SaaS オファーのその他のオプションについては、コマーシャルマーケットプレースの測定サービス API を参照してください。
さまざまなプログラミング言語とサンプルのクライアントを確認して使用
テストガイダンスについては、「SaaS サービスでの Webhook の実装」を参照してください。

次の方法で共有

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

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

`https://marketplaceapi.microsoft.com/api/saas/subscriptions/resolve?api-version=<ApiVersion>` を投稿する

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

`https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/activate?api-version=<ApiVersion>` を投稿する

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

`https://marketplaceapi.microsoft.com/api/saas/subscriptions?api-version=<ApiVersion>` を取得する

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

`https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>` を取得する

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

`https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/listAvailablePlans?api-version=<ApiVersion>&planId=<planId>` を取得する

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

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

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

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

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

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

フィードバック

その他のリソース

次の方法で共有

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

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

https://marketplaceapi.microsoft.com/api/saas/subscriptions/resolve?api-version=<ApiVersion> を投稿する

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

https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/activate?api-version=<ApiVersion> を投稿する

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

https://marketplaceapi.microsoft.com/api/saas/subscriptions?api-version=<ApiVersion> を取得する

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

https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion> を取得する

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

https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/listAvailablePlans?api-version=<ApiVersion>&planId=<planId> を取得する

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

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

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

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

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

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

関連コンテンツ

フィードバック

その他のリソース

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

`https://marketplaceapi.microsoft.com/api/saas/subscriptions/resolve?api-version=<ApiVersion>` を投稿する

`https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/activate?api-version=<ApiVersion>` を投稿する

`https://marketplaceapi.microsoft.com/api/saas/subscriptions?api-version=<ApiVersion>` を取得する

`https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>` を取得する

`https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/listAvailablePlans?api-version=<ApiVersion>&planId=<planId>` を取得する

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

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

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