Powiadomienia push

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

Omówienie

Interfejs Directory API wysyła powiadomienia push, które umożliwiają monitorowanie zmian w zasobach. Dzięki tej funkcji możesz poprawić wydajność aplikacji. Dzięki temu możesz wyeliminować dodatkowe koszty sieci i przetwarzania związane z zasobami ankietowania, aby określić, czy uległy zmianie. Gdy obserwowany zasób ulegnie zmianie, interfejs Directory API wysyła powiadomienie do Twojej aplikacji.

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

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

    To serwer HTTPS, który obsługuje wiadomości z powiadomieniami interfejsu API, które są 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 zasób kanału ulegnie zmianie, interfejs Directory API wysyła wiadomość z powiadomieniem w postaci żądania POST do tego adresu URL.

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

Tworzenie kanałów powiadomień

Aby żądać powiadomień push, musisz skonfigurować kanał powiadomień dla każdego zasobu, który chcesz monitorować. Gdy skonfigurujesz kanały powiadomień, interfejs Directory API będzie informować aplikację o zmianach w obserwowanych zasobach.

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

Każdy zasób interfejsu Directory API, który można oglądać, ma powiązaną metodę watch o identyfikatorze URI w takim formacie:

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 z konkretnym użytkownikiem i konkretnym zasobem (lub zestawem zasobów). Żądanie watch nie zostanie zrealizowane, chyba że bieżący użytkownik lub konto usługi ma własność tego zasobu lub ma do niego uprawnienia.

Przykłady

Wszystkie żądania oglądania zasobu User w przypadku jednej domeny mają ogólny format:

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", // Your channel ID.
  "type": "web_hook",
  "address": "https://mydomain.com/notifications", // Your receiving URL.
  ...
  "token": "target=myApp-myFilesChannelDest", // (Optional) Your channel token.
  "params": {
    "ttl": 3600 // (Optional) Your requested time-to-live for this channel.
  }
}

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

Wszystkie żądania obserwowania zasobu Użytkownik dla klienta mają ogólny format:

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", // Your channel ID.
  "type": "web_hook",
  "address": "https://mydomain.com/notifications", // Your receiving URL.
  ...
  "token": "target=myApp-myFilesChannelDest", // (Optional) Your channel token.
  "params": {
    "ttl": 3600 // (Optional) Your requested time-to-live for this channel.
  }
}

Parametry customer i event służą do określania unikalnego identyfikatora konta Google klienta oraz typu zdarzenia, o którym chcesz otrzymywać powiadomienia.

Możliwe wartości atrybutu event to:

  • add: zdarzenie utworzone przez użytkownika
  • delete: zdarzenie usunięcia przez użytkownika
  • makeAdmin: zdarzenie zmiany stanu administratora użytkownika
  • undelete: zdarzenie przywrócenia pliku przez użytkownika
  • update: zdarzenie zaktualizowania użytkownika

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

Wypatruj zdarzenia utworzone przez użytkownika w domenie mydomain.com:

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

Zwróć uwagę na zdarzenia utworzone przez użytkownika w przypadku 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:

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

    Ustawiony przez Ciebie identyfikator jest odzwierciedlany w nagłówku HTTP X-Goog-Channel-Id każdej wiadomości z powiadomieniem, którą otrzymasz na tym kanale.

  • 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 dla tego kanału powiadomień. To jest 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 pasuje do docelowej nazwy 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 dowolną wartość ciągu 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 dołączany do nagłówka HTTP X-Goog-Channel-Token w ramach 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.

  • expiration ciąg znaków właściwości ustawiony na sygnatura czasowa Unixa (w milisekundach) z datą i godziną, kiedy interfejs Directory API ma przestać wysyłać wiadomości na ten kanał powiadomień.

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

Więcej informacji o tym żądaniu znajdziesz w metodie watch zasobu Users w dokumentacji interfejsu 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 kanału powiadomień, który właśnie utworzono. Przykład takiej odpowiedzi znajdziesz poniżej.

{
  "kind": "api#channel",
  "id": "01234567-89ab-cdef-0123456789ab", // ID you specified for this channel.
  "resourceId": "B4ibMJiIhTjAQd7Ff2K2bexk8G4", // ID of the watched resource.
  "resourceUri": "https://admin.googleapis.com/admin/directory/v1/users?domain=domain&event=event", // Version-specific ID of the watched resource.
  "token": "target=myApp-myFilesChannelDest", // Present only if one was provided.
  "expiration": 1384823632000, // 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 w metodzie watch w przypadku zasobu Users w przewodniku po interfejsie API.

Synchronizowanie wiadomości

Po utworzeniu kanału powiadomień, który ma obserwować zasób, interfejs Directory API wysyła komunikat sync, aby wskazać, że powiadomienia są już wysyłane. Wartość nagłówka HTTP X-Goog-Resource-State w tych wiadomościach to sync. Ze względu na problemy z synchronizacją sieci może się zdarzyć, że wiadomość sync zostanie wysłana, zanim otrzymasz odpowiedź metody watch.

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

Poniżej przedstawiamy format wiadomości sync wysyłanych przez interfejs Directory API do adresu URL odbierającego.

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 na tym kanale ma numer większy od poprzedniego, ale numery wiadomości nie będą uporządkowane.

Odnawianie kanałów powiadomień

Kanał powiadomień może mieć czas ważności określony przez Twoje żądanie lub przez limity wewnętrzne interfejsu Directory API lub domyślne wartości (używana jest bardziej restrykcyjna wartość). 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ń. Gdy kanał zbliża się do końca, musisz go zastąpić nowym, wywołując metodę watch. Jak zawsze, w przypadku właściwości id nowego kanału musisz użyć unikalnej wartości. Pamiętaj, że prawdopodobnie będzie okres „nakładania się”, gdy 2 kanały powiadomień dla tego samego zasobu będą aktywne.

otrzymywanie powiadomień;

Za każdym razem, gdy obserwowany zasób ulegnie zmianie, Twoja aplikacja otrzyma powiadomienie o tej zmianie. Interfejs Directory API wysyła te wiadomości jako żądania HTTPS POST do adresu URL podanego jako address właściwość tego kanału powiadomień.

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 Directory API w przypadku adresu URL odbierającego zawierają te nagłówki HTTP:

Nagłówek Opis
Zawsze widoczne
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. Numery wiadomości zwiększają się 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 zasobu monitorowanego, który jest specyficzny dla wersji interfejsu API.
Czasami
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.

Treść komunikatu z powiadomieniem dla użytkowników zawiera te informacje:

Właściwość Opis
kind Identyfikuje ten zasób jako zasób użytkownika. Wartość: ustalony ciąg znaków „admin#directory#user”.
id Unikalny identyfikator zasobu użytkownika.
etag ETag wiadomości z powiadomieniem. Różni się od ETag zasobu Użytkownik.
primaryEmail Podstawowy adres e-mail użytkownika.

Przykłady

Komunikaty o zdarzeniach dotyczących zasobów User mają ogólny format:

POST https://mydomain.com/notifications // Your receiving URL.
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 // Your receiving URL.
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 interfejsu API Google i zwraca wartości 500, 502, 503 lub 504, interfejs Directory API próbuje ponownie z eksponencjalnym opóźnieniem. Każdy inny kod stanu zwrotu jest uznawany za błąd wiadomości.

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

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