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ź polesubscription_suspension_reasons
.SUBSCRIPTION_SUSPENSION_REVOKED
: zawieszenie zostało cofnięte w przypadku wcześniej zawieszonej subskrypcji.SUBSCRIPTION_CANCELLED
: subskrypcja została anulowana. Sprawdź polesubscription_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.