Powiadomienia push

Przegląd

Interfejs Reseller API wykorzystuje interfejs Pub/Sub API do dostarczania powiadomień push o różnych 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 Google Cloud.
  • Przyznaj kontu usługi w projekcie w Cloud role uprawnień Pub/Sub. Przyznanie roli roles/pubsub.editor to dobre rozwiązanie (proste i niezbyt szerokie), ale możesz użyć bardziej szczegółowych uprawnień Pub/Sub.

Tworzenie tematu

Aby utworzyć temat, musisz zarejestrować się w interfejsie Reseller API za pomocą metody resellernotify.register. Metoda resellernotify.register przyjmuje jako parametr adres e-mail konta usługi. Tylko konta usługi autoryzowane tą metodą mogą subskrybować nowo utworzony 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.

Oto przykładowa odpowiedź:

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

Aby autoryzować dodatkowe konta usługi do korzystania z tematu, możesz ponownie wywołać funkcję resellernotify.register.

Cofanie dostępu konta usługi

Interfejs Reseller API umożliwia też wyrejestrowanie kont 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 musisz skonfigurować sposób, w jaki aplikacja będzie wykorzystywać 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 wysyła wywołanie HTTP, aby pobrać wszystkie zmiany w kolejce.

Oto 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: utworzony wcześniej temat Pub/Sub.
  • PUSH_NOTIFICATION_ENDPOINT: punkt końcowy obsługi powiadomień push.

Pomyślna odpowiedź zwraca kod stanu HTTP 200. Oto 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 są przesyłane jako ciąg tekstowy JSON zakodowany w formacie Base64.

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

Oto 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 depended on event_type
  "subscription_suspension_reasons": [],
  "subscription_cancellation_reason": "REASON"
}

Typy zdarzeń

Poniżej znajdziesz listę wszystkich możliwych typów 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 roczny. To zdarzenie nie jest wywoływane, jeśli klient przejdzie z abonamentu ze zobowiązaniem na abonament 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. Sprawdź pole subscription_suspension_reasons.
  • SUBSCRIPTION_SUSPENSION_REVOKED: zawieszenie zostało cofnięte w przypadku wcześniej zawieszonej subskrypcji.
  • SUBSCRIPTION_CANCELLED: subskrypcja została anulowana. Sprawdź pole subscription_cancellation_reason. Może też służyć do wykrywania przelewów.
  • SUBSCRIPTION_CONVERTED: subskrypcja została przekonwertowana. Oto kilka przykładów, w których może wystąpić to zdarzenie:

    • Przekształć subskrypcję bezpośrednią w subskrypcję 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ę. Na przykład subskrypcja została uaktualniona z Google Workspace Business Starter do Business Standard.

  • SUBSCRIPTION_DOWNGRADE: SKU objęty subskrypcją został zmieniony na niższą wersję. Na przykład subskrypcja została zmieniona z Google Workspace Business Standard na Business Starter.

  • LICENSE_ASSIGNMENT_CHANGED: Licencja została przypisana do użytkownika lub odebrana użytkownikowi. Za pomocą tego zdarzenia możesz reaktywnie śledzić zmiany liczby miejsc w przypadku subskrypcji elastycznych.

Powody anulowania subskrypcji

Powód anulowania subskrypcji jest wypełniany, gdy event_type ma wartość SUBSCRIPTION_CANCELLED. Możliwe przyczyny anulowania:

  • TRANSFERRED_OUT: klient przeszedł na płatności bezpośrednie lub do innego sprzedawcy.
  • PURCHASE_OF_SUBSUMING_SKU: klient przeszedł na kod SKU, który zastępuje inny. Jeśli na przykład klient korzystający z Google Workspace Business Starter i Google Vault przejdzie na Google Workspace Business Plus, subskrypcja Vault zostanie wchłonięta, ponieważ jest częścią Google Workspace Business Plus.
  • RESELLER_INITIATED: sprzedawca anulował subskrypcję.
  • OTHER: subskrypcja została anulowana z innego powodu niż wymienione.

Przyczyny zawieszenia subskrypcji

Przyczyna zawieszenia subskrypcji jest podawana, gdy event_type jest SUBSCRIPTION_SUSPENDED. Możliwe przyczyny zawieszenia:

  • PENDING_TOS_ACCEPTANCE: klient nie zalogował się i nie zaakceptował Warunków korzystania z usług Google Workspace w ramach odsprzedaży.
  • RENEWAL_WITH_TYPE_CANCEL: zobowiązanie klienta wygasło, a usługa została anulowana z końcem okresu zobowiązania.
  • RESELLER_INITIATED: sprzedawca ręcznie zawiesił subskrypcję.
  • TRIAL_ENDED: okres próbny klienta wygasł, a klient nie wybrał abonamentu innego niż próbny.
  • OTHER: klient został zawieszony z powodu wewnętrznego Google, np. nadużycia.

Ograniczenia Pub/Sub

Kolejność powiadomień push nie jest gwarantowana. Wiadomości mogą być dostarczane wielokrotnie, a w ekstremalnych sytuacjach wcale. Zalecamy używanie reseller.subscriptions.get w przypadku wszystkich zmienionych subskrypcji, aby pobrać bieżący stan.