Powiadomienia push

Z tego dokumentu dowiesz się, jak korzystać z powiadomień push informujących aplikacji w przypadku zmiany zasobu.

Omówienie

Interfejs API Admin SDK udostępnia powiadomienia push, które umożliwiają monitorowanie zmian w zasobach. Możesz korzystać z tej funkcji, aby poprawić skuteczność Twojej aplikacji. Dzięki temu możesz wyeliminować dodatkowe koszty sieci i przetwarzania związane z zasobami ankietowania, aby określić, czy uległy zmianie. Za każdym razem, gdy obserwowany zasób ulegnie zmianie, interfejs API Admin SDK powiadomi aplikacji.

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

  • Skonfiguruj odbierający adres URL lub „webhook” odbiornika wywołania zwrotnego.

    Ten to serwer HTTPS, który obsługuje powiadomienia interfejsu API wywoływane po zmianie zasobu.

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

    Kanał określa informacje o przekierowywaniu wiadomości z powiadomieniami. W ramach konfiguracji kanału musisz podać konkretny adres URL, pod którym chcesz otrzymywać powiadomienia. Gdy nastąpi zmiana zasobu kanału, interfejs Admin SDK wysyła wiadomość z powiadomieniem w postaci żądania POST do tego adresu URL.

Obecnie interfejs Admin SDK obsługuje powiadomienia o zmianach zasobu Activities.

Tworzenie kanałów powiadomień

Aby otrzymywać 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 aplikację o zmianach w obserwowanych zasobach.

Przesyłanie żądań dotyczących oglądania

Każdy dostępny do obserwacji zasób interfejsu API Admin SDK ma powiązane watch w identyfikatorze URI o następującej formie:

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

Aby skonfigurować kanał powiadomień dla wiadomości 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, określonego zasobu (lub zbioru zasobów). Żądanie watch nie powiedzie się, chyba że bieżący użytkownik lub konto usługi jest właścicielem tego zasobu lub ma do niego uprawnienia dostępu.

Przykłady

Wszystkie żądania zegarka dotyczące zasobu aktywności 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", // 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 o określonych zdarzeniach, użytkownikach lub aplikacjach.

Uwaga: w przykładach poniżej pominięto treść żądania w celu ułatwienia ich zrozumienia.

Sprawdzanie wszystkich działań administratora:

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

Monitoruj wszystkie działania dotyczące dokumentów:

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

Zwracaj uwagę na czynności administracyjne określonego użytkownika:

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

Obserwowanie konkretnego zdarzenia, np. zmiany hasła użytkownika:

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

Śledź zmiany 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:

  • Unikalny ciąg znaków właściwości id, który jednoznacznie identyfikuje ten nowy kanał powiadomień w Twoim projekcie. Zalecamy użycie uniwersalny identyfikator (UUID) lub podobny jest unikalny ciąg znaków. Maksymalna długość: 64 znaki.

    Ustawiona przez Ciebie wartość identyfikatora jest odzwierciedlana w nagłówku HTTP X-Goog-Channel-Id każdego powiadomienia, które otrzymujesz z tego kanału.

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

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

    Pamiętaj, że interfejs API Admin SDK może wysyłać powiadomienia do ten adres HTTPS, tylko jeśli został zainstalowany prawidłowy certyfikat SSL na serwerze WWW. 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 celem, nazwa hosta.

Właściwości opcjonalne

W prośbie watch możesz też podać te pola opcjonalne:

  • 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 stosować do różnych celów. Możesz na przykład użyć tokena, aby sprawdzić, czy każda przychodząca wiadomość jest przeznaczona do kanału utworzonego przez Twoją aplikację (aby mieć pewność, że powiadomienie nie jest sfałszowane) lub przekierować wiadomość do odpowiedniego miejsca w aplikacji na podstawie celu tego kanału. Maksymalna długość: 256 znaków.

    Token jest zawarty w nagłówku HTTP X-Goog-Channel-Token w każdej wiadomości z powiadomieniem, którą aplikacja otrzymuje na tym kanale.

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

    • Użyj formatu kodowania umożliwiającego rozszerzanie, 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, o której interfejs API Admin SDK ma zaprzestać wysyłania wiadomości z tego kanału powiadomień.

    Jeśli kanał ma datę ważności, jest on podany jako wartość. nagłówka HTTP X-Goog-Channel-Expiration (w formacie czytelnym dla człowieka) ) w każdej wiadomości z powiadomieniem, otrzymuje tyle zgłoszeń dotyczących tego kanału.

Więcej informacji o tym żądaniu znajdziesz w metodie watch zasobu Activities w przewodniku po interfejsie API.

Odpowiedź

Jeśli żądanie watch tworzy kanał powiadomień, zwraca kod stanu HTTP 200 OK.

Treść odpowiedzi na obejrzenie filmu zawiera informacje o korzystaniu z konkretnego kanału powiadomień, jak pokazano w przykładzie poniżej.

{
  "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 informacje zwracane zawierają też wartości resourceId i resourceUri, które wskazują zasób wyświetlany na tym kanale powiadomień.

Możesz przekazać zwrócone informacje do innych operacji na kanale powiadomień, na przykład gdy chcesz zatrzymać otrzymywanie powiadomień.

Więcej informacji o odpowiedzi znajdziesz tutaj: watch dla zasobu Activities (Działania) w dokumentacji interfejsu API.

Zsynchronizuj wiadomość

Po utworzeniu kanału powiadomień, który ma monitorować zasób, interfejs API pakietu Admin SDK wysyła wiadomość sync, aby wskazać, że powiadomienia się rozpoczęły. Protokół HTTP X-Goog-Resource-State wartość nagłówka tych wiadomości to sync. Ze względu na sieć problemy z czasem, możesz otrzymać komunikat sync jeszcze przed otrzymaniem odpowiedzi metody watch.

Możesz bezpiecznie zignorować powiadomienie sync, ale możesz go użyć. Jeśli na przykład nie chcesz przechowywać kanału, możesz korzystać z funkcji X-Goog-Channel-ID i X-Goog-Resource-ID wartości w wywołaniu do wyłączyć otrzymywanie powiadomień. Możesz też użyć powiadomienia sync, aby przeprowadzić wstępną konfigurację w celu przygotowania się do późniejszych zdarzeń.

Format komunikatów sync, do których interfejs Admin SDK API wysyła Twój adres URL odbierania jest widoczny 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 mają zawsze wartość nagłówka HTTP X-Goog-Message-Number 1. Każde kolejne powiadomienie z tego kanału numer wiadomości jest większy niż poprzedni, mimo że komunikat liczby nie występują po sobie.

Odnawianie kanałów powiadomień

Kanał powiadomień może mieć czas wygaśnięcia i podaną wartość określane na podstawie żądania lub wewnętrznych limitów interfejsu API Admin SDK lub wartości domyślne (stosowana jest wartość bardziej restrykcyjna). Czas wygaśnięcia kanału (jeśli istnieje) jest podawany jako oznaczenie czasu uniksowego (w milisekundach) w informacjach zwracanych przez metodę watch. Dodatkowo data i godzina wygaśnięcia (w czytelnym dla człowieka formacie) są zawarte w każdej wiadomości z powiadomieniem, którą aplikacja otrzymuje dla tego kanału w nagłówku HTTP X-Goog-Channel-Expiration.

Obecnie nie ma automatycznego sposobu odnawiania kanału powiadomień. Kiedy kanał wkrótce wygaśnie. Musisz zastąpić go nowym, dzwoniąc metodę watch. Jak zawsze, musisz użyć unikalnej wartości dla argumentu właściwość id nowego kanału. Pamiętaj, że prawdopodobnie będzie okres „nakładania się”, gdy 2 kanały powiadomień dla tego samego zasobu będą aktywne.

Otrzymywanie powiadomień

Po każdej zmianie obserwowanego zasobu aplikacja otrzymuje powiadomienie z opisem zmiany. Interfejs API Admin SDK wysyła te jako żądania HTTPS POST do adresu URL określonego jako address usługa dla tego powiadomienia kanał.

Interpretowanie formatu 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 w adresie URL odbiorczym zawierają te nagłówki HTTP:

Nagłówek Opis
Zawsze wyświetlaj
X-Goog-Channel-ID Identyfikator UUID lub inny unikalny ciąg znaków, który umożliwia identyfikację tego kanału powiadomień.
X-Goog-Message-Number Wartość całkowita identyfikująca to powiadomienie dla tego kanału powiadomień. W przypadku wiadomości sync wartość zawsze wynosi 1. Wiadomość ich liczba rośnie z każdą kolejną wiadomością na kanale, ale nie sekwencyjną.
X-Goog-Resource-ID Nieprzejrzysta 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 zasobu monitorowanego, 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 zrozumiałym dla człowieka. Występuje tylko wtedy, gdy jest zdefiniowany.
X-Goog-Channel-Token Token kanału powiadomień ustawiony przez Twoją aplikację, którego możesz użyć do zweryfikowania źródła powiadomienia. Występuje tylko wtedy, gdy jest zdefiniowany.

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

Właściwość Opis
kind wskazuje, że jest to 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 w argumencie Format daty i godziny w standardzie ISO 8601. Czas to pełna data z godziną, minutami i sekundami w formacie RRRR-MM-DDThh:mm:ssTZD. Na przykład 2010-04-05T17:30:04+01:00.
id.uniqueQualifier Unikalny wyróżnik, 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 wykonujący działanie.
actor.callerType Typ autora, który wykonał działanie wymienione w raporcie. W tej wersji interfejsu API callerType to żądanie encji USER lub OAuth 2LO, które wykonało 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ściciel dokumentów w aplikacji Dokumenty. Jest to domena, której dotyczy 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ć fizycznej lokalizacji użytkownika. Przykładowo adres IP może być adresem serwera proxy użytkownika lub wirtualnej sieci prywatnej (VPN). Interfejs API obsługuje IPv4 i IPv6.
events[] Zdarzenia aktywności uwzględnione w raporcie.
events[].type Typ zdarzenia. Usługa lub funkcja Google Workspace zmieniona przez administratora jest określana we właściwości type, która identyfikuje zdarzenie za pomocą właściwości eventName.
events[].name Nazwa zdarzenia. Jest to nazwa aktywności zgłaszanej przez interfejs API. Każdy z nich eventName jest powiązany z konkretną usługą lub funkcją Google Workspace, którą interfejs API porządkuje według typów zdarzeń.
W przypadku parametrów żądania eventName:
  • Jeśli nie podasz żadnej wartości eventName, raport zwróci wszystkie możliwe wystąpienia wartości eventName.
  • Gdy wysyłasz żądanie eventName, odpowiedź interfejsu API zwraca wszystkie aktywności, które zawierają ten element eventName. Możliwe, że zwrócone działania będą miały inne właściwości eventName oprócz tej żądanej.
events[].parameters[] Pary wartości parametrów dla różnych aplikacji.
events[].parameters[].name Nazwa parametru.
events[].parameters[].value Wartość parametru w postaci ciągu znaków.
events[].parameters[].intValue Wartość liczby całkowitej przypisana do parametru.
events[].parameters[].boolValue Wartość logiczna parametru.

Przykłady

Powiadomienia o zdarzeniach dotyczących zasobu aktywności mają ogólną 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 zdarzenia dotyczącego 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ć 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 wartości 500, 502, 503 lub 504, interfejs API Admin SDK próbuje ponownie, stosując eksponencjalne wycofanie. Każdy inny kod stanu zwrotu jest uznawany za błąd wiadomości.

Informacje o zdarzeniach powiadomień interfejsu Admin SDK API

Ta sekcja zawiera szczegółowe informacje na temat powiadomień, które możesz w przypadku korzystania z powiadomień push za pomocą interfejsu API Admin SDK.

Powiadomienia push interfejsu Reports API zawierają 2 typy wiadomości: synchronizacji i zdarzenia. Typ wiadomości jest podany w nagłówku HTTP X-Goog-Resource-State. 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 przestaną być wysyłane automatycznie. Możesz przestać otrzymywać powiadomienia z określonego 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 API Admin SDK zawiera kilka typów zasobów z watch metodą, jest 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, tylko ta sama osoba korzystająca z tego samego klienta (identyfikowana przez identyfikatory klienta OAuth 2.0 z tokenów uwierzytelniających) może zatrzymać 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 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"
}