Powiadomienia o zmianach zasobów

Ten dokument opisuje sposób korzystania z powiadomień push, które informują aplikację o zmianie zasobu.

Przegląd

Interfejs Google Drive API udostępnia powiadomienia push, które umożliwiają monitorowanie zmian w zasobach. Możesz użyć tej funkcji, aby zwiększyć wydajność swojej aplikacji. Pozwala wyeliminować dodatkowe koszty sieci i obliczeniowe związane z odpytywaniem zasobów w celu sprawdzenia, czy uległy zmianie. Za każdym razem, gdy obserwowany zasób się zmieni, interfejs Google Drive API powiadomi Twoją aplikację.

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

  • Skonfiguruj adres URL odbierania lub odbiornik wywołań zwrotnych „webhooka”.

    To jest 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 obserwować.

    Kanał określa informacje o routingu dla wiadomości z powiadomieniami. Podczas konfigurowania kanału musisz podać dokładny adres URL, na który chcesz otrzymywać powiadomienia. Po każdej zmianie zasobu kanału 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.

Utwórz kanały powiadomień

Aby żądać powiadomień push, musisz skonfigurować kanał powiadomień dla każdego zasobu, który chcesz monitorować. Gdy kanały powiadomień zostaną skonfigurowane, interfejs Google Drive API poinformuje Twoją aplikację o zmianie dowolnego monitorowanego zasobu.

Wyślij prośby o zegarek

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

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

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

Każdy kanał powiadomień jest powiązany zarówno z określonym użytkownikiem, jak i z konkretnym zasobem (lub zbiorem zasobów). Żądanie watch nie zostanie zakończone, jeśli bieżący użytkownik lub konto usługi jest właścicielem tego zasobu lub ma do niego uprawnienia dostępu.

Przykłady

Poniższy przykładowy kod pokazuje, jak za pomocą zasobu channels rozpocząć śledzenie zmian pojedynczego zasobu files przy użyciu 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.
}

Poniższy przykładowy kod pokazuje, jak użyć zasobu channels, aby rozpocząć oglądanie wszystkich zasobów changes przy użyciu 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 każdym żądaniu watch musisz wypełnić te pola:

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

    Ustawiona wartość identyfikatora jest powtarzana w nagłówku HTTP X-Goog-Channel-Id każdego powiadomienia otrzymanego z 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, 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, 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. Tokenów kanału powiadomień można używać do różnych celów. Za pomocą tokena możesz na przykład sprawdzić, czy każda wiadomość przychodząca dotyczy kanału utworzonego przez Twoją aplikację (aby upewnić się, że powiadomienie nie jest podszywane) lub kierować wiadomość do właściwego miejsca docelowego w aplikacji odpowiednio do przeznaczenia tego kanału. Maksymalna długość: 256 znaków.

    Token jest umieszczony w nagłówku HTTP X-Goog-Channel-Token w każdym powiadomieniu, które aplikacja otrzymuje dla tego kanału.

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

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

  • Ciąg właściwości expiration z sygnaturą czasową uniksową (w milisekundach) określającą datę i godzinę, kiedy interfejs Google Drive API ma przestać wysyłać wiadomości do tego kanału powiadomień.

    Jeśli kanał ma określony czas wygaśnięcia, jest on podawany jako wartość nagłówka HTTP X-Goog-Channel-Expiration (w formacie zrozumiałym dla człowieka) w każdym powiadomieniu, które aplikacja otrzymuje dla tego kanału.

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ń, zwróci kod stanu HTTP 200 OK.

Treść wiadomości w odpowiedzi odtwarzania zawiera informacje o właśnie utworzonym kanale powiadomień, tak jak 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/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 zawierają również atrybuty resourceId i resourceUri identyfikujące zasób obserwowany w tym kanale powiadomień.

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

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

Zsynchronizuj wiadomość

Po utworzeniu kanału powiadomień umożliwiającego oglądanie zasobu interfejs Google Drive API wysyła komunikat sync, aby wskazać, że powiadomienia się uruchamiają. Wartość nagłówka HTTP X-Goog-Resource-State tych wiadomości to sync. Ze względu na problemy z czasem sieci komunikat sync może się pojawić nawet przed otrzymaniem odpowiedzi metody watch.

Możesz bezpiecznie zignorować powiadomienie sync, ale możesz też go użyć. Jeśli na przykład stwierdzisz, ż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 do przeprowadzenia inicjowania, aby przygotować się na późniejsze zdarzenia.

Poniżej znajduje się format wiadomości sync wysyłanych przez interfejs Google Drive API na Twój 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

Synchronizowane wiadomości zawsze mają wartość nagłówka HTTP X-Goog-Message-Number 1. Każde kolejne powiadomienie z tego kanału zawiera numer wiadomości, który jest większy niż poprzednie, jednak numery wiadomości nie następują po sobie.

Odnawianie kanałów powiadomień

Kanał powiadomień może mieć czas wygaśnięcia, którego wartość jest określana na żądanie albo przez wewnętrzne limity lub wartości domyślne interfejsu Google Drive API (stosowana jest bardziej restrykcyjna wartość). Czas wygaśnięcia kanału, jeśli jest podany, jest podawany jako sygnatura czasowa uniksowa (w milisekundach) w informacjach zwracanych przez metodę watch. Ponadto data i godzina wygaśnięcia są podane (w formacie zrozumiałym dla człowieka) w każdym powiadomieniu, które aplikacja otrzymuje dla tego kanału, w nagłówku HTTP X-Goog-Channel-Expiration.

Obecnie nie można automatycznie odnowić kanału powiadomień. Gdy kanał zbliża się do końca, 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. Pamiętaj, że może nastąpić okres „pokrywania się” dwóch kanałów powiadomień dotyczących tego samego zasobu.

Odbieranie powiadomień

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

Interpretowanie formatu wiadomości powiadomienia

Wszystkie komunikaty powiadomień 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 publikowane przez interfejs Google Drive API pod Twoim adresem URL zawierają te nagłówki HTTP:

Nagłówek Opis
Zawsze wyświetlaj
X-Goog-Channel-ID UUID lub inny unikalny ciąg znaków podany przez Ciebie do identyfikacji tego kanału powiadomień.
X-Goog-Message-Number Liczba całkowita, która identyfikuje tę wiadomość w przypadku tego kanału powiadomień. W przypadku wiadomości typu sync zawsze wartość wynosi 1. Numery wiadomości zwiększają się w przypadku każdej kolejnej wiadomości na kanale, ale nie pojawiają się po kolei.
X-Goog-Resource-ID Nieprzejrzysta wartość identyfikująca obserwowany zasób. Ten identyfikator jest niezmienny 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 lub change.
X-Goog-Resource-URI specyficzny dla wersji interfejsu API identyfikatora obserwowanego zasobu,
Czasami występują
X-Goog-Changed Dodatkowe informacje o zmianach. Możliwe wartości: content, parents, children lub permissions. Nie podano sync wiadomości.
X-Goog-Channel-Expiration Data i godzina wygaśnięcia kanału powiadomień wyrażona w formacie zrozumiałym dla człowieka. Występuje tylko wtedy, gdy został określony.
X-Goog-Channel-Token Token kanału powiadomień ustawiony przez Twoją aplikację, którego możesz używać do weryfikowania źródła powiadomień. Występuje tylko wtedy, gdy został określony.

Powiadomienia z kategorii files i changes są puste.

Przykłady

Zmiana komunikatu z powiadomieniem dotyczącego files zasobów, który 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 komunikatu z powiadomieniem dotyczącego changes zasobów, 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 oznaczyć powodzenie, możesz zwrócić dowolny 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, interfejs Google Drive API ponawia próbę wykładniczego ponowienia. Każdy inny kod stanu zwrotu jest uważany za niepowodzenie otrzymania wiadomości.

Informacje o zdarzeniach związanych z powiadomieniami interfejsu Google Drive API

Ta sekcja zawiera szczegółowe informacje na temat powiadomień, które możesz otrzymywać, gdy używasz powiadomień push za pomocą interfejsu Google Drive API.

X-Goog-Resource-State Dotyczy Dostarczono, gdy
sync files, changes Kanał został utworzony. Zaczniesz otrzymywać związane z nim powiadomienia.
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żna podać nagłówek HTTP X-Goog-Changed. Nagłówek ten zawiera rozdzielaną przecinkami listę typów wprowadzonych zmian.

Typ zmiany Znaczenie
content Zawartość zasobu została zaktualizowana.
properties Zaktualizowano co najmniej 1 usługę zasobu.
parents Dodano lub usunięto co najmniej 1 zasób nadrzędny.
children Dodano lub usunięto co najmniej 1 zasób podrzędny.
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ą być zatrzymywane automatycznie. Możesz przestać otrzymywać powiadomienia z konkretnego kanału, zanim wygaśnie, 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 korzystających z metod watch, istnieje 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, kanał może zatrzymać tylko ten sam użytkownik tego samego klienta (zgodnie z identyfikatorami klienta OAuth 2.0 w tokenach uwierzytelniania), który utworzył kanał.
  • Jeśli kanał został utworzony przez konto usługi, każdy użytkownik tego samego klienta może zatrzymać kanał.

Przeanalizuj przykładowy kod poniżej, aby dowiedzieć się, jak wyłączyć 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"
}