推播通知

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

總覽

Admin SDK API 提供推播通知，方便您監控資源變更。您可以使用這項功能提升應用程式效能。這樣一來，您就不必輪詢資源來判斷資源是否已變更，進而省下額外的網路和運算費用。每當受監控的資源發生變化，Admin SDK API 就會通知您的應用程式。

如要使用推播通知，請務必完成以下兩個動作：

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

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

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

  管道會指定通知訊息的路由資訊。設定管道時，您必須指定要接收通知的特定網址。每當管道的資源發生變化，Admin SDK API 就會以 POST 要求的形式，將通知訊息傳送至該網址。

注意：本文所用的「管道」一詞，專指通知管道，而非這個 API 或服務中使用的任何其他類型管道。同一資源可同時啟用多個通知管道。

目前，Admin SDK API 支援「活動」資源的變更通知。

建立通知管道

如要要求推播通知，您必須為要監控的每個資源設定通知管道。設定通知管道後，當任何監控資源發生變化時，Admin SDK API 就會通知應用程式。

提出智慧手錶要求

每個可監看的 Admin SDK API 資源都有相關聯的 watch 方法，URI 格式如下：

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

如要為特定資源的變更訊息設定通知管道，請向該資源的 watch 方法傳送 POST 要求。

每個通知管道都會與特定使用者和特定資源 (或一組資源) 建立關聯。除非目前使用者或服務帳戶擁有或有權存取這項資源，否則 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",
  "type": "web_hook",
  "address": "https://mydomain.com/notifications",
  ...
  "token": "target=myApp-myFilesChannelDest",
  "payload": true,
  "expiration": 3600
}

要求主體具有下列屬性：

• id：UUID 或類似的專屬字串，用於識別這個頻道。
• type：傳送機制類型。這個欄位的值必須為 web_hook。
• address：傳送通知的網址。
• token：每次傳送通知時，系統都會將任意字串傳送至目標地址，以驗證通知是否來自信任來源。
• payload：布林值標記，表示通知是否應包含酬載。
• expiration：通知管道的存留時間 (以秒為單位)。

您可以使用 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/[e-mail]/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 屬性字串，用於在專案中唯一識別這個新通知管道。建議使用通用唯一識別碼 (UUID) 或任何類似的專屬字串。長度上限為 64 個半形字元。

  針對這個頻道收到的每則通知訊息，您設定的 ID 值都會在 X-Goog-Channel-Id HTTP 標頭中回傳。

• type 屬性字串設為 web_hook 值。

• 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 標頭中包含到期時間值 (以人類可解讀的格式)。

注意： 對於 Admin SDK API，最長到期時間為 21600 秒。如果未在要求中設定 expiration 屬性，預設到期時間為目前時間後的 21600 秒。

如要進一步瞭解要求，請參閱 API 參考資料中「活動」資源的 watch 方法。

觀看回覆

如果 watch 要求成功建立通知管道，則會傳回 HTTP 200 OK 狀態碼。

手錶回應的訊息主體會提供您剛建立的通知管道相關資訊，如下列範例所示。

{
  "kind": "api#channel",
  "id": "reportsApiId",
  "resourceId": "o3hgv1538sdjfh",
  "resourceUri": "https://admin.googleapis.com/admin/reports/v1/activity/userKey/applications/applicationName",
  "token": "target=myApp-myFilesChannelDest",
  "expiration": 3600
}

除了您在要求中傳送的屬性外，傳回的資訊也包含 resourceId 和 resourceUri，用於識別這個通知管道上監看的資源。

注意：resourceId 屬性是資源的穩定識別碼，與版本無關。resourceUri 屬性是目前 API 版本中受監控資源的標準 URI，因此是特定版本專用。

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

如要進一步瞭解回應，請參閱 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 屬性網址。

注意：通知傳送 HTTPS 要求會指定 APIs-Google 的使用者代理程式，並遵守 robots.txt 指令，詳情請參閱「APIs Google 使用者代理程式」。

解讀通知訊息格式

所有通知訊息都包含一組具有 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	表示這是 Activity 資源。值：固定字串「admin#reports#activity」。
id	活動記錄的專屬 ID。
id.time	活動發生時間。值採用 ISO 8601 日期和時間格式。時間為完整日期加上時、分、秒，格式為 YYYY-MM-DDThh:mm:ssTZD。例如 2010-04-05T17:30:04+01:00。
id.uniqueQualifier	如果多個事件的時間相同，請使用專屬限定符。
id.applicationName	事件所屬的應用程式名稱。可能的值包括： admin 日曆 雲端硬碟 群組 groups_enterprise login 行動裝置 saml 權杖 user_accounts
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 要求參數如下： 如未提供 eventName，報表會傳回 eventName 的所有可能執行個體。 要求 eventName 時，API 回應會傳回包含該 eventName 的所有活動。傳回的活動可能除了要求的屬性外，還會包含其他 eventName 屬性。
events[].parameters[]	各種應用程式的參數值配對。
events[].parameters[].name	參數的名稱。
events[].parameters[].value	參數的字串值。
events[].parameters[].intValue	參數的整數值。
events[].parameters[].boolValue	參數的布林值。

範例

Activity 資源事件的通知訊息一般格式如下：

POST https://mydomain.com/notifications
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
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": "[e-mail]",
    "profileId": "0123456789987654321"
  },
  "ownerDomain": "apps-reporting.example.com",
  "ipAddress": "192.0.2.0",
  "events": [
    {
      "type": "USER_SETTINGS",
      "name": "CREATE_USER",
      "parameters": [
        {
          "name": "USER_EMAIL",
          "value": "[e-mail]"
        }
      ]
    }
  ]
}

根據通知內容採取行動

如要表示成功，可以傳回下列任一狀態碼：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 方法相同。每個應用程式都有專屬事件：

• admin
• 日曆
• 雲端硬碟
• 群組
• login
• 行動裝置
• saml
• 權杖
• user_accounts

注意：隨著時間推移，系統可能會新增其他資源狀態事件。通知訊息處理常式應會忽略任何非預期的值。

停止通知

expiration 屬性會控管通知自動停止的時間。您可以在特定管道到期前呼叫 stop 方法，選擇停止接收通知，URI 如下：

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

特殊注意事項

使用推播通知時，請注意下列事項：

通知並非 100% 可靠。在正常工作條件下，預期會有少部分訊息遭到捨棄。請務必妥善處理這些遺失的訊息，確保應用程式即使未收到推送訊息，仍能同步處理。

通知的傳送順序可能與事件發生順序不同。