새로운 상거래 구독 전환

아티클
09/25/2024

적용 대상: 파트너 센터 | 21Vianet에서 운영하는 파트너 센터 | 미국 정부용 Microsoft 클라우드 파트너 센터

적절한 역할

관리 에이전트

이러한 방법은 기존 및 새 상거래 원본 구독을 모두 지원합니다.

참고 항목

라이선스 기반 서비스에 대한 새로운 상거래 환경에는 많은 새로운 기능이 포함되어 있으며 모든 CSP(클라우드 솔루션 공급자)에서 사용할 수 있습니다. 자세한 내용은 새 상거래 환경 개요를 참조하세요.

고객의 새 상거래 구독을 대상 구독으로 업그레이드하거나 NCE 평가판을 유료 구독으로 변환하는 데 사용됩니다. 구독을 전환하려면 두 개의 API 요청을 수행해야 합니다. 업그레이드에 사용할 수 있는 SKU를 얻으려면 먼저 적격 전환을 가져옵니다. 그런 다음 POST 전환을 실행하여 전환을 실행합니다.

전환 자격 가져오기

지정된 고객, 구독 및 요청된 유형에 대한 적격 전환 목록을 반환합니다. 대상 구독 업그레이드 자격도 반환합니다. 전환 자격에는 EndofSaleWithConversions 상태에 있는 제품이 포함될 수 있습니다.

필수 조건

자격 증명(파트너 센터 인증에서 설명). 이 시나리오는 독립 실행형 앱과 App+사용자 자격 증명을 모두 사용하여 인증을 지원합니다.
고객 ID (customer-tenant-id). 고객의 ID를 모르는 경우 고객 작업 영역을 선택하고 고객 목록에서 고객을 선택한 다음 계정을 선택하여 파트너 센터에서 조회할 수 있습니다. 고객 계정 페이지의 고객 계정 정보 섹션에서 Microsoft ID를 찾습니다. Microsoft ID는 고객 ID(customer-tenant-id)와 동일합니다.
초기 구독에 대한 구독 ID입니다.

GDAP 역할

다음 GDAP 역할 중 하나 이상이 필요합니다.

디렉터리 읽기 권한자
전역 판독기

참고 항목

이 API는 레거시 및 NCE에 사용할 수 있지만 GDAP는 레거시에만 필요합니다.

REST 요청

요청 구문

메서드	요청 URI
GET	{baseURL}/v1/customers/{customer-tenant-id}/subscriptions/{subscription-id}/transitionEligibilities?eligibilityType={immediate, scheduled} HTTP/1.1

URI 매개 변수

다음 쿼리 매개 변수를 사용하여 적격 전환을 반환합니다.

속성	Type	필수	설명
customer-tenant-id	guid	Y	고객의 테넌트에 해당하는 GUID입니다.
subscription-id	guid	Y	초기 구독에 해당하는 GUID입니다.
eligibilityType	string	N	전환을 실행할 시기를 설명합니다. 는 즉시 또는 예약될 수 있습니다. 기본값은 `Immediate`입니다.

요청 헤더

자세한 내용은 파트너 센터 REST 헤더를 참조하세요.

요청 본문

None

요청 예제

GET https://api.partnercenter.microsoft.com/v1/customers/{customer-tenant-id}/subscriptions/{subscription-id}/transitionEligibilities?eligibilityType=immediate HTTP/1.1
Authorization: Bearer <token>
Accept: application/json
MS-RequestId: 18752a69-1aa1-4ef7-8f9d-eb3681b2d70a
MS-CorrelationId: aaaa0000-bb11-2222-33cc-444444dddddd
X-Locale: en-US

REST 응답

성공하면 이 메서드는 응답 본문에서 지정된 구독에 적합한 전환 목록을 반환합니다.

응답 성공 및 오류 코드

각 응답에는 성공 또는 실패 및 더 많은 디버깅 정보를 나타내는 HTTP 상태 코드가 함께 제공됩니다. 네트워크 추적 도구를 사용하여 이 코드, 오류 유형 및 기타 매개 변수를 읽습니다. 전체 목록은 오류 코드를 참조하세요.

자격 오류

오류 설명 및 의미입니다.

오류 설명	의미
구독을 전환할 수 없습니다. 원본 구독이 활성화되어 있지 않습니다.	원래 하위 상태가 활성 상태가 아님
구독을 전환할 수 없습니다. 원본 구독이 아직 프로비전되지 않았습니다.	원래 하위 FulfillmentState가 성공하지 않음
전환 유형은 호환되지 않습니다. AzureAD 구독 매핑이 필요합니다.	GetSubscriptionUpgradeConflicts를 호출할 때 LegacyCannotConvertSubscriptionId 오류
전환 유형은 호환되지 않습니다. 라이선스 전송에 대한 구독이 충돌합니다.	Microsoft Entra 서비스에 다른 구독의 구독 ID가 있는 경우 충돌 목록에 추가합니다(레거시 또는 최신 구매 흐름으로 구매한 항목 포함).

구독 자격 오류

대상 구독을 업그레이드할 수 없는 경우 다음 이유 중 하나가 반환됩니다.

원본 구독이 평가판이거나 자격 유형이 Scheduled로 지정된 경우 빈 목록이 반환됩니다. 예약된 변경이 아닌 즉시("중간" 전환이라고도 함)를 사용하여 기존 구독으로만 전환할 수 있습니다.

오류 설명	오류 코드
구독이 활성 상태가 아닙니다.	SubscriptionNotActive = 1
구독이 취소 기간 내에 있습니다.	SubscriptionInCancellationWindow = 2
구독 기간은 원본 구독의 기간 기간보다 짧습니다.	SubscriptionTermDurationShorterThanSourceTermDuration = 3
구독 기간 종료 날짜는 원본 구독의 기간 종료 날짜 이전입니다.	구독 기간 종료 날짜는 원본 구독의 기간 종료 날짜 이전입니다. = 4

응답 예제

HTTP/1.1 200 OK
Content-Length: 138
Content-Type: application/json
MS-CorrelationId: aaaa0000-bb11-2222-33cc-444444dddddd
MS-RequestId: 18752a69-1aa1-4ef7-8f9d-eb3681b2d70a
Date: Fri, 26 Feb 2021 20:42:26 GMT

{
  "totalCount": 2,
  "items": [
    {
      "operationId": "1caf8ec7-62cc-4ab5-b35d-572d2a62974c",
      "catalogItemId": "CFQ7TTC0KZCR:0001:CFQ7TTC0K71H",
      "title": "Microsoft 365 E5 Test Sku Title",
      "description": "Microsoft 365 E5 Test Sku Description",
      "quantity": 1,
      "subscriptionEligibilities": [
        {
          "isEligible": false,
          "subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
          "subscriptionFriendlyName": "Microsoft 365 Business Premium",
          "subscriptionTermDuration": "P1M",
          "subscriptionBillingCycle": "monthly",
          "errors": [
            {
              "code": 3,
              "description": "The subscription's term duration is shorter than the source subscription's term duration."
            }
          ]
        },
        {
          "isEligible": true,
          "subscriptionId": "bbbb1b1b-cc2c-dd3d-ee4e-ffffff5f5f5f",
          "subscriptionFriendlyName": "Microsoft 365 Business Premium",
          "subscriptionTermDuration": "P1Y",
          "subscriptionBillingCycle": "monthly",
          "errors": []
        }
      ],
      "eligibilities": [
        {
          "isEligible": true,
          "transitionType": "transition_only",
          "errors": []
        },
        {
          "isEligible": false,
          "transitionType": "transition_with_license_transfer",
          "errors": [
            {
              "code": 3,
              "description": "Subscription cannot be transitioned because there are conflicting services."
            }
          ]
        }
      ],
      "attributes": {
        "objectType": "TransitionEligibility"
      }
    },
    {
      "operationId": "1caf8ec7-62cc-4ab5-b35d-572d2a62974c",
      "catalogItemId": "CFQ7TTC0L4M3:0001:CFQ7TTC0K78T",
      "title": "Business Premium Test Sku Title",
      "description": "Business Premium Test Sku Description",
      "quantity": 1,
      "eligibilities": [
        {
          "isEligible": false,
          "transitionType": "transition_with_license_transfer",
          "errors": [
            {
              "code": 3,
              "description": "Subscription cannot be transitioned because there are conflicting services."
            }
          ]
        }
      ],
      "attributes": {
        "objectType": "TransitionEligibility"
      }
    }
  ],
  "attributes": {
    "objectType": "Collection"
  }
}

전환 후

지정된 고객 및 구독에 대한 전환 요청을 게시합니다. 초기 상태의 전환을 반환합니다.

필수 조건

자격 증명(파트너 센터 인증에서 설명). 이 시나리오는 독립 실행형 앱과 App+사용자 자격 증명을 모두 사용하여 인증을 지원합니다.
고객 ID (customer-tenant-id). 고객의 ID를 모르는 경우 고객 작업 영역을 선택하고 고객 목록에서 고객을 선택한 다음 계정을 선택하여 파트너 센터에서 조회할 수 있습니다. 고객 계정 페이지의 고객 계정 정보 섹션에서 Microsoft ID를 찾습니다. Microsoft ID는 고객 ID(customer-tenant-id)와 동일합니다.
초기 구독에 대한 구독 ID입니다.

GDAP 역할

다음 GDAP 역할 중 하나 이상이 필요합니다.

디렉터리 읽기 권한자 또는 전역 읽기 권한자(전환에만 해당)
디렉터리 기록기(라이선스 전송으로 전환)

참고 항목

이 API는 레거시 및 NCE에 사용할 수 있지만 GDAP는 레거시에만 필요합니다.

REST 요청

요청 구문

메서드	요청 URI
POST	{baseURL}/v1/customers/{customer-tenant-id}/subscriptions/{subscription-id}/transitions HTTP/1.1

URI 매개 변수

다음 쿼리 매개 변수를 사용하여 전환을 실행합니다.

속성	Type	필수	설명
customer-tenant-id	guid	Y	고객의 테넌트에 해당하는 GUID입니다.
subscription-id	guid	Y	초기 구독에 해당하는 GUID입니다.

요청 헤더

자세한 내용은 파트너 센터 REST 헤더를 참조하세요.

요청 본문

이 표에서는 요청 본문의 전환 속성에 대해 설명합니다.

속성	형식	필수	설명
fromCatalogItemId	string	아니요	전환할 카탈로그 항목입니다.
fromSubscriptionId	string	아니요	전환 중인 구독 ID입니다.
toCatalogItemId	string	예	전환할 카탈로그 항목입니다.
toSubscriptionId	string	아니요	전환 중인 구독 ID입니다.
quantity	정수	예	전환할 라이선스 수입니다.
termDuration	string	아니요	구독 기간 지정
billingCycle	string	아니요	구독의 청구 주기 지정합니다.
transitionType	string	예	전환 유형입니다. 가능한 값 - `transition_only`, `transition_with_license_transfer`.

요청 예제

POST https://api.partnercenter.microsoft.com/v1/customers/{customerId}/subscriptions/{subscriptionId}/transitions HTTP/1.1
Authorization: Bearer <token>
Accept: application/json
MS-RequestId: 18752a69-1aa1-4ef7-8f9d-eb3681b2d70a
MS-CorrelationId: aaaa0000-bb11-2222-33cc-444444dddddd
X-Locale: en-US

{
    "fromCatalogItemId": "CFQ7TTC0LF8Q:0001:CFQ7TTC0K39X",
    "fromSubscriptionId": "e487e8dc-421e-4275-cb42-3c1c8daccf70",
    "toCatalogItemId": "CFQ7TTC0LF8R:0001:CFQ7TTC0KCSV",
    "toSubscriptionId": "0af52192-4a2a-4364-d25b-c8ecab3a5697",
    "quantity": 2,
    "termDuration": "P1M",
    "billingCycle": "Monthly",
    "transitionType": "transition_only"
}

REST 응답

성공하면 이 메서드는 초기 상태의 전환 리소스를 반환합니다.

응답 성공 및 오류 코드

응답 예제

HTTP/1.1 200 OK
Content-Length: 138
Content-Type: application/json
MS-CorrelationId: aaaa0000-bb11-2222-33cc-444444dddddd
MS-RequestId: 18752a69-1aa1-4ef7-8f9d-eb3681b2d70a
Date: Fri, 26 Feb 2021 20:42:26 GMT

{
    "fromCatalogItemId": "CFQ7TTC0LF8Q:0001:CFQ7TTC0K39X",
    "fromSubscriptionId": "e487e8dc-421e-4275-cb42-3c1c8daccf70",
    "toCatalogItemId": "CFQ7TTC0LF8R:0001:CFQ7TTC0KCSV",
    "toSubscriptionId": "0af52192-4a2a-4364-d25b-c8ecab3a5697",
    "quantity": 2,
    "termDuration": "P1M",
    "billingCycle": "Monthly",
    "transitionType": "transition_only"
    "Events": [
        {
            "name": "Conversion",
            "status": "Started ",
            "timestamp": "2021-01-08T18:01:14.7488618Z",
            "attributes":
            {
                "objectType": "TransitionEvent"
            }
        }
    ],
    "attributes":
    {
        "objectType": "Transition" 
    }
}

다음을 통해 공유

새로운 상거래 구독 전환

전환 자격 가져오기

필수 조건

GDAP 역할

REST 요청

요청 구문

URI 매개 변수

요청 헤더

요청 본문

요청 예제

REST 응답

응답 성공 및 오류 코드

자격 오류

구독 자격 오류

응답 예제

전환 후

필수 조건

GDAP 역할

REST 요청

요청 구문

URI 매개 변수

요청 헤더

요청 본문

요청 예제

REST 응답

응답 성공 및 오류 코드

응답 예제

피드백

추가 리소스