다음을 통해 공유

Microsoft 상업용 Marketplace의 SaaS 처리 구독 API v2

  • 아티클

이 문서에서는 SaaS 처리 구독 API 버전 2에 대해 설명합니다.

구매한 구독 확인

확인 엔드포인트를 사용하면 게시자는 상업용 Marketplace의 구매 식별 토큰(구매했지만 아직 활성화되지 않음에서는 토큰이라고 함)을 영구적으로 구매한 SaaS 구독 ID 및 세부 정보와 교환할 수 있습니다.

고객이 파트너의 방문 페이지 URL로 리디렉션되면 고객 ID 토큰이 이 URL 호출에서 토큰 매개 변수로 전달됩니다. 파트너는 이 토큰을 사용하고 해결을 요청해야 합니다. 확인 API 응답에는 구매를 고유하게 식별하는 SaaS 구독 ID 및 기타 세부 정보가 포함됩니다. 방문 페이지 URL 호출과 함께 제공되는 토큰은 24시간 동안 유효합니다. 받은 토큰이 만료된 경우 최종 사용자에게 다음 지침을 제공하는 것이 좋습니다.

"이 구매를 식별할 수 없습니다. Azure Portal 또는 Microsoft 365 관리 센터에서 이 SaaS 구독을 다시 열고 "계정 구성" 또는 "계정 관리"를 다시 선택합니다.

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)입니다. 이 값이 제공되지 않으면 응답 헤더에 값이 생성되고 제공됩니다.
x-ms-correlationid 클라이언트의 작업에 대한 고유한 문자열 값입니다. 이 매개 변수는 클라이언트 작업의 모든 이벤트를 서버 쪽의 이벤트와 상호 연결합니다. 이 값이 제공되지 않으면 응답 헤더에 값이 생성되고 제공됩니다.
authorization 이 API 호출을 만드는 게시자를 식별하는 고유한 액세스 토큰입니다. 형식은 "Bearer <access_token>" Microsoft Entra 앱을 기반으로 토큰 가져오기에 설명된 대로 게시자가 토큰 값을 검색하는 경우입니다.
x-ms-marketplace-token 확인할 구매 ID 토큰 매개 변수입니다. 고객이 SaaS 파트너의 웹 사이트(예: https://contoso.com/signup?token=<token><authorization_token>)로 리디렉션될 때 토큰이 방문 페이지 URL 호출에 전달됩니다.

인코딩되는 토큰 값은 방문 페이지 URL의 일부이므로 이 API 호출에서 매개 변수로 사용되기 전에 디코딩해야 합니다.

다음은 URLcontoso.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 가 없거나, 형식이 잘못되었거나, 잘못되었거나, 만료되었습니다.

코드: 403 사용할 수 없음. 권한 부여 토큰이 잘못되었거나, 만료되었거나, 제공되지 않았습니다. 요청이 권한 부여 토큰을 만드는 데 사용된 것과 다른 Microsoft Entra 앱 ID로 게시된 제품에 대한 SaaS 구독에 액세스하려고 시도합니다.

이 오류는 종종 SaaS 등록을 제대로 수행하지 않았을 때 발생하는 증상입니다.

코드: 500 내부 서버 오류. API 호출을 다시 시도합니다. 오류가 지속되면 Microsoft 지원에 문의하세요.

구독 활성화

SaaS 계정이 최종 사용자에 대해 구성된 후, 게시자는 Microsoft 쪽에서 구독 활성화 API를 호출해야 합니다. 이 API 호출이 성공하지 않으면 고객에게 요금이 청구되지 않습니다.

올리기 https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/activate?api-version=<ApiVersion>

쿼리 매개 변수:

매개 변수 값
ApiVersion 2018-08-31을 사용합니다.
subscriptionId 구매한 SaaS 구독의 고유 식별자입니다. 이 ID는 Resolve API를 사용하여 상업용 Marketplace 권한 부여 토큰을 확인한 후에 가져옵니다.

요청 헤더:

매개 변수 값
content-type application/json
x-ms-requestid 클라이언트의 요청을 추적하기 위한 고유 문자열 값(GUID)입니다. 이 값이 제공되지 않으면 응답 헤더에 값이 생성되고 제공됩니다.
x-ms-correlationid 클라이언트의 작업에 대한 고유한 문자열 값입니다. 이 문자열은 클라이언트 작업의 모든 이벤트를 서버 쪽의 이벤트와 상호 연결합니다. 이 값이 제공되지 않으면 응답 헤더에 값이 생성되고 제공됩니다.
authorization 이 API 호출을 만드는 게시자를 식별하는 고유한 액세스 토큰입니다. 형식은 "Bearer <access_token>" Microsoft Entra 앱을 기반으로 토큰 가져오기에 설명된 대로 게시자가 토큰 값을 검색하는 경우입니다.

응답 코드:

코드: 200 구독을 업데이트하고 "구독됨"으로 표시하는 요청이 수신됩니다. ISV(독립 소프트웨어 공급업체)는 몇 분 후에 구독의 상태 대해 검사 수 있습니다(구독 상태 검사 가져오기 작업에 대해 읽어 보세요). 이렇게 하면 구독이 성공적으로 업데이트되었는지 여부를 확인할 수 있습니다. 구독하지 않으면 "구독 취소" 웹후크가 자동으로 전송됩니다.

이 호출에 대한 응답 본문이 없습니다.

코드: 400 잘못된 요청: 유효성 검사에 실패했습니다.

  • SaaS 구독이 일시 중단됨 상태입니다.

코드: 403 사용할 수 없음. 권한 부여 토큰이 잘못되었거나, 만료되었거나, 제공되지 않았습니다. 요청이 권한 부여 토큰을 만드는 데 사용된 것과 다른 Microsoft Entra 앱 ID로 게시된 제품에 대한 SaaS 구독에 액세스하려고 시도합니다.

이 오류는 종종 SaaS 등록을 제대로 수행하지 않았을 때 발생하는 증상입니다.

코드: 404를 찾을 수 없음. SaaS 구독이 구독 되지 않은 상태입니다.

코드: 500 내부 서버 오류. API 호출을 다시 시도합니다. 오류가 지속되면 Microsoft 지원에 문의하세요.

모든 구독 목록 가져오기

이 API는 상업용 Marketplace에서 게시자가 게시하는 모든 제품에 대해 구매한 모든 SaaS 구독의 목록을 검색합니다. 가능한 모든 상태 SaaS 구독이 반환됩니다. 이 정보는 Microsoft 쪽에서 삭제되지 않으므로 구독되지 않은 SaaS 구독도 반환됩니다.

API는 페이지당 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)입니다. 이 값이 제공되지 않으면 응답 헤더에 값이 생성되고 제공됩니다.
x-ms-correlationid 클라이언트의 작업에 대한 고유한 문자열 값입니다. 이 매개 변수는 클라이언트 작업의 모든 이벤트를 서버 쪽의 이벤트와 상호 연결합니다. 이 값이 제공되지 않으면 응답 헤더에 값이 생성되고 제공됩니다.
authorization 이 API 호출을 수행하는 게시자를 식별하는 고유한 액세스 토큰입니다. 형식은 "Bearer <access_token>" Microsoft Entra 앱을 기반으로 토큰 가져오기에 설명된 대로 게시자가 토큰 값을 검색하는 경우입니다.

응답 코드:

Code: 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는 상업용 Marketplace에서 게시자가 게시하는 SaaS 제품에 대해 구매한 특정 SaaS 구독 목록을 검색합니다. 이 호출을 사용하여 모든 구독 목록을 가져오는 데 사용되는 API를 호출하는 대신 ID로 특정 SaaS 구독에 사용 가능한 모든 정보를 가져옵니다.

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

쿼리 매개 변수:

매개 변수 값
ApiVersion 2018-08-31을 사용합니다.
subscriptionId 구매한 SaaS 구독의 고유 식별자입니다. 이 ID는 확인 API를 사용하여 상업용 Marketplace 권한 부여 토큰을 확인한 후에 가져옵니다.

요청 헤더:

매개 변수 값
content-type application/json
x-ms-requestid 클라이언트의 요청을 추적하기 위한 고유 문자열 값(GUID)입니다. 이 값이 제공되지 않으면 응답 헤더에 값이 생성되고 제공됩니다.
x-ms-correlationid 클라이언트의 작업에 대한 고유한 문자열 값입니다. 이 매개 변수는 클라이언트 작업의 모든 이벤트를 서버 쪽의 이벤트와 상호 연결합니다. 이 값이 제공되지 않으면 응답 헤더에 값이 생성되고 제공됩니다.
authorization 이 API 호출을 수행하는 게시자를 식별하는 고유한 액세스 토큰입니다. 형식은 "Bearer <access_token>" Microsoft Entra 앱을 기반으로 토큰 가져오기에 설명된 대로 게시자가 토큰 값을 검색하는 경우입니다.

응답 코드:

Code: 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.
  }
}

코드: 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는 확인 API를 사용하여 상업용 Marketplace 권한 부여 토큰을 확인한 후에 가져옵니다.
planId (Optional) 가져오려는 특정 계획의 계획 ID입니다. 이는 선택 사항이며 무시된 경우 모든 계획을 반환합니다.

요청 헤더:

매개 변수 값
content-type application/json
x-ms-requestid 클라이언트의 요청을 추적하기 위한 고유 문자열 값(GUID)입니다. 이 값이 제공되지 않으면 응답 헤더에 값이 생성되고 제공됩니다.
x-ms-correlationid 클라이언트의 작업에 대한 고유한 문자열 값입니다. 이 매개 변수는 클라이언트 작업의 모든 이벤트를 서버 쪽의 이벤트와 상호 연결합니다. 이 값이 제공되지 않으면 응답 헤더에 값이 생성되고 제공됩니다.
authorization 이 API 호출을 수행하는 게시자를 식별하는 고유한 액세스 토큰입니다. 형식은 "Bearer <access_token>" Microsoft Entra 앱을 기반으로 토큰 가져오기에 설명된 대로 게시자가 토큰 값을 검색하는 경우입니다.

응답 코드:

Code: 200 이미 구매한 플랜을 포함하여 기존 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 구독에 대해 구매한 기존 플랜을 새 플랜(퍼블릭 또는 프라이빗)으로 업데이트할 수 있습니다. 게시자는 상업용 Marketplace에서 구매한 SaaS 구독의 게시자 쪽에서 계획이 변경될 때 이 API를 호출해야 합니다.

이 API는 활성 구독에 대해서만 호출할 수 있습니다. 모든 플랜은 다른 기존 계획(퍼블릭 또는 프라이빗)으로 변경할 수 있지만 그 자체로는 변경할 수 없습니다. 프라이빗 플랜의 경우 파트너 센터에서 고객의 테넌트를 플랜 대상 그룹의 일부로 정의해야 합니다.

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

쿼리 매개 변수:

매개 변수 값
ApiVersion 2018-08-31을 사용합니다.
subscriptionId 구매한 SaaS 구독의 고유 식별자입니다. 이 ID는 확인 API를 사용하여 상업용 Marketplace 권한 부여 토큰을 확인한 후에 가져옵니다.

요청 헤더:

매개 변수 값
content-type application/json
x-ms-requestid 클라이언트의 요청을 추적하기 위한 고유 문자열 값(GUID)입니다. 이 값이 제공되지 않으면 응답 헤더에 값이 생성되고 제공됩니다.
x-ms-correlationid 클라이언트의 작업에 대한 고유한 문자열 값입니다. 이 매개 변수는 클라이언트 작업의 모든 이벤트를 서버 쪽의 이벤트와 상호 연결합니다. 이 값이 제공되지 않으면 응답 헤더에 값이 생성되고 제공됩니다.
authorization 이 API 호출을 수행하는 게시자를 식별하는 고유한 액세스 토큰입니다. 형식은 "Bearer <access_token>" Microsoft Entra 앱을 기반으로 토큰 가져오기에 설명된 대로 게시자가 토큰 값을 검색하는 경우입니다.

요청 페이로드 예제:

{
  "planId": "gold" // the ID of the new plan to be purchased
}

응답 코드:

코드: 202 계획 변경 요청이 비동기적으로 수락되고 처리되었습니다. 파트너는 작업 위치 URL을 폴링하여 변경 계획 요청의 성공 또는 실패를 결정해야 합니다. 작업의 최종 상태를 나타내는 실패, 성공 또는 충돌이 수신될 때까지 몇 초마다 폴링을 수행해야 합니다. 최종 작업 상태 신속하게 반환해야 하지만 경우에 따라 몇 분 정도 걸릴 수 있습니다.

또한 파트너는 상업용 Marketplace 쪽에서 작업이 성공적으로 완료될 준비가 되면 웹후크 알림을 받습니다. 그런 다음에만 게시자가 게시자 쪽에서 계획을 변경해야 합니다.

응답 헤더:

매개 변수 값
Operation-Location 작업의 상태 가져오기 위한 URL입니다. 예를 들어 https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31

코드: 400 잘못된 요청: 유효성 검사 실패.

  • 새 계획이 없거나 이 특정 SaaS 구독에 사용할 수 없습니다.
  • 새 계획은 현재 계획과 동일합니다.
  • SaaS 구독 상태 구독되지 않습니다.
  • SaaS 구독에 대한 업데이트 작업은 에 포함되지 allowedCustomerOperations않습니다.

코드: 403 사용할 수 없음. 권한 부여 토큰이 잘못되었거나 만료되었거나 제공되지 않았습니다. 요청이 권한 부여 토큰을 만드는 데 사용된 것과 다른 Microsoft Entra 앱 ID로 게시된 제품에 대한 SaaS 구독에 액세스하려고 시도합니다.

이 오류는 종종 SaaS 등록을 제대로 수행하지 않았을 때 발생하는 증상입니다.

코드: 404를 찾을 수 없음. SaaS 구독을 subscriptionId 찾을 수 없습니다.

코드: 500 내부 서버 오류. API 호출을 다시 시도합니다. 오류가 지속되면 Microsoft 지원에 문의하세요.

참고 항목

플랜 또는 사용자 수량을 한 번에 하나씩 변경할 수 있고, 동시에 변경할 수는 없습니다.

이 API는 최종 사용자의 변경에 대한 명시적 승인을 받은 후에만 호출할 수 있습니다.

SaaS 구독의 사용자 수 변경

이 API를 사용하여 SaaS 구독에 대해 구매한 사용자 수를 업데이트(늘리거나 줄임)합니다. 상업용 Marketplace에서 구매한 SaaS 구독의 사용자 수가 게시자 쪽에서 변경될 때 게시자는 이 API를 호출해야 합니다.

사용자 수량은 현재 계획에서 허용되는 수량보다 많을 수 없습니다. 이 경우 게시자는 사용자 수를 변경하기 전에 계획을 변경해야 합니다.

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

쿼리 매개 변수:

매개 변수 값
ApiVersion 2018-08-31을 사용합니다.
subscriptionId 구매한 SaaS 구독의 고유 식별자입니다. 이 ID는 확인 API를 사용하여 상업용 Marketplace 권한 부여 토큰을 확인한 후에 가져옵니다.

요청 헤더:

매개 변수 값
content-type application/json
x-ms-requestid 클라이언트의 요청을 추적하기 위한 고유 문자열 값(GUID)입니다. 이 값이 제공되지 않으면 응답 헤더에 값이 생성되고 제공됩니다.
x-ms-correlationid 클라이언트의 작업에 대한 고유한 문자열 값입니다. 이 매개 변수는 클라이언트 작업의 모든 이벤트를 서버 쪽의 이벤트와 상호 연결합니다. 이 값이 제공되지 않으면 응답 헤더에 값이 생성되고 제공됩니다.
authorization 이 API 호출을 수행하는 게시자를 식별하는 고유한 액세스 토큰입니다. 형식은 "Bearer <access_token>" Microsoft Entra 앱을 기반으로 토큰 가져오기에 설명된 대로 게시자가 토큰 값을 검색하는 경우입니다.

요청 페이로드 예제:

{
  "quantity": 5 // the new amount of seats to be purchased
}

응답 코드:

코드: 202 수량 변경 요청이 비동기적으로 수락되고 처리되었습니다. 파트너는 작업 위치 URL을 폴링하여 변경 수량 요청의 성공 또는 실패를 결정해야 합니다. 작업의 최종 상태를 나타내는 실패, 성공 또는 충돌이 수신될 때까지 몇 초마다 폴링을 수행해야 합니다. 최종 작업 상태는 신속하게 반환되지만, 경우에 따라 몇 분 정도 걸릴 수 있습니다.

또한 파트너는 상업용 Marketplace 쪽에서 작업이 성공적으로 완료될 준비가 되면 웹후크 알림을 받습니다. 그런 다음에만 게시자가 게시자 쪽에서 수량을 변경해야 합니다.

응답 헤더:

매개 변수 값
Operation-Location 작업 상태를 가져오는 리소스의 링크입니다. 예들 들어 https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31입니다.

코드: 400 잘못된 요청: 유효성 검사 실패.

  • 새 수량이 현재 계획 제한보다 크거나 낮습니다.
  • 새 수량이 없습니다.
  • 새 수량은 현재 수량과 동일합니다.
  • SaaS 구독 상태 구독되지 않습니다.
  • SaaS 구독에 대한 업데이트 작업이 allowedCustomerOperations에 포함되지 않았습니다.

코드: 403 사용할 수 없음. 권한 부여 토큰이 잘못되었거나, 만료되었거나, 제공되지 않았습니다. 요청이 현재 게시자에 속하지 않는 구독에 액세스하려고 시도합니다.

이 오류는 종종 SaaS 등록을 제대로 수행하지 않았을 때 발생하는 증상입니다.

코드: 404를 찾을 수 없음. SaaS 구독을 subscriptionId 찾을 수 없습니다.

코드: 500 내부 서버 오류. API 호출을 다시 시도합니다. 오류가 지속되면 Microsoft 지원에 문의하세요.

참고 항목

플랜 또는 수량을 한 번에 하나씩 변경할 수 있고, 동시에 변경할 수는 없습니다.

이 API는 최종 사용자로부터 명시적인 변경 승인을 받은 후에만 호출할 수 있습니다.

구독 취소

이 API를 사용하여 지정된 SaaS 구독을 구독 취소합니다. 게시자는 이 API를 사용할 필요가 없으며 고객이 상업용 Marketplace로 이동하여 SaaS 구독을 취소하는 것이 좋습니다.

상업용 Marketplace에 구매한 SaaS 구독의 취소를 게시자 쪽에서 구현하기로 결정하는 게시자는 이 API를 호출해야 합니다. 이 호출이 완료되면 구독의 상태 Microsoft 쪽에서 구독 취소됩니다.

구매 후 72시간 이내에 구독이 취소된 경우 고객에게 요금이 청구되지 않습니다.

이전 유예 기간 이후에 구독이 취소되면 고객에게 요금이 청구됩니다. 고객은 취소 직후 Microsoft 쪽에서 SaaS 구독에 대한 액세스 권한을 잃게 됩니다.

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

쿼리 매개 변수:

매개 변수 값
ApiVersion 2018-08-31을 사용합니다.
subscriptionId 구매한 SaaS 구독의 고유 식별자입니다. 이 ID는 확인 API를 사용하여 상업용 Marketplace 권한 부여 토큰을 확인한 후에 가져옵니다.

요청 헤더:

매개 변수 값
content-type application/json
x-ms-requestid 클라이언트의 요청을 추적하기 위한 고유 문자열 값(GUID)입니다. 이 값이 제공되지 않으면 응답 헤더에 값이 생성되고 제공됩니다.
x-ms-correlationid 클라이언트의 작업에 대한 고유한 문자열 값입니다. 이 매개 변수는 클라이언트 작업의 모든 이벤트를 서버 쪽의 이벤트와 상호 연결합니다. 이 값이 제공되지 않으면 응답 헤더에 값이 생성되고 제공됩니다.
authorization 이 API 호출을 만드는 게시자를 식별하는 고유한 액세스 토큰입니다. 형식은 "Bearer <access_token>" Microsoft Entra 앱을 기반으로 토큰 가져오기에 설명된 대로 게시자가 토큰 값을 검색하는 경우입니다.

응답 코드:

코드: 202 구독 취소 요청이 비동기적으로 수락되고 처리되었습니다. 파트너는 작업 위치 URL을 폴링하여 이 요청의 성공 또는 실패를 결정해야 합니다. 작업의 최종 상태를 나타내는 실패, 성공 또는 충돌이 수신될 때까지 몇 초마다 폴링을 수행해야 합니다. 최종 작업 상태는 신속하게 반환되지만, 경우에 따라 몇 분 정도 걸릴 수 있습니다.

또한 파트너는 상업용 Marketplace 쪽에서 작업이 성공적으로 완료되면 웹후크 알림을 받습니다. 그 후 게시자는 게시자 쪽에서 구독을 취소해야 합니다.

코드: 200 구독이 이미 구독되지 않은 상태입니다.

응답 헤더:

매개 변수 값
Operation-Location 작업 상태를 가져오는 리소스의 링크입니다. 예들 들어 https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31입니다.

코드: 400 잘못된 요청. 이 SaaS 구독의 allowedCustomerOperations 목록에 삭제가 없습니다.

코드: 403 사용할 수 없음. 권한 부여 토큰이 잘못되었거나 만료되었거나 사용할 수 없습니다.

이 오류는 종종 SaaS 등록을 제대로 수행하지 않았을 때 발생하는 증상입니다.

코드: 404를 찾을 수 없음. SaaS 구독을 subscriptionId 찾을 수 없습니다.

코드: 409

보류 중인 작업으로 인해 구독이 잠겨 있으므로 삭제를 완료할 수 없습니다.

코드: 500 내부 서버 오류. API 호출을 다시 시도합니다. 오류가 지속되면 Microsoft 지원에 문의하세요.

다음 단계