Powiadomienia push

Z tego dokumentu dowiesz się, jak korzystać z powiadomień push, które informują aplikację o zmianach zasobów.

Przegląd

Interfejs API pakietu Admin SDK udostępnia powiadomienia push, które umożliwiają monitorowanie zmian w zasobach. Możesz użyć tej funkcji, aby zwiększyć wydajność aplikacji. Pozwala to wyeliminować dodatkowe koszty sieciowe i obliczeniowe związane z odpytywaniem zasobów w celu sprawdzenia, czy uległy zmianie. Gdy tylko zmieni się obserwowany zasób, interfejs Admin SDK API powiadomi o tym Twoją aplikację.

Aby korzystać z powiadomień push, musisz wykonać 2 czynności:

  • Skonfiguruj adres URL odbioru lub odbiornik wywołania zwrotnego „webhook”.

    Jest to serwer HTTPS, który obsługuje wiadomości z powiadomieniami API wywoływane, gdy zasób ulegnie zmianie.

  • Skonfiguruj kanał powiadomień dla każdego punktu końcowego zasobu, który chcesz obserwować.

    Kanał określa informacje o kierowaniu wiadomości z powiadomieniami. W ramach konfiguracji kanału musisz wskazać konkretny adres URL, na który chcesz otrzymywać powiadomienia. Za każdym razem, gdy zmieni się zasób kanału, interfejs Admin SDK API wysyła wiadomość z powiadomieniem w postaci POSTżądania na ten adres URL.

Obecnie interfejs Admin SDK API obsługuje powiadomienia o zmianach w zasobie 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 Admin SDK API informuje aplikację o zmianach w dowolnym obserwowanym zasobie.

Wysyłanie próśb dotyczących zegarka

Każdy zasób interfejsu API pakietu Admin SDK, który można obserwować, ma powiązaną watch metodę pod adresem URI w tym formacie:

https://www.googleapis.com/API_NAME/API_VERSION/RESOURCE_PATH/watch

Aby skonfigurować kanał powiadomień o zmianach w konkretnym 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 zestawem zasobów). Żądanie watch nie zostanie zrealizowane, chyba że bieżący użytkownik lub konto usługi jest właścicielem tego zasobu albo ma do niego dostęp.

Przykłady

Wszystkie żądania obserwowania zasobu Activities mają ogólną postać:

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",
  "type": "web_hook",
  "address": "https://mydomain.com/notifications",
  ...
  "token": "target=myApp-myFilesChannelDest",
  "payload": true,
  "expiration": 3600
}

Treść żądania ma te właściwości:

  • id: unikalny identyfikator UUID lub podobny ciąg znaków, który identyfikuje ten kanał.
  • type: typ mechanizmu dostarczania. Wartość tego pola musi wynosić web_hook.
  • address: adres URL, na który są wysyłane powiadomienia.
  • token: dowolny ciąg znaków dostarczany na adres docelowy z każdym powiadomieniem w celu sprawdzenia, czy powiadomienie pochodzi z zaufanego źródła.
  • payload: flaga wartości logicznej, która określa, czy ładunek ma być dołączony do powiadomienia.
  • expiration: Czas życia w sekundach dla kanału powiadomień.

Możesz użyć parametrów userKey, applicationName, eventName i filters, aby otrzymywać powiadomienia tylko o określonych zdarzeniach, użytkownikach lub aplikacjach.

Uwaga: w poniższych przykładach pominięto treść żądania, aby były bardziej czytelne.

Obserwuj wszystkie działania administratorów:

POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin/watch

Obserwuj wszystkie działania w Dokumentach:

POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/docs/watch

Obserwowanie aktywności administracyjnej konkretnego użytkownika:

POST https://admin.googleapis.com/admin/reports/v1/activity/users/liz@example.com/applications/admin/watch

Obserwuj konkretne zdarzenie, np. zmianę hasła użytkownika:

POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin/watch?eventName=CHANGE_PASSWORD

Śledzenie zmian w konkretnym 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 każdym żądaniu watch musisz podać te pola:

  • Ciąg znaków id, który jednoznacznie identyfikuje ten nowy kanał powiadomień w projekcie. Zalecamy używanie unikalnego identyfikatora uniwersalnego (UUID) lub podobnego unikalnego ciągu znaków. Maksymalna długość: 64 znaki.

    Ustawiona wartość identyfikatora jest zwracana w X-Goog-Channel-Idnagłówku HTTP każdego powiadomieniaX-Goog-Channel-Id, które otrzymujesz w przypadku tego kanału.

  • Ciąg znaków właściwości type ustawiony na wartość web_hook.

  • Ciąg znaków właściwości address ustawiony na adres URL, który nasłuchuje i odpowiada na powiadomienia dotyczące tego kanału powiadomień. Jest to adres URL wywołania zwrotnego webhooka, który musi używać protokołu HTTPS.

    Pamiętaj, że interfejs Admin SDK API 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, których podmiot nie jest zgodny z docelową nazwą hosta,

Właściwości opcjonalne

W watch możesz też podać te opcjonalne pola:

  • Właściwość token, która określa dowolny ciąg znaków do użycia jako token kanału. Tokeny kanału powiadomień możesz wykorzystywać do różnych celów. Możesz na przykład użyć tokena, aby sprawdzić, czy każda przychodząca wiadomość jest przeznaczona dla kanału utworzonego przez Twoją aplikację. Dzięki temu możesz mieć pewność, że powiadomienie nie jest fałszywe, lub kierować wiadomość do odpowiedniego miejsca w aplikacji na podstawie przeznaczenia kanału. Maksymalna długość: 256 znaków.

    Token jest dołączany do nagłówka HTTP X-Goog-Channel-Token w każdej wiadomości z powiadomieniem, którą aplikacja otrzymuje w przypadku tego kanału.

    Jeśli używasz tokenów kanału powiadomień, zalecamy:

    • Używaj 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 znaków właściwości expiration ustawiony na sygnaturę czasową w formacie Unix (w milisekundach) daty i godziny, o której interfejs API SDK Admin ma przestać wysyłać wiadomości na ten kanał powiadomień.

    Jeśli kanał ma czas wygaśnięcia, jest on uwzględniany jako wartość X-Goog-Channel-Expiration nagłówka HTTP (w formacie czytelnym dla człowieka) w każdej wiadomości z powiadomieniem, którą aplikacja otrzymuje w przypadku tego kanału.

Więcej informacji o żądaniu znajdziesz w opisie metody watch zasobu Activities w dokumentacji interfejsu API.

Obejrzyj odpowiedź

Jeśli żądanie watch spowoduje utworzenie kanału powiadomień, zwróci kod stanu HTTP 200 OK.

Treść odpowiedzi zegarka zawiera informacje o utworzonym właśnie kanale powiadomień, jak pokazano w przykładzie poniżej.

{
  "kind": "api#channel",
  "id": "reportsApiId",
  "resourceId": "o3hgv1538sdjfh",
  "resourceUri": "https://admin.googleapis.com/admin/reports/v1/activity/userKey/applications/applicationName",
  "token": "target=myApp-myFilesChannelDest",
  "expiration": 3600
}

Oprócz właściwości przesłanych w ramach żądania zwrócone informacje zawierają też resourceId i resourceUri, które identyfikują zasób obserwowany na tym kanale powiadomień.

Zwrócone informacje możesz przekazywać do innych operacji na kanale powiadomień, np. gdy chcesz przestać otrzymywać powiadomienia.

Więcej informacji o odpowiedzi znajdziesz w sekcji dotyczącej metody watch zasobu Activities w dokumentacji interfejsu API.

Synchronizuj wiadomości

Po utworzeniu kanału powiadomień do monitorowania zasobu interfejs Admin SDK API wysyła komunikat sync, aby poinformować, że powiadomienia są uruchamiane. Wartość nagłówka HTTP X-Goog-Resource-State w przypadku tych wiadomości to sync. Ze względu na problemy z czasem w sieci możesz otrzymać wiadomość sync jeszcze przed otrzymaniem odpowiedzi na metodę watch.

Powiadomienie sync można zignorować, 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 funkcji stop receiving notifications. Możesz też użyć powiadomienia sync, aby przeprowadzić inicjację i przygotować się na późniejsze zdarzenia.

Format wiadomości sync, które interfejs Admin SDK API wysyła na Twój adres URL odbioru, jest pokazany poniżej.

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 zawsze mają wartość nagłówka HTTP X-Goog-Message-Number równą 1. Każde kolejne powiadomienie z tego kanału ma numer wiadomości większy od poprzedniego, ale numery wiadomości nie są kolejnymi liczbami.

Odnowienie kanałów powiadomień

Kanał powiadomień może mieć czas wygaśnięcia, którego wartość jest określana przez Twoje żądanie lub przez wewnętrzne limity lub wartości domyślne interfejsu Admin SDK API (używana jest bardziej restrykcyjna wartość). Czas wygaśnięcia kanału (jeśli taki istnieje) jest podany jako sygnatura czasowa Unix (w milisekundach) w informacjach zwracanych przez metodę watch. Dodatkowo data i godzina wygaśnięcia (w formacie czytelnym dla człowieka) są zawarte w każdej wiadomości z powiadomieniem, którą aplikacja otrzymuje w przypadku tego kanału, w X-Goog-Channel-Expirationnagłówku HTTP.

Obecnie nie ma automatycznego sposobu odnowienia kanału powiadomień. Gdy kanał zbliża się do daty wygaśnięcia, musisz zastąpić go nowym, wywołując metodę watch. Jak zawsze, musisz użyć unikalnej wartości we właściwości id nowego kanału. Pamiętaj, że prawdopodobnie wystąpi okres „nakładania się”, w którym aktywne będą 2 kanały powiadomień dotyczące tego samego zasobu.

otrzymywanie powiadomień;

Gdy obserwowany zasób ulegnie zmianie, aplikacja otrzyma wiadomość z powiadomieniem opisującym tę zmianę. Interfejs API pakietu Admin SDK wysyła te wiadomości jako żądania HTTPS POST na adres URL określony jako właściwość address tego kanału powiadomień.

Interpretowanie formatu wiadomości powiadomienia

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łówki

Wiadomości z powiadomieniami publikowane przez interfejs Admin SDK API na adres URL odbiorcy zawierają te nagłówki HTTP:

Nagłówek Opis
Zawsze obecny
X-Goog-Channel-ID Identyfikator UUID lub inny unikalny ciąg znaków, który został podany w celu identyfikacji tego kanału powiadomień.
X-Goog-Message-Number Liczba całkowita identyfikująca tę wiadomość na tym kanale powiadomień. W przypadku wiadomości sync wartość zawsze wynosi 1. Numery wiadomości rosną w przypadku każdej kolejnej wiadomości na kanale, ale nie są sekwencyjne.
X-Goog-Resource-ID Nieczytelna wartość identyfikująca obserwowany zasób. Ten identyfikator jest stabilny we wszystkich wersjach interfejsu API.
X-Goog-Resource-State Nowy stan zasobu, który wywołał powiadomienie. Możliwe wartości:sync lub nazwa zdarzenia.
X-Goog-Resource-URI Identyfikator obserwowanego zasobu, który jest specyficzny dla wersji interfejsu API.
Czasami występuje
X-Goog-Channel-Expiration Data i godzina wygaśnięcia kanału powiadomień w formacie czytelnym dla człowieka. Występuje tylko wtedy, gdy jest zdefiniowany.
X-Goog-Channel-Token Token kanału powiadomień ustawiony przez aplikację, którego możesz użyć do weryfikacji źródła powiadomienia. Występuje tylko wtedy, gdy jest zdefiniowany.

Wiadomości z powiadomieniami o aktywnościach zawierają w treści żądania te informacje:

Właściwość Opis
kind Określa, że jest to zasób Activity. Wartość: ustalony ciąg znaków „admin#reports#activity”.
id Unikalny identyfikator rekordu aktywności.
id.time Czas wystąpienia aktywności. Wartość jest podana w formacie daty i godziny ISO 8601. Czas to pełna data z godziną, minutami i sekundami w formacie RRRR-MM-DDTgg:mm:ssTZD. Na przykład 2010-04-05T17:30:04+01:00.
id.uniqueQualifier Unikalny kwalifikator, jeśli kilka zdarzeń ma ten sam czas.
id.applicationName Nazwa aplikacji, do której należy zdarzenie. Możliwe wartości:
id.customerId Unikalny identyfikator konta Google Workspace.
actor Użytkownik, który wykonuje działanie.
actor.callerType Typ autora, który wykonał działanie wymienione w raporcie. W tej wersji interfejsu API callerType to USER lub podmiot OAuth 2LO, który wykonał działanie wymienione w raporcie .
actor.email Podstawowy adres e-mail użytkownika, którego działania są raportowane.
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 w raporcie.
ipAddress Adres IP użytkownika, który wykonał działanie. Jest to adres IP użytkownika podczas logowania się w Google Workspace, który może, ale nie musi odzwierciedlać fizycznej lokalizacji użytkownika. Może to być na przykład adres serwera proxy użytkownika lub adres wirtualnej sieci prywatnej (VPN). Interfejs API obsługuje IPv4 i IPv6.
events[] zdarzenia aktywności w raporcie.
events[].type Typ zdarzenia. Usługa lub funkcja Google Workspace, którą administrator zmienia, jest identyfikowana we właściwości type, która identyfikuje zdarzenie za pomocą właściwości eventName.
events[].name Nazwa zdarzenia. Jest to konkretna nazwa aktywności zgłoszona przez interfejs API. Każdy eventName jest powiązany z konkretną usługą lub funkcją Google Workspace, którą interfejs API porządkuje w typy zdarzeń.
W przypadku eventName parametrów żądania ogólnie:
  • Jeśli nie podano żadnego eventName, raport zwraca wszystkie możliwe wystąpienia eventName.
  • Gdy wyślesz żądanie eventName, w odpowiedzi z interfejsu API otrzymasz wszystkie działania, które zawierają ten eventName. Możliwe, że zwrócone działania będą miały inne właściwości eventName oprócz tej, o którą prosisz.
events[].parameters[] Pary wartości parametrów dla różnych aplikacji.
events[].parameters[].name Nazwa parametru.
events[].parameters[].value Wartość ciągu parametru.
events[].parameters[].intValue Wartość parametru jako liczba całkowita.
events[].parameters[].boolValue Wartość logiczna parametru.

Przykłady

Powiadomienia o zdarzeniach zasobu Activity mają ogólną postać:

POST https://mydomain.com/notifications
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 zdarzenia dotyczącego aktywności administratora:

POST https://mydomain.com/notifications
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ć 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 Admin SDK API ponawia próbę z wykładniczym wycofywaniem. Każdy inny kod stanu zwrotu jest uznawany za błąd wiadomości.

Informacje o zdarzeniach powiadomień interfejsu Admin SDK API

W tej sekcji znajdziesz szczegółowe informacje o komunikatach z powiadomieniami, które możesz otrzymywać podczas korzystania z powiadomień push za pomocą interfejsu Admin SDK API.

Powiadomienia push interfejsu Reports API zawierają 2 typy wiadomości: wiadomości sync i powiadomienia o zdarzeniach. Typ wiadomości jest podany w X-Goog-Resource-Statenagłówku HTTP. Możliwe wartości powiadomień o wydarzeniach 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ą być automatycznie zatrzymywane. Możesz zrezygnować z otrzymywania powiadomień z danego kanału przed jego wygaśnięciem, wywołując metodę stop pod tym adresem 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 Admin SDK API ma kilka typów zasobów z metodami watch, istnieje tylko jedna metoda stop.

Tylko użytkownicy z odpowiednimi uprawnieniami mogą zatrzymać kanał. W szczególności:

  • Jeśli kanał został utworzony przez zwykłe konto użytkownika, może go zatrzymać tylko ten sam użytkownik z tego samego klienta (zidentyfikowanego przez identyfikatory klienta OAuth 2.0 z tokenów uwierzytelniających), który utworzył kanał.
  • Jeśli kanał został utworzony przez konto usługi, każdy użytkownik z tego samego klienta może go zatrzymać.

Poniższy przykładowy kod pokazuje, jak zatrzymać otrzymywanie powiadomień:

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"
}