Powiadomienia o zmianach zasobów

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

Przegląd

Interfejs Google Drive API udostępnia powiadomienia push, dzięki którym możesz monitorować zmiany w zasobach. Dzięki tej funkcji możesz zwiększyć wydajność swojej aplikacji. Pozwala wyeliminować dodatkowe koszty sieci i obliczeniowe związane z zasobami odpytywania w celu określenia, czy się zmieniły. Gdy obserwowany zasób ulegnie zmianie, interfejs Google Drive API powiadamia aplikację.

Aby korzystać z powiadomień push, musisz zrobić 2 rzeczy:

• Skonfiguruj adres URL odbierania lub odbiornik wywołania zwrotnego „webhooka”.

  Jest to serwer HTTPS obsługujący komunikaty z powiadomieniami interfejsu API, które są aktywowane po zmianie zasobu.

• Skonfiguruj (kanał powiadomień) dla każdego punktu końcowego zasobu, który chcesz oglądać.

  Kanał określa informacje dotyczące routingu wiadomości z powiadomieniami. Podczas konfigurowania kanału musisz określić adres URL, na który chcesz otrzymywać powiadomienia. Przy każdej zmianie zasobu kanału interfejs Google Drive API wysyła na ten adres URL powiadomienie jako żądanie POST.

Uwaga: słowo „kanał” używane w tym dokumencie odnosi się do kanału powiadomień, a nie do innych typów kanałów używanych w tym interfejsie API lub usłudze.

Obecnie interfejs Google Drive API obsługuje powiadomienia o zmianach w metodach files i changes.

Tworzenie kanałów powiadomień

Aby wysyłać żądania powiadomień push, musisz skonfigurować kanał powiadomień dla każdego zasobu, który chcesz monitorować. Po skonfigurowaniu kanałów powiadomień interfejs Google Drive API informuje Twoją aplikację o zmianie jakichkolwiek obserwowanych zasobów.

Wysyłaj prośby o zegarek

Każdy dostępny do obejrzenia zasób interfejsu Google Drive API ma powiązaną metodę watch pod identyfikatorem URI mającym postać:

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

Aby skonfigurować kanał powiadomień dla wiadomości o zmianach w określonym 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 zbiorem zasobów). Żądanie watch nie zostanie zrealizowane, chyba że bieżący użytkownik lub konto usługi jest właścicielem zasobu lub ma uprawnienia dostępu do niego.

Przykłady

Poniższy przykładowy kod pokazuje, jak za pomocą metody files.watch użyć zasobu channels, aby rozpocząć obserwację zmian w pojedynczym zasobie files:

POST https://www.googleapis.com/drive/v3/files/fileId/watch
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
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 files channel token.
  "expiration": 1426325213000 // (Optional) Your requested channel expiration date and time.
}

Poniższy przykładowy kod pokazuje, jak użyć zasobu channels, aby rozpocząć oglądanie wszystkich changes za pomocą metody changes.watch:

POST https://www.googleapis.com/drive/v3/changes/watch
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

{
  "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a77", // Your channel ID.
  "type": "web_hook",
  "address": "https://mydomain.com/notifications", // Your receiving URL.
  ...
  "token": "target=myApp-myChangesChannelDest", // (Optional) Your changes channel token.
  "expiration": 1426325213000 // (Optional) Your requested channel expiration date and time.
}

Właściwości wymagane

W przypadku każdego żądania watch musisz wypełnić te pola:

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

  Ustawiona wartość identyfikatora jest powtarzana w nagłówku HTTP X-Goog-Channel-Id każdej wiadomości powiadomienia otrzymanej w związku z danym kanałem.

• Ciąg tekstowy właściwości type ustawiony na wartość web_hook.

• Ciąg właściwości address ustawiony na URL, który nasłuchuje i odpowiada na powiadomienia z tego kanału powiadomień. To jest adres URL wywołania zwrotnego webhooka, który musi używać protokołu HTTPS.

  Pamiętaj, że interfejs Google Drive 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 podmiotem niezgodnym z docelową nazwą 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 wartość dowolnego ciągu znaków do użycia jako token kanału. Tokenów kanałów powiadomień możesz używać 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 upewnić się, że powiadomienie nie jest próbą podszywania się) lub aby przekierować wiadomość do właściwego miejsca w aplikacji na podstawie przeznaczenia tego kanału. Maksymalna długość: 256 znaków.

  Token znajduje się w nagłówku HTTP X-Goog-Channel-Token w każdej wiadomości powiadomienia, którą aplikacja otrzymuje dla tego kanału.

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

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

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

  Uwaga: jeśli musisz wysłać dane poufne, przed dodaniem ich do tokena upewnij się, że są one zaszyfrowane.

• Ciąg właściwości expiration ustawiony na sygnatura czasowa uniksową (w milisekundach) daty i godziny, kiedy interfejs Google Drive API ma przestać wysyłać komunikaty z tego kanału powiadomień.

  Jeśli kanał ma określony czas ważności, jest on podawany jako wartość nagłówka HTTP X-Goog-Channel-Expiration (w formacie zrozumiałym dla człowieka) w każdej wiadomości z powiadomieniem otrzymywanej przez aplikację dla tego kanału.

Uwaga: w przypadku interfejsu Google Drive API maksymalny czas wygaśnięcia wynosi 86 400 sekund (1 dzień) po aktualnej godzinie w przypadku zasobu files i 604 800 sekund (1 tydzień) w przypadku changes. Jeśli nie ustawisz w żądaniu właściwości expiration, czas wygaśnięcia będzie domyślnie ustawiony na 3600 sekund po aktualnej godzinie.

Więcej informacji o tym żądaniu znajdziesz w opisie metody watch w przypadku metod files i changes w dokumentacji interfejsu API.

Obejrzyj odpowiedź

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

Treść wiadomości odpowiedzi zegarka zawiera informacje o nowo utworzonym kanale powiadomień, jak pokazano w poniższym przykładzie.

{
  "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/drive/v3/files/o3hgv1538sdjfh", // Version-specific ID of the watched resource.
  "token": "target=myApp-myFilesChannelDest", // Present only if one was provided.
  "expiration": 1426325213000, // Actual expiration date and time as UNIX timestamp (in milliseconds), if applicable.
}

Oprócz właściwości wysłanych w ramach żądania zwrócone informacje obejmują też resourceId i resourceUri pozwalające zidentyfikować zasób, który chcesz obserwować w tym kanale powiadomień.

Uwaga: właściwość resourceId to stabilny identyfikator zasobu niezależny od wersji. Właściwość resourceUri to kanoniczny identyfikator URI obserwowanego zasobu w kontekście bieżącej wersji interfejsu API, więc jest zależna od wersji.

Możesz przekazać zwrócone informacje do innych operacji w kanale powiadomień, na przykład kiedy chcesz przestać otrzymywać powiadomienia.

Więcej informacji o odpowiedzi znajdziesz w dokumentacji metody watch dotyczącej metod files i changes w dokumentacji interfejsu API.

Synchronizuj wiadomość

Gdy utworzysz kanał powiadomień w celu obejrzenia zasobu, interfejs Google Drive API wysyła komunikat sync informujący o rozpoczęciu powiadomień. Wartość nagłówka HTTP X-Goog-Resource-State dla tych wiadomości to sync. Ze względu na problemy z czasem sieci możesz otrzymać komunikat sync jeszcze przed otrzymaniem odpowiedzi metody watch.

Możesz bezpiecznie zignorować powiadomienie sync, 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, aby przestać otrzymywać powiadomienia. Możesz też użyć powiadomienia sync, aby przeprowadzić inicjalizację, aby przygotować się na późniejsze zdarzenia.

Poniżej znajdziesz format komunikatów sync, które interfejs API Dysku Google wysyła na 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 mają zawsze wartość nagłówka HTTP X-Goog-Message-Number o wartości 1. Każde kolejne powiadomienie z tego kanału ma numer wiadomości większy od poprzedniego, przy czym numery wiadomości nie są ułożone kolejne.

Odnów kanały powiadomień

Kanał powiadomień może mieć czas wygaśnięcia. Wartość może być określana na podstawie żądania albo dowolnych wewnętrznych limitów interfejsu API Dysku Google lub wartości domyślnych (stosowana jest bardziej restrykcyjna wartość). Czas wygaśnięcia kanału, jeśli go ma, jest podawany jako sygnatura czasowa uniksowa (w milisekundach) w informacjach zwracanych przez metodę watch. Dodatkowo data i godzina wygaśnięcia są podawane (w formacie czytelnym dla człowieka) w każdej wiadomości powiadomienia odbieranej przez aplikację dla danego kanału w nagłówku HTTP X-Goog-Channel-Expiration.

Obecnie nie ma możliwości automatycznego 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 właściwości id nowego kanału. Zwróć uwagę, że w przypadku aktywnych kanałów powiadomień dotyczących tego samego zasobu może wystąpić okres „nakładanie się”.

Odbieranie powiadomień

Po każdej zmianie obserwowanego zasobu aplikacja otrzyma powiadomienie z opisem tej zmiany. Interfejs Google Drive API wysyła te komunikaty jako żądania HTTPS POST na adres URL podany przez Ciebie jako usługa address dla tego kanału powiadomień.

Uwaga: żądania HTTPS dostarczenia powiadomień określają klienta użytkownika APIs-Google i przestrzegają dyrektyw pliku robots.txt zgodnie z opisem w artykule Klienty użytkownika Google API.

Interpretowanie formatu wiadomości z powiadomieniem

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łówków,

Komunikaty z powiadomieniami publikowane przez interfejs Google Drive API na otrzymany adres URL mają te nagłówki HTTP:

Nagłówek	Opis
Zawsze obecne
X-Goog-Channel-ID	Identyfikator UUID lub inny unikalny ciąg podany przez Ciebie, aby zidentyfikować ten kanał powiadomień.
X-Goog-Message-Number	Liczba całkowita identyfikująca tę wiadomość w kanale powiadomień. W przypadku sync wiadomości wartość to zawsze 1. Każda kolejna wiadomość na kanale zwiększa liczbę wiadomości, ale nie jedna po drugiej.
X-Goog-Resource-ID	Nieprzejrzysta 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, add, remove, update, trash, untrash oraz change.
X-Goog-Resource-URI	Identyfikator wersji interfejsu API obserwowanego zasobu.
Czasami obecne
X-Goog-Changed	Dodatkowe informacje o zmianach. Możliwe wartości: content, parents, children lub permissions. Nie podano w przypadku sync wiadomości.
X-Goog-Channel-Expiration	Data i godzina wygaśnięcia kanału powiadomień podane w formacie zrozumiałym dla człowieka. Widoczny tylko wtedy, gdy został zdefiniowany.
X-Goog-Channel-Token	Token kanału powiadomień ustawiony przez Twoją aplikację, którego możesz użyć do zweryfikowania źródła powiadomień. Widoczny tylko wtedy, gdy został zdefiniowany.

Powiadomienia z files i changes są puste.

Przykłady

Zmień wiadomość z powiadomieniem dotyczącą files zasobu, która nie zawiera treści żądania:

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/drive/v3/files/ret08u3rv24htgh289g
X-Goog-Resource-State:  update
X-Goog-Changed: content,properties
X-Goog-Message-Number: 10

Zmiana powiadomienia o zmianie wiadomości dotyczącej changes zasobu, która zawiera treść żądania:

POST https://mydomain.com/notifications // Your receiving URL.
Content-Type: application/json; utf-8
Content-Length: 118
X-Goog-Channel-ID: 8bd90be9-3a58-3122-ab43-9823188a5b43
X-Goog-Channel-Token: 245t1234tt83trrt333
X-Goog-Channel-Expiration: Tue, 19 Nov 2013 01:13:52 GMT
X-Goog-Resource-ID:  ret987df98743md8g
X-Goog-Resource-URI: https://www.googleapis.com/drive/v3/changes
X-Goog-Resource-State:  changed
X-Goog-Message-Number: 23

{
  "kind": "drive#changes"
}

Odpowiedz na powiadomienia

Aby pokazać, że 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 API Dysku Google ponawia próbę z wykładniczym czasem ponowienia. Każdy inny kod stanu zwrotu jest uznawany za niepowodzenie wiadomości.

Zdarzenia powiadomień interfejsu Google Drive API

Ta sekcja zawiera szczegółowe informacje o wiadomościach z powiadomieniami, które możesz otrzymywać, gdy używasz powiadomień push z interfejsem Google Drive API.

X-Goog-Resource-State	Dotyczy	Dostarczone, gdy
sync	files, changes	Kanał został utworzony. Teraz możesz spodziewać się powiadomień na ten temat.
add	files	Zasób został utworzony lub udostępniony.
remove	files	Istniejący zasób został usunięty lub cofnięto udostępnianie.
update	files	Zaktualizowano co najmniej jedną właściwość (metadane) zasobu.
trash	files	Zasób został przeniesiony do kosza.
untrash	files	Zasób został usunięty z kosza.
change	changes	Dodano co najmniej 1 element historii zmian.

Z czasem do tej listy mogą być dodawane dodatkowe zdarzenia dotyczące stanu zasobów. Mogą wystąpić nieoczekiwane typy zdarzeń. Moduły obsługi zdarzeń powinny je zignorować.

W przypadku zdarzeń update może być podany nagłówek HTTP X-Goog-Changed. Ten nagłówek zawiera rozdzieloną przecinkami listę opisującą typy wprowadzonych zmian.

Typ zmiany	Znaczenie
content	Zawartość zasobu została zaktualizowana.
properties	Zaktualizowano co najmniej jedną właściwość zasobu.
parents	Dodano lub usunięto co najmniej jeden element nadrzędny zasobu.
children	Dodano lub usunięto co najmniej 1 podrzędny zasób.
permissions	Uprawnienia zasobu zostały zaktualizowane.

Przykład z nagłówkiem X-Goog-Changed:

X-Goog-Resource-State: update
X-Goog-Changed: content, permissions

Zatrzymaj powiadomienia

Właściwość expiration określa, kiedy powiadomienia mają się automatycznie zatrzymać. Możesz zrezygnować z otrzymywania powiadomień z konkretnego kanału, zanim straci ważność, wywołując metodę stop pod tym identyfikatorem URI:

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

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

Tylko użytkownicy z odpowiednimi uprawnieniami mogą zablokować kanał. W szczególności:

• Jeśli kanał został utworzony przy użyciu zwykłego konta użytkownika, tylko ten sam użytkownik tego samego klienta (identyfikowany za pomocą identyfikatorów klienta OAuth 2.0 w tokenach uwierzytelniania), który utworzył kanał, może go zatrzymać.
• Jeśli kanał został utworzony przy użyciu konta usługi, może go zatrzymać każdy użytkownik korzystający z tego samego klienta.

Z tego przykładowego kodu dowiesz się, jak przestać otrzymywać powiadomienia:

POST https://www.googleapis.com/drive/v3/channels/stop
  
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

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