Powiadomienia o zmianach zasobów

Z tego dokumentu dowiesz się, jak korzystać z powiadomień push informujących aplikacji w przypadku zmiany zasobu.

Omówienie

Interfejs Google Drive API zapewnia powiadomienia push, które umożliwiają monitorowanie zmian w zasobach. Możesz korzystać z tej funkcji, aby poprawić skuteczność Twojej aplikacji. Pozwala wyeliminować dodatkową sieć i moc obliczeniową koszty związane z zasobami odpytywania w celu określenia, czy uległy zmianie. Za każdym razem, gdy obserwowany zasób się zmieni, interfejs Google Drive API powiadomi aplikacji.

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

  • Konfigurowanie adresu URL odbierania (webhooka) .

    Ten to 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 zegarka.

    Kanał określa informacje o routingu dla powiadomień wiadomości. Podczas zakładania kanału musisz podać dokładny adres URL, pod którym chcesz otrzymywać powiadomienia. Za każdym razem, gdy zasoby kanału się zmieniają, interfejs Google Drive API wysyła powiadomienie jako POST do tego adresu URL.

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

Utwórz kanały powiadomień

Aby otrzymywać powiadomienia push, musisz skonfigurować kanał powiadomień dla każdego zasobu, który chcesz monitorować. Po ustawieniu kanałów powiadomień interfejs API Dysku Google informuje aplikację, gdy dowolny monitorowany zasób zmian.

Wyślij prośby o zegarek

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

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

Aby skonfigurować kanał powiadomień o wiadomościach o zmianach w określonego zasobu, wyślij żądanie POST do Metoda watch dla zasobu.

Każdy kanał powiadomień jest powiązany zarówno z konkretnym użytkownikiem, określonego zasobu (lub zbioru zasobów). Prośba o: watch nie powiedzie się, chyba że 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 znaków właściwości id, który jednoznacznie określa tę właściwość nowy kanał powiadomień w projekcie. Zalecamy użycie uniwersalny identyfikator (UUID) lub podobny jest unikalny ciąg znaków. Maksymalna długość: 64 znaki.

    Ustawiona wartość identyfikatora jest odczytywana ponownie Nagłówek HTTP X-Goog-Channel-Id każdego powiadomienia jaką wiadomość otrzymujesz na temat 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 i odpowiada na powiadomienia z tego kanału powiadomień. To jest adresu URL wywołania zwrotnego webhooka i musi on używać protokołu HTTPS.

    Pamiętaj, że interfejs Google Drive API może wysyłać powiadomienia do ten adres HTTPS, tylko jeśli został zainstalowany prawidłowy certyfikat SSL na serwerze WWW. Nie prawidłowe certyfikaty to między innymi:

    • podpisane samodzielnie,
    • podpisane przez niezaufane źródło,
    • unieważnione.
    • Certyfikaty z tematem, który nie pasuje do celu nazwa hosta.

Właściwości opcjonalne

Te opcjonalne pola możesz też określić za pomocą Prośba o środki (watch):

  • właściwość token, która określa dowolny ciąg znaków. do użycia jako token kanału. Możesz użyć kanału powiadomień do różnych celów. Na przykład możesz użyć atrybutu token do potwierdzenia, że każda przychodząca wiadomość pochodzi z kanału, utworzona aplikacja – by upewnić się, że powiadomienie nie jest wysyłane sfałszowana – lub aby skierować wiadomość do właściwego miejsca docelowego w: zgodnie z przeznaczeniem kanału. Maksymalna długość: 256 znaków.

    Token znajduje się w sekcji Nagłówek HTTP X-Goog-Channel-Token w każdym powiadomieniu wyświetlany w aplikacji dla tego kanału.

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

    • Użyj możliwego formatu kodowania, takiego jak zapytanie 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 Sygnatura czasowa uniksowa (w milisekundach) daty i godziny, o której interfejs Google Drive API ma zaprzestać wysyłania wiadomości z tego kanału powiadomień.

    Jeśli kanał ma datę ważności, jest on podany jako wartość. nagłówka HTTP X-Goog-Channel-Expiration (w formacie czytelnym dla człowieka) ) w każdej wiadomości z powiadomieniem, otrzymuje tyle zgłoszeń dotyczących tego kanału.

.

Aby dowiedzieć się więcej o żądaniu, zapoznaj się z metodą watch dla metod files i changes w dokumentacji interfejsu API.

Obejrzyj odpowiedź

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

Treść wiadomości w odpowiedzi zegarka zawiera informacje o kanału powiadomień, tak jak pokazano to 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 parametr zwrócone informacje obejmują również resourceId i resourceUri, aby zidentyfikować zasób, który jest na nim obserwowany kanału powiadomień.

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

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

Zsynchronizuj wiadomość

Po utworzeniu kanału powiadomień, aby oglądać zasób, Interfejs Google Drive API wysyła komunikat sync, aby wskazać, że powiadomienia. Protokół HTTP X-Goog-Resource-State wartość nagłówka tych wiadomości to sync. Ze względu na sieć problemy z czasem, możesz otrzymać komunikat sync jeszcze przed otrzymaniem odpowiedzi metody watch.

Możesz bezpiecznie zignorować powiadomienie sync, ale możesz go użyć. Jeśli na przykład nie chcesz przechowywać kanału, możesz korzystać z funkcji X-Goog-Channel-ID i X-Goog-Resource-ID wartości w wywołaniu do wyłączyć otrzymywanie powiadomień. Możesz też użyć usługi Powiadomienie sync dotyczące inicjalizacji w celu przygotowania późniejszych wydarzeń.

Format wiadomości sync, do których interfejs Google Drive API wysyła Twój adres URL odbierania jest widoczny 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

Synchronizowane wiadomości zawsze mają żądanie HTTP X-Goog-Message-Number 1. Każde kolejne powiadomienie z tego kanału numer wiadomości jest większy niż poprzedni, mimo że komunikat liczby nie występują po sobie.

Odnawianie kanałów powiadomień

Kanał powiadomień może mieć czas wygaśnięcia i podaną wartość określane na podstawie żądania lub wewnętrznych limitów interfejsu Google Drive API lub wartości domyślne (stosowana jest wartość bardziej restrykcyjna). Wygaśnięcie kanału Godzina (jeśli go występuje), jest dołączana jako sygnatura czasowa uniksowa (w milisekundach) w informacjach zwracanych przez metodę watch. Dodatkowo data i godzina wygaśnięcia są podane (w formacie czytelnym dla człowieka) w każdym powiadomienie dotyczące tego kanału, które Twoja aplikacja otrzyma w Nagłówek HTTP X-Goog-Channel-Expiration.

Obecnie nie można automatycznie odnowić kanału powiadomień. Kiedy kanał wkrótce wygaśnie. Musisz zastąpić go nowym, dzwoniąc metodę watch. Jak zawsze, musisz użyć unikalnej wartości dla argumentu właściwość id nowego kanału. Pamiętaj, że istnieje możliwość aby „pokrywać się” okresu, w którym dwa kanały powiadomień są aktywne takie same zasoby.

Otrzymywanie powiadomień

Po każdej zmianie obserwowanego zasobu aplikacja otrzymuje powiadomienie z opisem zmiany. Interfejs Google Drive API wysyła te jako żądania HTTPS POST do adresu URL określonego jako address usługa dla tego powiadomienia kanał.

Interpretowanie formatu wiadomości powiadomienia

Wszystkie powiadomienia zawierają zestaw nagłówków HTTP X-Goog- prefiksy. Niektóre typy powiadomień mogą też zawierać treść wiadomości.

Nagłówki

Wiadomości z powiadomieniami publikowane przez interfejs Google Drive API do odbiorców Adres URL zawiera te nagłówki HTTP:

Nagłówek Opis
Zawsze wyświetlaj
X-Goog-Channel-ID Identyfikator UUID lub inny unikalny ciąg znaków podany przez Ciebie w celu identyfikacji kanału powiadomień.
X-Goog-Message-Number Liczba całkowita określająca tę wiadomość w przypadku tego powiadomienia kanał. W przypadku wiadomości typu sync zawsze wartość wynosi 1. Wiadomość ich liczba rośnie z każdą kolejną wiadomością na kanale, ale nie sekwencyjną.
X-Goog-Resource-ID Nieprzejrzysta wartość identyfikująca obserwowany zasób. Ten identyfikator to stabilna 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żone w zrozumiałego dla człowieka. Występuje tylko wtedy, gdy został określony.
X-Goog-Channel-Token token kanału powiadomień ustawiony przez Twoją aplikację; aby zweryfikować źródło powiadomień. Występuje tylko wtedy, gdy zdefiniowano jego definicję.

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żna wyświetlić dowolny z tych kodów stanu: 200, 201, 202, 204 lub 102.

Jeśli Twoja usługa używa biblioteki klienta interfejsów API Google i zwraca 500, 502, 503 lub 504, interfejs Google Drive API ponawia próby z wykładniczym czasem ponowienia. Każdy inny kod stanu zwrotu jest uważany za niepowodzenie dostarczenia 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 otrzymywane w powiadomieniach 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. Dostępne opcje wyłączyć otrzymywanie powiadomień z kanału, zanim zacznie się wyświetlać wygasa przez wywołanie metody stop na stronie ten identyfikator URI:

https://www.googleapis.com/drive/v3/channels/stop

Ta metoda wymaga podania przynajmniej id i resourceId, jak pokazano w przykład poniżej. Pamiętaj, że jeśli interfejs Google Drive API zawiera kilka typów zasobów z watch metodą, jest 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 to samo tego samego klienta (zgodnie z identyfikatorami klienta OAuth 2.0 w sekcji tokeny uwierzytelniania), który utworzył kanał, może zatrzymać jego działanie.
  • Jeśli kanał został utworzony przez konto usługi, dowolny użytkownik z tego samego konta, 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"
}