Zmiana harmonogramu dla nowej subskrypcji komercyjnej przy użyciu interfejsów API Centrum Partnerskiego

Dotyczy: Centrum Partnerskiego

W tym artykule opisano, jak można użyć interfejsu API Centrum partnerskiego do zaplanowania zmian dla nowej subskrypcji handlowej , które nastąpią tylko podczas odnowienia. Ten interfejs API obsługuje subskrypcje oparte na nowych licencjach handlowych oraz subskrypcje oprogramowania.

Notatka

Nowe środowiska handlowe dla usług opartych na licencjach obejmują wiele nowych funkcji i są dostępne dla wszystkich dostawców rozwiązań w chmurze (CSP). Aby uzyskać więcej informacji, zobacz omówienie nowych środowisk handlowych.

Utworzenie zaplanowanych zmian umożliwia automatyczne modyfikowanie subskrypcji po następnym odnowieniu. Planując zmiany, możesz zwiększyć lub zmniejszyć liczbę licencji, zmodyfikować okres rozliczeniowy i częstotliwość, a nawet wybrać uaktualnienie jednostki SKU. Planowanie zmian umożliwia wprowadzanie modyfikacji subskrypcji podczas odnawiania, a nie natychmiast w trakcie bieżącego okresu.

Ważny

Jeśli przed datą odnowienia wprowadzisz natychmiastową zmianę w trakcie trwania umowy, wszystkie zmiany zaplanowane do wprowadzenia przy odnowieniu zostaną usunięte.

Warunki wstępne

Poświadczenia zgodnie z opisem w uwierzytelnianie w Centrum partnerskim. Ten scenariusz obsługuje uwierzytelnianie zarówno przy użyciu poświadczeń samodzielnej aplikacji, jak i poświadczeń aplikacji i użytkownika.
Identyfikator klienta (customer-tenant-id). Jeśli nie znasz identyfikatora klienta, możesz wyszukać go w centrum partnerskim , wybierając obszar roboczy Klienci, a następnie klient z listy klientów, a następnie konto. Na stronie konta klienta poszukaj identyfikatora Microsoft w sekcji Informacje o koncie klienta. Identyfikator Firmy Microsoft jest taki sam jak identyfikator klienta (customer-tenant-id).
Identyfikator subskrypcji.
Automatyczne odnawianie jest włączone w ramach subskrypcji.

Metoda Centrum partnerskiego

Aby zaplanować zmiany subskrypcji w Centrum partnerskim:

Wybierz klienta.
Wybierz subskrypcję, dla której chcesz zaplanować zmiany.
Włącz automatyczne odnawianie.
Wybierz opcję Zarządzaj odnawianiem.
Wprowadź modyfikacje subskrypcji w celu odnowienia.
Wybierz pozycję Okay, aby zamknąć panel boczny.
wybierz pozycję Prześlij, aby zapisać zmiany.

Notatka

Odnowienia są przetwarzane po ostatnim dniu okresu, począwszy od 12:00 czasu UTC następnego dnia. Odnowienia są przetwarzane w kolejce i przetwarzanie może potrwać do 24 godzin.

C#

Aby zaplanować zmiany dla subskrypcji klienta:

Pobierz subskrypcję według identyfikatora.
Uzyskaj kwalifikowalność do przejścia dla zaplanowanego typu kwalifikowalności do przejścia.
Utwórz obiekt ScheduledNextTermInstructions i ustaw go na właściwość subskrypcji.
Wywołaj metodę Patch(), aby zaktualizować subskrypcję za pomocą zaplanowanych zmian.

var selectedSubscription = subscriptionOperations.Get();
selectedSubscription.ScheduledNextTermInstructions = new ScheduledNextTermInstructions
{
    Product = new ProductTerm
    {
        ProductId = changeToProductId,
        SkuId = changeToSkuId,
        AvailabilityId = changeToAvailabilityId,
        BillingCycle = changeToBillingCycle,
        TermDuration = changeToTermDuration,
    },
    Quantity = changeToQuantity,
    customTermEndDate = DateTime,
};
var updatedSubscription = subscriptionOperations.Patch(selectedSubscription);

Aby zaplanować zmiany dla subskrypcji klienta, w której żądana zmiana zaplanowana jest na inny produkt:

Pobierz subskrypcję według identyfikatora.
Uzyskaj kwalifikowalność do przejścia dla zaplanowanego typu kwalifikowalności do przejścia.
Wywołaj metodę Patch(), aby zaktualizować subskrypcję za pomocą zaplanowanych zmian.

Żądanie REST

Składnia żądania

Metoda	Identyfikator URI żądania
POPRAWKA	{baseURL}/v1/customers/{customer-tenant-id}/subscriptions/{subscription-id} HTTP/1.1

Parametr identyfikatora URI

W tej tabeli wymieniono wymagane parametry zapytania do wywołania interfejsu API.

Nazwa	Typ	Wymagane	Opis
identyfikator-klienta-najemcy	guid	Y	Identyfikator GUID odpowiadający klientowi.
identyfikator subskrypcji	guid	Y	Identyfikator GUID odpowiadający subskrypcji.

Nagłówki żądań

Aby uzyskać więcej informacji, odwiedź sekcję Nagłówki REST w Centrum Partnerskim.

Treść żądania

W treści żądania wymagany jest pełny zasób subskrypcji z zdefiniowaną właściwością scheduledNextTermInstructions. Aby zaplanować zmiany dla subskrypcji, upewnij się, że właściwość AutoRenewEnabled jest ustawiona na true.

Oferty z konwersjami, identyfikowane przez identyfikator dostępności po zakończeniu sprzedaży (EndofSaleWithConversions):

GetTransitionEligibility w celu zwrócenia identyfikatora CatalogItemID.

a. Upewnij się, że ustawiono typ uprawnień jako 'Zaplanowany', w przeciwnym razie wartością domyślną będzie 'Natychmiastowy'.
Użyj identyfikatora CatalogItemID, aby wyodrębnić identyfikator dostępności.

Jeśli używasz funkcji GET Availabilities, aby ustalić dostępność dla zaplanowanych instrukcji scheduledNextTerm, i wszystkie terminy są w stanie EOS, otrzymasz pustą listę. Najlepszym sposobem określenia prawidłowych ścieżek jest wywołanie interfejsu API GetTransitionEligibility, aby zwrócić prawidłowe opcje.

Pole	Typ	Wymagane	Opis
zaplanowaneKolejnyTerminInstrukcje	obiekt	Y	Definiuje instrukcje dotyczące następnego terminu dla subskrypcji. Właściwość zawiera obiekt `product` i pole `quantity`.

Korzystanie z scheduledActions do ustawiania instrukcji dotyczących następnego okresu (zaplanowanych zmian)

Rozszerzone postanowienia dotyczące usług wprowadzają nowy sposób ustawiania instrukcji dotyczących zakończenia terminu. Nowy konstrukt scheduledActions umożliwia partnerom jednolity sposób definiowania aktualizacji na kolejny okres, w tym anulowania, odnowienia do rozszerzonych okresów świadczenia usług lub odnowienia do innych opcji docelowych na koniec okresu. Partnerzy mogą ustawiać instrukcje scheduledActions.RenewToNewTerm zamiast poprzednich scheduledNextTermInstructions. Więcej informacji na temat używania funkcji scheduledActions do ustawiania kolejnych instrukcji dotyczących terminów można znaleźć w dokumentacji rozszerzonego terminu usługi.

Partnerzy korzystający z usługi scheduledActions powinni unikać również przekazywać scheduledNextTermInstructions podczas aktualizowania subskrypcji kwalifikujących się do wydłużonych okresów świadczenia usług. Partnerzy mogą zdecydować się na przekazanie obu tych elementów, należy pamiętać, że rozważane są tylko zaplanowane elementy Action. Partnerzy mogą nadal przekazywać tylko zaplanowane instrukcje dotyczące następnego terminu w ramach NextTermInstructions.

Ważny

Unikaj przekazywania instrukcji dotyczących następnego okresu rozliczeniowego zarówno w scheduledActions, jak i w nextTermInstructions. Użyj jednego lub drugiego. Jeśli oba są przekazywane, instrukcje scheduledActions są domyślnie włączone.

Żądanie za pomocą zaplanowanych działań

{
  "autoRenewEnabled": true,
  "scheduledActions": [
    {
      "scheduledType": "TermEnd",
      "actionType": "RenewToNewTerm",
      "instructions": {
        "product": {
          "productId": "CFQ7TTC0LHXH",
          "skuId": "0001",
          "availabilityId": "CFQ7TTC0LHXH",
          "billingCycle": "annual",
          "termDuration": "P1Y",
          "promotionId": "39NFJQT20KJ2:0001:39NFJQT1Q5KK"
        },
        "quantity": 25,
        "customTermEndDate": "2027-11-31T23:59:59.000Z"
      }
    }
  ]
}

Odpowiedź przy użyciu zaplanowanych akcji

{
  "autoRenewEnabled": true,
  "scheduledNextTermInstructions" : {
     "product": {
        "productId": "CFQ7TTC0LHXH",
        "skuId": "0001",
        "availabilityId": "CFQ7TTC0LHXH",
        "billingCycle": "annual",
        "termDuration": "P1Y",
        "promotionId": "39NFJQT20KJ2:0001:39NFJQT1Q5KK"
      },
      "quantity": 25,
      "customTermEndDate": "2027-11-31T23:59:59.000Z"
  },
  "scheduledActions":   "scheduledActions": [
    {
      "scheduledType": "TermEnd",
      "actionType": "RenewToNewTerm",
      "instructions": {
        "product": {
          "productId": "CFQ7TTC0LHXH",
          "skuId": "0001",
          "availabilityId": "CFQ7TTC0LHXH",
          "billingCycle": "annual",
          "termDuration": "P1Y",
          "promotionId": "39NFJQT20KJ2:0001:39NFJQT1Q5KK"
        },
        "quantity": 25,
        "customTermEndDate": "2027-11-31T23:59:59.000Z"
      }
    }
  ]
}

Ustawianie przejść w rocznicę przy użyciu funkcji scheduledActions

Wybrane trzyletnie jednostki SKU z usługą Teams można zaplanować do przejścia w rocznicę okresu obowiązywania.

Żądanie przy użyciu zaplanowanych akcji

{ 
    "id": "c10138d2-083b-4330-cf0d-6565dfaf22be", 
    "offerId": "CFQ7TTC0ZSXT:0001:CFQ7TTC0K85Z", 
    … 
    "scheduledActions": [ 
        { 
            "scheduleType": "CustomDate", // currently supported - EndOfTerm
            "actionType": "Transition", // currently supported - RenewToNewTerm, RenewToExtendedServiceTerm, Cancel 
            "effectiveDate": "2026-08-01", 
            "instructions": { 
                "product": { 
                    "productId": "CFQ7TTC0ZSXT", 
                    "skuId": "0001", 
                    "availabilityId": "CFQ7TTC0K8B0", 
                    "billingCycle": "monthly", 
                    "termDuration": "P1M" 
                }, 
            } 
        } 
    ] 
}

Żądanie z użyciem zaplanowanych instrukcji dotyczących kolejnego terminu

PATCH https://api.partnercenter.microsoft.com/v1/customers/<customer-tenant-id>/subscriptions/<subscription-id> HTTP/1.1
Authorization: Bearer <token>
Accept: application/json
MS-RequestId: ca7c39f7-1a80-43bc-90d8-ee7d1cad3831
MS-CorrelationId: aaaa0000-bb11-2222-33cc-444444dddddd
If-Match: <etag>
Content-Type: application/json
Content-Length: 1029
Expect: 100-continue
Connection: Keep-Alive

{
    "id": "6e7aa601-629e-461b-8933-0898c3cc3c7c",
    "offerId": "DZH318Z0BXWC:0001:DZH318Z0BMJX",
    "offerName": "offer Name",
    "friendlyName": "friendly Name",
    "quantity": 1,
    "customTermEndDate": "2019-01-09T00:21:45.9263727",
    "unitType": "License(s)",
    "hasPurchasableAddons": false,
    "creationDate": "2019-01-04T01:00:12.6647304Z",
    "effectiveStartDate": "2019-01-09T00:21:45.9263727+00:00",
    "commitmentEndDate": "2019-02-08T00:21:45.9263727+00:00",
    "status": "active",
    "autoRenewEnabled": true,
    "scheduledNextTermInstructions": { 
      "product": { 
         "productId":  "DG7GMGF0DVSV", 
         "skuId":  "000P", 
         "availabilityId":  "DG7GMGF0F3Q9", 
         "billingCycle":  "Annual", 
         "termDuration":  "P3Y",
         "promotionId": "39NFJQT1PFPJ:000H:39NFJQT1Q5DK"
        }, 
      "quantity":  1 
      "customTermEndDate" : "2019-01-09T00:21:45.9263727",
     },  // original value = null 
    "isTrial": false,
    "billingType": "license",
    "billingCycle": "monthly",
    "termDuration": "P1M",
    "refundOptions": [{
        "type": "Full",
        "expiresAt": "2019-01-10T00:21:45.9263727+00:00"
    }],
    "isMicrosoftProduct": false,
    "partnerId": "",
    "contractType": "subscription",
    "publisherName": "publisher Name",
    "orderId": "ImxjLNL4_fOc-2KoyOxGTZcrlIquzls11",
    "attributes": {"objectType": "Subscription"},
}

Odpowiedź REST

Jeśli żądanie zakończy się pomyślnie, ta metoda zwraca zaktualizowane właściwości zasobu subskrypcji w treści odpowiedzi.

Kody sukcesu i błędu odpowiedzi

Każda odpowiedź zawiera kod stanu HTTP, który wskazuje powodzenie lub niepowodzenie oraz inne informacje o debugowaniu. Użyj narzędzia do śledzenia sieci, aby odczytać ten kod, typ błędu i inne parametry. Aby uzyskać pełną listę, zobacz Kody błędów.

Odpowiedz zgodnie z zaplanowanymi instrukcjami na następny okres

HTTP/1.1 200 OK
Content-Length: 1322
Content-Type: application/json; charset=utf-8
MS-RequestId: ca7c39f7-1a80-43bc-90d8-ee7d1cad3831
MS-CorrelationId: aaaa0000-bb11-2222-33cc-444444dddddd
X-Locale: en-US

{
    "id": "6e7aa601-629e-461b-8933-0898c3cc3c7c",
    "offerId": "DZH318Z0BXWC:0001:DZH318Z0BMJX",
    "offerName": "offer Name",
    "friendlyName": "friendly Name",
    "quantity": 1,
    "customTermEndDate": "2019-01-09T00:21:45.9263727",
    "unitType": "License(s)",
    "hasPurchasableAddons": false,
    "creationDate": "2019-01-04T01:00:12.6647304Z",
    "effectiveStartDate": "2019-01-09T00:21:45.9263727+00:00",
    "commitmentEndDate": "2019-02-08T00:21:45.9263727+00:00",
    "status": "active",
    "autoRenewEnabled": true,
    "scheduledNextTermInstructions": { 
      "product": { 
         "productId":  "DG7GMGF0DVSV", 
         "skuId":  "000P", 
         "availabilityId":  "DG7GMGF0F3Q9", 
         "billingCycle":  "Annual", 
         "termDuration":  "P3Y",
         "promotionId": "39NFJQT1PFPJ:000H:39NFJQT1Q5DK"
        }, 
      "quantity":  1 
      "customTermEndDate": "2019-01-09T00:21:45.9263727",
     },  // original value = null 
    "isTrial": false,
    "billingType": "license",
    "billingCycle": "monthly",
    "termDuration": "P1M",
    "refundOptions": [{
        "type": "Full",
        "expiresAt": "2019-01-10T00:21:45.9263727+00:00"
    }],
    "isMicrosoftProduct": false,
    "partnerId": "",
    "contractType": "subscription",
    "publisherName": "publisher Name",
    "orderId": "ImxjLNL4_fOc-2KoyOxGTZcrlIquzls11",
    "attributes": {"objectType": "Subscription"},
}

Opinia

Czy ta strona była pomocna?

Last updated on 2026-06-29