Powiadomienia push

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

Przegląd

Interfejs Directory API 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 Directory 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 zasób kanału ulegnie zmianie, interfejs Directory API wysyła wiadomość z powiadomieniem w postaci żądania POST na ten adres URL.

Obecnie interfejs Directory API obsługuje powiadomienia o zmianach w zasobie Users.

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 Directory API informuje aplikację o zmianach w dowolnym obserwowanym zasobie.

Wysyłanie próśb dotyczących zegarka

Każdy zasób interfejsu Directory API, który można obserwować, ma powiązaną metodę watch pod identyfikatorem URI w tej postaci:

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 wyświetlenia zasobu User w przypadku jednej domeny mają ogólną postać:

POST https://admin.googleapis.com/admin/directory/v1/users/watch?domain=domain&event=event
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",
  "params": {
    "ttl": 3600
  }
}

W treści żądania podaj swój kanał id, type jako web_hook i adres URL odbiorcy w address. Możesz też opcjonalnie podać:

  • token, którego możesz użyć jako tokena kanału.
  • Wpisz ttl w params, aby poprosić o czas życia tego kanału w sekundach.

Użyj parametrów domain i event, aby określić domenę i typ zdarzenia, w przypadku których chcesz otrzymywać powiadomienia.

Wszystkie żądania obserwowania zasobu User w przypadku klienta mają ogólną postać:

POST https://admin.googleapis.com/admin/directory/users/v1/watch?customer=customer&event=event
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",
  "params": {
    "ttl": 3600
  }
}

Użyj parametrów customer i event, aby określić unikalny identyfikator konta Google klienta oraz typ zdarzenia, w przypadku którego chcesz otrzymywać powiadomienia.

Możliwe wartości event to:

  • add: zdarzenie utworzone przez użytkownika
  • delete: zdarzenie usunięcia użytkownika
  • makeAdmin: zdarzenie zmiany stanu administratora użytkowników
  • undelete: zdarzenie przywrócone przez użytkownika
  • update: zdarzenie aktualizacji użytkownika

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

Obserwuj zdarzenia utworzone przez użytkowników w domenie mydomain.com:

POST https://admin.googleapis.com/admin/directory/v1/users/watch?domain=mydomain.com&event=add

Obserwuj zdarzenia utworzone przez użytkownika klienta my_customer:

POST https://admin.googleapis.com/admin/directory/v1/users/watch?customer=my_customer&event=add

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 Directory 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ą Unix (w milisekundach) daty i godziny, po której interfejs Directory API 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 dokumentacji interfejsu API w sekcji dotyczącej metody watch zasobu Users.

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": "01234567-89ab-cdef-0123456789ab",
  "resourceId": "B4ibMJiIhTjAQd7Ff2K2bexk8G4",
  "resourceUri": "https://admin.googleapis.com/admin/directory/v1/users?domain=domain&event=event",
  "token": "target=myApp-myFilesChannelDest",
  "expiration": 1384823632000
}

Treść odpowiedzi zawiera szczegóły kanału, takie jak:

  • id: identyfikator określony przez Ciebie dla tego kanału.
  • resourceId: identyfikator obserwowanego zasobu.
  • resourceUri: identyfikator obserwowanego zasobu przypisany do konkretnej wersji.
  • token: token podany w treści żądania.
  • expiration: czas wygaśnięcia kanału jako sygnatura czasowa w milisekundach.

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 w przypadku zasobu Users w dokumentacji interfejsu API.

Synchronizuj wiadomości

Po utworzeniu kanału powiadomień do monitorowania zasobu interfejs Directory 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 sync wiadomości, które interfejs Directory 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 Directory 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 Directory API 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 Directory 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 dla użytkowników zawierają w treści żądania te informacje:

Właściwość Opis
kind Określa, że jest to zasób User. Wartość: ustalony ciąg znaków „admin#directory#user”.
id Unikalny identyfikator zasobu użytkownika.
etag ETag powiadomienia. Różni się od tagu ETag zasobu Użytkownik.
primaryEmail Podstawowy adres e-mail użytkownika.

Przykłady

Powiadomienia o zdarzeniach dotyczących zasobu User mają ogólną postać:

POST https://mydomain.com/notifications
Content-Type: application/json; utf-8
Content-Length: 0
X-Goog-Channel-ID: directoryApiId
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/directory/v1/users?domain=domain&event=event
X-Goog-Resource-State:  event
X-Goog-Message-Number: 10

{
  "kind": "admin#directory#user",
  "id": long,
  "etag": string,
  "primaryEmail": string
}

Przykład zdarzenia usunięcia przez użytkownika:

POST https://mydomain.com/notifications
Content-Type: application/json; utf-8
Content-Length: 189
X-Goog-Channel-ID: deleteChannel
X-Goog-Channel-Token: 245t1234tt83trrt333
X-Goog-Channel-Expiration: Mon, 09 Dec 2013 22:24:23 GMT
X-Goog-Resource-ID:  B4ibMJiIhTjAQd7Ff2K2bexk8G4
X-Goog-Resource-URI: https://admin.googleapis.com/admin/directory/v1/users?domain=mydomain.com&event=delete&alt=json
X-Goog-Resource-State:  delete
X-Goog-Message-Number: 236440

{
  "kind": "admin#directory#user",
  "id": "111220860655841818702",
  "etag": "\"Mf8RAmnABsVfQ47MMT_18MHAdRE/evLIDlz2Fd9zbAqwvIp7Pzq8UAw\"",
  "primaryEmail": "user@mydomain.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 Directory API ponawia próbę z wykładniczym wycofywaniem. Każdy inny kod stanu zwrotu jest uznawany za błąd wiadomości.

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/directory_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 Directory 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/directory_v1/channels/stop
  
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

{
  "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a66",
  "resourceId": "ret08u3rv24htgh289g"
}