Powiadomienia o zmianach zasobów

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

Opis

Interfejs Google Drive API udostępnia powiadomienia push, które umożliwiają monitorowanie zmian w zasobach. Możesz użyć tej funkcji, aby poprawić wydajność swojej aplikacji. Pozwala wyeliminować dodatkowe koszty sieci i mocy obliczeniowej związane z zasobami odpytywania w celu określenia, czy się zmieniły. Przy każdej zmianie obserwowanego zasobu interfejs Google Drive API powiadamia aplikację.

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

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

    Jest to serwer HTTPS obsługujący wiadomości z powiadomieniami interfejsu API wywoływane w przypadku zmiany zasobu.

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

    Kanał określa informacje routingu dla wiadomości z powiadomieniami. Podczas konfigurowania kanału musisz określić adres URL, pod którym chcesz otrzymywać powiadomienia. Za każdym razem, gdy zasób kanału ulegnie zmianie, interfejs Google Drive API wysyła na ten adres URL wiadomość z powiadomieniem jako żądanie POST.

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ć. Po skonfigurowaniu kanałów powiadomień interfejs Google Drive API informuje Twoją aplikację o każdej zmianie 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 tym identyfikatorem URI:

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 konkretnym zasobem (lub zbiorem zasobów). Żądanie watch nie zostanie zrealizowane, jeśli bieżący użytkownik lub konto usługi nie jest właścicielem zasobu lub ma uprawnienia dostępu do niego.

Przykłady

Z przykładowego kodu poniżej dowiesz się, jak za pomocą zasobu channels zacząć obserwować zmiany 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", // 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.
}

Z przykładowego kodu poniżej dowiesz się, jak użyć zasobu channels, aby rozpocząć oglądanie wszystkich elementów 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 niepowtarzalnego identyfikatora uniwersalnego (UUID) lub innego podobnego unikalnego ciągu znaków. Maksymalna długość: 64 znaki.

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

  • Ciąg tekstowy 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 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 ważny certyfikat SSL. Nie prawidłowe certyfikaty to między innymi:

    • podpisane samodzielnie,
    • podpisane przez niezaufane źródło,
    • unieważnione.
    • Certyfikaty z podmiotem, który nie jest zgodny 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 dowolną wartość ciągu znaków do użycia jako token kanału. Tokenów kanału 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 pochodzi z kanału utworzonego przez Twoją aplikację – i upewnić się, że powiadomienie nie jest sfałszowana – lub do kierowania wiadomości do właściwego miejsca w aplikacji zgodnie z przeznaczeniem 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 otrzyma z tego kanału.

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

    • Użyj rozszerzalnego formatu kodowania, np. parametrów zapytania w adresie 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 sygnaturę czasową 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 czytelnym dla człowieka) w każdej wiadomości powiadomienia o danym kanale, którą aplikacja otrzymuje.

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

Obejrzyj odpowiedź

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

Treść wiadomości odpowiedzi na zegarek zawiera informacje o nowo utworzonym kanale powiadomień, tak jak w tym 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 zwracane informacje obejmują też resourceId i resourceUri identyfikujące zasób, który chcesz obserwować na tym kanale powiadomień.

Zwrócone informacje możesz przekazywać do innych operacji związanych z kanałem powiadomień, na przykład wtedy, gdy 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ń, aby obserwować zasób, interfejs Google Drive API wysyła komunikat sync informujący o tym, że powiadomienia są uruchamiane. Wartość nagłówka HTTP X-Goog-Resource-State dla tych wiadomości to sync. Ze względu na problemy z czasem działania sieci możesz otrzymać komunikat sync jeszcze przed otrzymaniem odpowiedzi metody watch.

Powiadomienie sync możesz bez obaw zignorować, ale możesz też go użyć. 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 znajduje się 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 będą ułożone jedna po drugiej.

Odnów kanały powiadomień

Kanał powiadomień może mieć określony czas ważności, którego wartość zależy od żądania lub dowolnych wewnętrznych limitów interfejsu Google Drive API lub wartości domyślnych (używana jest bardziej restrykcyjna wartość). Czas wygaśnięcia kanału, jeśli taki istnieje, jest uwzględniany w informacjach zwracanych przez metodę watch jako sygnatura czasowa uniksowa (w milisekundach). Dodatkowo data i godzina wygaśnięcia są podawane (w formacie czytelnym dla człowieka) w każdej wiadomości powiadomienia, którą aplikacja otrzymuje dla danego kanału, w nagłówku HTTP X-Goog-Channel-Expiration.

Obecnie nie ma możliwości automatycznego odnowienia kanału powiadomień. Gdy kończy się okres ważności kanału, musisz go zastąpić nowym, wywołując metodę watch. Jak zawsze musisz użyć unikalnej wartości właściwości id nowego kanału. Pamiętaj, że w fazie „nakładanie się” może wystąpić sytuacja, gdy aktywne są 2 kanały powiadomień dotyczące tego samego zasobu.

Odbieranie powiadomień

Po każdej zmianie obserwowanego zasobu aplikacja otrzymuje powiadomienie z opisem zmiany. Google Drive API wysyła te wiadomości jako żądania HTTPS POST na adres URL podany jako właściwość address dla tego kanału powiadomień.

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,

Wiadomości z powiadomieniami wysyłane przez interfejs Google Drive API na Twój adres URL mają następujące nagłówki HTTP:

Nagłówek Opis
Zawsze obecny
X-Goog-Channel-ID Identyfikator UUID lub inny unikalny ciąg znaków podany przez Ciebie w celu zidentyfikowania tego kanału powiadomień.
X-Goog-Message-Number Liczba całkowita identyfikująca tę wiadomość dla danego kanału powiadomień. Wartość to zawsze 1 dla sync wiadomości. Liczba wiadomości zwiększa się przy każdej kolejnej wiadomości na kanale, ale nie następuje to po sobie.
X-Goog-Resource-ID Nieprzejrzysta wartość identyfikująca obserwowany zasób. Ten identyfikator jest stały 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 oraz permissions. Nie podano sync wiadomości.
X-Goog-Channel-Expiration Data i godzina wygaśnięcia kanału powiadomień w formacie czytelnym dla człowieka. Występuje 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 aplikacji files i changes są puste.

Przykłady

Zmień wiadomość z powiadomieniem dla 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

Powiadomienie o zmianie dotyczące changes zasobu, który 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 wskazać, że wykonano operację, należy 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 Google Drive API ponawia próbę z wykładniczym ponownym opóźnieniem. Każdy inny kod stanu jest uważany za błąd wiadomości.

Omówienie zdarzeń 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 przez interfejs Google Drive API.

X-Goog-Resource-State Obejmuje Dostarczono, gdy
sync files, changes Kanał został utworzony. Możesz spodziewać się, że zaczniesz otrzymywać powiadomienia na jego temat.
add files Zasób został utworzony lub udostępniony.
remove files Istniejący zasób został usunięty lub cofnięto jego 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.

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

Typ zmiany Znaczenie
content Zawartość zasobu została zaktualizowana.
properties Zaktualizowano co najmniej 1 właściwości 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 dotyczące 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 utraci on 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 przykładzie poniżej. Pamiętaj, że jeśli interfejs Google Drive API ma kilka typów zasobów z metodą watch, występuje tylko jedna metoda stop.

Tylko użytkownicy z odpowiednimi uprawnieniami mogą zatrzymać 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 (określony na podstawie identyfikatorów klienta OAuth 2.0 z tokenów uwierzytelniania), który utworzył kanał, może zatrzymać kanał.
  • Jeśli kanał został utworzony za pomocą konta usługi, każdy użytkownik z tego samego klienta może zatrzymać kanał.

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