Powiadomienia o zmianach zasobów

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

Przegląd

Interfejs Google Drive API udostępnia powiadomienia push, które pozwalają monitorować zmiany 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 Google Drive API 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 Google Drive API wyśle komunikat powiadomienia jako POST żądanie na ten adres URL.

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

Tworzenie kanałów powiadomień

Aby poprosić o powiadomienia push, musisz skonfigurować kanał powiadomień dla każdego zasobu, który chcesz monitorować. Gdy skonfigurujesz kanały powiadomień, interfejs Google Drive API będzie informować Twoją aplikację o każdej zmianie obserwowanego zasobu.

Wysyłanie żądań obserwowania

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

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

Aby skonfigurować kanał powiadomień dotyczący zmian 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 zostanie zrealizowane, chyba że bieżący użytkownik lub konto usługi jest właścicielem tego zasobu albo ma do niego dostęp.

Przykłady

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

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",
  "type": "web_hook",
  "address": "https://mydomain.com/notifications",
  ...
  "token": "target=myApp-myFilesChannelDest",
  "expiration": 1426325213000
}

W treści żądania podaj id kanału, type jako web_hook oraz adres URL odbioru w polu address. Opcjonalnie możesz też podać:

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

Poniższy przykładowy kod pokazuje, jak użyć zasobu channels, aby rozpocząć obserwowanie 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",
  "type": "web_hook",
  "address": "https://mydomain.com/notifications",
  ...
  "token": "target=myApp-myChangesChannelDest",
  "expiration": 1426325213000
}

W treści żądania podaj id kanału, type jako web_hook oraz adres URL odbioru w polu 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 powtarzana 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 address ustawiony na adres URL, który nasłuchuje i odpowiada na powiadomienia z tego kanału. Jest to 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 Twoim serwerze 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 pasuje do docelowej nazwy 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ó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żdy przychodzący komunikat jest przeznaczony 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 adresu URL . Przykład: forwardTo=hr&createdBy=mobile

    • niepodawanie 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, o której interfejs Google Drive API ma przestać wysyłać komunikaty na ten kanał 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 metod files i changes.

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/drive/v3/files/o3hgv1538sdjfh",
  "token": "target=myApp-myFilesChannelDest",
  "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 danej 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 metod files i changes.

Synchronizuj wiadomość

Po utworzeniu kanału powiadomień do obserwowania zasobu interfejs Google Drive API wysyła sync komunikat, aby poinformować, że powiadomienia się rozpoczynają. Wartość nagłówka X-Goog-Resource-State HTTP w tych komunikatach 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 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. Powiadomienia sync możesz też użyć do przeprowadzenia inicjalizacji, aby przygotować się na późniejsze zdarzenia.

Poniżej przedstawiamy format komunikatów sync, które interfejs Google Drive 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 wiadomości większy od poprzedniego, ale numery wiadomości nie są kolejnymi liczbami.

Odnawianie 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 Drive API (używana jest bardziej restrykcyjna wartość). Czas wygaśnięcia kanału, jeśli taki istnieje, jest dołączany jako sygnatura czasowa Unix w informacjach zwracanych przez metodę watch. Dodatkowo 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 oba kanały powiadomień dla tego samego zasobu będą aktywne.

Otrzymuj powiadomienia

Gdy obserwowany zasób ulegnie zmianie, Twoja aplikacja otrzyma komunikat powiadomienia opisujący tę zmianę. Interfejs Google Drive API wysyła te komunikaty jako żądania HTTPS POST 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ń wysyłane przez interfejs Google Drive 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ą kolejnymi liczbami.
X-Goog-Resource-ID Nieczytelna wartość identyfikująca obserwowany zasób. Ten identyfikator jest stabilny w różnych 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, lub change .
X-Goog-Resource-URI Identyfikator obserwowanego zasobu właściwy dla danej wersji interfejsu API.
Czasami obecny
X-Goog-Changed Dodatkowe informacje o zmianach. Możliwe wartości: content, parents, children, lub permissions . Nie jest podawany w komunikatach sync.
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ń dotyczące zarówno zasobów files (w tym zdarzeń add, remove, update, trash i untrash), jak i zasobów changes są zawsze puste (treść żądania HTTP jest pusta, czyli Content-Length: 0).

Przykłady

Komunikat powiadomienia dotyczący zasobów files, gdy zasób zostanie dodany (treść żądania jest pusta):

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: 3a98f1a2b3c4d5e6f7
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:  add
X-Goog-Message-Number: 10

Komunikat powiadomienia o zmianie dotyczący zasobów files, gdy zasób zostanie zaktualizowany (treść żądania jest pusta):

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: 3a98f1a2b3c4d5e6f7
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: 11

Komunikat powiadomienia o zmianie dotyczący zasobów changes (treść żądania jest pusta):

POST https://mydomain.com/notifications
Content-Type: application/json; utf-8
Content-Length: 0
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

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 interfejsu API Google i zwraca kod 500, 502, 503 lub 504, interfejs Google Drive 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 Google Drive API

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

X-Goog-Resource-State Dotyczy: Dostarczane, gdy:
sync files, changes Kanał został utworzony. Możesz zacząć otrzymywać powiadomienia.
add files Zasób został utworzony lub udostępniony.
remove files Istniejący zasób został usunięty lub przestano go udostępniać.
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 dziennika zmian.

W przypadku zdarzeń update może zostać podany nagłówek HTTP X-Goog-Changed. Ten nagłówek zawiera rozdzieloną przecinkami listę opisującą typy zmian, które zaszły.

Typ zmiany Znaczenie
content Treść zasobu została zaktualizowana.
properties Zaktualizowano co najmniej jedną właściwość zasobu.
parents Dodano lub usunięto co najmniej 1 element nadrzędny zasobu.
children Dodano lub usunięto co najmniej 1 element podrzędny zasobu.
permissions Uprawnienia do 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 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/drive/v3/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 Drive API ma kilka typów zasobów, które mają watch metody, to jest tylko 1 stop metoda.

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/drive/v3/channels/stop
  
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

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