資源變更通知

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

總覽

Google Drive API 提供推播通知,可讓您監控資源的變化。您可以使用這項功能提升應用程式效能。如此一來,您就能省去輪詢資源衍生的額外網路和運算費用,判斷資源是否有所變動。 每當觀察到資源變更時,Google Drive API 都會通知您的應用程式。

如要使用推播通知,您必須執行下列兩項操作:

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

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

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

    管道可指定通知訊息的轉送資訊。在設定管道時,您必須指定要接收通知的特定網址。每當管道的資源變更,Google Drive API 都會以 POST 要求的形式傳送通知訊息給該網址。

目前,Google Drive API 支援 fileschanges 方法變更的通知。

建立通知管道

如要要求推播通知,您必須為要監控的每項資源設定通知管道。通知管道設定完成後,只要監控的資源有所變更,Google Drive API 就會通知您的應用程式。

提出觀看要求

每個可觀察的 Google Drive API 資源都有相關聯的 watch 方法,其 URI 格式如下:

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

如要設定特定資源變更相關訊息的通知管道,請將 POST 要求傳送至該資源的 watch 方法。

每個通知管道都會與特定使用者與一項資源 (或一組資源) 建立關聯。除非目前的使用者或服務帳戶擁有這項資源,或是具備這項資源的存取權,否則 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 屬性字串,專門用來識別專案中的新通知管道。建議您使用通用專屬 ID (UUID) 或任何類似的不重複字串。長度上限:64 個半形字元。

    您設定的 ID 值會回送到您對此管道收到的每則通知訊息的 X-Goog-Channel-Id HTTP 標頭中。

  • 設為 web_hook 值的 type 屬性字串。

  • 這個 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 參考資料中 fileschanges 方法的 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.
}

除了您在要求中傳送的屬性外,傳回的資訊也包含 resourceIdresourceUri,以便識別這個通知管道正在查看的資源。

您可以將傳回的資訊傳送至其他通知管道作業,例如想要停止接收通知的時間。

如要進一步瞭解回應,請參閱 API 參考資料中 fileschanges 方法的 watch 方法。

同步處理訊息

建立用來監控資源的通知管道後,Google Drive API 會傳送 sync 訊息,表示通知已開始。這些訊息的 X-Goog-Resource-State HTTP 標頭值是 sync。由於網路時間問題,即使您收到 watch 方法回應,也可能收到 sync 訊息。

您可以放心忽略 sync 通知,但也可以使用此通知。舉例來說,如果您決定不保留管道,可以在呼叫中使用 X-Goog-Channel-IDX-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 Drive API 內部限製或預設值決定 (使用較嚴格的值)。通道的到期時間 (如有) 會以 Unix 時間戳記 (以毫秒為單位) 的形式納入 watch 方法傳回的資訊中。此外,應用程式收到的每則通知訊息中,都會在 X-Goog-Channel-Expiration HTTP 標頭中,以清楚易懂的格式提供到期日和時間 (使用人類可讀的格式)。

目前系統無法自動續訂通知管道,當管道即將到期時,您必須呼叫 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 觸發通知的新資源狀態。可能的值:syncaddremoveupdatetrashuntrashchange
X-Goog-Resource-URI 受監控資源的 API 版本專屬 ID。
有時會展示
X-Goog-Changed 關於異動的其他詳細資料。 可能的值:contentparentschildrenpermissions。 未提供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"
}

根據通知內容採取行動

如要表示成功,您可以傳回下列任一狀態碼:200201202204102

如果您的服務使用 Google API 用戶端程式庫,並傳回 500502503504,Google Drive API 就會以指數輪詢進行重試。每組其他傳回狀態碼都會視為訊息失敗。

瞭解 Google Drive API 通知事件

本節詳細瞭解搭配 Google Drive API 使用推播通知時,會收到的通知訊息。

X-Goog-Resource-State 適用對象 發送時間
sync fileschanges 已成功建立頻道。您應該會開始收到這項動作的通知。
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

這個方法需要您至少提供頻道的 idresourceId 屬性,如以下範例所示。請注意,如果 Google Drive 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"
}