Powiadomienia push

Przegląd

Interfejs Seller API używa interfejsu Pub/Sub API do dostarczania powiadomień push o różnych zdarzeniach subskrypcji Google Workspace. Możesz na przykład skonfigurować powiadomienia push, aby otrzymywać informacje o zmianach stanu subskrypcji swoich klientów.

Wymagania wstępne

• Włącz w projekcie Google Cloud interfejs Pub/Sub API.
• Przypisz role uprawnień Pub/Sub do konta usługi w projekcie Cloud. Przypisanie roli roles/pubsub.editor to dobry kompromis (prosty i niezbyt szeroki), ale warto użyć bardziej konkretnych uprawnień Pub/Sub.

Tworzenie tematu

Aby utworzyć temat, musisz zarejestrować się w interfejsie Seller API, korzystając z metody resellernotify.register. Metoda resellernotify.register wykorzystuje adres e-mail konta usługi jako parametr. Tylko konta usługi autoryzowane przy użyciu tej metody mogą subskrybować Twój nowo utworzony temat.

POST https://reseller.googleapis.com/apps/reseller/v1/resellernotify/register
{
  "serviceAccountEmailAddress": "[e-mail]"
}

Pomyślna odpowiedź zwraca kod stanu HTTP 200 i odpowiedź 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ć metodę resellernotify.register.

Anulowanie dostępu konta usługi

Interfejs Seller 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": "[e-mail]"
}

Subskrybowanie tematu

Po utworzeniu tematu Pub/Sub musisz skonfigurować sposób wykorzystania przez aplikację zdarzeń zmiany. Wybierz jedną z tych opcji:

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

Uwaga: aby wysłać to żądanie, musisz użyć klienta Pub/Sub i uwierzytelnić się za pomocą jednego z kont usługi zarejestrowanych w poprzednim kroku. Więcej informacji znajdziesz w sekcji Subskrybent.

Oto przykładowa prośba o zasubskrybowanie 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 Twoją subskrypcję.
• TOPIC_NAME: utworzony wcześniej temat Pub/Sub.
• PUSH_NOTIFICATION_ENDPOINT: punkt końcowy modułu 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 w postaci ciągu znaków JSON zakodowanego w formacie base64.

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

Oto przykładowy obiekt message.data po zdekodowaniu:

{
  "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ższa lista zawiera wszystkie możliwe typy zdarzeń:

• NEW_SUBSCRIPTION_CREATED: utworzono nową subskrypcję.
• SUBSCRIPTION_TRIAL_ENDED: zakończył się okres próbny subskrypcji.
• PRICE_PLAN_SWITCHED: klient przeszedł z abonamentu elastycznego na abonament roczny. To zdarzenie nie jest wywoływane, jeśli w ramach odnowienia klient przejdzie z abonamentu opartego na zobowiązaniach na abonament elastyczny.
• COMMITMENT_CHANGED: roczne zobowiązanie zostało zwiększone lub zmniejszone.
• SUBSCRIPTION_RENEWED: subskrypcja roczna została odnowiona.
• SUBSCRIPTION_SUSPENDED: subskrypcja została zawieszona. Zobacz pole subscription_suspension_reasons.
• SUBSCRIPTION_SUSPENSION_REVOKED: zawieszenie subskrypcji, która została wcześniej zawieszona, zostało odwołane.
• SUBSCRIPTION_CANCELLED: subskrypcja została anulowana. Zobacz pole subscription_cancellation_reason. Może też służyć do wykrywania transferów.

• SUBSCRIPTION_CONVERTED: subskrypcja została przekonwertowana. Oto kilka przykładów tego zdarzenia:

  • Zmień subskrypcję bezpośrednią na subskrypcję sprzedawcy.
  • Przekształć płatną subskrypcję na ofertę z odroczoną płatnością.
  • Przekonwertuj subskrypcję online na subskrypcję offline.

• SUBSCRIPTION_UPGRADE: przeszedłeś na wyższą wersję SKU subskrypcji. Na przykład przenieśliśmy subskrypcję z Google Workspace Business Starter na Business Standard.

• SUBSCRIPTION_DOWNGRADE: kod SKU subskrypcji został obniżony. np. zmieniono subskrypcję z Google Workspace Business Standard na wersję Business Starter.

• LICENSE_ASSIGNMENT_CHANGED: licencja została przypisana użytkownikowi lub mu odebrana. Możesz użyć tego zdarzenia do reaktywnego śledzenia zmian liczby stanowisk w przypadku subskrypcji elastycznych.

Powody anulowania subskrypcji

Powód anulowania subskrypcji jest podawany, gdy event_type ma wartość SUBSCRIPTION_CANCELLED. Oto możliwe przyczyny anulowania:

• TRANSFERRED_OUT: klient przeszedł na rozliczenia bezpośrednie lub do innego sprzedawcy.
• PURCHASE_OF_SUBSUMING_SKU: klient przeszedł na SKU, który zastępuje inny kod SKU. 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 podliczona, ponieważ jest dostępna w Google Workspace Business Plus.
• RESELLER_INITIATED: sprzedawca anulował subskrypcję.
• OTHER: subskrypcja została anulowana z innego powodu niż podano na liście.

Przyczyny zawieszenia subskrypcji

Powód zawieszenia subskrypcji jest podawany, gdy event_type ma wartość SUBSCRIPTION_SUSPENDED. Oto możliwe przyczyny zawieszenia:

• PENDING_TOS_ACCEPTANCE: klient nie zalogował się i nie zaakceptował Warunków sprzedaży Google Workspace.
• RENEWAL_WITH_TYPE_CANCEL: zobowiązanie klienta zakończyło się, a jego usługa została anulowana z końcem umowy.
• RESELLER_INITIATED: sprzedawca ręcznie zawiesił subskrypcję.
• TRIAL_ENDED: okres próbny klienta dobiegł końca, a klient nie wybrał abonamentu innego niż okres próbny.
• OTHER: klient został zawieszony z powodów wewnętrznych Google, na przykład wskutek nadużycia.

Ograniczenia Pub/Sub

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