本頁面由 Cloud Translation API 翻譯而成。

推播通知

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

總覽

Admin SDK API 提供推播通知調整資源運用方式您可以運用這項功能提高應用程式可讓您擺脫額外的網路和運算資源輪詢資源判定資源是否發生變化所衍生的費用。每當監控的資源變更時，Admin SDK API 就會通知您應用程式。

若要使用推播通知，您必須執行下列兩項操作：

設定接收網址或「Webhook」回呼接收接聽程式。
這個是 HTTPS 伺服器，可處理會在資源變更時觸發
為每個要更新的資源端點設定 (「通知管道」) 手錶。
管道會指定通知的轉送資訊訊息。設定頻道時，您必須指明含有選擇要接收通知的意願只要頻道資源有所變更 Admin SDK API 會以 POST 的形式傳送通知訊息要求至該網址

目前，Admin SDK API 支援活動資源。

建立通知管道

如要請求推播通知，請設定通知管道選擇要監控的資源設定通知管道後後，Admin SDK API 會在任何查看資源時，通知應用程式並輸入變更內容

提出觀看要求

每項可觀察的 Admin SDK API 資源都具有 watch 方法，格式如下：

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 標頭的訊息。
設為值的 type 屬性字串 web_hook。
address 屬性字串，設為監聽的網址並回應這個通知管道的通知。這是您的 Webhook 回呼網址，且必須使用 HTTPS。

請注意，Admin SDK API 可以傳送通知給您必須安裝有效的 SSL 憑證網路伺服器無效的憑證包括：
- 自行簽署的憑證。
- 由不受信任的來源所簽署的憑證。
- 已撤銷的憑證。
- 憑證與目標不符的憑證主機名稱。

選用屬性

您也可以透過 watch 要求：

指定任意字串的 token 屬性值做為頻道符記。您可以使用通知管道符記舉例來說，您可以使用以便驗證每則傳入訊息的代表管道應用程式建立元件，以確保使用者不會收到通知或將此郵件轉送至該網路中的正確目的地追蹤您的應用程式長度上限： 256 個半形字元，
權杖會包含在每則通知都包含 X-Goog-Channel-Token HTTP 標頭您應用程式收到的訊息

如果你使用通知管道權杖，建議您：
- 使用延伸編碼格式，例如網址查詢參數。範例：forwardTo=hr&createdBy=mobile
- 請勿加入 OAuth 權杖等機密資料。
，瞭解如何調查及移除這項存取權。
注意：如果必須傳送高度敏感資料資料，請確定資料已加密，再新增到符記。
將 expiration 屬性字串設為 Unix 時間戳記您希望 Admin SDK API 發送的日期和時間 (以毫秒為單位) 停止傳送這個通知管道的訊息。

如果管道設有到期時間，系統就會將其納入 X-Goog-Channel-Expiration HTTP 標頭 (人類可讀) 格式) 傳送給您的應用程式獲得的收益

，瞭解如何調查及移除這項存取權。

注意： Admin SDK API 的到期時間最長為 21,600 秒。如果您沒有設定 expiration 屬性，過期時間預設為 21600 秒。

如要進一步瞭解要求，請參閱 watch 方法。針對 API 參考資料中的 Activities 資源。

觀看回覆

如果 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，用於識別此項目正在觀看的資源通知管道

注意：resourceId 屬性為資源的穩定版本 ID。 resourceUri 屬性是所監控項目的標準 URI 與目前 API 版本相關的部分資源專屬版本

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

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

同步處理訊息

建立要查看資源的通知管道後 Admin SDK API 會傳送 sync 訊息來表示正在啟動通知。X-Goog-Resource-State HTTP 這些郵件的標頭值是 sync。因網路限制時間問題，有可能收到 sync 訊息您就會收到 watch 方法回應

您可以放心忽略 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 內部限制決定或預設值 (使用限制較嚴格的值)。頻道的有效期限時間 (如果有的話)，也會納入 Unix 時間戳記中 watch 方法傳回的資訊 (以毫秒為單位)。此外，每個通知訊息，您的應用程式在 X-Goog-Channel-Expiration HTTP 標頭。

目前目前無法自動續訂通知管道。時間某個管道即將到期，您必須呼叫 watch 方法。一如往常，您必須在新頻道的 id 屬性。請注意視為「重疊」系統會在這段時間內是否正在使用相同資源

接收通知

每當已監控的資源變更時，應用程式就會收到系統會發送通知訊息來說明變更Admin SDK API 會將視為 HTTPS POST 要求，並對您所指定的網址這則通知的 address 屬性頻道。

注意：通知傳送 HTTPS 要求指定 APIs-Google 的使用者代理程式，並遵循 robots.txt 的設定指令，如 API 使用者代理程式。

解讀通知訊息格式

所有通知訊息都包含一組 HTTP 標頭 X-Goog- 前置字串。部分通知類型還包括訊息內文。

標頭

Admin SDK API 發布至您收到的通知訊息網址包含下列 HTTP 標頭：

標頭	說明
一律顯示在所有人的主畫面上
`X-Goog-Channel-ID`	UUID 或其他專屬字串，用來識別這個 ID 通知管道
`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-DDThh:mm:ssTZD。例如：2010-04-05T17:30:04+01:00。
`id.uniqueQualifier`	如果多個事件的時間相同，則為不重複的限定詞。
`id.applicationName`	事件所屬的應用程式名稱。可能的值包括：管理員日曆雲端硬碟群組 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`	參數的布林值。

範例

活動資源事件的通知訊息採用一般格式：

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 屬性可控制自動停止通知的時間。你可以選擇停止接收特定頻道的通知過期方法是呼叫 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"
}