Powiadomienia push

Omówienie

Interfejs Reseller API korzysta z interfejsu Pub/Sub API do dostarczania powiadomień push o różnych zdarzeniach dotyczących subskrypcji Google Workspace. Możesz na przykład skonfigurować powiadomienia push, aby otrzymywać powiadomienia o zmianach stanu subskrypcji klientów.

Wymagania wstępne

  • Włącz interfejs Pub/Sub API w projekcie Google Cloud.
  • Przypisz do konta usługi w projekcie Cloud role uprawnień Pub/Sub. Przyznanie roli roles/pubsub.editor to dobry kompromis (łatwe i niezbyt ogólne rozwiązanie), ale możesz też użyć bardziej szczegółowych uprawnień Pub/Sub.

Tworzenie tematu

Aby utworzyć temat, musisz zarejestrować się w interfejsie Reseller API, korzystając z metody resellernotify.register. Metoda resellernotify.register przyjmuje jako parametr adres e-mail konta usługi. Do subskrybowania nowo utworzonego tematu mogą być autoryzowane tylko konta usługi autoryzowane tą metodą.

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

Pomyślna odpowiedź zwraca kod stanu HTTP 200oraz odpowiedź JSON zawierająca nazwę tematu Pub/Sub.

Oto przykład odpowiedzi:

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

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

Odmowa dostępu kontu usługi

Interfejs Reseller API umożliwia też wyrejestrowanie kont usług 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 ma obsługiwać zdarzenia zmiany. Wybierz jedną z tych opcji:

  • Subskrypcja push: podajesz wywołanie zwrotne HTTP POST. Pub/Sub używa tego wywołania zwrotnego, aby powiadomić aplikację o nowych zdarzeniach.
  • Subskrypcja pobierania: aplikacja okresowo wysyła żądanie HTTP, aby pobrać wszystkie zmiany oczekujące w kolejce.
.

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

Pomyślna odpowiedź zwraca kod stanu HTTP 200. Oto przykład odpowiedzi: 

{
  "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: subskrypcja została wykupiona po okresie próbnym.
  • PRICE_PLAN_SWITCHED: klient przeszedł z abonamentu elastycznego na abonament roczny. To zdarzenie nie jest wywoływane, jeśli klient w ramach odnowienia przejdzie z abonamentu ze zobowiązaniem na abonament elastyczny.
  • COMMITMENT_CHANGED: zwiększono lub zmniejszono roczne zobowiązanie.
  • SUBSCRIPTION_RENEWED: subskrypcja roczna została odnowiona.
  • SUBSCRIPTION_SUSPENDED: subskrypcja jest zawieszona. Zapoznaj się z polem subscription_suspension_reasons.
  • SUBSCRIPTION_SUSPENSION_REVOKED: zawieszenie zostało anulowane w przypadku wcześniej zawieszonego abonamentu.
  • SUBSCRIPTION_CANCELLED: subskrypcja została anulowana. Zapoznaj się z polem subscription_cancellation_reason. Może też służyć do wykrywania transferów.

  • SUBSCRIPTION_CONVERTED: subskrypcja została przekonwertowana. Oto kilka przykładowych przypadków użycia tego zdarzenia:

    • Przekształcanie subskrypcji bezpośredniej w subskrypcję sprzedawcy
    • Przekształcanie płatnej subskrypcji w ofertę prolongaty.
    • Przekształcanie subskrypcji online w subskrypcję offline.

  • SUBSCRIPTION_UPGRADE: kod SKU subskrypcji został przeniesiony na wyższą wersję. Na przykład subskrypcja została przeniesiona z Google Workspace Business Starter na Business Standard.

  • SUBSCRIPTION_DOWNGRADE: obniżono poziom subskrypcji. Na przykład subskrypcja została obniżona z Google Workspace Business Standard do Business Starter.

  • LICENSE_ASSIGNMENT_CHANGED: licencja została przypisana do użytkownika lub jej odebranie zostało anulowane. Zdarzenia tego typu możesz używać do reaktywnego śledzenia zmian liczby miejsc w przypadku subskrypcji elastycznych.

Powody anulowania subskrypcji

Przyczyna anulowania subskrypcji jest wypełniana, gdy event_type to SUBSCRIPTION_CANCELLED. Możliwe przyczyny anulowania:

  • TRANSFERRED_OUT: klient został przeniesiony do płatności bezpośrednich lub do innego sprzedawcy.
  • PURCHASE_OF_SUBSUMING_SKU: klient uaktualnił SKU, które zastępuje inne. 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 włączona, ponieważ jest ona uwzględniona w Google Workspace Business Plus.
  • RESELLER_INITIATED: sprzedawca anulował subskrypcję.
  • OTHER: subskrypcja została anulowana z innego powodu.

Powody zawieszenia subskrypcji

Przyczyna zawieszenia subskrypcji jest wypełniana, gdy event_type to SUBSCRIPTION_SUSPENDED. Możliwe przyczyny zawieszenia:

  • PENDING_TOS_ACCEPTANCE: klient nie zalogował się i nie zaakceptował Warunków korzystania z usługi Google Workspace Resold.
  • RENEWAL_WITH_TYPE_CANCEL: zobowiązanie klienta dobiegło końca, a usługa została anulowana po zakończeniu okresu obowiązywania umowy.
  • RESELLER_INITIATED: sprzedawca ręcznie zawiesił subskrypcję.
  • TRIAL_ENDED: okres próbny klienta wygasł, a klient nie wybrał abonamentu bez okresu próbnego.
  • OTHER: konto klienta zostało zawieszone z wewnętrznych powodów Google, np. z powodu nadużycia.

Ograniczenia Pub/Sub

Kolejność powiadomień push nie jest gwarantowana. Wiadomości mogą być dostarczane wielokrotnie, a w skrajnych przypadkach wcale. Zalecamy użycie parametru reseller.subscriptions.get we wszystkich zmienionych subskrypcjach, aby pobrać bieżący stan.