Powiadomienia push

Na tej stronie dowiesz się, jak używać powiadomień push w interfejsie Reseller API.

Przegląd

Interfejs Reseller API wykorzystuje interfejs Pub/Sub API do dostarczania powiadomień push o zdarzeniach związanych z subskrypcją Google Workspace. Możesz na przykład skonfigurować powiadomienia push, aby otrzymywać informacje o zmianach stanu subskrypcji klientów.

Wymagania wstępne

  • Włącz Pub/Sub API w projekcie w chmurze Google.
  • Przypisz do konta usługi w projekcie w chmurze role uprawnień Pub/Sub. Przyznanie roli roles/pubsub.editor jest zalecane, ale możesz użyć bardziej szczegółowych uprawnień Pub/Sub.

Tworzenie tematu

Aby utworzyć temat, zarejestruj się w interfejsie Reseller API za pomocą metody resellernotify.register. Ta metoda przyjmuje jako parametr adres e-mail konta usługi. Tylko konta usługi autoryzowane tą metodą mogą subskrybować Twój temat.

POST https://reseller.googleapis.com/apps/reseller/v1/resellernotify/register
{
  "serviceAccountEmailAddress": "reseller@reseller-project.iam.gserviceaccount.com"
}

Odpowiedź zakończona powodzeniem zwraca kod stanu HTTP 200 i odpowiedź w formacie JSON zawierającą nazwę tematu Pub/Sub.

Przykładowa odpowiedź:

{
  "topicName": "projects/partner-watch/topics/C0abcdefg"
}

Aby autoryzować więcej kont usługi, ponownie wywołaj funkcję resellernotify.register.

Cofanie dostępu konta usługi

Interfejs Reseller API może wyrejestrować konta usługi za pomocą punktu końcowego resellernotify.unregister:

POST https://reseller.googleapis.com/apps/reseller/v1/resellernotify/unregister
{
  "serviceAccountEmailAddress": "reseller@reseller-project.iam.gserviceaccount.com"
}

Subskrybowanie tematu

Po utworzeniu tematu Pub/Sub skonfiguruj sposób, w jaki aplikacja wykorzystuje zdarzenia zmiany. Wybierz jedną z tych opcji:

  • Subskrypcja push: podajesz wywołanie zwrotne HTTP POST. Pub/Sub używa tego wywołania zwrotnego, aby powiadamiać aplikację o nowych zdarzeniach.
  • Subskrypcja pull: aplikacja okresowo wykonuje wywołanie HTTP, aby pobrać zmiany w kolejce.

Przykładowe żądanie subskrypcji tematu:

PUT https://pubsub.googleapis.com/v1/projects/PROJECT/subscriptions/SUBSCRIPTION_NAME
{
  "topic": "TOPIC_NAME"
  // Only needed for push configurations
  "pushConfig": {
    "pushEndpoint": "PUSH_NOTIFICATION_ENDPOINT"
  },
}

Zastąp następujące elementy:

  • PROJECT: Twój projekt Google Cloud.
  • SUBSCRIPTION_NAME: Nazwa identyfikująca subskrypcję.
  • TOPIC_NAME: temat Pub/Sub utworzony wcześniej.
  • PUSH_NOTIFICATION_ENDPOINT: punkt końcowy obsługi powiadomień push.

Odpowiedź zakończona powodzeniem zwraca kod stanu HTTP 200. Przykładowa odpowiedź:

{
  "name": "projects/PROJECT/subscriptions/SUBSCRIPTION_NAME",
  "topic": "TOPIC_NAME",
  "pushConfig": {
    "pushEndpoint": "PUSH_NOTIFICATION_ENDPOINT"
    },
  "ackDeadlineSeconds": 10
}

Formaty powiadomień

Poniżej znajdziesz przykładowe powiadomienie Pub/Sub. Dane wiadomości to ciąg tekstowy JSON zakodowany w formacie Base64.

{
  "message": {
    "attributes": {},
    "data": "eyJza3VfaWQiOiAiR29vZ2xlLUFwcHMtVW5saW1pdGVkIiwgImV2ZW50X3R5cGUiOiAiU1VCU0NSSVBUSU9OX0NBTkNFTExFRCIsICJjdXN0b21lcl9kb21haW5fbmFtZSI6ICJkb21haW4uY29tIiwgInN1YnNjcmlwdGlvbl9pZCI6ICIxMjM0NTY3IiwgImN1c3RvbWVyX2lkIjogIkMwYWJjZGVmIiwgIm1lc3NhZ2VfaWQiOiAiODY3NTMwOSIsICJwdWJsaXNoX3RpbWUiOiB7InNlY29uZHMiOiAxNDU3NzMxODQ2LCAibmFub3MiOiAzNDkwMDAwMDB9LCAicmVzZWxsZXJfY3VzdG9tZXJfaWQiOiAiQzByZXNlbGxlciJ9",
    "message_id": 1234567891012131
  },
  "subscription": "projects/PROJECT/subscriptions/SUBSCRIPTION_NAME"
}

Przykład obiektu message.data po dekodowaniu:

{
  "customer_id": "C0abcdef",
  "customer_domain_name": "domain.com",
  "event_type": "SUBSCRIPTION_CANCELLED",
  "sku_id": "Google-Apps-Unlimited",
  "subscription_id": "1234567",
  // Optional fields dependent on event_type
  "subscription_suspension_reasons": [],
  "subscription_cancellation_reason": "REASON"
}

Typy zdarzeń

Możliwe typy zdarzeń:

  • NEW_SUBSCRIPTION_CREATED: Utworzono nową subskrypcję.
  • SUBSCRIPTION_TRIAL_ENDED: okres próbny subskrypcji zakończył się.
  • PRICE_PLAN_SWITCHED: klient zmienił abonament elastyczny na abonament roczny. To zdarzenie nie jest wywoływane, jeśli klient przechodzi z abonamentu rocznego na elastyczny w ramach odnowienia.
  • COMMITMENT_CHANGED: Zobowiązanie roczne zostało zwiększone lub zmniejszone.
  • SUBSCRIPTION_RENEWED: odnowiono subskrypcję roczną.
  • SUBSCRIPTION_SUSPENDED: subskrypcja jest zawieszona. Zobacz subscription_suspension_reasons.
  • SUBSCRIPTION_SUSPENSION_REVOKED: zawieszenie zostało cofnięte.
  • SUBSCRIPTION_CANCELLED: subskrypcja została anulowana. Zobacz subscription_cancellation_reason. Może też wykrywać przesiadki.
  • SUBSCRIPTION_CONVERTED: Subskrypcja została przekonwertowana. Przykłady:
    • Przekształć subskrypcję kupioną bezpośrednio w subskrypcję od sprzedawcy.
    • Przekształcanie płatnej subskrypcji w ofertę prolongaty.
    • Przekształć subskrypcję online w subskrypcję offline.
  • SUBSCRIPTION_UPGRADE: SKU subskrypcji zostało przełączone na wyższą wersję. Przykład: przechodzenie z Google Workspace Business Starter na Business Standard.
  • SUBSCRIPTION_DOWNGRADE: SKU objęty subskrypcją został przełączony na niższą subskrypcję. Przykład: Google Workspace Business Standard na Business Starter.
  • LICENSE_ASSIGNMENT_CHANGED: licencja została przypisana lub odebrana. Użyj tego parametru, aby śledzić zmiany liczby miejsc w przypadku subskrypcji elastycznych.

Powody anulowania subskrypcji

Pole Powód anulowania jest wypełniane, gdy wartość event_type to SUBSCRIPTION_CANCELLED. Możliwe przyczyny:

  • TRANSFERRED_OUT: klient został przeniesiony na płatności bezpośrednie lub do innego sprzedawcy.
  • PURCHASE_OF_SUBSUMING_SKU: klient przeszedł na kod SKU, który zastępuje inny. Przykład: klient korzystający z Google Workspace Business Starter i Vault przechodzi na Business Plus, która obejmuje Vault.
  • RESELLER_INITIATED: sprzedawca anulował subskrypcję.
  • OTHER: subskrypcja została anulowana z innego powodu.

Przyczyny zawieszenia subskrypcji

Przyczyna zawieszenia jest wypełniana, gdy event_type ma wartość SUBSCRIPTION_SUSPENDED. Możliwe przyczyny:

  • PENDING_TOS_ACCEPTANCE: klient nie zaakceptował Warunków korzystania z usługi Google Workspace w ramach odsprzedaży.
  • RENEWAL_WITH_TYPE_CANCEL: zobowiązanie klienta wygasło, a usługa została anulowana.
  • RESELLER_INITIATED: sprzedawca ręcznie zawiesił subskrypcję.
  • TRIAL_ENDED: okres próbny klienta wygasł bez wybrania planu innego niż próbny.
  • OTHER: klient został zawieszony z powodu wewnętrznego Google, np. nadużycia.

Ograniczenia Pub/Sub

Kolejność powiadomień push nie zawsze jest sekwencyjna. Wiadomości mogą być dostarczane wielokrotnie lub wcale. W przypadku zmienionych subskrypcji zalecamy używanie reseller.subscriptions.get, aby pobrać bieżący stan.