Powiadomienia push

Stay organized with collections Save and categorize content based on your preferences.

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

Omówienie

Interfejs Google Calendar API zapewnia powiadomienia push, które pozwalają obserwować zmiany w zasobach. Możesz użyć tej funkcji, aby zwiększyć wydajność aplikacji. Pozwala to wyeliminować dodatkowe koszty sieci i mocy obliczeniowej związane z zasobami odpytywania w celu określenia, czy uległy zmianie. Za każdym razem, gdy zmieni się obserwowany zasób, interfejs Google Calendar API powiadomi Twoją aplikację.

Aby używać powiadomień push, musisz wykonać 2 rzeczy:

  • Skonfiguruj docelowy adres URL odbierania (inicjator webhooka).

    To serwer HTTPS, który obsługuje komunikaty powiadomień interfejsu API wywoływane po zmianie zasobu.

  • Skonfiguruj kanał powiadomień dla każdego punktu końcowego zasobów, który chcesz obejrzeć.

    Kanał określa informacje o routingu wiadomości z powiadomieniami. W ramach konfiguracji kanału określasz adres URL, na który chcesz otrzymywać powiadomienia. Za każdym razem, gdy zasób kanału ulegnie zmianie, interfejs Google Calendar API wyśle powiadomienie w postaci żądania POST na ten adres URL.

Obecnie interfejs Google Calendar API obsługuje powiadomienia o zmianach w zasobach ACL, CalendarList, Wydarzeniach i Ustawieniach.

Tworzenie kanałów powiadomień

Aby żądać powiadomień push, musisz skonfigurować kanał powiadomień dla każdego zasobu, który chcesz oglądać. Gdy skonfigurujesz kanały powiadomień, interfejs Google Calendar API poinformuje Twoją aplikację o każdej zmianie zasobu.

Zgłaszanie próśb o obejrzenie

Z każdym dostępnym do oglądania zasobem interfejsu Google Calendar API powiązana jest metoda watch z identyfikatorem URI takiej formy:

https://www.googleapis.com/apiName/apiVersion/resourcePath/watch

Aby skonfigurować kanał powiadomień dla wiadomości o zmianach w konkretnym zasobie, wyślij żądanie POST do metody watch dla tego zasobu.

Każdy kanał powiadomień jest powiązany z konkretnym użytkownikiem i określonym zasobem (lub zbiorem zasobów). Żądanie watch nie zostanie zrealizowane, jeśli bieżący użytkownik nie jest właścicielem ani właścicielem zasobu.

Przykład

Zacznij obserwować zmiany w kolekcji wydarzeń z danego kalendarza:

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", // Your channel ID.
  "type": "web_hook",
  "address": "https://mydomain.com/notifications", // Your receiving URL.
  ...
  "token": "target=myApp-myCalendarChannelDest", // (Optional) Your channel token.
  "expiration": 1426325213000 // (Optional) Your requested channel expiration time.
}

Właściwości wymagane

W przypadku każdego żądania watch musisz podać:

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

    Ustawiona wartość identyfikatora jest odczytywana w nagłówku X-Goog-Channel-Id każdej wiadomości z powiadomieniem dotyczącej tego kanału.

  • Ciąg 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 powiadomień z tego kanału powiadomień i odpowiada na nie. To jest adres URL wywołania zwrotnego webhooka i musi używać protokołu HTTPS.

    Pamiętaj, że interfejs Google Calendar API będzie mógł wysyłać powiadomienia na ten adres HTTPS tylko wtedy, gdy na serwerze WWW jest zainstalowany ważny certyfikat SSL. Nie prawidłowe certyfikaty to między innymi:

    • podpisane samodzielnie,
    • podpisane przez niezaufane źródło,
    • unieważnione.
    • Certyfikaty o temacie innym niż nazwa docelowego hosta.

Właściwości opcjonalne

W żądaniu watch możesz też określić te opcjonalne pola:

  • Właściwość token, która określa dowolną wartość ciągu znaków, który ma być używany jako token kanału. Tokenów kanału powiadomień można używać do różnych celów. Na przykład możesz użyć tokena, aby sprawdzić, czy każda wiadomość przychodzących pochodzi z kanału utworzonego przez aplikację, dzięki czemu powiadomienie nie będzie sfałszowane, lub aby kierować wiadomość do odpowiedniego miejsca docelowego w aplikacji na podstawie celu tego kanału. Maksymalna długość: 256 znaków.

    Token znajduje się w nagłówku HTTP X-Goog-Channel-Token każdej wiadomości z powiadomieniem, którą otrzymuje Twój kanał.

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

    • Użyj elastycznego formatu kodowania, takiego jak parametry zapytania z adresu URL. Przykład: forwardTo=hr&createdBy=mobile

    • Nie podawaj danych wrażliwych, takich jak tokeny OAuth.

  • Ciąg właściwości expiration ustawiony na sygnatura czasowa Unix (w ms) daty i godziny, kiedy interfejs Google Calendar API ma przestać wysyłać wiadomości dla tego kanału powiadomień.

    Jeśli czas trwania kanału jest określony, zostanie on uwzględniony jako wartość nagłówka HTTP X-Goog-Channel-Expiration (tym razem w postaci zrozumiałej dla człowieka) w każdym powiadomieniu wysyłanym do aplikacji przez ten kanał.

Więcej informacji o żądaniu znajdziesz w metodzie watch zasobów Acl, Calendar, zdarzeń i ustawień w API.

Obserwuj odpowiedź

Jeśli żądanie watch utworzy kanał powiadomień, będzie zwracać kod stanu HTTP 200 OK.

Treść wiadomości z odpowiedzi na zegarek zawiera informacje o stworzeniu właśnie utworzonego kanału powiadomień (przykład poniżej).

{
  "kind": "api#channel",
  "id": "01234567-89ab-cdef-0123456789ab"", // ID you specified for this channel.
  "resourceId": "o3hgv1538sdjfh", // ID of the watched resource.
  "resourceUri": "https://www.googleapis.com/calendar/v3/calendars/my_calendar@gmail.com/events", // Version-specific ID of the watched resource.
  "token": "target=myApp-myCalendarChannelDest", // Present only if one was provided.
  "expiration": 1426325213000, // Actual expiration time as Unix timestamp (in ms), if applicable.
}

Oprócz właściwości wysłanych w ramach żądania, zwracane informacje obejmują też resourceId i resourceUri, które wskazują zasób wyświetlany w tym kanale powiadomień.

Te informacje możesz przekazywać do innych operacji związanych z kanałami powiadomień, na przykład wtedy, gdy chcesz przestać otrzymywać powiadomienia.

Więcej informacji o odpowiedzi znajdziesz w opisie metody watch dotyczącej zasobów ACL, CalendarList, zdarzeń i ustawień w dokumentacji API.

Synchronizuj wiadomość

Gdy utworzysz nowy kanał powiadomień, żeby obejrzeć zasób, interfejs Google Calendar API wyśle sync, aby poinformować, że powiadomienia się rozpoczynają. Wartość nagłówka HTTP X-Goog-Resource-State tych wiadomości to sync. Ze względu na problemy z czasem sieciowym może się zdarzyć, że otrzymasz wiadomość sync, jeszcze zanim otrzymasz odpowiedź metody watch.

Możesz zignorować powiadomienie sync, ale możesz z niego skorzystać. Jeśli na przykład postanowisz nie zachowywać kanału, możesz użyć wartości X-Goog-Channel-ID i X-Goog-Resource-ID w wywołaniu, aby wyłączyć powiadomienia. Możesz też użyć powiadomienia sync, aby przeprowadzić inicjację na potrzeby przyszłych zdarzeń.

Format wiadomości sync wysyłanych przez interfejs Google Calendar API na adres docelowy 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 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 równą 1. Każde kolejne powiadomienie z tego kanału będzie mieć numer wiadomości wyższy od poprzedniego, ale numery wiadomości nie będą sekwencyjne.

Odnawianie kanałów powiadomień

Kanał powiadomień może mieć termin ważności, którego wartość jest potwierdzona przez żądanie lub wewnętrzne limity interfejsu API Kalendarza Google (używana jest bardziej restrykcyjna wartość). Czas wygaśnięcia kanału (jeśli go ma) jest podany jako sygnatura czasowa Unix (w ms) w informacjach zwracanych przez metodę watch. Dodatkowo data i godzina wygaśnięcia (w formacie czytelnym dla człowieka) jest podana w nagłówku HTTP X-Goog-Channel-Expiration w powiadomieniach, które aplikacja otrzymuje w związku z danym kanałem.

Obecnie nie ma możliwości automatycznego odnawiania kanału powiadomień. Gdy zbliża się data wygaśnięcia ważności kanału, musisz utworzyć nowy, wywołując metodę watch. Jak zawsze musisz użyć unikalnej wartości właściwości id nowego kanału. Pamiętaj, że okres między pokrywającymi się zasobami powiadomień dla tego samego zasobu może być taki sam.

Odbieranie powiadomień

Za każdym razem, gdy zmieni się obserwowany zasób, aplikacja otrzyma powiadomienie z opisem zmiany. Interfejs Google Calendar API wysyła te wiadomości jako żądania HTTPS POST na adres URL podany jako adres tego kanału powiadomień.

Omówienie formatu wiadomości z powiadomieniem

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

Nagłówki

Wiadomości wysyłane przez interfejs Google Calendar API na adres URL odbiorcy zawierają te nagłówki HTTP:

Nagłówek Opis
Zawsze dostępne
X-Goog-Channel-ID Identyfikator UUID lub inny unikalny ciąg znaków podany przez Ciebie do zidentyfikowania tego kanału powiadomień.
X-Goog-Message-Number Liczba całkowita, która identyfikuje tę wiadomość w przypadku tego kanału powiadomień. Wartość w przypadku sync wiadomości wynosi 1. Liczba wiadomości wzrasta w przypadku każdej kolejnej wiadomości na kanale, ale nie są one sekwencyjne.
X-Goog-Resource-ID Nieprzezroczysta wartość identyfikująca oglądany zasób. Ten identyfikator jest stały w przypadku wersji 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 specyficzny dla interfejsu API dla obserwowanego zasobu.
Czasami występuje
X-Goog-Channel-Expiration Data i godzina wygaśnięcia kanału powiadomień podana w postaci zrozumiałej dla człowieka. Wartość dostępna tylko wtedy, gdy jest zdefiniowana.
X-Goog-Channel-Token Token kanału powiadomień ustawiony przez Twoją aplikację, którego możesz używać do weryfikowania źródła powiadomień. Jest obecny tylko wtedy, gdy jest zdefiniowany.

Wiadomości 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 zmiany, musisz wykonać kolejne wywołanie interfejsu API.

Przykłady

Zmiana powiadomienia o zmodyfikowanym zbiorze 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

Odpowiadanie na powiadomienia

Aby wskazać, że projekt zakończył się powodzeniem, możesz użyć dowolnego z tych kodów stanu: 200, 201, 202, 204 lub 102.

Jeśli Twoja usługa używa biblioteki klienta interfejsu API Google i zwraca 500,502, 503 lub 504, Google Calendar API ponawia próby za pomocą wykładniczego ponowienia. Każdy inny kod stanu zwrotu jest uznawany za niepowodzenie wiadomości.

Omówienie zdarzeń powiadomień interfejsu Google Calendar API

Ta sekcja zawiera szczegółowe informacje na temat wiadomości, jakie możesz otrzymywać, gdy używasz powiadomień push za pomocą interfejsu Google Calendar API.

X-Goog-Resource-State Dotyczy Dostarczono, gdy
sync Listy ACL, listy kalendarzy, wydarzenia i ustawienia. Utworzono nowy kanał. Możesz zacząć otrzymywać o nim powiadomienia.
exists Listy ACL, listy kalendarzy, wydarzenia i ustawienia. Wystąpiła zmiana w zasobie. Możliwe zmiany obejmują utworzenie nowego zasobu lub zmianę lub usunięcie istniejącego zasobu.

Zatrzymuję powiadomienia

Data ważności wygasa, gdy powiadomienia są zatrzymywane automatycznie. Możesz zrezygnować z otrzymywania powiadomień z danego kanału, zanim straci ważność, wywołując metodę stop za pomocą tego identyfikatora URI:

https://www.googleapis.com/calendar/v3/channels/stop

Ta metoda wymaga podania właściwości co najmniej id i właściwości resourceId, jak pokazano w poniższym przykładzie. Pamiętaj, że nawet jeśli interfejs Google Calendar API zawiera 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żeli kanał został utworzony przez zwykłego użytkownika, może to powstrzymać tylko ten sam użytkownik (zgodnie z identyfikatorami klienta OAuth 2.0), który utworzył kanał.
  • Jeśli kanał został utworzony za pomocą konta usługi, wszyscy użytkownicy tego samego klienta mogą go zatrzymać.
POST https://www.googleapis.com/calendar/v3/channels/stop
  
Authorization: Bearer {auth_token_for_current_user}
Content-Type: application/json

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