Odbieraj powiadomienia push

W tym dokumencie opisujemy, jak korzystać z powiadomień push, które informują aplikację o zmianie zasobu.

Przegląd

Interfejs Kalendarza Google API udostępnia powiadomienia push, które umożliwiają monitorowanie zmian w zasobach. Dzięki tej funkcji możesz zwiększyć wydajność aplikacji. Pozwala ona wyeliminować dodatkowe koszty sieciowe i obliczeniowe związane z sondowaniem zasobów w celu sprawdzenia, czy uległy zmianie. Gdy obserwowany zasób ulegnie zmianie, interfejs API Kalendarza Google powiadomi o tym Twoją aplikację.

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

  • Skonfiguruj adres URL odbioru lub odbiornik wywołań zwrotnych „webhook”.

    Jest to serwer HTTPS, który obsługuje komunikaty powiadomień 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 routingu komunikatów powiadomień. W ramach konfiguracji kanału musisz określić adres URL, na który chcesz otrzymywać powiadomienia. Gdy zasób kanału ulegnie zmianie, interfejs Kalendarza Google API wyśle komunikat powiadomienia jako POST żądanie na ten adres URL.

Obecnie interfejs Kalendarza Google 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 Kalendarz Google API informuje aplikację o każdej zmianie obserwowanego zasobu.

Wysyłanie żądań obserwowania

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

https://www.googleapis.com/API_NAME/API_VERSION/RESOURCE_PATH/watch

Aby skonfigurować kanał powiadomień o zmianach w a określonym 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 powiedzie się, jeśli biecieżący użytkownik nie jest właścicielem tego zasobu ani nie ma do niego dostępu.

Przykład

Rozpocznij obserwowanie zmian 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 id kanału, type jako web_hook oraz adres URL odbioru w address. Opcjonalnie możesz też podać:

  • token, który będzie używany jako token kanału.
  • expiration – czas wygaśnięcia w milisekundach.

Właściwości wymagane

W każdym żądaniu watch musisz podać te pola:

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

    Ustawiona wartość identyfikatora jest zwracana w nagłówku HTTP X-Goog-Channel-Id każdego komunikatu powiadomienia , który otrzymujesz na tym kanale.

  • Ciąg znaków 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ń. 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 zainstalowany jest 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 żądaniu watch możesz też określić te pola opcjonalne:

  • Właściwość token, która określa dowolną wartość ciągu znaków , która ma być używana jako token kanału. Tokeny kanałów powiadomień możesz wykorzystywać do różnych celów. Możesz na przykład użyć tokena, aby sprawdzić, czy każda wiadomość przychodząca jest przeznaczona dla kanału utworzonego przez Twoją aplikację (aby mieć pewność, że powiadomienie nie jest fałszywe), lub aby kierować komunikat do odpowiedniego miejsca w aplikacji na podstawie przeznaczenia tego kanału. Maksymalna długość: 256 znaków.

    Token jest dołączany do X-Goog-Channel-Token nagłówka HTTP w każdym komunikacie powiadomienia , który Twoja aplikacja otrzymuje na tym kanale.

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

    • Używanie rozszerzalnego formatu kodowania, np. parametrów zapytania URL . Przykład: forwardTo=hr&createdBy=mobile

    • Nie podawanie 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, kiedy interfejs Kalendarza Google API ma przestać wysyłać komunikaty na tym kanale powiadomień.

    Jeśli kanał ma czas wygaśnięcia, jest on dołączany jako wartość nagłówka HTTP X-Goog-Channel-Expiration (w formacie czytelnym dla człowieka) w każdym komunikacie powiadomienia, który Twoja aplikacja otrzymuje na tym kanale.

Więcej informacji o żądaniu znajdziesz w dokumentacji interfejsu API w opisie metody watch dla zasobów ACL, CalendarList, Events i Settings.

Odpowiedź na żądanie obserwowania

Jeśli żądanie watch pomyślnie utworzy kanał powiadomień, zwróci kod stanu HTTP 200 OK status code.

Treść wiadomości odpowiedzi na żądanie obserwowania zawiera informacje o utworzonym 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 interfejsu API.
  • id: identyfikator określony dla tego kanału.
  • resourceId: identyfikator obserwowanego zasobu.
  • resourceUri: identyfikator obserwowanego zasobu właściwy dla wersji.
  • token: token podany w treści żądania.
  • expiration: czas wygaśnięcia kanału jako sygnatura czasowa Unix w milisekundach.

Oprócz właściwości wysł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 przekazać do innych operacji na kanale powiadomień, np. gdy chcesz przestać otrzymywać powiadomienia.

Więcej informacji o odpowiedzi znajdziesz w dokumentacji interfejsu API w opisie metody watch dla zasobów ACL, CalendarList, Events i Settings.

Komunikat synchronizacji

Po utworzeniu kanału powiadomień do obserwowania zasobu interfejs Google Calendar API wysyła komunikat sync, aby wskazać, że powiadomienia są uruchamiane. Wartość nagłówka HTTP X-Goog-Resource-State dla tych komunikatów to sync. Ze względu na problemy z synchronizacją sieci możesz otrzymać komunikat sync jeszcze przed otrzymaniem odpowiedzi na metodę watch.

Powiadomienie sync można zignorować, ale możesz też z niego korzystać. 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, aby przestać otrzymywać powiadomienia. Powiadomienia sync możesz też używać do inicjowania, aby przygotować się na późniejsze zdarzenia.

Poniżej przedstawiamy format komunikatów sync, które interfejs Kalendarza Google API wysyła na Twój adres URL odbioru.

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

Komunikaty synchronizacji zawsze mają wartość nagłówka HTTP X-Goog-Message-Number równą 1. Każde kolejne powiadomienie na tym kanale ma numer komunikatu większy od poprzedniego, ale numery komunikatów nie są sekwencyjne.

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 ustawienia domyślne interfejsu Google Calendar API (używana jest wartość bardziej restrykcyjna). Czas wygaśnięcia kanału, jeśli taki istnieje, jest dołączany jako sygnatura czasowa Unix w informacjach zwracanych przez metodę watch. Ponadto data i godzina wygaśnięcia są dołączane (w formacie czytelnym dla człowieka) w każdym komunikacie powiadomienia, który Twoja aplikacja otrzymuje na tym kanale, w nagłówku HTTP X-Goog-Channel-Expiration.

Obecnie nie ma automatycznego sposobu odnowienia kanału powiadomień. Gdy kanał zbliża się do wygaśnięcia, musisz zastąpić go nowym, wywołując metodę watch. Jak zawsze, musisz użyć unikalnej wartości dla 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ń dla tego samego zasobu.

Otrzymywanie powiadomień

Gdy obserwowany zasób ulegnie zmianie, Twoja aplikacja otrzyma komunikat powiadomienia opisujący tę zmianę. Interfejs Kalendarza Google API wysyła te komunikaty jako żądania POST HTTPS na adres URL określony jako address właściwość tego kanału powiadomień.

Interpretowanie formatu komunikatu powiadomienia

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

Nagłówki

Komunikaty powiadomień publikowane przez interfejs Kalendarza Google API na Twój adres URL odbioru zawierają te nagłówki HTTP:

Nagłówek Opis
Zawsze obecny
X-Goog-Channel-ID UUID lub inny unikalny ciąg znaków podany przez Ciebie w celu identyfikacji tego kanału powiadomień.
X-Goog-Message-Number Liczba całkowita, która identyfikuje ten komunikat na tym kanale powiadomień. W przypadku komunikatów sync wartość jest zawsze równa 1. Numery komunikatów zwiększają się w przypadku każdego kolejnego komunikatu 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 właściwy dla wersji interfejsu API.
Czasami obecny
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 Twoją aplikację, i którego możesz użyć do zweryfikowania źródła powiadomienia. Występuje tylko wtedy, gdy jest zdefiniowany.

Komunikaty powiadomień publikowane przez interfejs Calendar API na Twój adres URL odbioru nie zawierają treści wiadomości. Te komunikaty nie zawierają szczegółowych informacji o zaktualizowanych zasobach. Aby zobaczyć pełne szczegóły zmian, musisz wykonać kolejne wywołanie interfejsu API.

Przykład

Komunikat powiadomienia o zmianie zmodyfikowanej kolekcji wydarzeń:

POST https://mydomain.com/notifications
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

Odpowiadanie 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 500, 502, 503 lub 504, interfejs Kalendarza Google API ponawia próbę z wzrastającym czasem do ponowienia. Każdy inny kod stanu zwrotu jest uważany za niepowodzenie komunikatu.

Informacje o zdarzeniach powiadomień interfejsu Kalendarza Google API

W tej sekcji znajdziesz szczegółowe informacje o komunikatach powiadomień, które możesz otrzymywać podczas korzystania z powiadomień push w interfejsie Google Calendar API.

X-Goog-Resource-State Dotyczy: Dostarczane, gdy:
sync Listy ACL, listy kalendarzy, wydarzenia, ustawienia. Nowy kanał został utworzony. Można teraz odbierać powiadomienia.
exists Listy ACL, listy kalendarzy, wydarzenia, ustawienia. Zasób uległ zmianie. Możliwe zmiany to utworzenie nowego zasobu lub zmodyfikowanie bądź usunięcie istniejącego zasobu.

Zatrzymywanie powiadomień

Właściwość expiration określa, kiedy powiadomienia mają się automatycznie zatrzymać. Możesz przestać otrzymywać powiadomienia z danego kanału przed jego wygaśnięciem, wywołując metodę stop pod tym adresem URI:

https://www.googleapis.com/workspace/calendar/api/v3/reference/channels/stop

Ta metoda wymaga podania co najmniej właściwości kanału id i resourceId, jak pokazano w przykładzie poniżej. Pamiętaj, że jeśli interfejs Google Calendar API ma kilka typów zasobów z metodami watch, to jest tylko 1 metoda stop.

Kanał mogą zatrzymać tylko użytkownicy z odpowiednimi uprawnieniami. 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 (identyfikowanego przez identyfikatory klienta OAuth 2.0 z tokenów autoryzacji), który utworzył kanał.
  • Jeśli kanał został utworzony przez konto usługi, może go zatrzymać dowolny użytkownik z tego samego klienta.

Poniższy przykładowy kod pokazuje, jak przestać otrzymywać powiadomienia:

POST https://www.googleapis.com/workspace/calendar/api/v3/reference/channels/stop
  
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

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