本文將說明如何使用推播通知,在資源發生變更時通知應用程式。
總覽
Admin SDK API 提供推播通知,方便您監控資源的變更。您可以使用這項功能改善應用程式效能。這可讓您消除與輪詢資源相關的額外網路和運算成本,以便判斷資源是否已變更。每當監控的資源變更時,Admin SDK API 就會通知應用程式。
如要使用推播通知,您必須完成以下兩個步驟:
設定接收網址或「Webhook」回呼接收器。
這個 HTTPS 伺服器會處理在資源變更時觸發的 API 通知訊息。
為每個要監控的資源端點設定 (通知管道)。
管道會指定通知訊息的路由資訊。在管道設定中,您必須指定要接收通知的特定網址。每當頻道的資源發生變更時,Admin SDK API 就會將通知訊息以
POST
要求傳送至該網址。
目前,Admin SDK API 支援通知,可用於通知 Activities 資源的變更。
建立通知管道
若要要求推播通知,您必須針對要監控的每項資源設定通知管道。設定通知管道後,Admin SDK API 會在任何監控的資源發生變更時通知應用程式。
提出監控要求
每個可觀看的 Admin SDK API 資源都有一個相關聯的 watch
方法,位於下列格式的 URI:
https://www.googleapis.com/API_NAME/API_VERSION/RESOURCE_PATH/watch
如要設定通知管道,以便接收有關特定資源變更的訊息,請將 POST
要求傳送至資源的 watch
方法。
每個通知管道都會與特定使用者和特定資源 (或一組資源) 建立關聯。除非目前的使用者或服務帳戶擁有或具備存取此資源的權限,否則 watch
要求不會成功。
範例
所有活動資源的監控要求都採用一般格式:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/userKey or all/applications/applicationName/watch Authorization: Bearer auth_token_for_current_user 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 channel token. "payload": true, // (Optional) Whether to include the payload (message body) in notifications. "expiration": 3600 // (Optional) Your requested channel expiration time. }
您可以使用 userKey、applicationName、eventName
和 filters
參數來只接收特定事件、使用者或應用程式的通知。
注意:為了方便說明,以下範例省略了要求主體。
監控所有管理員活動:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin/watch
監控所有文件活動:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/docs/watch
留意特定使用者的管理員活動:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/liz@example.com/applications/admin/watch
監控特定事件 (例如變更使用者密碼):
POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin/watch?eventName=CHANGE_PASSWORD
監控特定文件的變更:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/docs/watch?eventName=EDIT&filters==doc_id=123456abcdef
必要屬性
您必須在每個 watch
要求中提供下列欄位:
-
id
屬性字串,專門用來在專案中識別這個新通知管道。建議您使用通用專屬 ID (UUID) 或任何類似的專屬字串。長度上限:64 個半形字元。您設定的 ID 值會在您透過這個管道收到的每則通知訊息的
X-Goog-Channel-Id
HTTP 標頭中回傳。 -
設為
web_hook
值的type
屬性字串。 -
address
屬性字串,設為監聽並回應這個通知管道的通知。這是您的 Webhook 回呼網址,必須使用 HTTPS。請注意,只有在網路伺服器上安裝有效的 SSL 憑證時,Admin SDK API 才能將通知傳送至這個 HTTPS 位址。無效的憑證包括:
- 自行簽署的憑證。
- 由不受信任的來源所簽署的憑證。
- 已撤銷的憑證。
- 憑證的主體與目標主機名稱不符。
選用屬性
您也可以在 watch
要求中指定這些選用欄位:
-
token
屬性可指定任意字串值,用於做為頻道權杖。您可以將通知管道符記用於各種用途。舉例來說,您可以使用權杖驗證每則傳入訊息是否屬於應用程式建立的管道,以確保通知不會遭到偽造,或是根據管道的用途,將訊息路由至應用程式中的正確目的地。長度上限:256 個半形字元。權杖會納入應用程式透過這個管道收到的每則通知訊息中的
X-Goog-Channel-Token
HTTP 標頭。如果您使用通知管道符記,建議您:
使用經過延伸的編碼格式,例如網址查詢參數。範例:
forwardTo=hr&createdBy=mobile
請勿加入 OAuth 權杖等機密資料。
-
expiration
屬性字串,設定為您希望 Admin SDK API 停止傳送此通知管道的訊息日期和時間的 Unix 時間戳記 (以毫秒為單位)。如果管道設有到期時間,則會在應用程式收到的每則管道通知訊息中,將該時間納入
X-Goog-Channel-Expiration
HTTP 標頭的值 (以人類可讀格式表示)。
如要進一步瞭解要求,請參閱 API 參考資料中 Activities 資源的 watch
方法。
觀看回應
如果 watch
要求成功建立通知管道,則會傳回 HTTP 200 OK
狀態碼。
手錶回應的訊息主體會提供您剛建立的通知管道相關資訊,如以下範例所示。
{ "kind": "api#channel", "id": "reportsApiId", // ID you specified for this channel. "resourceId": "o3hgv1538sdjfh", // ID of the watched resource. "resourceUri": "https://admin.googleapis.com/admin/reports/v1/activity/userKey/applications/applicationName", // Version-specific ID of the watched resource. "token": "target=myApp-myFilesChannelDest", // Present only if one was provided. "expiration": 3600, // Actual expiration time as Unix timestamp (in ms), if applicable. }
除了您在要求中傳送的屬性之外,系統也會傳回 resourceId
和 resourceUri
,用於識別這個通知管道中正在監控的資源。
您可以將傳回的資訊傳遞至其他通知管道操作,例如想停止接收通知時。
如要進一步瞭解回應,請參閱 API 參考資料中 Activities 資源的 watch
方法。
同步處理訊息
建立通知管道來監控資源後,Admin SDK API 會傳送 sync
訊息,指出通知已開始。這些訊息的 X-Goog-Resource-State
HTTP 標頭值為 sync
。由於網路時間問題,您可能會在收到 watch
方法回應之前,就收到 sync
訊息。
您可以安全地忽略 sync
通知,但也可以使用這項通知。舉例來說,如果您決定不保留管道,可以在呼叫中使用 X-Goog-Channel-ID
和 X-Goog-Resource-ID
值,停止接收通知。您也可以使用 sync
通知執行一些初始化作業,為日後的事件做好準備。
Admin SDK 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
。這個管道的後續通知訊息編號會比前一個大,但訊息編號不會依序排列。
更新通知管道
通知管道可以設有到期時間,其值取決於您的要求,或由任何 Admin SDK API 內部限製或預設值決定 (使用較嚴格的值)。如果管道有到期時間,watch
方法會在傳回的資訊中加入 Unix 時間戳記 (以毫秒為單位),做為管道的到期時間。此外,應用程式在 X-Goog-Channel-Expiration
HTTP 標頭中,為這個管道收到的每則通知訊息中,都會包含到期日和時間 (以人類可讀格式)。
目前無法自動續訂通知管道。當管道即將到期時,您必須呼叫 watch
方法,將其替換為新的管道。如往常一樣,您必須為新管道的 id
屬性使用專屬值。請注意,當同一個資源的兩個通知管道都處於作用中狀態時,可能會出現「重疊」的時間。
接收通知
每當監控的資源有所變更,應用程式就會收到說明變更內容的通知訊息。Admin SDK API 會將這些訊息以 HTTPS POST
要求的形式傳送至您為此通知管道指定的 address
屬性網址。
解讀通知訊息格式
所有通知訊息都包含一組具有 X-Goog-
前置字串的 HTTP 標頭。某些類型的通知也可以包含訊息主體。
標頭
Admin SDK API 發布至接收網址的通知訊息包含下列 HTTP 標頭:
標頭 | 說明 |
---|---|
一律顯示 | |
|
您提供的 UUID 或其他專屬字串,用於識別這個通知管道。 |
|
這個通知管道用來識別此訊息的整數。sync 訊息的值一律為 1 。頻道上的後續訊息會增加訊息編號,但並非依序排列。 |
|
識別受監控資源的不易解讀值。這個 ID 在各 API 版本中皆為穩定狀態。 |
|
觸發通知的新資源狀態。可能的值:
sync 或事件名稱。
|
|
受監控資源的 API 版本專屬 ID。 |
有時會出現 | |
|
通知管道到期的日期和時間,以使用者可理解的格式表示。只有在定義時才會出現。 |
|
應用程式設定的通知管道權杖,可用於驗證通知來源。只有在定義時才會出現。 |
活動通知訊息會在要求主體中包含下列資訊:
屬性 | 說明 |
---|---|
kind |
用來標示這項資源為活動資源。值:固定字串「admin#reports#activity 」。 |
id |
活動記錄的專屬識別碼。 |
id.time |
活動發生時間。這個值採用 ISO 8601 日期和時間格式,時間為完整日期加上時、分、秒,格式為 YYYY-MM-DDTh:mm:ssTZD。例如 2010-04-05T17:30:04+01:00。 |
id.uniqueQualifier |
如果有多個事件發生在同一時間,則使用這個專屬限定條件。 |
id.applicationName |
事件所屬的應用程式名稱。可能的值包括: |
id.customerId |
Google Workspace 帳戶的專屬 ID。 |
actor |
執行動作的使用者。 |
actor.callerType |
執行報告所列活動的作者類型。在這個 API 版本中,callerType 是執行報告中列出動作的 USER 或 OAuth 2LO 實體要求。 |
actor.email |
遭檢舉活動的使用者主要電子郵件地址。 |
actor.profileId |
使用者的專屬 Google Workspace 個人資料 ID。 |
ownerDomain |
管理控制台或文件應用程式的文件擁有者的網域。這是指受到報表事件影響的網域。 |
ipAddress |
執行動作的使用者 IP 位址。這是使用者登入 Google Workspace 時的網際網路通訊協定位址 (IP 位址),可能會反映使用者的實際位置,也可能不會。舉例來說,IP 位址可能是使用者 Proxy 伺服器的位址,也可能是虛擬私人網路 (VPN) 位址。這個 API 支援 IPv4 和 IPv6。 |
events[] |
報表中的活動事件。 |
events[].type |
事件類型。管理員變更的 Google Workspace 服務或功能會在 type 屬性中標示,而該屬性會使用 eventName 屬性標示事件。 |
events[].name |
事件的名稱。這是 API 回報的活動具體名稱。每個 eventName 都與特定 Google Workspace 服務或功能相關,API 會將這些服務或功能歸類為不同類型的事件。一般而言,對於 eventName 要求參數:
|
events[].parameters[] |
各種應用程式的參數值組合。 |
events[].parameters[].name |
參數的名稱。 |
events[].parameters[].value |
參數的字串值。 |
events[].parameters[].intValue |
參數的整數值。 |
events[].parameters[].boolValue |
參數的布林值。 |
範例
活動資源事件的通知訊息一般格式如下:
POST https://mydomain.com/notifications // Your receiving URL. Content-Type: application/json; utf-8 Content-Length: 0 X-Goog-Channel-ID: reportsApiId X-Goog-Channel-Token: 398348u3tu83ut8uu38 X-Goog-Channel-Expiration: Tue, 29 Oct 2013 20:32:02 GMT X-Goog-Resource-ID: ret08u3rv24htgh289g X-Goog-Resource-URI: https://admin.googleapis.com/admin/reports/v1/activity/userKey/applications/applicationName X-Goog-Resource-State: eventName X-Goog-Message-Number: 10 { "kind": "admin#reports#activity", "id": { "time": datetime, "uniqueQualifier": long, "applicationName": string, "customerId": string }, "actor": { "callerType": string, "email": string, "profileId": long }, "ownerDomain": string, "ipAddress": string, "events": [ { "type": string, "name": string, "parameters": [ { "name": string, "value": string, "intValue": long, "boolValue": boolean } ] } ] }
管理員活動事件範例:
POST https://mydomain.com/notifications // Your receiving URL. Content-Type: application/json; utf-8 Content-Length: 596 X-Goog-Channel-ID: reportsApiId X-Goog-Channel-Token: 245t1234tt83trrt333 X-Goog-Channel-Expiration: Tue, 29 Oct 2013 20:32:02 GMT X-Goog-Resource-ID: ret987df98743md8g X-Goog-Resource-URI: https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin?alt=json X-Goog-Resource-State: CREATE_USER X-Goog-Message-Number: 23 { "kind": "admin#reports#activity", "id": { "time": "2013-09-10T18:23:35.808Z", "uniqueQualifier": "-0987654321", "applicationName": "admin", "customerId": "ABCD012345" }, "actor": { "callerType": "USER", "email": "admin@example.com", "profileId": "0123456789987654321" }, "ownerDomain": "apps-reporting.example.com", "ipAddress": "192.0.2.0", "events": [ { "type": "USER_SETTINGS", "name": "CREATE_USER", "parameters": [ { "name": "USER_EMAIL", "value": "liz@example.com" } ] } ] }
根據通知內容採取行動
如要表示成功,您可以傳回下列任一狀態碼:200
、201
、202
、204
或 102
。
如果您的服務使用 Google 的 API 用戶端程式庫,並傳回 500
、502
、503
或 504
,Admin SDK API 會以指數遞減方式重試。其他所有傳回狀態碼都會視為訊息傳送失敗。
瞭解 Admin SDK API 通知事件
本節將詳細說明搭配 Admin SDK API 使用推播通知時可接收的通知訊息。
Reports API 推播通知包含兩種類型的訊息:同步訊息和事件通知。郵件類型會顯示在 X-Goog-Resource-State
HTTP 標頭中。事件通知的可能值與 activities.list
方法相同。每個應用程式都有獨特的事件:
停止通知
expiration
屬性可控制通知何時自動停止。您可以透過下列 URI 呼叫 stop
方法,選擇在特定頻道到期前停止接收通知:
https://www.googleapis.com/admin/reports_v1/channels/stop
這個方法需要您至少提供管道的 id
和 resourceId
屬性,如以下範例所示。請注意,如果 Admin SDK API 有多種含有 watch
方法的資源類型,則只有一個 stop
方法。
只有具備適當權限的使用者才能停止頻道。請特別注意以下幾點:
- 如果頻道是由一般使用者帳戶建立,只有建立頻道的使用者 (透過 OAuth 2.0 授權憑證的用戶端 ID 識別) 才能停止頻道。
- 如果頻道是由服務帳戶建立,則同一個用戶端的任何使用者都可以停止頻道。
以下程式碼範例說明如何停止接收通知:
POST https://www.googleapis.com/admin/reports_v1/channels/stop Authorization: Bearer CURRENT_USER_AUTH_TOKEN Content-Type: application/json { "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a66", "resourceId": "ret08u3rv24htgh289g" }