Powiadomienia o zmianach zasobów

Z tego dokumentu dowiesz się, jak korzystać z powiadomień push, które informują aplikację o zmianach zasobów.

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ść aplikacji. Pozwala to wyeliminować dodatkowe koszty sieciowe i obliczeniowe związane z odpytywaniem zasobów w celu sprawdzenia, czy uległy zmianie. Za każdym razem, gdy zmieni się obserwowany zasób, interfejs Google Drive API powiadomi Twoją aplikację.

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

  • Skonfiguruj adres URL odbioru lub odbiornik wywołania zwrotnego „webhook”.

    Jest to serwer HTTPS, który obsługuje wiadomości z powiadomieniami 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 kierowaniu wiadomości z powiadomieniami. W ramach konfiguracji kanału musisz podać konkretny adres URL, na który chcesz otrzymywać powiadomienia. Gdy zasób kanału ulegnie zmianie, interfejs Google Drive API wysyła komunikat z powiadomieniem w postaci żądania POST do tego adresu 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ć. Po skonfigurowaniu kanałów powiadomień interfejs Google Drive API informuje aplikację o zmianach w dowolnym obserwowanym zasobie.

Wysyłanie próśb dotyczących zegarka

Każdy zasób interfejsu Google Drive API, który można obserwować, ma powiązaną metodę watch 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 konkretnym 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 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ąć śledzenie 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", // 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ąć 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", // 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 podać te pola:

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

    Ustawiona wartość identyfikatora jest zwracana w X-Goog-Channel-Idnagłówku HTTP każdego powiadomienia, które otrzymujesz w przypadku tego kanału.

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

  • Ciąg znaków właściwości address ustawiony na adres URL, który nasłuchuje i odpowiada na powiadomienia z tego kanału powiadomień. 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 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 jest zgodny z docelową nazwą hosta,

Właściwości opcjonalne

Możesz też określić te opcjonalne pola w watch żądaniu:

  • Właściwość token, która określa dowolny ciąg znaków do użycia jako token kanału. Tokeny kanału powiadomień możesz wykorzystywać do różnych celów. Możesz na przykład użyć tokena, aby sprawdzić, czy każda przychodząca wiadomość jest przeznaczona dla kanału utworzonego przez Twoją aplikację. Dzięki temu możesz mieć pewność, że powiadomienie nie jest fałszywe, lub kierować wiadomość do odpowiedniego miejsca w aplikacji na podstawie przeznaczenia kanału. Maksymalna długość: 256 znaków.

    Token jest umieszczany w nagłówku HTTP X-Goog-Channel-Token każdej wiadomości z powiadomieniem, którą aplikacja otrzymuje w przypadku tego kanału.

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

    • Używaj 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 znaków właściwości expiration ustawiony na sygnaturę czasową w formacie Unix (w milisekundach) daty i godziny, o której interfejs Google Drive API ma przestać wysyłać wiadomości na ten kanał powiadomień.

    Jeśli kanał ma czas wygaśnięcia, jest on uwzględniany jako wartość X-Goog-Channel-Expiration nagłówka HTTP (w formacie czytelnym dla człowieka) w każdej wiadomości z powiadomieniem, którą aplikacja otrzymuje w przypadku tego kanału.

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

Odpowiedź na zegarku

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

Treść odpowiedzi zegarka zawiera informacje o utworzonym właśnie kanale powiadomień, jak pokazano 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 przesłanych w ramach żądania zwrócone informacje zawierają też parametry resourceId i resourceUri, które identyfikują zasób obserwowany na tym kanale powiadomień.

Zwrócone informacje możesz przekazywać do innych operacji na kanale powiadomień, np. gdy chcesz przestać otrzymywać powiadomienia.

Więcej informacji o odpowiedzi znajdziesz w watchmetodzie files i changes w dokumentacji interfejsu API.

Synchronizuj wiadomości

Po utworzeniu kanału powiadomień do obserwowania zasobu interfejs Google Drive API wysyła komunikat sync, aby poinformować, że powiadomienia są uruchamiane. Wartość nagłówka HTTP X-Goog-Resource-State w przypadku tych wiadomości to sync. Ze względu na problemy z synchronizacją sieci możesz otrzymać wiadomość 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 funkcji stop receiving notifications. Możesz też użyć powiadomienia sync, aby przeprowadzić inicjację i przygotować się na późniejsze zdarzenia.

Format sync wiadomości wysyłanych przez interfejs Google Drive API na Twój adres URL odbioru jest pokazany 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

Wiadomości synchronizacji mają zawsze wartość nagłówka HTTP X-Goog-Message-Number równą 1. Każde kolejne powiadomienie z tego kanału ma numer wiadomości większy od poprzedniego, ale numery wiadomości nie są kolejne.

Odnowienie kanałów powiadomień

Kanał powiadomień może mieć czas ważności, którego wartość jest określana przez Twoje żądanie lub przez wewnętrzne limity lub wartości domyślne interfejsu Google Drive API (używana jest bardziej restrykcyjna wartość). Czas wygaśnięcia kanału, jeśli taki istnieje, jest podany jako sygnatura czasowa w formacie Unix (w milisekundach) w informacjach zwracanych przez metodę watch. Dodatkowo data i godzina wygaśnięcia (w formacie czytelnym dla człowieka) są zawarte w każdej wiadomości z powiadomieniem, którą aplikacja otrzymuje w przypadku tego kanału, w X-Goog-Channel-Expirationnagłówku HTTP.

Obecnie nie ma automatycznego sposobu odnowienia kanału powiadomień. Gdy kanał zbliża się do daty wygaśnięcia, musisz zastąpić go nowym, wywołując metodę watch. Jak zawsze, musisz użyć unikalnej wartości we właściwości id nowego kanału. Pamiętaj, że prawdopodobnie wystąpi okres „nakładania się”, w którym aktywne będą 2 kanały powiadomień dotyczące tego samego zasobu.

otrzymywanie powiadomień;

Gdy obserwowany zasób ulegnie zmianie, Twoja aplikacja otrzyma wiadomość z powiadomieniem opisującym tę zmianę. Interfejs Google Drive API wysyła te wiadomości jako żądania HTTPS POST na adres URL, który został określony jako właściwość address tego kanału powiadomień.

Interpretowanie formatu wiadomości powiadomienia

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łówki

Wiadomości z powiadomieniami publikowane przez interfejs Google Drive API na adres URL odbiorcy zawierają te nagłówki HTTP:

Nagłówek Opis
Zawsze obecny
X-Goog-Channel-ID UUID lub inny unikalny ciąg znaków, który został podany w celu identyfikacji tego kanału powiadomień.
X-Goog-Message-Number Liczba całkowita, która identyfikuje tę wiadomość na tym kanale powiadomień. W przypadku wiadomości sync wartość zawsze wynosi 1. Numery wiadomości rosną w przypadku każdej kolejnej wiadomości na kanale, ale nie są sekwencyjne.
X-Goog-Resource-ID Nieczytelna 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 obserwowanego zasobu, który jest specyficzny dla wersji interfejsu API.
Czasami występuje
X-Goog-Changed Dodatkowe informacje o zmianach. Możliwe wartości:content,parents,children lubpermissions. Nie jest podawana w przypadku wiadomości 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 aplikację, którego możesz użyć do weryfikacji źródła powiadomienia. Występuje tylko wtedy, gdy jest zdefiniowany.

Wiadomości powiadomień dotyczące files i changes są puste.

Przykłady

Komunikat powiadomienia o zmianie zasobów files, 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

Komunikat powiadomienia o zmianie zasobów changes, 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ć 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 kody 500, 502, 503 lub 504, interfejs Google Drive API ponawia próbę z wykładniczym wycofywaniem. Każdy inny kod stanu zwrotu jest uznawany za błąd wiadomości.

Informacje o zdarzeniach powiadomień interfejsu Google Drive API

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

X-Goog-Resource-State Dotyczy Dostarczono, gdy
sync files, changes Kanał został utworzony. Powinny zacząć przychodzić powiadomienia dotyczące tego kanału.
add files Utworzono lub udostępniono zasób.
remove files Istniejący zasób został usunięty lub cofnięto jego udostępnianie.
update files Została zaktualizowana co najmniej jedna 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 być podany nagłówek HTTP X-Goog-Changed. Ten nagłówek zawiera listę rozdzieloną przecinkami, która opisuje rodzaje zmian, jakie zaszły.

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 jednego rodzica zasobu.
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ć automatycznie zatrzymywane. Możesz zrezygnować z otrzymywania powiadomień 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 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 metodami 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, tylko ten sam użytkownik z tego samego klienta (zidentyfikowany przez identyfikatory klienta OAuth 2.0 z tokenów uwierzytelniających), który utworzył kanał, może go zatrzymać.
  • Jeśli kanał został utworzony przez konto usługi, każdy użytkownik z tego samego klienta może go zatrzymać.

Poniższy przykładowy kod pokazuje, jak zatrzymać otrzymywanie powiadomień:

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