W tym dokumencie opisujemy, jak korzystać z powiadomień push, które informują aplikację o zmianie zasobu.
Opis
Interfejs API pakietu Admin SDK udostępnia powiadomienia push, które umożliwiają monitorowanie zmian w zasobach. Możesz użyć tej funkcji, aby poprawić wydajność swojej aplikacji. Pozwala wyeliminować dodatkowe koszty sieci i mocy obliczeniowej związane z zasobami odpytywania w celu określenia, czy się zmieniły. Po każdej zmianie obserwowanego zasobu interfejs API pakietu Admin SDK powiadamia aplikację.
Aby korzystać z powiadomień push, musisz zrobić 2 rzeczy:
Skonfiguruj odbierany URL lub odbiornik wywołania zwrotnego „webhooka”.
Jest to serwer HTTPS obsługujący wiadomości z powiadomieniami interfejsu API wywoływane w przypadku zmiany zasobu.
Skonfiguruj kanał powiadomień dla każdego punktu końcowego zasobu, który chcesz oglądać.
Kanał określa informacje routingu dla wiadomości z powiadomieniami. Podczas konfigurowania kanału musisz określić adres URL, pod którym chcesz otrzymywać powiadomienia. Za każdym razem, gdy zasób kanału się zmieni, 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 poprosić o powiadomienia 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 dotyczących obserwowanych zasobów.
Wysyłaj prośby o zegarek
Każdy dostępny do obejrzenia zasób interfejsu Admin SDK API ma powiązaną metodę watch
pod identyfikatorem URI w tej formie:
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 konkretnym zasobem (lub zbiorem zasobów). Żądanie watch
nie zostanie zrealizowane, jeśli bieżący użytkownik lub konto usługi nie jest właścicielem zasobu lub ma uprawnienia dostępu do niego.
Przykłady
Wszystkie prośby o obejrzenie zasobu dotyczące 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. }
Parametrów userKey, applicationName, eventName
i filters
możesz używać, aby otrzymywać powiadomienia dotyczące tylko określonych zdarzeń, użytkowników lub aplikacji.
Uwaga: w podanych niżej przykładach pominięto treść żądania, aby była bardziej przejrzysta.
Obserwuj wszystkie działania administratora:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin/watch
Szukaj wszystkich działań związanych z dokumentami:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/docs/watch
Obserwuj aktywność administratora konkretnego użytkownika:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/liz@example.com/applications/admin/watch
Sprawdź, czy wystąpiło 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
Szukaj zmian 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 niepowtarzalnego identyfikatora uniwersalnego (UUID) lub innego podobnego unikalnego ciągu znaków. Maksymalna długość: 64 znaki.Ustawiona wartość identyfikatora jest odczytywana w nagłówku HTTP
X-Goog-Channel-Id
każdej wiadomości powiadomienia otrzymanej w związku z tym kanałem. -
Ciąg tekstowy właściwości
type
ustawiony na wartośćweb_hook
. -
Ciąg właściwości
address
ustawiony na adres 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 pakietu 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, który nie jest zgodny 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 dowolną wartość ciągu znaków do użycia jako token kanału. Tokenów kanału 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 pochodzi z kanału utworzonego przez Twoją aplikację – i upewnić się, że powiadomienie nie jest sfałszowana – lub do kierowania wiadomości do właściwego miejsca w aplikacji zgodnie z przeznaczeniem 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 otrzyma z tego kanału.Jeśli używasz tokenów kanału powiadomień, zalecamy wykonanie tych czynności:
Użyj rozszerzalnego 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 sygnatura czasowa uniksowa (w milisekundach) daty i godziny, kiedy interfejs API Admin SDK 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 czytelnym dla człowieka) w każdej wiadomości powiadomienia o danym kanale, którą aplikacja otrzymuje.
Więcej informacji o żądaniu znajdziesz w opisie metody watch
dotyczącej zasobu Activities (Działania) w dokumentacji interfejsu API.
Obejrzyj odpowiedź
Jeśli żądanie watch
utworzy kanał powiadomień, zwraca kod stanu HTTP 200 OK
.
Treść wiadomości odpowiedzi na zegarek zawiera informacje o nowo utworzonym kanale powiadomień, tak jak w tym 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 zwracane informacje obejmują też resourceId
i resourceUri
identyfikujące zasób, który chcesz obserwować na tym kanale powiadomień.
Zwrócone informacje możesz przekazywać do innych operacji związanych z kanałem powiadomień, na przykład wtedy, gdy 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ń, aby oglądać zasób, interfejs Admin SDK API wysyła komunikat sync
informujący o tym, że powiadomienia są uruchamiane. Wartość nagłówka HTTP X-Goog-Resource-State
dla tych wiadomości to sync
. Ze względu na problemy z czasem działania sieci możesz otrzymać komunikat sync
jeszcze przed otrzymaniem odpowiedzi metody watch
.
Powiadomienie sync
możesz bez obaw zignorować, ale możesz też go użyć. 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 pakietu Admin SDK wysyła na Twój adres URL odbierania.
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 będą ułożone jedna po drugiej.
Odnów kanały powiadomień
Kanał powiadomień może mieć określony czas ważności, którego wartość zależy od żądania lub przez dowolne wewnętrzne limity interfejsu API pakietu Admin SDK lub wartości domyślne (stosowana jest bardziej restrykcyjna wartość). Czas wygaśnięcia kanału, jeśli taki istnieje, jest uwzględniany w informacjach zwracanych przez metodę watch
jako sygnatura czasowa uniksowa (w milisekundach). Dodatkowo data i godzina wygaśnięcia są podawane (w formacie czytelnym dla człowieka) w każdej wiadomości powiadomienia, którą aplikacja otrzymuje dla danego kanału, w nagłówku HTTP X-Goog-Channel-Expiration
.
Obecnie nie ma możliwości automatycznego odnowienia kanału powiadomień. Gdy kończy się okres ważności kanału, musisz go zastąpić nowym, wywołując metodę watch
. Jak zawsze musisz użyć unikalnej wartości właściwości id
nowego kanału. Pamiętaj, że w fazie „nakładanie się” może wystąpić sytuacja, gdy aktywne są 2 kanały powiadomień dotyczące tego samego zasobu.
Odbieranie powiadomień
Po każdej zmianie obserwowanego zasobu aplikacja otrzymuje powiadomienie z opisem zmiany. Interfejs API pakietu Admin SDK wysyła te wiadomości jako żądania HTTPS POST
na adres URL podany jako właściwość 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 Twój odbierający adres URL zawierają te nagłówki HTTP:
Nagłówek | Opis |
---|---|
Zawsze obecny | |
|
Identyfikator UUID lub inny unikalny ciąg znaków podany przez Ciebie w celu zidentyfikowania tego kanału powiadomień. |
|
Liczba całkowita identyfikująca tę wiadomość dla danego kanału powiadomień. Wartość to zawsze 1 dla sync wiadomości. Liczba wiadomości zwiększa się przy każdej kolejnej wiadomości na kanale, ale nie następuje to po sobie. |
|
Nieprzejrzysta wartość identyfikująca obserwowany zasób. Ten identyfikator jest stały 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ń w formacie czytelnym dla człowieka. Występuje 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. |
Wiadomości z powiadomieniami o działaniach zawierają w treści żądania 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 zapisu aktywności. |
id.time |
Czas wystąpienia działania. Wartość jest podana w formacie daty i godziny ISO 8601. Czas to pełna data oraz godziny, minuty i sekundy w formacie RRRR-MM-DDTgg:mm:ssTZD. Na przykład 2010-04-05T17:30:04+01:00. |
id.uniqueQualifier |
Unikalny kwalifikator, jeśli w tym samym czasie występuje kilka zdarzeń. |
id.applicationName |
Nazwa aplikacji, do której należy zdarzenie. Możliwe wartości: |
id.customerId |
Unikalny identyfikator konta Google Workspace. |
actor |
Użytkownik wykonujący działanie. |
actor.callerType |
Rodzaj autora, który wykonał aktywność wymienioną w raporcie. W tej wersji interfejsu API callerType to żądanie jednostki USER lub OAuth 2LO, która wykonała działanie wymienione w raporcie . |
actor.email |
Podstawowy adres e-mail użytkownika, którego aktywność jest raportowana. |
actor.profileId |
Unikalny identyfikator profilu Google Workspace użytkownika. |
ownerDomain |
Domena konsoli administracyjnej lub właściciela dokumentu w aplikacji Dokumenty. Na tę domenę wpływa zdarzenie z 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 związane z aktywnością w raporcie. |
events[].type |
Typ zdarzenia. Zmieniona przez administratora usługa lub funkcja Google Workspace jest określana w usłudze type . Zdarzenie to jest rozpoznawane za pomocą właściwości eventName . |
events[].name |
Nazwa zdarzenia. Jest to konkretna nazwa aktywności zgłoszonej przez interfejs API. A każdy element eventName jest powiązany z konkretną usługą lub funkcją Google Workspace, którą interfejs API dzieli 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 przypisana do parametru. |
events[].parameters[].boolValue |
Wartość logiczna parametru. |
Przykłady
Powiadomienia o zdarzeniach związanych z zasobem Aktywność 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ładowe zdarzenie związane z aktywnością 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 wskazać, że wykonano operację, należy zwrócić dowolny z tych kodów stanu: 200
, 201
, 202
, 204
lub 102
.
Jeśli Twoja usługa korzysta z biblioteki klienta interfejsu API Google i zwraca 500
, 502
, 503
lub 504
, interfejs API Admin SDK ponawia próbę z wykładniczym ponownym opóźnieniem.
Każdy inny kod stanu jest uważany za błąd 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ć, gdy używasz powiadomień push za pomocą interfejsu API Admin SDK.
Powiadomienia push interfejsu Reports API zawierają 2 rodzaje wiadomości: wiadomości o synchronizacji 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 dla 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 utraci on 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 przykładzie poniżej. Pamiętaj, że jeśli interfejs API pakietu Admin SDK zawiera kilka typów zasobów z metodami watch
, występuje tylko 1 metoda stop
.
Tylko użytkownicy z odpowiednimi uprawnieniami mogą zatrzymać 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 (określony na podstawie identyfikatorów klienta OAuth 2.0 z tokenów uwierzytelniania), który utworzył kanał, może zatrzymać kanał.
- Jeśli kanał został utworzony za pomocą konta usługi, każdy użytkownik z tego samego klienta może zatrzymać kanał.
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" }