推播通知

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

總覽

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

您可以使用 userKeyapplicationNameeventNamefilters 參數來只接收特定事件、使用者或應用程式的通知。

注意:為了方便說明,以下範例省略了要求主體。

監控所有管理員活動:

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

除了您在要求中傳送的屬性之外,系統也會傳回 resourceIdresourceUri,用於識別這個通知管道中正在監控的資源。

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

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

同步處理訊息

建立通知管道來監控資源後,Admin SDK API 會傳送 sync 訊息,指出通知已開始。這些訊息的 X-Goog-Resource-State HTTP 標頭值為 sync。由於網路時間問題,您可能會在收到 watch 方法回應之前,就收到 sync 訊息。

您可以安全地忽略 sync 通知,但也可以使用這項通知。舉例來說,如果您決定不保留管道,可以在呼叫中使用 X-Goog-Channel-IDX-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 標頭:

標頭 說明
一律顯示
X-Goog-Channel-ID 您提供的 UUID 或其他專屬字串,用於識別這個通知管道。
X-Goog-Message-Number 這個通知管道用來識別此訊息的整數。sync 訊息的值一律為 1。頻道上的後續訊息會增加訊息編號,但並非依序排列。
X-Goog-Resource-ID 識別受監控資源的不易解讀值。這個 ID 在各 API 版本中皆為穩定狀態。
X-Goog-Resource-State 觸發通知的新資源狀態。可能的值: sync事件名稱
X-Goog-Resource-URI 受監控資源的 API 版本專屬 ID。
有時會出現
X-Goog-Channel-Expiration 通知管道到期的日期和時間,以使用者可理解的格式表示。只有在定義時才會出現。
X-Goog-Channel-Token 應用程式設定的通知管道權杖,可用於驗證通知來源。只有在定義時才會出現。

活動通知訊息會在要求主體中包含下列資訊:

屬性 說明
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 支援 IPv4IPv6
events[] 報表中的活動事件。
events[].type 事件類型。管理員變更的 Google Workspace 服務或功能會在 type 屬性中標示,而該屬性會使用 eventName 屬性標示事件。
events[].name 事件的名稱。這是 API 回報的活動具體名稱。每個 eventName 都與特定 Google Workspace 服務或功能相關,API 會將這些服務或功能歸類為不同類型的事件。
一般而言,對於 eventName 要求參數:
  • 如果沒有提供 eventName,報表會傳回 eventName 的所有可能例項。
  • 當您要求 eventName 時,API 的回應會傳回包含該 eventName 的所有活動。除了所要求的活動以外,傳回的活動可能還有其他 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"
        }
      ]
    }
  ]
}

根據通知內容採取行動

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

如果您的服務使用 Google 的 API 用戶端程式庫,並傳回 500502503504,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

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