Pobieranie i aktualizowanie subskrypcji

Po pobraniu subskrypcji możesz użyć informacji z odpowiedzi o sukcesie, aby zmienić stan subskrypcji lub ją zaktualizować. Na tej stronie omawiamy różne sposoby pobierania i aktualizowania subskrypcji.

Pobieranie subskrypcji

Aby pobrać subskrypcję, która została zamówiona lub przeniesiona, użyj tego GETżądania HTTP.

GET https://reseller.googleapis.com/apps/reseller/v1/customers/CUSTOMER_ID/subscriptions/SUBSCRIPTION_ID

Zastąp następujące elementy:

  • CUSTOMER_ID: nazwa domeny podstawowej klienta lub jego unikalny identyfikator.
  • SUBSCRIPTION_ID: identyfikator subskrypcji, który jest niepowtarzalny dla każdego klienta. Możesz pobrać tę wartość za pomocą metody pobierania wszystkich subskrypcji sprzedawcy.

Ta operacja nie ma parametrów w treści żądania.

Odpowiedź świadcząca o powodzeniu zwraca kod stanu HTTP 200 i ustawienia subskrypcji. W odpowiedzi w przykładzie poniżej właściwość isInTrial ma wartość false, ale nie ma właściwości trialEndTime, co oznacza, że ten klient nigdy nie korzystał z 30-dniowego bezpłatnego okresu próbnego w ramach tego abonamentu.

{
  "kind": "reseller#subscription",
  "customerId": "C0123456",
  "subscriptionId": "123",
  "skuId": "1010020028",
  "billingMethod": "ONLINE",
  "creationTime": "1331647980142",
  "plan": {
    "planName": "ANNUAL",
    "isCommitmentPlan": true,
    "commitmentInterval": {
      "startTime": "1331647980142",
      "endTime": "1363183980142"
    }
  },
  "seats": {
    "kind": "subscriptions#seats",
    "numberOfSeats": 10,
    "licensedNumberOfSeats": 10
  },
  "trialSettings": {
    "isInTrial": false
  },
  "renewalSettings": {
    "kind": "subscriptions#renewalSettings",
    "renewalType": "RENEW_CURRENT_USERS_MONTHLY_PAY"
  },
  "purchaseOrderId": "example.com_annual_1",
  "status": "ACTIVE",
  "resourceUiUrl": "URL to customer's Subscriptions page in the Admin console",
  "skuName": "Google Workspace Business Standard"
}

Pobieranie wszystkich subskrypcji klienta

Aby pobrać wszystkie subskrypcje konkretnego klienta odsprzedawcy, które zostały zamówione lub przeniesione, użyj tego żądania HTTP GET i dołącz token autoryzacji:

GET https://reseller.googleapis.com/apps/reseller/v1/subscriptions?customerId=CUSTOMER_ID value&pageToken=START_DATE&maxResults=MAX_NUMBER

Zastąp następujące elementy:

  • CUSTOMER_ID: nazwa domeny podstawowej klienta lub jego unikalny identyfikator.
  • START_DATE: data rozpoczęcia w formacie YYYY-MM-DD.
  • MAX_NUMBER: maksymalna liczba wyników zwracanych na stronie odpowiedzi.

Ta operacja nie ma parametrów w treści żądania.

Odpowiedź informująca o powodzeniu zwraca kod stanu HTTP 200 oraz listę subskrypcji i ustawień klienta. Lista subskrypcji może zawierać produkty, którymi nie można zarządzać w tej wersji interfejsu Reseller API.

Jeśli nie zarządzasz tym klientem, zwracany jest błąd 403 "Forbidden".

Pobieranie wszystkich subskrypcji klienta, które można przenieść

Aby pobrać wszystkie subskrypcje klienta, które można przenieść do zarządzania przez odsprzedawcę, użyj tego GETżądania HTTP i dołącz token autoryzacji. Pole customerId jest wymagane i zawiera unikalny identyfikator klienta zwracany podczas pobierania konta klienta sprzedawcy. customerAuthToken to token przeniesienia udostępniony przez klienta, który jest powiązany z Twoim identyfikatorem sprzedawcy. Po wygenerowaniu przez klienta jest on ważny przez 30 dni. Więcej informacji o tym, jak klienci generują token, znajdziesz w artykule Przenoszenie konta Google Workspace do sprzedawcy.

GET https://reseller.googleapis.com/apps/reseller/v1/subscriptions?customerId=CUSTOMER_ID&customerAuthToken=AUTH_TOKEN&pageToken=START_DATE&maxResults=MAX_NUMBER

Zastąp następujące elementy:

  • CUSTOMER_ID: nazwa domeny podstawowej klienta lub jego unikalny identyfikator.
  • AUTH_TOKEN: token przeniesienia przekazany przez klienta, który jest powiązany z Twoim identyfikatorem sprzedawcy. Po wygenerowaniu przez klienta jest on ważny przez 30 dni. Więcej informacji o tym, jak klienci generują token, znajdziesz w artykule Przenoszenie konta Google Workspace do sprzedawcy. Jeśli ta wartość jest nieprawidłowa lub wygasła, w odpowiedzi interfejsu API zwracany jest błąd 403 "Forbidden".
  • START_DATE: data rozpoczęcia w formacie YYYY-MM-DD.
  • MAX_NUMBER: maksymalna liczba wyników zwracanych na stronie odpowiedzi.

Ta operacja nie ma parametrów w treści żądania.

Prawidłowa odpowiedź zwraca kod stanu HTTP 200 i listę subskrypcji klienta, które można przenieść, z datą ważności tokena przeniesienia i minimalną liczbą miejsc potrzebną w zamówieniu przeniesienia. Klient może mieć dodatkowe subskrypcje, których nie można przenieść.

{
  "kind": "reseller#subscriptions",
  "subscriptions": [
    {
      "kind": "subscriptions#subscription",
      "customerId": "custId-6543",
      "subscriptionId": "432",
      "skuId": "1010020028",
      "billingMethod": "ONLINE",
      "creationTime": "1331647980142",
      "plan": {
        "planName": "ANNUAL",
        "isCommitmentPlan": true,
        "commitmentInterval": {
          "startTime": "1331647980142",
          "endTime": "1363183980142"
        }
      },
      "seats": {
        "kind": "subscriptions#seats",
        "numberOfSeats": 10,
        "maximumNumberOfSeats": 500,
        "licensedNumberOfSeats": 10
      },
      "trialSettings": {
        "isInTrial": false
      },
      "renewalSettings": {
        "kind": "subscriptions#renewalSettings",
        "renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
      },
      "transferInfo": {
        "transferabilityExpirationTime": "1333183980142",
        "minimumTransferableSeats": "20"
      },
      "purchaseOrderId": "PO_890",
      "status": "ACTIVE",
      "resourceUiUrl": "URL to customer's Subscriptions page in the Admin console",
      "skuName": "Google Workspace Business Standard"
    },
    {
      "kind": "subscriptions#subscription",
      "customerId": "custId-6543",
      "subscriptionId": "140",
      "skuId": "1010020028",
      "creationTime": "1329389322728",
      "plan": {
        "planName": "FLEXIBLE",
        "isCommitmentPlan": false
      },
      "seats": {
        "kind": "subscriptions#seats",
        "maximumNumberOfSeats": 50
        "licensedNumberOfSeats": 10
      },
      "trialSettings": {
        "isInTrial": false,
        "trialEndTime": "1331877480016"
      },
      "renewalSettings": {
        "kind": "subscriptions#renewalSettings",
        "renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
      },
      "transferInfo": {
        "transferabilityExpirationTime": "1333183780159",
        "minimumTransferableSeats": "10"
      },
      "purchaseOrderId": "",
      "status": "ACTIVE",
      "resourceUiUrl": "URL to customer's Subscriptions page in the Admin console",
      "skuName": "Google Workspace Business Standard"
    },
  ],
  "nextPageToken": "token"
}

Jeśli planujesz przenieść te subskrypcje za pomocą operacji wsadowej, przenieś wszystkie subskrypcje. Przenoszenie każdej subskrypcji pojedynczo powoduje błąd. Dodatkowo operacja wsadowa przenosi tylko subskrypcje ze statusem ACTIVE. Więcej informacji znajdziesz w artykule Przenoszenie subskrypcji.

Pobieranie wszystkich subskrypcji sprzedawcy

Aby pobrać wszystkie subskrypcje, które zostały pomyślnie zamówione lub przeniesione przez sprzedawcę, użyj tego żądania HTTP GET i dołącz token autoryzacji. 

GET https://reseller.googleapis.com/apps/reseller/v1/subscriptions?customerNamePrefix=PREFIX &pageToken=TOKEN&maxResults=MAX_NUMBER

Zastąp następujące elementy:

  • PREFIX: początek imienia i nazwiska klienta, którego subskrypcji szukasz.
  • TOKEN: token identyfikujący konkretną stronę wyników, którą serwer powinien zwrócić.
  • MAX_NUMBER: maksymalna liczba wyników zwracanych na stronie odpowiedzi.

Ta operacja może używać zakresu dostępu tylko do odczytu OAuth. Parametry customerNamePrefix, pageToken i maxResults są opcjonalnymi ciągami zapytania.

W tym przykładzie pobierane są wszystkie subskrypcje odsprzedawcy, które należą do klientów, których nazwy zaczynają się od „exam”:

GET https://reseller.googleapis.com/apps/reseller/v1/subscriptions?customerNamePrefix=exam

{
  "kind": "reseller#subscriptions",
  "subscriptions": [
    {
      "kind": "subscriptions#subscription",
      "customerId": "C0123456",
      "subscriptionId": "123",
      "skuId": "1010020028",
      "creationTime": "1331647980142",
      "billingMethod": "ONLINE",
      "plan": {
        "planName": "ANNUAL",
        "isCommitmentPlan": true,
        "commitmentInterval": {
          "startTime": "1331647980142",
          "endTime": "1363183980142"
        }
      },
      "seats": {
        "kind": "subscriptions#seats",
        "numberOfSeats": 10,
        "licensedNumberOfSeats": 10
      },
      "trialSettings": {
        "isInTrial": false
      },
      "renewalSettings": {
        "kind": "subscriptions#renewalSettings",
        "renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
      },
      "purchaseOrderId": "PO_135",
      "status": "ACTIVE",
      "resourceUiUrl": "URL to customer's Subscriptions page in the Admin console",
      "skuName": "Google Workspace Business Standard"
    },
    {
      "kind": "subscriptions#subscription",
      "customerId": "custId-5678",
      "subscriptionId": "1404686",
      "skuId": "1010020028",
      "billingMethod": "ONLINE",
      "creationTime": "1329389322728",
      "plan": {
        "planName": "FLEXIBLE",
        "isCommitmentPlan": false
      },
      "seats": {
        "kind": "subscriptions#seats",
        "maximumNumberOfSeats": 50,
        "licensedNumberOfSeats": 10
      },
      "trialSettings": {
        "isInTrial": false,
        "trialEndTime": "1331877480016"
      },
      "renewalSettings": {
        "kind": "subscriptions#renewalSettings",
        "renewalType": "AUTO_RENEW"
      },
      "purchaseOrderId": "",
      "status": "ACTIVE",
      "resourceUiUrl": "URL to customer's Subscriptions page in the Admin console",
      "skuName": "Google Workspace Business Standard"
    },
  ],
  "nextPageToken": "token"
}

Aktualizowanie abonamentu

Aktualizacja abonamentów Google Workspace różni się w zależności od abonamentu. Zanim zaktualizujesz plan, weź pod uwagę te kwestie:

  • Gdy tworzysz subskrypcję, a klient spełnia warunki, może on skorzystać z 30-dniowego okresu próbnego. Zarówno abonament elastyczny, jak i roczny mogą być 30-dniowymi bezpłatnymi okresami próbnymi. W okresie próbnym możesz dowolną liczbę razy zmieniać abonament subskrypcji na elastyczny lub roczny. Gdy jednak okres próbny się skończy i subskrypcja stanie się aktywna, aktualizacja subskrypcji będzie podlegać tym samym zasadom co w przypadku innych aktywnych subskrypcji. Aby natychmiast przejść z subskrypcji próbnej na aktywną, rozpocznij korzystanie z płatnej usługi w ramach 30-dniowego bezpłatnego okresu próbnego. Więcej informacji o 30-dniowym okresie próbnym i zasadach kwalifikacji klientów znajdziesz w Centrum pomocy dla administratorów.

  • Możesz zmienić abonament elastyczny na abonament roczny.

  • Nie możesz zaktualizować rocznego abonamentu.

  • Nie wszystkie plany działają ze wszystkimi produktami. Więcej informacji o tym, z jakich usług korzystają te plany, znajdziesz w sekcji Usługi i SKU.

Aby zaktualizować abonament na 30-dniowy okres próbny lub abonament elastyczny do abonamentu rocznego, użyj tego żądania HTTP POST:

POST https://reseller.googleapis.com/apps/reseller/v1/customers/CUSTOMER_ID/subscriptions/SUBSCRIPTION_ID/changePlan

Zastąp następujące elementy:

  • CUSTOMER_ID: nazwa domeny podstawowej klienta lub jego unikalny identyfikator.
  • SUBSCRIPTION_ID: identyfikator subskrypcji, który jest niepowtarzalny dla każdego klienta. Możesz pobrać tę wartość za pomocą metody pobierania wszystkich subskrypcji sprzedawcy.

W tym przykładzie subskrypcja jest aktualizowana za pomocą parametru subscriptionId o wartości 123. Wartość customerId to C0123456.

POST https://reseller.googleapis.com/apps/reseller/v1/customers/C0123456/subscriptions/123/changePlan

Treść żądania zawiera:

{
  "kind": "reseller#changePlanRequest",
  "planName": "ANNUAL_MONTHLY_PAY",
  "seats": {
    "kind": "subscriptions#seats",
    "numberOfSeats": 10
  },
  "purchaseOrderId": "123_March2012"
}

Odpowiedź zakończona powodzeniem zwraca kod stanu HTTP 201 i zaktualizowane ustawienia planu subskrypcji:

{
  "kind": "reseller#subscription",
  "customerId": "C0123456",
  "subscriptionId": "123",
  "skuId": "1010020028",
  "creationTime": "1331647980142",
  "plan": {
    "planName": "ANNUAL",
    "isCommitmentPlan": true,
    "commitmentInterval": {
      "startTime": "1331647980142",
      "endTime": "1363183980142"
    }
  },
  "seats": {
    "kind": "subscriptions#seats",
    "numberOfSeats": 10,
    "licensedNumberOfSeats": 10
  },
  "trialSettings": {
    "isInTrial": false
  },
  "renewalSettings": {
    "kind": "subscriptions#renewalSettings",
    "renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
  },
  "purchaseOrderId": "123_March2012",
  "status": "ACTIVE",
  "skuName": "Google Workspace Business Standard"
}

Aktualizowanie stanowisk w subskrypcji

Aktualizacja subskrypcji abonamentu rocznego wykorzystuje inne właściwości subskrypcji niż aktualizacja subskrypcji abonamentu elastycznego Google Workspace.

Aktualizowanie liczby licencji w subskrypcji w abonamencie rocznym

Aby zaktualizować ustawienia licencji użytkownika w przypadku subskrypcji rocznej, użyj tego żądania HTTP:POST

POST https://reseller.googleapis.com/apps/reseller/v1/customers/CUSTOMER_ID/subscriptions/SUBSCRIPTION_ID/changeSeats

Zastąp następujące elementy:

  • CUSTOMER_ID: nazwa domeny podstawowej klienta lub jego unikalny identyfikator.
  • SUBSCRIPTION_ID: identyfikator subskrypcji, który jest niepowtarzalny dla każdego klienta. Możesz pobrać tę wartość za pomocą metody pobierania wszystkich subskrypcji sprzedawcy.

W przykładzie poniżej aktualizujemy subskrypcję za pomocą identyfikatora 123 subscriptionId. Wartość customerId to C0123456. Treść żądania różni się w zależności od typu abonamentu:

POST https://reseller.googleapis.com/apps/reseller/v1/customers/C0123456/subscriptions/123/changeSeats

Subskrypcja rocznego abonamentu Google Workspace używa tego treści żądania do aktualizowania liczby licencji użytkowników. Wartość numberOfSeats to suma. Jeśli na przykład masz 10 licencji użytkownika, a klient zamówi 5 nowych licencji, łączna liczba w treści żądania dla parametru numberOfSeats wyniesie 15, jak pokazano w tym przykładzie:

{
    "kind": "subscriptions#seats",
    "numberOfSeats": 15
}

Aktualizowanie stanowisk w subskrypcji w abonamencie elastycznym

Subskrypcja abonamentu elastycznego Google Workspace używa treści żądania do aktualizowania licencji użytkowników. Wartość maximumNumberOfSeats to suma dotychczasowych i nowych licencji. Jest to maksymalna liczba licencji użytkowników, które można udostępnić na koncie.

{
  "kind": "subscriptions#seats",
  "maximumNumberOfSeats": 15
}

Odpowiedź zakończona powodzeniem zwraca kod stanu HTTP 201 i zaktualizowane ustawienia licencji na subskrypcję:

{
  "kind": "reseller#subscription",
  "customerId": "C0123456",
  "subscriptionId": "123",
  "skuId": "1010020028",
  "creationTime": "1331647980142",
  "plan": {
    "planName": "FLEXIBLE",
    "isCommitmentPlan": false
  },
  "seats": {
    "kind": "subscriptions#seats",
    "maximumNumberOfSeats": 15,
    "licensedNumberOfSeats": 10
  },
  "trialSettings": {
    "isInTrial": false
  },
  "skuName": "Google Workspace Business Standard"
}

Aktualizowanie ustawień odnawiania subskrypcji

Aby zaktualizować ustawienia odnowienia subskrypcji z rocznym zobowiązaniem, użyj tego żądania HTTP:POST

POST https://reseller.googleapis.com/apps/reseller/v1/customers/CUSTOMER_ID/subscriptions/SUBSCRIPTION_ID/changeRenewalSettings

Zastąp następujące elementy:

  • CUSTOMER_ID: nazwa domeny podstawowej klienta lub jego unikalny identyfikator.
  • SUBSCRIPTION_ID: identyfikator subskrypcji, który jest niepowtarzalny dla każdego klienta. Możesz pobrać tę wartość za pomocą metody pobierania wszystkich subskrypcji sprzedawcy.

Oto przykładowa treść żądania:

{
  "kind": "subscriptions#renewalSettings",
  "renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
}

Wartość właściwości renewalType może być dowolna z tych opcji:

  • AUTO_RENEW_YEARLY_PAY: po zakończeniu okresu zobowiązania w ramach abonamentu rocznego automatycznie odnów abonament jako ANNUAL_YEARLY_PAY z tym samym numberOfSeats.
  • AUTO_RENEW_MONTHLY_PAY: Po zakończeniu okresu rocznego abonamentu automatycznie odnawiaj subskrypcję jako ANNUAL_MONTHLY_PAY z tym samym numberOfSeats.
  • RENEW_CURRENT_USERS_YEARLY_PAY: na koniec okresu rocznego zobowiązania odnów abonament jako ANNUAL_YEARLY_PAY, ale użyj łącznej liczby bieżących aktywnych licencji użytkowników. Jest to ustawienie domyślne w przypadku aktywnych abonamentów rocznych (płatnych co roku).
  • RENEW_CURRENT_USERS_MONTHLY_PAY: na koniec okresu rocznego zobowiązania odnów abonament jako ANNUAL_MONTHLY_PAY, ale użyj łącznej liczby bieżących aktywnych licencji użytkowników. Jest to ustawienie domyślne w przypadku aktywnych abonamentów rocznych (płatnych co miesiąc).
  • RENEW_ON_PROPOSED_OFFER: Po zakończeniu bieżącego okresu zobowiązania odnów subskrypcję zgodnie z najnowszą propozycją odnowienia, w której liczba stanowisk jest równa liczbie bieżących aktywnych licencji użytkowników lub zobowiązaniu w ramach proponowanej oferty, w zależności od tego, która z tych wartości jest większa.
  • SWITCH_TO_PAY_AS_YOU_GO: po zakończeniu okresu abonamentu bazującego na zobowiązaniu rocznym zmień go na abonament elastyczny.
  • CANCEL: po zakończeniu okresu zobowiązania rocznego subskrypcja zostaje zawieszona. Aby dowiedzieć się, jak cofnąć zawieszenie, odwiedź Centrum pomocy dla administratorów.

Odpowiedź zakończona powodzeniem zwraca kod stanu HTTP 201 i zaktualizowane ustawienia odnowienia subskrypcji:

{
  "kind": "reseller#subscription",
  "customerId": "C0123456",
  "subscriptionId": "123",
  "skuId": "1010020028",
  "creationTime": "1331647980142",
  "plan": {
    "planName": "ANNUAL",
    "isCommitmentPlan": true,
    "commitmentInterval": {
      "startTime": "1331647980142",
      "endTime": "1363183980142"
    }
  },
  "seats": {
    "kind": "subscriptions#seats",
    "numberOfSeats": 15,
    "licensedNumberOfSeats": 15
  },
  "trialSettings": {
    "isInTrial": false
  },
  "renewalSettings": {
    "kind": "subscriptions#renewalSettings",
    "renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
  },
  "skuName": "Google Workspace Business Standard"
}

Przejście na usługę płatną z bezpłatnej subskrypcji próbnej

Aby natychmiast przenieść 30-dniową subskrypcję w ramach bezpłatnego okresu próbnego na płatną subskrypcję usługi, jeśli dla subskrypcji w ramach okresu próbnego skonfigurowano już abonament, użyj tego żądania HTTP: POST. 

POST https://reseller.googleapis.com/apps/reseller/v1/customers/CUSTOMER_ID/subscriptions/SUBSCRIPTION_ID/startPaidService

Zastąp następujące elementy:

  • CUSTOMER_ID: nazwa domeny podstawowej klienta lub jego unikalny identyfikator.
  • SUBSCRIPTION_ID: identyfikator subskrypcji, który jest niepowtarzalny dla każdego klienta. Możesz pobrać tę wartość za pomocą metody pobierania wszystkich subskrypcji sprzedawcy.

W tym przykładzie C0123456 to customerId, a subscriptionId to 123:

POST https://reseller.googleapis.com/apps/reseller/v1/customers/C0123456/subscriptions/123/startPaidService

Ta operacja nie ma parametrów w treści żądania.

Odpowiedź zakończona powodzeniem zwraca kod stanu HTTP 201 i zaktualizowane ustawienia subskrypcji:

{
  "kind": "reseller#subscription",
  "customerId": "C0123456",
  "subscriptionId": "123",
  "skuId": "1010020028",
  "creationTime": "1331647980142",
  "plan": {
    "planName": "ANNUAL",
    "isCommitmentPlan": true,
    "commitmentInterval": {
      "startTime": "1331647980142",
      "endTime": "1363183980142"
    }
  },
  "seats": {
    "kind": "subscriptions#seats",
    "numberOfSeats": 15,
    "licensedNumberOfSeats": 15
  },
  "trialSettings": {
    "isInTrial": false
  },
  "renewalSettings": {
    "kind": "subscriptions#renewalSettings",
    "renewalType": "SWITCH_TO_PAY_AS_YOU_GO"
  },
  "skuName": "Google Workspace Business Standard"
}

Przechodzenie na wyższą lub niższą wersję subskrypcji

Nie możesz przejść na niższą wersję abonamentu rocznego w trakcie jego trwania ani zaplanować przejścia na niższą wersję za pomocą ustawień odnawiania. Zalecamy ustawienie opcji odnowienia na FLEXIBLE, a następnie obniżenie wersji po upływie czasu odnowienia.

Aby przejść na wyższą lub niższą wersję subskrypcji, utwórz nową subskrypcję z skuId, na którą chcesz przejść.

POST https://reseller.googleapis.com/apps/reseller/v1/customers/CUSTOMER_ID/subscriptions

Zastąp następujące elementy:

  • CUSTOMER_ID: nazwa domeny podstawowej klienta lub jego unikalny identyfikator.

To wywołanie kończy poprzednią subskrypcję i tworzy nową.

Więcej informacji o uaktualnieniach i obniżeniach wersji znajdziesz na stronie Produkty i numery SKU.