資源變更通知

本文件將說明如何使用推播通知 並在資源變更時套用應用程式

總覽

Google Drive API 提供推播通知 調整資源運用方式您可以運用這項功能提高 應用程式可讓您擺脫額外的網路和運算資源 輪詢資源判定資源是否發生變化所衍生的費用。 每當已監控的資源變更時，Google Drive API 就會通知您 應用程式。

若要使用推播通知，您必須執行下列兩項操作：

  • 設定接收網址或「Webhook」回呼接收接聽程式。

    這個 是 HTTPS 伺服器，可處理 會在資源變更時觸發

  • 為每個要更新的資源端點設定 (「通知管道」) 手錶。

    管道會指定通知的轉送資訊 訊息。設定頻道時，您必須指明含有 選擇要接收通知的意願只要頻道資源有所變更 Google Drive API 會以 POST 的形式傳送通知訊息 要求至該網址

目前 Google Drive API 支援對以下項目的異動通知： files 和 changes 方法。

建立通知管道

如要請求推播通知，請設定通知管道 選擇要監控的資源設定通知管道後 時，Google Drive API 會在任何查看資源時，通知應用程式 並輸入變更內容

提出觀看要求

每項可觀察的 Google Drive API 資源都有相關聯的 watch 方法，格式如下：

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

必要屬性

每個 watch 要求都必須提供下列欄位：

  • 專門用於識別此項目的 id 屬性字串 新的通知管道為求明確，建議採用 全域專屬 ID (UUID) 或類似 不重複的字串。長度上限：64 個半形字元。

    您設定的 ID 值會回傳到 每則通知的 X-Goog-Channel-Id HTTP 標頭 的訊息。

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

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

    請注意，Google Drive API 可傳送通知給 您必須安裝有效的 SSL 憑證 網路伺服器無效的憑證包括：

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

選用屬性

您也可以透過 watch 要求：

  • 指定任意字串的 token 屬性 值做為頻道符記。您可以使用通知管道 符記舉例來說，您可以使用 以便驗證每則傳入訊息的代表管道 應用程式建立元件，以確保使用者不會收到通知 或將此郵件轉送至該網路中的正確目的地 追蹤您的應用程式長度上限： 256 個半形字元，

    權杖會包含在 每則通知都包含 X-Goog-Channel-Token HTTP 標頭 您應用程式收到的訊息

    如果你使用通知管道權杖，建議您：

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

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

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

    如果管道設有到期時間，系統就會將其納入 X-Goog-Channel-Expiration HTTP 標頭 (人類可讀) 格式) 傳送給您的 應用程式獲得的收益

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

觀看回覆

如果 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，用於識別此項目正在觀看的資源 通知管道

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

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

同步處理訊息

建立要查看資源的通知管道後 Google Drive API 會傳送 sync 訊息來表示 正在啟動通知。X-Goog-Resource-State HTTP 這些郵件的標頭值是 sync。因網路限制 時間問題，有可能收到 sync 訊息 您就會收到 watch 方法回應

您可以放心忽略 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 Drive API 內部限制決定 或預設值 (使用限制較嚴格的值)。頻道的有效期限 時間 (如果有的話)，也會納入 Unix 時間戳記中 watch 方法傳回的資訊 (以毫秒為單位)。此外， 每個 通知訊息，您的應用程式在 X-Goog-Channel-Expiration HTTP 標頭。

目前目前無法自動續訂通知管道。時間 某個管道即將到期，您必須呼叫 watch 方法。一如往常，您必須在 新頻道的 id 屬性。請注意 視為「重疊」系統會在這段時間內 是否正在使用相同資源

接收通知

每當已監控的資源變更時，應用程式就會收到 系統會發送通知訊息來說明變更您可以透過 Google Drive API 將 視為 HTTPS POST 要求，並對您所指定的網址 這則通知的 address 屬性 管道。

解讀通知訊息格式

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

標頭

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

標頭 說明
一律顯示在所有人的主畫面上
X-Goog-Channel-ID UUID 或其他專屬字串，用來識別這個 ID 通知管道
X-Goog-Message-Number 用於識別此通知訊息的整數 管道。sync 訊息的值一律為 1。訊息 頻道後續訊息的成長率 順序。
X-Goog-Resource-ID 識別受監控資源的不透明值。這個 ID 是 各個 API 版本皆保持穩定
X-Goog-Resource-State 觸發通知的新資源狀態。 可能的值包括： sync、add、remove、update、 trash、untrash 或 change ，直接在 Google Cloud 控制台實際操作。
X-Goog-Resource-URI 受監控資源的 API 版本專屬 ID。
有時會
X-Goog-Changed 變更項目的其他詳細資料。 可能的值包括： content, parents、 children，或 permissions ，直接在 Google Cloud 控制台實際操作。 不含 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 屬性可控制自動停止通知的時間。你可以 選擇停止接收特定頻道的通知 過期方法是呼叫 stop 方法，呼叫期限為 以下 URI：

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

使用這個方法時，您至少必須提供頻道的 id 和 resourceId 屬性，如 範例。請注意，如果 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"
}