W tym dokumencie opisujemy, jak korzystać z powiadomień push informujących aplikację o zmianie zasobu.
Przegląd
Interfejs API pakietu Admin SDK udostępnia powiadomienia push, które umożliwiają monitorowanie zmian w zasobach. Dzięki tej funkcji możesz zwiększyć wydajność swojej aplikacji. Pozwala wyeliminować dodatkowe koszty sieci i obliczeniowe związane z zasobami odpytywania w celu określenia, czy się zmieniły. Po każdej zmianie obserwowanych zasobów interfejs Admin SDK API powiadomi o tym aplikację.
Aby korzystać z powiadomień push, musisz zrobić 2 rzeczy:
Skonfiguruj adres URL odbierania lub odbiornik wywołania zwrotnego „webhooka”.
Jest to serwer HTTPS obsługujący komunikaty z powiadomieniami interfejsu API, które są aktywowane po zmianie zasobu.
Skonfiguruj (kanał powiadomień) dla każdego punktu końcowego zasobu, który chcesz oglądać.
Kanał określa informacje dotyczące routingu wiadomości z powiadomieniami. Podczas konfigurowania kanału musisz określić adres URL, na który chcesz otrzymywać powiadomienia. Przy każdej zmianie zasobów kanału interfejs API pakietu Admin SDK wysyła na ten adres URL wiadomość z powiadomieniem jako żądanie
POST
.
Obecnie interfejs API pakietu Admin SDK obsługuje powiadomienia o zmianach w zasobie Activities (Działania).
Tworzenie kanałów powiadomień
Aby wysyłać żądania powiadomień push, musisz skonfigurować kanał powiadomień dla każdego zasobu, który chcesz monitorować. Po skonfigurowaniu kanałów powiadomień interfejs API pakietu Admin SDK informuje Twoją aplikację o zmianach w obserwowanych zasobach.
Wysyłaj prośby o zegarek
Każdy dostępny do obejrzenia zasób interfejsu API pakietu Admin SDK ma powiązaną metodę watch
w identyfikatorze URI w formacie:
https://www.googleapis.com/API_NAME/API_VERSION/RESOURCE_PATH/watch
Aby skonfigurować kanał powiadomień dla wiadomości o zmianach w określonym zasobie, wyślij żądanie POST
do metody watch
tego zasobu.
Każdy kanał powiadomień jest powiązany zarówno z konkretnym użytkownikiem, jak i z konkretnym zasobem (lub zbiorem zasobów). Żądanie watch
nie zostanie zrealizowane, chyba że bieżący użytkownik lub konto usługi jest właścicielem zasobu lub ma uprawnienia dostępu do niego.
Przykłady
Wszystkie prośby o obejrzenie dotyczące zasobu działań mają postać ogólną:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/userKey or all/applications/applicationName/watch Authorization: Bearer auth_token_for_current_user Content-Type: application/json { "id": "01234567-89ab-cdef-0123456789ab", // Your channel ID. "type": "web_hook", "address": "https://mydomain.com/notifications", // Your receiving URL. ... "token": "target=myApp-myFilesChannelDest", // (Optional) Your channel token. "payload": true, // (Optional) Whether to include the payload (message body) in notifications. "expiration": 3600 // (Optional) Your requested channel expiration time. }
Za pomocą parametrów userKey, applicationName, eventName
i filters
możesz otrzymywać powiadomienia tylko dotyczące określonych zdarzeń, użytkowników lub aplikacji.
Uwaga: dla jasności w poniższych przykładach pominięto treść żądania.
Obserwuj wszystkie działania administratora:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin/watch
Obserwuj wszystkie aktywności związane z dokumentami:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/docs/watch
Obserwuj aktywność administratora określonego użytkownika:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/liz@example.com/applications/admin/watch
Czekaj na określone zdarzenie, takie jak zmiana hasła użytkownika:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin/watch?eventName=CHANGE_PASSWORD
Obserwuj zmiany w określonym dokumencie:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/docs/watch?eventName=EDIT&filters==doc_id=123456abcdef
Właściwości wymagane
W przypadku każdego żądania watch
musisz wypełnić te pola:
-
Ciąg właściwości
id
jednoznacznie identyfikujący nowy kanał powiadomień w projekcie. Zalecamy użycie unikalnego identyfikatora uniwersalnego (UUID) lub podobnego unikalnego ciągu znaków. Maksymalna długość: 64 znaki.Ustawiona wartość identyfikatora jest powtarzana w nagłówku HTTP
X-Goog-Channel-Id
każdej wiadomości powiadomienia otrzymanej w związku z danym kanałem. -
Ciąg tekstowy właściwości
type
ustawiony na wartośćweb_hook
. -
Ciąg właściwości
address
ustawiony na URL, który nasłuchuje i odpowiada na powiadomienia z tego kanału powiadomień. To jest adres URL wywołania zwrotnego webhooka, który musi używać protokołu HTTPS.Pamiętaj, że interfejs API Admin SDK może wysyłać powiadomienia na ten adres HTTPS tylko wtedy, gdy na serwerze WWW jest zainstalowany prawidłowy certyfikat SSL. Nie prawidłowe certyfikaty to między innymi:
- podpisane samodzielnie,
- podpisane przez niezaufane źródło,
- unieważnione.
- Certyfikaty z podmiotem niezgodnym z docelową nazwą hosta.
Właściwości opcjonalne
W żądaniu watch
możesz też określić te opcjonalne pola:
-
Właściwość
token
, która określa wartość dowolnego ciągu znaków do użycia jako token kanału. Tokenów kanałów powiadomień możesz używać do różnych celów. Możesz na przykład użyć tokena, aby sprawdzić, czy każda wiadomość przychodząca jest przeznaczona dla kanału utworzonego przez Twoją aplikację (aby upewnić się, że powiadomienie nie jest próbą podszywania się) lub aby przekierować wiadomość do właściwego miejsca w aplikacji na podstawie przeznaczenia tego kanału. Maksymalna długość: 256 znaków.Token znajduje się w nagłówku HTTP
X-Goog-Channel-Token
w każdej wiadomości powiadomienia, którą aplikacja otrzymuje dla tego kanału.Jeśli używasz tokenów kanału powiadomień, zalecamy wykonanie tych czynności:
Użyj rozszerzonego formatu kodowania, np. parametrów zapytania w adresie URL. Przykład:
forwardTo=hr&createdBy=mobile
Nie podawaj danych wrażliwych, takich jak tokeny OAuth.
-
Ciąg właściwości
expiration
ustawiony na sygnaturę czasową uniksową (w milisekundach) daty i godziny, kiedy interfejs Admin SDK API ma przestać wysyłać komunikaty z tego kanału powiadomień.Jeśli kanał ma określony czas ważności, jest on podawany jako wartość nagłówka HTTP
X-Goog-Channel-Expiration
(w formacie zrozumiałym dla człowieka) w każdej wiadomości z powiadomieniem otrzymywanej przez aplikację dla tego kanału.
Więcej informacji o tym żądaniu znajdziesz w opisie metody watch
dla zasobu Activities (Działania) w dokumentacji interfejsu API.
Obejrzyj odpowiedź
Jeśli żądanie watch
utworzy kanał powiadomień, zwróci kod stanu HTTP 200 OK
.
Treść wiadomości odpowiedzi zegarka zawiera informacje o nowo utworzonym kanale powiadomień, jak pokazano w poniższym przykładzie.
{ "kind": "api#channel", "id": "reportsApiId", // ID you specified for this channel. "resourceId": "o3hgv1538sdjfh", // ID of the watched resource. "resourceUri": "https://admin.googleapis.com/admin/reports/v1/activity/userKey/applications/applicationName", // Version-specific ID of the watched resource. "token": "target=myApp-myFilesChannelDest", // Present only if one was provided. "expiration": 3600, // Actual expiration time as Unix timestamp (in ms), if applicable. }
Oprócz właściwości wysłanych w ramach żądania zwrócone informacje obejmują też resourceId
i resourceUri
pozwalające zidentyfikować zasób, który chcesz obserwować w tym kanale powiadomień.
Możesz przekazać zwrócone informacje do innych operacji w kanale powiadomień, na przykład kiedy chcesz przestać otrzymywać powiadomienia.
Więcej informacji o odpowiedzi znajdziesz w opisie metody watch
dla zasobu Activities (Działania) w dokumentacji interfejsu API.
Synchronizuj wiadomość
Gdy utworzysz kanał powiadomień w celu oglądania zasobu, interfejs Admin SDK API wysyła komunikat sync
informujący o rozpoczęciu powiadomień. Wartość nagłówka HTTP X-Goog-Resource-State
dla tych wiadomości to sync
. Ze względu na problemy z czasem sieci możesz otrzymać komunikat sync
jeszcze przed otrzymaniem odpowiedzi metody watch
.
Możesz bezpiecznie zignorować powiadomienie sync
, ale możesz też z niego skorzystać. Jeśli na przykład zdecydujesz, że nie chcesz zachować kanału, możesz użyć wartości X-Goog-Channel-ID
i X-Goog-Resource-ID
w wywołaniu, aby przestać otrzymywać powiadomienia. Możesz też użyć powiadomienia sync
, aby przeprowadzić inicjalizację, aby przygotować się na późniejsze zdarzenia.
Poniżej znajdziesz format komunikatów sync
, które interfejs API Admin SDK wysyła na adres URL odbiorcy.
POST https://mydomain.com/notifications // Your receiving URL. X-Goog-Channel-ID: channel-ID-value X-Goog-Channel-Token: channel-token-value X-Goog-Channel-Expiration: expiration-date-and-time // In human-readable format. Present only if the channel expires. X-Goog-Resource-ID: identifier-for-the-watched-resource X-Goog-Resource-URI: version-specific-URI-of-the-watched-resource X-Goog-Resource-State: sync X-Goog-Message-Number: 1
Wiadomości synchronizacji mają zawsze wartość nagłówka HTTP X-Goog-Message-Number
o wartości 1
. Każde kolejne powiadomienie z tego kanału ma numer wiadomości większy od poprzedniego, przy czym numery wiadomości nie są ułożone kolejne.
Odnów kanały powiadomień
Kanał powiadomień może mieć czas wygaśnięcia. Wartość może być określana na podstawie żądania lub dowolnych wewnętrznych limitów interfejsu API Admin SDK bądź wartości domyślnych (stosowana jest bardziej restrykcyjna wartość). Czas wygaśnięcia kanału, jeśli go ma, jest podawany jako sygnatura czasowa uniksowa (w milisekundach) w informacjach zwracanych przez metodę watch
. Dodatkowo data i godzina wygaśnięcia są podawane (w formacie czytelnym dla człowieka) w każdej wiadomości powiadomienia odbieranej przez aplikację dla danego kanału w nagłówku HTTP X-Goog-Channel-Expiration
.
Obecnie nie ma możliwości automatycznego odnowienia kanału powiadomień. Gdy kanał zbliża się do wygaśnięcia, musisz zastąpić go nowym, wywołując metodę watch
. Jak zawsze musisz użyć unikalnej wartości właściwości id
nowego kanału. Zwróć uwagę, że w przypadku aktywnych kanałów powiadomień dotyczących tego samego zasobu może wystąpić okres „nakładanie się”.
Odbieranie powiadomień
Po każdej zmianie obserwowanego zasobu aplikacja otrzyma powiadomienie z opisem tej zmiany. Interfejs API pakietu Admin SDK wysyła te komunikaty jako żądania HTTPS POST
na adres URL podany przez Ciebie jako usługa address
dla tego kanału powiadomień.
Interpretowanie formatu wiadomości z powiadomieniem
Wszystkie wiadomości z powiadomieniami zawierają zestaw nagłówków HTTP z prefiksami X-Goog-
.
Niektóre typy powiadomień mogą też zawierać treść wiadomości.
nagłówków,
Komunikaty z powiadomieniami publikowane przez interfejs API pakietu Admin SDK na odbierany adres URL zawierają te nagłówki HTTP:
Nagłówek | Opis |
---|---|
Zawsze obecne | |
|
Identyfikator UUID lub inny unikalny ciąg podany przez Ciebie, aby zidentyfikować ten kanał powiadomień. |
|
Liczba całkowita identyfikująca tę wiadomość w kanale powiadomień. W przypadku sync wiadomości wartość to zawsze 1 . Każda kolejna wiadomość na kanale zwiększa liczbę wiadomości, ale nie jedna po drugiej. |
|
Nieprzejrzysta wartość identyfikująca obserwowany zasób. Ten identyfikator jest stabilny we wszystkich wersjach interfejsu API. |
|
Nowy stan zasobu, który wywołał powiadomienie.
Możliwe wartości: sync lub nazwa zdarzenia.
|
|
Identyfikator wersji interfejsu API obserwowanego zasobu. |
Czasami obecne | |
|
Data i godzina wygaśnięcia kanału powiadomień podane w formacie zrozumiałym dla człowieka. Widoczny tylko wtedy, gdy został zdefiniowany. |
|
Token kanału powiadomień ustawiony przez Twoją aplikację, którego możesz użyć do zweryfikowania źródła powiadomień. Widoczny tylko wtedy, gdy został zdefiniowany. |
Powiadomienia dotyczące działań zawierają w treści te informacje:
Właściwość | Opis |
---|---|
kind |
Identyfikuje go jako zasób aktywności. Wartość: ustalony ciąg znaków „admin#reports#activity ”. |
id |
Unikalny identyfikator rekordu aktywności. |
id.time |
Czas wystąpienia działania. Wartość jest podana w formacie daty i godziny ISO 8601. Czas to pełna data z liczbą godzin, minut i sekund w formacie RRRR-MM-DDTgg:mm:ssTZD. Na przykład 2010-04-05T17:30:04+01:00. |
id.uniqueQualifier |
Unikalny kwalifikator, jeśli wiele zdarzeń wystąpiło w tym samym czasie. |
id.applicationName |
Nazwa aplikacji, do której należy zdarzenie. Możliwe wartości: |
id.customerId |
Niepowtarzalny identyfikator konta Google Workspace. |
actor |
Użytkownik wykonujący działanie. |
actor.callerType |
Rodzaj autora, który wykonał czynność wymienioną w raporcie. W tej wersji interfejsu API callerType to żądanie jednostki USER lub OAuth 2LO, które wykonały działanie wymienione w raporcie . |
actor.email |
Podstawowy adres e-mail użytkownika, którego aktywność jest zgłaszana. |
actor.profileId |
Unikalny identyfikator profilu Google Workspace użytkownika. |
ownerDomain |
Domena konsoli administracyjnej lub właściciela dokumentu w aplikacji Dokumenty. Jest to domena, której dotyczy zdarzenie raportu. |
ipAddress |
Adres IP użytkownika wykonującego działanie. Jest to adres IP użytkownika podczas logowania się w Google Workspace, który może, ale nie musi, odzwierciedlać jego fizyczną lokalizację. Na przykład adres IP może być adresem serwera proxy użytkownika lub wirtualnej sieci prywatnej (VPN). Interfejs API obsługuje protokoły IPv4 i IPv6. |
events[] |
Zdarzenia aktywności w raporcie. |
events[].type |
Typ zdarzenia. Usługa lub funkcja Google Workspace, którą zmieni administrator, jest określana we właściwości type . Pozwala ona identyfikować zdarzenie za pomocą właściwości eventName . |
events[].name |
Nazwa zdarzenia. Jest to konkretna nazwa aktywności zgłaszanej przez interfejs API. Każdy element eventName jest powiązany z konkretną usługą lub funkcją Google Workspace, którą interfejs API podzieli na typy zdarzeń.
Ogólnie w przypadku parametrów żądania eventName :
|
events[].parameters[] |
Pary wartości parametrów dla różnych aplikacji. |
events[].parameters[].name |
Nazwa parametru. |
events[].parameters[].value |
Wartość parametru. |
events[].parameters[].intValue |
Liczba całkowita dla parametru. |
events[].parameters[].boolValue |
Wartość logiczna parametru. |
Przykłady
Powiadomienia o zdarzeniach związanych z zasobem aktywności mają postać:
POST https://mydomain.com/notifications // Your receiving URL. Content-Type: application/json; utf-8 Content-Length: 0 X-Goog-Channel-ID: reportsApiId X-Goog-Channel-Token: 398348u3tu83ut8uu38 X-Goog-Channel-Expiration: Tue, 29 Oct 2013 20:32:02 GMT X-Goog-Resource-ID: ret08u3rv24htgh289g X-Goog-Resource-URI: https://admin.googleapis.com/admin/reports/v1/activity/userKey/applications/applicationName X-Goog-Resource-State: eventName X-Goog-Message-Number: 10 { "kind": "admin#reports#activity", "id": { "time": datetime, "uniqueQualifier": long, "applicationName": string, "customerId": string }, "actor": { "callerType": string, "email": string, "profileId": long }, "ownerDomain": string, "ipAddress": string, "events": [ { "type": string, "name": string, "parameters": [ { "name": string, "value": string, "intValue": long, "boolValue": boolean } ] } ] }
Przykład działania administratora:
POST https://mydomain.com/notifications // Your receiving URL. Content-Type: application/json; utf-8 Content-Length: 596 X-Goog-Channel-ID: reportsApiId X-Goog-Channel-Token: 245t1234tt83trrt333 X-Goog-Channel-Expiration: Tue, 29 Oct 2013 20:32:02 GMT X-Goog-Resource-ID: ret987df98743md8g X-Goog-Resource-URI: https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin?alt=json X-Goog-Resource-State: CREATE_USER X-Goog-Message-Number: 23 { "kind": "admin#reports#activity", "id": { "time": "2013-09-10T18:23:35.808Z", "uniqueQualifier": "-0987654321", "applicationName": "admin", "customerId": "ABCD012345" }, "actor": { "callerType": "USER", "email": "admin@example.com", "profileId": "0123456789987654321" }, "ownerDomain": "apps-reporting.example.com", "ipAddress": "192.0.2.0", "events": [ { "type": "USER_SETTINGS", "name": "CREATE_USER", "parameters": [ { "name": "USER_EMAIL", "value": "liz@example.com" } ] } ] }
Odpowiedz na powiadomienia
Aby pokazać, że powodzenie, możesz zwrócić dowolny z tych kodów stanu: 200
, 201
, 202
, 204
lub 102
.
Jeśli Twoja usługa korzysta z biblioteki klienta interfejsów API Google i zwraca 500
, 502
, 503
lub 504
, interfejs API Admin SDK ponawia próbę z wykładniczym czasem ponowienia.
Każdy inny kod stanu zwrotu jest uznawany za niepowodzenie wiadomości.
Omówienie zdarzeń powiadomień interfejsu API pakietu Admin SDK
Ta sekcja zawiera szczegółowe informacje o wiadomościach z powiadomieniami, które możesz otrzymywać podczas korzystania z powiadomień push za pomocą interfejsu Admin SDK API.
Powiadomienia push z interfejsu Reports API zawierają 2 rodzaje wiadomości: wiadomości o synchronizowaniu i powiadomienia o zdarzeniach. Typ wiadomości jest podany w nagłówku HTTP X-Goog-Resource-State
. Możliwe wartości powiadomień o zdarzeniach są takie same jak w przypadku metody activities.list
. Każda aplikacja ma unikalne zdarzenia:
Zatrzymaj powiadomienia
Właściwość expiration
określa, kiedy powiadomienia mają się automatycznie zatrzymać. Możesz zrezygnować z otrzymywania powiadomień z konkretnego kanału, zanim straci ważność, wywołując metodę stop
pod tym identyfikatorem URI:
https://www.googleapis.com/admin/reports_v1/channels/stop
Ta metoda wymaga podania co najmniej właściwości id
i resourceId
kanału, jak pokazano w poniższym przykładzie. Pamiętaj, że jeśli interfejs API pakietu Admin SDK ma kilka typów zasobów z metodami watch
, jest tylko 1 metoda stop
.
Tylko użytkownicy z odpowiednimi uprawnieniami mogą zablokować kanał. W szczególności:
- Jeśli kanał został utworzony przy użyciu zwykłego konta użytkownika, tylko ten sam użytkownik tego samego klienta (identyfikowany za pomocą identyfikatorów klienta OAuth 2.0 w tokenach uwierzytelniania), który utworzył kanał, może go zatrzymać.
- Jeśli kanał został utworzony przy użyciu konta usługi, może go zatrzymać każdy użytkownik korzystający z tego samego klienta.
Z tego przykładowego kodu dowiesz się, jak przestać otrzymywać powiadomienia:
POST https://www.googleapis.com/admin/reports_v1/channels/stop Authorization: Bearer CURRENT_USER_AUTH_TOKEN Content-Type: application/json { "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a66", "resourceId": "ret08u3rv24htgh289g" }