資源變更通知

本文說明如何使用推播通知，在資源變更時通知應用程式。

總覽

Google 雲端硬碟 API 提供推播通知，可讓您監控資源變更。您可以利用這項功能提升應用程式效能。這樣一來，您就不必輪詢資源來判斷資源是否已變更，進而省下額外的網路和運算費用。每當監控的資源發生變更，Google Drive API 就會通知您的應用程式。

如要使用推播通知，請務必完成以下兩個動作：

  • 設定接收網址或「Webhook」回呼接收端。

    這是 HTTPS 伺服器，可處理資源變更時觸發的 API 通知訊息。

  • 為要監看的每個資源端點設定通知管道。

    管道會指定通知訊息的路由資訊。設定管道時，您必須指定要接收通知的特定網址。每當管道的資源變更時，Google Drive API 就會以 POST 要求的形式，將通知訊息傳送至該網址。

目前 Google Drive API 支援 files 和 changes 方法的變更通知。

建立通知管道

如要要求推送通知，您必須為要監控的每個資源設定通知管道。設定通知管道後，Google Drive API 會在任何監控資源變更時，通知您的應用程式。

提出智慧手錶要求

每個可監看的 Google Drive API 資源都有相關聯的 watch 方法，URI 格式如下：

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

如要為特定資源的變更訊息設定通知管道，請向該資源的 watch 方法傳送 POST 要求。

每個通知管道都會與特定使用者和特定資源 (或一組資源) 建立關聯。除非目前使用者或服務帳戶擁有或有權存取這項資源，否則 watch 要求不會成功。

範例

下列程式碼範例說明如何使用 channels 資源，透過 files.watch 方法開始監控單一 files 資源的變更：

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

以下程式碼範例說明如何使用 channels 資源，透過 changes.watch 方法開始監看所有 changes：

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

必要屬性

每次發出 watch 要求時，都必須提供下列欄位：

  • id 屬性字串，用於在專案中唯一識別這個新通知管道。建議使用通用唯一識別碼 (UUID) 或任何類似的專屬字串。長度上限為 64 個半形字元。

    您設定的 ID 值會回傳至您為這個管道收到的每則通知訊息的 X-Goog-Channel-Id HTTP 標頭。

  • type 屬性字串設為 web_hook 值。

  • address 屬性字串，設為監聽及回應這個通知管道通知的網址。這是 Webhook 回呼網址，必須使用 HTTPS。

    請注意，只有在您的網路伺服器上安裝有效的 SSL 憑證時，Google Drive API 才能將通知傳送至這個 HTTPS 位址。無效的憑證包括：

    • 自行簽署的憑證。
    • 由不受信任的來源所簽署的憑證。
    • 已撤銷的憑證。
    • 憑證的主體與目標主機名稱不符。

選用屬性

您也可以在 watch 要求中指定下列選填欄位：

  • token 屬性，指定要用做管道權杖的任意字串值。通知管道權杖有多種用途，舉例來說，您可以利用這個權杖驗證每則傳入訊息是否來自應用程式建立的管道，確保通知未遭偽造，或根據管道用途將訊息導向應用程式內的正確目的地。長度上限： 256 個半形字元。

    應用程式透過這個管道收到的每則通知訊息，都會在 X-Goog-Channel-Token HTTP 標頭中包含權杖。

    如果您使用通知管道權杖，建議您採取下列行動：

    • 使用可擴充的編碼格式，例如網址查詢參數。範例：forwardTo=hr&createdBy=mobile

    • 請勿加入 OAuth 權杖等機密資料。

  • expiration 屬性字串，設為您希望 Google Drive API 停止傳送這個通知管道訊息的日期和時間的 Unix 時間戳記 (以毫秒為單位)。

    如果管道設有到期時間，應用程式為這個管道收到的每則通知訊息，都會在 X-Goog-Channel-Expiration HTTP 標頭中包含到期時間值 (以人類可解讀的格式)。

如要進一步瞭解要求，請參閱 API 參考資料中的 files 和 changes 方法的 watch 方法。

觀看回覆

如果 watch 要求成功建立通知管道，則會傳回 HTTP 200 OK 狀態碼。

手錶回應的訊息主體會提供您剛建立的通知管道相關資訊，如下列範例所示。

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

除了您在要求中傳送的屬性，傳回的資訊也包含 resourceId 和 resourceUri，用於識別這個通知管道上監看的資源。

您可以將傳回的資訊傳遞至其他通知管道作業，例如停止接收通知。

如要進一步瞭解回應，請參閱 API 參考資料中的 files 和 changes 方法的 watch 方法。

同步訊息

建立通知管道來監控資源後，Google 雲端硬碟 API 會傳送 sync 訊息，表示通知即將開始。這些訊息的 X-Goog-Resource-State HTTP 標頭值為 sync。由於網路時間問題，您可能會在收到 watch 方法回應前，先收到 sync 訊息。

您可以放心忽略 sync 通知，但也可以使用這項功能。舉例來說，如果您決定要移除管道，可以在呼叫停止接收通知時使用 X-Goog-Channel-ID 和 X-Goog-Resource-ID 值。您也可以使用 sync 通知執行一些初始化作業，為後續事件做準備。

Google Drive API 傳送至接收網址的 sync 訊息格式如下所示。

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

同步訊息的 X-Goog-Message-Number HTTP 標頭值一律為 1。這個管道的後續通知訊息編號會大於前一個，但訊息編號不會連續。

續訂通知管道

通知管道可以設定到期時間，值由要求或任何 Google 雲端硬碟 API 內部限制或預設值決定 (使用限制較嚴格的值)。如果頻道有到期時間，watch 方法傳回的資訊會以 Unix 時間戳記 (以毫秒為單位) 形式提供。此外，應用程式在這個管道收到的每則通知訊息中，X-Goog-Channel-ExpirationHTTP 標頭都會包含到期日期和時間 (人類可讀的格式)。

目前無法自動續訂通知管道。當管道即將到期時，您必須呼叫 watch 方法，以新管道取代舊管道。與往常一樣，新管道的 id 屬性必須使用專屬值。請注意，如果同一資源的兩個通知管道都處於啟用狀態，可能會出現「重疊」的時間間隔。

接收通知

每當監看的資源發生變化，應用程式就會收到說明變更內容的通知訊息。Google Drive API 會將這些訊息當做 HTTPS POST 要求，傳送至您為這個通知管道指定的 address 屬性網址。

解讀通知訊息格式

所有通知訊息都包含一組具有 X-Goog- 前置字串的 HTTP 標頭。部分類型的通知也可能包含訊息內文。

標頭

Google Drive API 發布至接收網址的通知訊息包含下列 HTTP 標頭：

標頭 說明
一律顯示
X-Goog-Channel-ID 您提供的 UUID 或其他專屬字串，用於識別這個通知管道。
X-Goog-Message-Number 整數，用於識別這個通知管道的這則訊息。sync 訊息的值一律為 1。頻道中每則後續訊息的訊息編號都會增加，但不會依序遞增。
X-Goog-Resource-ID 用於識別受監控資源的不透明值。這個 ID 在不同 API 版本中都保持不變。
X-Goog-Resource-State 觸發通知的新資源狀態。 可能的值： sync、add、remove、update、 trash、untrash 或 change 。
X-Goog-Resource-URI 受監控資源的 API 版本專屬 ID。
有時會出現
X-Goog-Changed 變更的其他詳細資料。 可能的值： content、 parents、 children 或 permissions 。 不會提供 sync 訊息。
X-Goog-Channel-Expiration 通知管道的到期日期和時間，以使用者可判讀的格式表示。只有在定義時才會顯示。
X-Goog-Channel-Token 應用程式設定的通知管道權杖，可用於驗證通知來源。只有在定義時才會顯示。

「files」和「changes」的通知訊息為空白。

範例

files 資源的變更通知訊息，不含要求主體：

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

changes 資源的變更通知訊息，包括要求主體：

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

根據通知內容採取行動

如要表示成功，可以傳回下列任一狀態碼：200、201、202、204 或 102。

如果您的服務使用 Google 的 API 用戶端程式庫，並傳回 500、502、503 或 504，Google Drive API 會使用指數輪詢重試。 其他任何傳回狀態碼都視為訊息傳送失敗。

瞭解 Google Drive API 通知事件

本節將詳細說明透過 Google Drive API 使用推播通知時，您可能會收到的通知訊息。

X-Goog-Resource-State 適用對象 送達時間
sync files、changes 頻道已成功建立。你應該會開始收到相關通知。
add files 已建立或共用資源。
remove files 現有資源已刪除或取消共用。
update files 資源的一或多項屬性 (中繼資料) 已更新。
trash files 資源已移至垃圾桶。
untrash files 資源已從垃圾桶移除。
change changes 已新增一或多個更新記錄項目。

如果是 update 事件，系統可能會提供 X-Goog-Changed HTTP 標頭。該標頭包含以半形逗號分隔的清單，說明發生的變更類型。

變更類型 意義
content 資源內容已更新。
properties 一或多項資源屬性已更新。
parents 已新增或移除一或多個資源父項。
children 已新增或移除一或多個資源子項。
permissions 已更新資源權限。

使用 X-Goog-Changed 標頭的範例：

X-Goog-Resource-State: update
X-Goog-Changed: content, permissions

停止通知

expiration 屬性會控制通知自動停止的時間。您可以在特定管道到期前，呼叫下列 URI 的 stop 方法，選擇停止接收通知：

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

這個方法至少需要提供頻道的 id 和 resourceId 屬性，如下列範例所示。請注意，如果 Google 雲端硬碟 API 有多種資源類型，且這些資源類型都有 watch 方法，則只會有一個 stop 方法。

只有具備適當權限的使用者才能停止頻道。請特別注意以下幾點：

  • 如果頻道是由一般使用者帳戶建立，只有建立頻道的同一位使用者 (由驗證權杖中的 OAuth 2.0 用戶端 ID 識別) 才能停止頻道。
  • 如果頻道是由服務帳戶建立，同一用戶端的任何使用者都可以停止頻道。

以下程式碼範例說明如何停止接收通知：

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