推播通知

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

總覽

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 的 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 屬性字串，專門用來在專案中識別這個新通知管道。建議您使用通用唯一識別碼 (UUID) 或任何類似的不重複字串。長度上限：64 個半形字元。

    每當您收到這個管道的通知訊息時，系統都會在 X-Goog-Channel-Id HTTP 標頭中回應您設定的 ID 值。

  • 設為 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 屬性字串設為 Unix 時間戳記 (以毫秒為單位)，指定您希望 Admin SDK API 停止為此通知管道傳送訊息的日期和時間。

    如果管道設有到期時間，會在應用程式收到該管道的每則通知訊息中，納入為 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 標頭：

標頭 說明
一律顯示
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。
id.time 活動的發生時間。這個值採用 ISO 8601 日期和時間格式。時間是完整日期加上小時、分鐘和秒，格式為 YYYY-MM-DDThh: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 事件類型。在 type 資源中，您可以識別使用 eventName 資源識別事件的 Google Workspace 服務或功能。
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"
        }
      ]
    }
  ]
}

根據通知內容採取行動

如要表示成功，您可以傳回下列任一狀態碼：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"
}