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. Pozwala wyeliminować dodatkową sieć i moc obliczeniową koszty związane z zasobami odpytywania w celu określenia, 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:

  • Konfigurowanie adresu URL odbierania (webhooka) .

    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 zegarka.

    Kanał określa informacje o routingu dla powiadomień wiadomości. Podczas zakładania kanału musisz podać dokładny adres URL, pod którym chcesz otrzymywać powiadomienia. Za każdym razem, gdy zasoby kanału się zmieniają, interfejs API Admin SDK wysyła powiadomienie jako POST. do tego adresu URL.

Obecnie interfejs API Admin SDK obsługuje powiadomienia o zmianach w Aktywności.

Utwórz kanały powiadomień

Aby otrzymywać powiadomienia push, musisz skonfigurować kanał powiadomień dla każdego zasobu, który chcesz monitorować. Po ustawieniu kanałów powiadomień interfejs API Admin SDK informuje aplikację, gdy dowolny monitorowany zasób zmian.

Wyślij prośby o zegarek

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ń o wiadomościach o zmianach w określonego zasobu, wyślij żądanie POST do Metoda watch dla zasobu.

Każdy kanał powiadomień jest powiązany zarówno z konkretnym użytkownikiem, określonego zasobu (lub zbioru zasobów). Prośba o: 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 poniższych przykładach pominięto treść żądania, aby uniknąć wątpliwości.

Monitoruj wszystkie działania administratorów:

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

Czekaj na 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 każdym żądaniu watch musisz wypełnić te pola:

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

    Ustawiona wartość identyfikatora jest odczytywana ponownie Nagłówek HTTP X-Goog-Channel-Id każdego powiadomienia jaką wiadomość otrzymujesz na temat tego kanału.

  • Ciąg 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 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 z tematem, który nie pasuje do celu nazwa hosta.

Właściwości opcjonalne

Te opcjonalne pola możesz też określić za pomocą Prośba o środki (watch):

  • właściwość token, która określa dowolny ciąg znaków. do użycia jako token kanału. Możesz użyć kanału powiadomień do różnych celów. Na przykład możesz użyć atrybutu token do potwierdzenia, że każda przychodząca wiadomość pochodzi z kanału, utworzona aplikacja – by upewnić się, że powiadomienie nie jest wysyłane sfałszowana – lub aby skierować wiadomość do właściwego miejsca docelowego w: zgodnie z przeznaczeniem kanału. Maksymalna długość: 256 znaków.

    Token znajduje się w sekcji Nagłówek HTTP X-Goog-Channel-Token w każdym powiadomieniu wyświetlany w aplikacji dla tego kanału.

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

    • Użyj możliwego formatu kodowania, takiego jak zapytanie 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.

.

Aby dowiedzieć się więcej o żądaniu, zapoznaj się z metodą watch dla zasobu Activities (Działania) w dokumentacji interfejsu API.

Obejrzyj odpowiedź

Jeśli żądanie watch utworzy powiadomienie kanału, zwraca kod stanu HTTP 200 OK.

Treść wiadomości w odpowiedzi zegarka zawiera informacje o kanału powiadomień, tak jak pokazano to 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 przesłanych w ramach żądania parametr zwrócone informacje obejmują również resourceId i resourceUri, aby zidentyfikować zasób, który jest na nim obserwowany kanału powiadomień.

Możesz przekazać zwrócone informacje do innego kanału powiadomień operacji, na przykład gdy chcesz przestać otrzymywać powiadomienia.

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

Zsynchronizuj wiadomość

Po utworzeniu kanału powiadomień, aby oglądać zasób, Interfejs API Admin SDK wysyła komunikat sync, aby wskazać, że powiadomienia. 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ć usługi Powiadomienie sync dotyczące inicjalizacji w celu przygotowania późniejszych wydarzeń.

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

Synchronizowane wiadomości zawsze mają żądanie 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). Wygaśnięcie kanału Godzina (jeśli go występuje), jest dołączana jako sygnatura czasowa uniksowa (w milisekundach) w informacjach zwracanych przez metodę watch. Dodatkowo data i godzina wygaśnięcia są podane (w formacie czytelnym dla człowieka) w każdym powiadomienie dotyczące tego kanału, które Twoja aplikacja otrzyma w Nagłówek HTTP X-Goog-Channel-Expiration.

Obecnie nie można automatycznie odnowić 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 istnieje możliwość aby „pokrywać się” okresu, w którym dwa kanały powiadomień są aktywne takie same zasoby.

Otrzymuj powiadomienia

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 wiadomości powiadomienia

Wszystkie powiadomienia zawierają zestaw nagłówków HTTP X-Goog- prefiksy. Niektóre typy powiadomień mogą też zawierać treść wiadomości.

Nagłówki

Wiadomości z powiadomieniami opublikowane przez interfejs API Admin SDK na adres odbiorcy Adres URL zawiera te nagłówki HTTP:

Nagłówek Opis
Zawsze wyświetlaj
X-Goog-Channel-ID Identyfikator UUID lub inny unikalny ciąg znaków podany przez Ciebie w celu identyfikacji kanału powiadomień.
X-Goog-Message-Number Liczba całkowita określająca tę wiadomość w przypadku tego powiadomienia kanał. W przypadku wiadomości typu sync zawsze wartość 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 to stabilna 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 specyficzny dla wersji interfejsu API identyfikatora obserwowanego zasobu,
Czasami występują
X-Goog-Channel-Expiration Data i godzina wygaśnięcia kanału powiadomień wyrażone w zrozumiałego dla człowieka. Występuje tylko wtedy, gdy został określony.
X-Goog-Channel-Token token kanału powiadomień ustawiony przez Twoją aplikację; aby zweryfikować źródło powiadomień. Występuje tylko wtedy, gdy zdefiniowano jego definicję.

Wiadomości z powiadomieniami o działaniach zawierają w treści żądania te informacje:

Właściwość Opis
kind Identyfikuje to 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 w argumencie Format daty i godziny w standardzie ISO 8601. Godzina to pełna data z godzinami, 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 wiele wydarzeń dotyczy tego samego czasu.
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 logującego się w Google Workspace, który może, ale nie musi, odzwierciedlać jego fizyczną lokalizację. Przykładowo adres IP może być adresem serwera proxy użytkownika lub wirtualnej sieci prywatnej (VPN). Interfejs API obsługuje IPv4 oraz 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 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 dzieli na typy zdarzeń.
Ogólnie w przypadku eventName parametrów żądania:
  • 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 aktywności 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ść parametru (liczba całkowita).
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 oznaczyć powodzenie, można wyświetlić dowolny z tych kodów stanu: 200, 201, 202, 204 lub 102.

Jeśli Twoja usługa używa biblioteki klienta interfejsów API Google i zwraca 500, 502, 503 lub 504, interfejs API Admin SDK ponawia próby z wykładniczym czasem ponowienia. Każdy inny kod stanu zwrotu jest uważany za niepowodzenie otrzymania wiadomości.

Omówienie zdarzeń 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: wiadomości o synchronizacji i powiadomienia o wydarzeniach. 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ą być zatrzymywane automatycznie. Dostępne opcje wyłączyć otrzymywanie powiadomień z kanału, zanim zacznie się wyświetlać wygasa przez wywołanie metody stop na stronie ten identyfikator URI:

https://www.googleapis.com/admin/reports_v1/channels/stop

Ta metoda wymaga podania przynajmniej id i resourceId, jak pokazano w przykład 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 to samo tego samego klienta (zgodnie z identyfikatorami klienta OAuth 2.0 w sekcji tokeny uwierzytelniania), który utworzył kanał, może zatrzymać jego działanie.
  • Jeśli kanał został utworzony przez konto usługi, dowolny użytkownik z tego samego konta, może zatrzymać kanał.

Przeanalizuj przykładowy kod poniżej, aby dowiedzieć się, jak wyłączyć 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"
}