Powiadomienia push

Z tego dokumentu dowiesz się, jak korzystać z powiadomień push informujących aplikacji w przypadku zmiany zasobu.

Omówienie

Interfejs Google Calendar API zapewnia powiadomienia push, które umożliwiają monitorowanie zmian w zasobach. Możesz korzystać z tej funkcji, aby poprawić skuteczność Twojej aplikacji. Pozwala wyeliminować dodatkową sieć i moc obliczeniową koszty związane z zasobami odpytywania w celu określenia, czy uległy zmianie. Za każdym razem, gdy obserwowany zasób się zmieni, interfejs Google Calendar API powiadomi aplikacji.

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

  • Konfigurowanie adresu URL odbierania (webhooka) .

    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 zegarka.

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

Obecnie interfejs Google Calendar API obsługuje powiadomienia o zmianach w zasoby Acl, CalendarList, Events i Settings (Ustawienia).

Utwórz kanały powiadomień

Aby otrzymywać powiadomienia push, musisz skonfigurować kanał powiadomień dla każdego zasobu, który chcesz monitorować. Po ustawieniu kanałów powiadomień interfejs API Kalendarza Google informuje Twoją aplikację o każdym monitorowanym zasobie zmian.

Wyślij prośby o zegarek

Każdy dostępny do obserwacji zasób interfejsu Google Calendar API ma powiązany element watch w identyfikatorze URI o następującej formie:

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

Aby skonfigurować kanał powiadomień o wiadomościach o zmianach w określonego zasobu, wyślij żądanie POST do Metoda watch dla zasobu.

Każdy kanał powiadomień jest powiązany zarówno z konkretnym użytkownikiem, określonego zasobu (lub zbioru zasobów). Prośba o: watch nie powiedzie się, chyba że bieżący użytkownik jest właścicielem tego zasobu lub ma do niego uprawnienia dostępu.

Przykład

Zacznij obserwować zmiany w zbiorze 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", // 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 każdym żądaniu watch musisz wypełnić te pola:

  • Ciąg znaków właściwości id, który jednoznacznie określa tę właściwość nowy kanał powiadomień w projekcie. Zalecamy użycie uniwersalny identyfikator (UUID) lub podobny jest unikalny ciąg 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 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 Google Calendar API może wysyłać powiadomienia do ten adres HTTPS, tylko jeśli został zainstalowany prawidłowy certyfikat SSL na serwerze WWW. 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

Te opcjonalne pola możesz też określić za pomocą Prośba o środki (watch):

  • 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. Na przykład możesz użyć atrybutu token do potwierdzenia, że każda przychodząca wiadomość pochodzi z kanału, utworzona aplikacja – by upewnić się, że powiadomienie nie jest wysyłane sfałszowana – lub aby skierować wiadomość do właściwego miejsca docelowego w: zgodnie z przeznaczeniem 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 właściwości expiration ustawiony na Sygnatura czasowa uniksowa (w milisekundach) daty i godziny, o której interfejs Google Calendar API ma zaprzestać wysyłania wiadomości z tego kanału 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.

Aby dowiedzieć się więcej o żądaniu, zapoznaj się z metodą watch dla zasobów Acl, CalendarList, Events i Settings, w dokumentacji 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": "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 przesłanych w ramach żądania parametr zwrócone informacje obejmują również resourceId i resourceUri, aby zidentyfikować zasób, który jest na nim obserwowany kanału 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 tutaj: watch dla zasobów Acl, CalendarList, Events i Settings, w dokumentacji API.

Zsynchronizuj wiadomość

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

Możesz bezpiecznie zignorować powiadomienie sync, ale możesz go użyć. 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 wiadomości sync, do których interfejs Google Calendar API wysyła 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 wygaśnięcia i podaną wartość określane na podstawie żądania lub wewnętrznych limitów interfejsu Google Calendar API lub wartości domyślne (stosowana jest wartość bardziej restrykcyjna). Wygaśnięcie kanału Godzina (jeśli go występuje), jest dołączana jako sygnatura czasowa uniksowa (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 można automatycznie odnowić 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 istnieje możliwość aby „pokrywać się” okresu, w którym dwa kanały powiadomień są aktywne takie same zasoby.

Otrzymuj powiadomienia

Po każdej zmianie obserwowanego zasobu aplikacja otrzymuje powiadomienie z opisem zmiany. Interfejs Google Calendar API wysyła te jako żądania HTTPS POST do adresu URL określonego jako address usługa dla tego powiadomienia kanał.

Interpretowanie formatu wiadomości powiadomienia

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

Nagłówki

Powiadomienia wysłane przez interfejs Google Calendar API do odbiorców Adres URL zawiera te nagłówki HTTP:

Nagłówek Opis
Zawsze wyświetlaj
X-Goog-Channel-ID Identyfikator UUID lub inny unikalny ciąg znaków podany przez Ciebie w celu identyfikacji kanału powiadomień.
X-Goog-Message-Number Liczba całkowita określająca tę wiadomość w przypadku tego powiadomienia kanał. W przypadku wiadomości typu sync zawsze wartość wynosi 1. Wiadomość ich liczba rośnie z każdą kolejną wiadomością na kanale, ale nie sekwencyjną.
X-Goog-Resource-ID Nieprzejrzysta 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, exists lub not_exists
X-Goog-Resource-URI specyficzny dla wersji interfejsu API identyfikatora obserwowanego zasobu,
Czasami występują
X-Goog-Channel-Expiration Data i godzina wygaśnięcia kanału powiadomień wyrażone w zrozumiałego dla człowieka. Występuje tylko wtedy, gdy został określony.
X-Goog-Channel-Token token kanału powiadomień ustawiony przez Twoją aplikację; aby zweryfikować źródło powiadomień. Występuje tylko wtedy, gdy zdefiniowano jego definicję.

Wiadomości z powiadomieniami publikowane przez interfejs Google Calendar API pod Twoim adresem URL odbiorcy nie zawierają treści. Komunikaty te nie zawierają konkretnych informacji o zaktualizowanych zasobach. Aby zobaczyć pełne szczegóły zmiany, trzeba wykonać kolejne wywołanie interfejsu API.

Przykłady

Zmiana wiadomości z powiadomieniem o zmodyfikowanej kolekcji wydarzeń:

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 oznaczyć powodzenie, można wyświetlić dowolny z tych kodów stanu: 200, 201, 202, 204 lub 102.

Jeśli Twoja usługa używa biblioteki klienta interfejsów API Google i zwraca 500, 502, 503 lub 504, interfejs Google Calendar API ponawia próby z wykładniczym czasem ponowienia. Każdy inny kod stanu zwrotu jest uważany za niepowodzenie otrzymania wiadomości.

Informacje o wydarzeniach związanych z powiadomieniami w interfejsie Google Calendar API

Ta sekcja zawiera szczegółowe informacje na temat powiadomień, które możesz otrzymywać podczas korzystania z powiadomień push za pomocą interfejsu Google Calendar API.

X-Goog-Resource-State Dotyczy Dostarczono, gdy
sync Listy kontroli dostępu, listy kalendarzy, wydarzenia, ustawienia. Utworzono nowy kanał. Zaczniesz otrzymywać związane z nim powiadomienia.
exists Listy kontroli dostępu, listy kalendarzy, wydarzenia, ustawienia. Wprowadzono zmianę w zasobie. Możliwe zmiany obejmują utworzenie nowego zasobu albo modyfikację lub usunięcie istniejącego.

Zatrzymaj powiadomienia

Właściwość expiration określa, kiedy powiadomienia mają być zatrzymywane automatycznie. Dostępne opcje wyłączyć otrzymywanie powiadomień z kanału, zanim zacznie się wyświetlać wygasa przez wywołanie metody stop na stronie ten identyfikator URI:

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

Ta metoda wymaga podania przynajmniej id i resourceId, jak pokazano w przykład poniżej. Pamiętaj, że jeśli interfejs Google Calendar 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 to samo tego samego klienta (zgodnie z identyfikatorami klienta OAuth 2.0 w sekcji tokeny uwierzytelniania), który utworzył kanał, może zatrzymać jego działanie.
  • Jeśli kanał został utworzony przez konto usługi, dowolny użytkownik z tego samego konta, może zatrzymać kanał.

Przeanalizuj przykładowy kod poniżej, aby dowiedzieć się, jak wyłączyć powiadomienia:

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"
}