Powiadomienia push

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

Omówienie

Interfejs Directory API umożliwia otrzymywanie powiadomień push, które pozwalają monitorować zmiany w zasobach. Dzięki tej funkcji możesz poprawić wydajność aplikacji. Pozwala wyeliminować dodatkową sieć i moc obliczeniową koszty związane z zasobami odpytywania w celu określenia, 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.

    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 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 Directory API wysyła powiadomienie jako POST do tego adresu URL.

Obecnie interfejs Directory API obsługuje powiadomienia o zmianach w zasób Users.

Tworzenie kanałów powiadomień

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

Wyślij prośby o zegarek

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). 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 User w jednej domenie mają postać ogólną:

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 obserwacji 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.
  }
}

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

Możliwe wartości parametru event to:

  • add: zdarzenie utworzone przez użytkownika
  • delete: wydarzenie usunięte przez użytkownika
  • makeAdmin: zdarzenie zmiany stanu administratora użytkownika
  • undelete: zdarzenie przywrócone przez użytkownika
  • update: zdarzenie zaktualizowania użytkownika

Uwaga: w przykładach poniżej pominięto treść żądania.

Sprawdź zdarzenia utworzone przez użytkowników dla domeny mydomain.com:

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

Sprawdź zdarzenia utworzone przez użytkowników dla klienta my_customer:

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

Właściwości wymagane

W przypadku każdego żądania 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.

    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 znaków 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 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 z tematem, który nie pasuje do celu 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. Możesz użyć kanału powiadomień 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 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 znaków właściwości expiration ustawiony na sygnatura czasowa Unix (w milisekundach) z datą i godziną, kiedy interfejs Directory API ma przestać wysyłać wiadomości na ten kanał 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 Users 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": "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 innego kanału powiadomień operacji, na przykład gdy chcesz przestać otrzymywać powiadomienia.

Więcej informacji o odpowiedzi znajdziesz w metodzie watch w przypadku zasobu Users w przewodniku po interfejsach API.

Synchronizuj wiadomość

Po utworzeniu kanału powiadomień, aby oglądać zasób, Interfejs Directory API wysyła komunikat sync, aby wskazać, że powiadomienia. Wartość nagłówka HTTP X-Goog-Resource-State tych wiadomości to sync. Ze względu na sieć problemy z czasem, możesz otrzymać komunikat sync jeszcze przed otrzymaniem odpowiedzi metody watch.

Powiadomienie sync możesz zignorować, ale możesz też z niego skorzystać. 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 wysyła interfejs Directory API 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 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 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 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 Directory API wysyła te wiadomości jako żądania HTTPS POST do adresu URL podanego jako address właściwość dla tego kanału powiadomień.

Interpretowanie formatu wiadomości powiadomienia

Wszystkie powiadomienia zawierają zestaw nagłówków HTTP z wartością X-Goog- prefiksy. 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 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 Liczba całkowita określająca tę wiadomość w przypadku tego powiadomienia kanał. 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 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 Identyfikator zasobu monitorowanego, który jest specyficzny dla wersji interfejsu API.
Czasami występują
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ę; aby zweryfikować źródło powiadomień. Występuje tylko wtedy, gdy jest zdefiniowany.

Wiadomości z powiadomieniami dla użytkowników zawierają w swoim treści 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 zasobu 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ętego 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 eksponencjalnie wydłużającymi się przerwami. 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 konkretnego kanału przed jego wygaśnięciem, wywołując metodę stop za pomocą tego URI:

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

Ta metoda wymaga podania przynajmniej id i resourceId, jak pokazano w przykład poniżej. Pamiętaj, że jeśli interfejs Directory API 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ć.

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