Powiadomienia o zmianach zasobów

Właściwości wymagane

W przypadku każdego żądania watch musisz podać 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.

  Ustawiony przez Ciebie identyfikator jest odzwierciedlany w nagłówku HTTP X-Goog-Channel-Id każdej wiadomości z powiadomieniem, którą otrzymasz na tym kanale.

• Ciąg znaków 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 dla tego kanału powiadomień. 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 w nagłówku HTTP X-Goog-Channel-Token w 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.

Odpowiedź

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

Treść odpowiedzi na obejrzenie filmu zawiera informacje o korzystaniu z niedawno utworzonego 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 informacje zwracane zawierają też wartości resourceId i resourceUri, które wskazują zasób wyświetlany na 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 metodach watch files i changes w przewodniku po interfejsie API.

Synchronizowanie wiadomości

Po utworzeniu kanału powiadomień, aby obserwować zasób, interfejs API Dysku Google wysyła komunikat sync, aby wskazać, że powiadomienia są włączone. Wartość nagłówka HTTP X-Goog-Resource-State tych wiadomości to sync. Ze względu na problemy z synchronizacją sieci może się zdarzyć, że wiadomość sync zostanie wysłana, zanim otrzymasz odpowiedź metody watch.

Powiadomienie sync możesz zignorować, 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 na tym kanale ma numer większy od poprzedniego, ale numery wiadomości nie będą uporządkowane.

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 istnieje) jest podawany jako oznaczenie czasu uniksowego (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, w przypadku właściwości id nowego kanału musisz użyć unikalnej wartości. Pamiętaj, że prawdopodobnie będzie okres „nakładania się”, gdy 2 kanały powiadomień dla tego samego zasobu będą aktywne.