Powiadomienia push

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

Przegląd

Interfejs Google Calendar 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 obserwowany zasób ulegnie zmianie, interfejs Google Calendar 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 zmieni się zasób kanału, interfejs Google Calendar API wysyła komunikat z powiadomieniem w postaci POSTżądania do tego adresu URL.

Obecnie interfejs Google Calendar API obsługuje powiadomienia o zmianach w zasobach Acl, CalendarList, Events i Settings.

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

Wysyłanie próśb dotyczących zegarka

Każdy zasób interfejsu Google Calendar API, który można obserwować, ma powiązaną metodę watch pod adresem 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 zakończy się niepowodzeniem, chyba że bieżący użytkownik jest właścicielem tego zasobu lub ma do niego uprawnienia dostępu.

Przykład

Aby zacząć obserwować zmiany w kolekcji wydarzeń w danym kalendarzu:

POST https://www.googleapis.com/calendar/v3/calendars/my_calendar@gmail.com/events/watch
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-myCalendarChannelDest",
  "expiration": 1426325213000
}

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.
  • expiration – czas w milisekundach, który określa czas wygaśnięcia żądanego kanału.

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 Google Calendar 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ą w formacie Unix (w milisekundach) daty i godziny, o której interfejs Google Calendar 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 opisie metody watch w przypadku zasobów Acl, CalendarList, Events i Settings w dokumentacji interfejsu API.

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": "o3hgv1538sdjfh",
  "resourceUri": "https://www.googleapis.com/calendar/v3/calendars/my_calendar@gmail.com/events",
  "token": "target=myApp-myCalendarChannelDest",
  "expiration": 1426325213000
}

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

  • kind: identyfikuje to jako zasób kanału API.
  • 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 dokumentacji API w sekcji metody watch dla zasobów Acl, CalendarList, Events i Settings.

Synchronizuj wiadomości

Po utworzeniu kanału powiadomień do obserwowania zasobu interfejs Google Calendar 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.

Poniżej przedstawiamy format syncwiadomości, które interfejs Google Calendar API wysyła na Twój adres URL odbiorcy.

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 ważności, którego wartość jest określana przez Twoje żądanie lub przez wewnętrzne limity lub wartości domyślne interfejsu Google Calendar 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 Google Calendar 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 interfejs Google Calendar 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, exists lub not_exists.
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 publikowane przez interfejs Google Calendar API na adres URL odbiorcy nie zawierają treści wiadomości. Te wiadomości nie zawierają szczegółowych informacji o zaktualizowanych zasobach. Aby zobaczyć pełne szczegóły zmian, musisz wykonać kolejne wywołanie interfejsu API.

Przykłady

Zmień wiadomość powiadomienia o zmodyfikowanej kolekcji zdarzeń:

POST https://mydomain.com/notifications // Your receiving URL.
Content-Type: application/json; utf-8
Content-Length: 0
X-Goog-Channel-ID: 4ba78bf0-6a47-11e2-bcfd-0800200c9a66
X-Goog-Channel-Token: 398348u3tu83ut8uu38
X-Goog-Channel-Expiration: Tue, 19 Nov 2013 01:13:52 GMT
X-Goog-Resource-ID:  ret08u3rv24htgh289g
X-Goog-Resource-URI: https://www.googleapis.com/calendar/v3/calendars/my_calendar@gmail.com/events
X-Goog-Resource-State:  exists
X-Goog-Message-Number: 10

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 Google Calendar API ponawia próbę z wykładniczym wycofywaniem. Każdy inny kod stanu zwrotu jest uznawany za błąd wiadomości.

Informacje o wydarzeniach powiadomień interfejsu Google Calendar API

Ta sekcja zawiera szczegółowe informacje o komunikatach z powiadomieniami, które możesz otrzymywać podczas korzystania z powiadomień push w interfejsie Google Calendar API.

X-Goog-Resource-State Dotyczy Dostarczono, gdy
sync Listy ACL, listy kalendarzy, wydarzenia, ustawienia. Nowy kanał został utworzony. Powinny zacząć przychodzić powiadomienia dotyczące tego kanału.
exists Listy ACL, listy kalendarzy, wydarzenia, ustawienia. Zasób został zmieniony. Możliwe zmiany to utworzenie nowego zasobu lub zmodyfikowanie bądź usunięcie istniejącego zasobu.

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/calendar/v3/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 Google Calendar API ma kilka typów zasobów, które mają metody 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/calendar/v3/channels/stop
  
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

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