Powiadomienia o zmianach zasobów

Z tego dokumentu dowiesz się, jak używać powiadomień push, które informują aplikację o zmianach zasobu.

Omówienie

Interfejs Google Drive API udostępnia powiadomienia push, które umożliwiają monitorowanie zmian w zasobach. Dzięki tej funkcji możesz poprawić wydajność aplikacji. Dzięki temu możesz wyeliminować dodatkowe koszty sieci i przetwarzania związane z zasobami ankietowania, aby określić, czy uległy zmianie. Za każdym razem, gdy obserwowany zasób ulegnie zmianie, interfejs API Dysku Google wysyła powiadomienie do Twojej aplikacji.

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

  • Skonfiguruj odbierający adres URL lub „webhook” odbiornika wywołania zwrotnego.

    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 przekierowywaniu wiadomości z powiadomieniami. W ramach konfiguracji kanału musisz podać konkretny adres URL, pod którym chcesz otrzymywać powiadomienia. Gdy zasób kanału ulegnie zmianie, interfejs API Dysku Google wysyła wiadomość z powiadomieniem w postaci POSTdo tego adresu URL.

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

Tworzenie kanałów powiadomień

Aby żądać powiadomień push, musisz skonfigurować kanał powiadomień dla każdego zasobu, który chcesz monitorować. Po skonfigurowaniu kanałów powiadomień interfejs API Dysku Google informuje Twoją aplikację o zmianach w obserwowanych zasobach.

Przesyłanie żądań dotyczących oglądania

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 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 lub ma do niego uprawnienia.

Przykłady

Poniższy przykładowy kod pokazuje, jak za pomocą zasobu channels zacząć sprawdzać zmiany w pojedynczym źródle 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ąć 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:

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

    Ustawiona przez Ciebie wartość identyfikatora jest odzwierciedlana w nagłówku HTTP X-Goog-Channel-Id każdego powiadomienia, które otrzymujesz z tego kanału.

  • Ciąg znaków 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 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 prośbie watch możesz też podać te pola opcjonalne:

  • Właściwość token, która określa dowolną wartość ciągu znaków do użycia jako token kanału. Tokeny kanału powiadomień możesz stosować do różnych celów. Możesz na przykład użyć tokena, aby sprawdzić, czy każda przychodząca wiadomość jest przeznaczona do kanału utworzonego przez Twoją aplikację (aby mieć pewność, że powiadomienie nie jest sfałszowane) lub przekierować wiadomość do odpowiedniego miejsca w aplikacji na podstawie celu tego kanału. Maksymalna długość: 256 znaków.

    Token jest dołączany do nagłówka HTTP X-Goog-Channel-Token w ramach każdej wiadomości z powiadomieniem, którą aplikacja otrzymuje na tym kanale.

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

    • Użyj formatu kodowania umożliwiającego rozszerzanie, 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 sygnatura czasowa Unixa (w milisekundach) z datą i godziną, kiedy interfejs Drive API Google ma przestać wysyłać wiadomości dla tego kanału powiadomień.

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

Więcej informacji o żądaniu znajdziesz w metodach watch files i changes w dokumentacji referencyjnej interfejsu API.

Odpowiedź

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

Treść odpowiedzi na obejrzenie filmu zawiera informacje o korzystaniu z konkretnego kanału 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 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 na kanale powiadomień, na przykład gdy chcesz zatrzymać otrzymywanie powiadomień.

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 w sieci możliwe jest, że wiadomość sync zostanie wysłana, zanim otrzymasz odpowiedź metody watch.

Możesz bezpiecznie zignorować powiadomienie sync, ale możesz też z niego skorzystać. Jeśli na przykład zdecydujesz się nie zachować kanału, możesz użyć wartości X-Goog-Channel-ID i X-Goog-Resource-ID w wywołaniu, aby zatrzymać otrzymywanie powiadomień. Możesz też użyć powiadomienia sync, aby przeprowadzić wstępną konfigurację w celu przygotowania się do późniejszych zdarzeń.

Format wiadomości sync wysyłanych przez interfejs Google Drive API do adresu URL odbierającego podany przez Ciebie w usłudze 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 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 ważności określony przez Twoje żądanie lub przez limity wewnętrzne interfejsu Google Drive lub domyślne wartości (używana 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. Dodatkowo data i godzina wygaśnięcia (w czytelnym dla człowieka formacie) są zawarte w każdej wiadomości z powiadomieniem, którą aplikacja otrzymuje dla tego kanału w nagłówku HTTP X-Goog-Channel-Expiration.

Obecnie nie ma automatycznego sposobu odnawiania kanału powiadomień. Gdy kanał zbliża się do daty wygaśnięcia, 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 prawdopodobnie będzie okres „nakładania się”, gdy 2 kanały powiadomień dla tego samego zasobu będą aktywne.

Otrzymywanie powiadomień

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

Interpretowanie formatu 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 API Dysku Google w przypadku adresów URL odbiorczych zawierają te nagłówki HTTP:

Nagłówek Opis
Zawsze widoczne
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 Wartość całkowita identyfikująca to powiadomienie dla tego kanału powiadomień. W przypadku komunikatów sync wartość zawsze wynosi 1. Numery wiadomości zwiększają się 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 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 Identyfikator zasobu monitorowanego, który jest specyficzny dla wersji interfejsu API.
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ń w formacie zrozumiałym dla człowieka. Występuje tylko wtedy, gdy jest zdefiniowany.
X-Goog-Channel-Token Token kanału powiadomień ustawiony przez Twoją aplikację, którego możesz użyć do zweryfikowania źródła powiadomienia. 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

Zmień powiadomienie o zmianie zasobów changes, które 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 interfejsu API Google i zwraca wartości 500, 502, 503 lub 504, interfejs API Dysku Google próbuje ponownie wykonać operację z eksponencjalnie wydłużającymi się przerwami. Każdy inny kod stanu zwrotu jest uznawany za błąd wiadomości.

Zdarzenia powiadomień 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 Dostarczone, gdy
sync files, changes Kanał został utworzony. Zaczniesz otrzymywać związane z nim powiadomienia.
add files Utworzono lub udostępniono zasób.
remove files Istniejący zasób został usunięty lub udostępnianie zostało wycofane.
update files Zaktualizowano co najmniej 1 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 zostać podany nagłówek HTTP X-Goog-Changed. Ten nagłówek zawiera listę rozdzielanych przecinkami typów zmian, które zostały wprowadzone.

Typ zmiany Znaczenie
content Treść zasobu została zaktualizowana.
properties Zaktualizowano co najmniej 1 właściwość zasobu.
parents Dodano lub usunięto co najmniej 1 rodzic zasobu.
children Dodano lub usunięto co najmniej 1 zasób podrzędny.
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 przestaną być wysyłane automatycznie. Możesz przestać otrzymywać powiadomienia z określonego 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 API Dysku Google obsługuje kilka typów zasobów, które mają metody watch, to 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ł.

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