本文件將說明如何使用推播通知 並在資源變更時套用應用程式
總覽
Google Drive API 提供推播通知 調整資源運用方式您可以運用這項功能提高 應用程式可讓您擺脫額外的網路和運算資源 輪詢資源判定資源是否發生變化所衍生的費用。 每當已監控的資源變更時,Google Drive API 就會通知您 應用程式。
若要使用推播通知,您必須執行下列兩項操作:
設定接收網址或「Webhook」回呼接收接聽程式。
這個 是 HTTPS 伺服器,可處理 會在資源變更時觸發
管道會指定通知的轉送資訊 訊息。設定頻道時,您必須指明含有 選擇要接收通知的意願只要頻道資源有所變更 Google Drive API 會以
POST
的形式傳送通知訊息 要求至該網址
建立通知管道
如要請求推播通知,請設定通知管道 選擇要監控的資源設定通知管道後 後,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
,用於識別此項目正在觀看的資源
通知管道
您可以將傳回的資訊傳遞至其他通知管道 例如您想要停止接收 通知。
同步處理訊息
建立要查看資源的通知管道後
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 標頭:
標頭 | 說明 |
---|---|
一律顯示在所有人的主畫面上 | |
|
UUID 或其他專屬字串,用來識別這個 ID 通知管道 |
|
用於識別此通知訊息的整數
頻道。sync 訊息的值一律為 1 。訊息
頻道後續訊息的成長率
順序。 |
|
識別受監控資源的不透明值。這個 ID 是 各個 API 版本皆保持穩定 |
|
觸發通知的新資源狀態。
可能的值包括:
sync 、add 、remove 、update 、
trash 、untrash 或 change
,直接在 Google Cloud 控制台實際操作。
|
|
受監控資源的 API 版本專屬 ID。 |
有時會 | |
|
變更項目的其他詳細資料。
可能的值包括:
content ,
parents ,
children ,或
permissions
,直接在 Google Cloud 控制台實際操作。
不含 sync 訊息。 |
|
通知管道到期的日期和時間,以 人類可讀的格式只有在已定義的情況下才會顯示。 |
|
由應用程式設定的通知管道符記 並用於驗證通知來源出現以下情況時才會顯示 |
「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 中使用推播通知時接收。
送達時間 | ||
---|---|---|
sync |
files 、changes |
已成功建立頻道。您應該會開始收到有關提醒的通知。 |
add |
files |
已建立或共用資源。 |
|
files |
已刪除或取消共用現有資源。 |
|
files |
資源的一或多個屬性 (中繼資料) 已更新。 |
|
files |
已將資源移至垃圾桶。 |
|
files |
已將資源從垃圾桶中移除。 |
|
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" }