推播通知

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

總覽

Directory API 提供推播通知 調整資源運用方式您可以使用這項功能改善應用程式效能。這可讓您消除與輪詢資源相關的額外網路和運算成本，以便判斷資源是否已變更。每當監控的資源變更時，Directory API 就會通知您 應用程式。

如要使用推播通知，您必須完成以下兩個步驟：

  • 設定接收網址或「Webhook」回呼接收接聽程式。

    這個 是 HTTPS 伺服器，可處理 會在資源變更時觸發

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

    管道會指定通知訊息的路由資訊。在管道設定中，您必須指定要接收通知的特定網址。只要頻道資源有所變更 Directory API 會以 POST 的形式傳送通知訊息 要求至該網址

目前，Directory API 支援 Users 資源變更的通知。

建立通知管道

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

提出觀看要求

每個可觀看的 Directory API 資源都有一個相關聯的 watch 方法，位於以下格式的 URI：

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

若要設定通知管道，以便接收有關 請將 POST 要求傳送給 資源的 watch 方法。

每個通知管道都會與特定使用者和特定資源 (或一組資源) 建立關聯。除非目前的使用者或服務帳戶擁有或具備存取此資源的權限，否則 watch 要求不會成功。

範例

單一網域的 User 資源的所有監控要求，一般格式如下：

POST https://admin.googleapis.com/admin/directory/v1/users/watch?domain=domain&event=event
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.
  "params": {
    "ttl": 3600 // (Optional) Your requested time-to-live for this channel.
  }
}

使用 domain 和 event 參數指定要接收通知的網域和事件類型。

客戶的使用者資源的所有觀看要求都採用一般格式：

POST https://admin.googleapis.com/admin/directory/users/v1/watch?customer=customer&event=event
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.
  "params": {
    "ttl": 3600 // (Optional) Your requested time-to-live for this channel.
  }
}

請使用 customer 和 event 參數指定客戶 Google 帳戶的專屬 ID，以及您要接收通知的事件類型。

event 的可能值如下：

  • add：使用者建立的事件
  • delete：使用者刪除事件
  • makeAdmin：使用者管理員狀態變更事件
  • undelete：使用者已取消刪除活動
  • update：使用者更新活動

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

監控使用者建立的網域 mydomain.com 事件：

POST https://admin.googleapis.com/admin/directory/v1/users/watch?domain=mydomain.com&event=add

留意使用者為客戶 my_customer 建立的事件：

POST https://admin.googleapis.com/admin/directory/v1/users/watch?customer=my_customer&event=add

必要屬性

您必須在每個 watch 要求中提供下列欄位：

  • 專門用於識別此項目的 id 屬性字串 新的通知管道為求明確，建議採用 全域專屬 ID (UUID) 或類似 不重複的字串。長度上限：64 個半形字元。

    您設定的 ID 值會在您透過這個管道收到的每則通知訊息的 X-Goog-Channel-Id HTTP 標頭中回傳。

  • 設為值的 type 屬性字串 web_hook。

  • address 屬性字串會設為網址，用於監聽及回應此通知管道的通知。這是 您的 Webhook 回呼網址，且必須使用 HTTPS。

    請注意，只有在網頁伺服器上安裝有效的 SSL 憑證時，Directory API 才能將通知傳送至這個 HTTPS 位址。無效的憑證包括：

    • 自行簽署的憑證。
    • 由不受信任的來源所簽署的憑證。
    • 已撤銷的憑證。
    • 憑證的主體與目標主機名稱不符。

選用屬性

您也可以在 watch 要求中指定這些選用欄位：

  • 指定任意字串的 token 屬性 值做為頻道符記。您可以將通知管道符記用於各種用途。舉例來說，您可以使用 以便驗證每則傳入訊息的代表管道 應用程式建立元件，以確保使用者不會收到通知 或將此郵件轉送至該網路中的正確目的地 定義您的應用程式長度上限：256 個半形字元。

    權杖會包含在 每則通知都包含 X-Goog-Channel-Token HTTP 標頭 您應用程式收到的訊息

    如果你使用通知管道權杖，建議您：

    • 使用可擴充的編碼格式，例如網址查詢參數。範例：forwardTo=hr&createdBy=mobile

    • 請勿加入 OAuth 權杖等機密資料。

  • 將 expiration 屬性字串設為 Unix 時間戳記 要求 Directory API 的日期和時間 (以毫秒為單位)。 停止傳送這個通知管道的訊息。

    如果管道設有到期時間，則在應用程式收到的每則管道通知訊息中，這項資訊會以 X-Goog-Channel-Expiration HTTP 標頭的值 (以人類可讀格式呈現) 的形式加入。

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

觀看回應

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

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

{
  "kind": "api#channel",
  "id": "01234567-89ab-cdef-0123456789ab", // ID you specified for this channel.
  "resourceId": "B4ibMJiIhTjAQd7Ff2K2bexk8G4", // ID of the watched resource.
  "resourceUri": "https://admin.googleapis.com/admin/directory/v1/users?domain=domain&event=event", // Version-specific ID of the watched resource.
  "token": "target=myApp-myFilesChannelDest", // Present only if one was provided.
  "expiration": 1384823632000, // Actual expiration time as Unix timestamp (in ms), if applicable.
}

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

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

如要進一步瞭解回應，請參閱 API 參考資料中 使用者 資源的 watch 方法。

同步處理訊息

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

您可以安全地忽略 sync 通知，但也可以使用這項通知。舉例來說，如果您決定不保留管道，可以在呼叫中使用 X-Goog-Channel-ID 和 X-Goog-Resource-ID 值，停止接收通知。您也可以使用 sync 通知進行一些初始化作業，為日後的事件做好準備。

Directory 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。這個管道的後續通知訊息編號會比前一個大，但訊息編號不會依序排列。

更新通知管道

通知管道可以有到期時間， 依據您的要求或 Directory API 內部限制決定 或預設值 (使用限制較嚴格的值)。如果管道有到期時間，watch 方法會在傳回的資訊中加入 Unix 時間戳記 (以毫秒為單位)，做為管道的到期時間。此外， 每個 通知訊息，您的應用程式在 X-Goog-Channel-Expiration HTTP 標頭。

目前目前無法自動續訂通知管道。時間 某個管道即將到期，您必須呼叫 watch 方法。一如往常，您必須在 新頻道的 id 屬性。請注意，當同一個資源的兩個通知管道都處於作用中狀態時，可能會出現「重疊」的時間。

接收通知

每當監控的資源有所變更，應用程式就會收到說明變更內容的通知訊息。Directory API 會將這些訊息以 HTTPS POST 要求的形式傳送至您為此通知管道指定的 address 屬性網址。

解讀通知訊息格式

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

標頭

Directory 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#directory#user」。
id 使用者資源的專屬 ID。
etag 通知訊息的 ETag。與使用者資源的 ETag 不同。
primaryEmail 使用者的主要電子郵件地址。

範例

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

POST https://mydomain.com/notifications // Your receiving URL.
Content-Type: application/json; utf-8
Content-Length: 0
X-Goog-Channel-ID: directoryApiId
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/directory/v1/users?domain=domain&event=event
X-Goog-Resource-State:  event
X-Goog-Message-Number: 10

{
  "kind": "admin#directory#user",
  "id": long,
  "etag": string,
  "primaryEmail": string
}

使用者刪除事件的範例：

POST https://mydomain.com/notifications // Your receiving URL.
Content-Type: application/json; utf-8
Content-Length: 189
X-Goog-Channel-ID: deleteChannel
X-Goog-Channel-Token: 245t1234tt83trrt333
X-Goog-Channel-Expiration: Mon, 09 Dec 2013 22:24:23 GMT
X-Goog-Resource-ID:  B4ibMJiIhTjAQd7Ff2K2bexk8G4
X-Goog-Resource-URI: https://admin.googleapis.com/admin/directory/v1/users?domain=mydomain.com&event=delete&alt=json
X-Goog-Resource-State:  delete
X-Goog-Message-Number: 236440

{
  "kind": "admin#directory#user",
  "id": "111220860655841818702",
  "etag": "\"Mf8RAmnABsVfQ47MMT_18MHAdRE/evLIDlz2Fd9zbAqwvIp7Pzq8UAw\"",
  "primaryEmail": "user@mydomain.com"
}

根據通知內容採取行動

如要表示成功，您可以傳回下列任一狀態碼： 200、201、202、204或 102。

如果您的服務使用 Google 的 API 用戶端程式庫，並傳回 500、502、503 或 504，Directory API 會以指數遞減方式重試。其他所有傳回狀態碼都視為郵件失敗。

停止通知

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

https://www.googleapis.com/admin/directory_v1/channels/stop

要使用這個方法，您至少必須提供頻道的 id 和 resourceId 屬性，如 範例。請注意，如果 Directory API 提供多個類型 含有 watch 方法的資源，但只有一個方法 stop 方法。

只有具備適當權限的使用者才能停止頻道。請特別注意以下幾點：

  • 如果頻道是由一般使用者帳戶所建立，則只有 來自同一用戶端的 OAuth 2.0 用戶端 ID 驗證權杖) 建立管道時即可停止管道。
  • 如果頻道是由服務帳戶建立，則同一個用戶端的任何使用者都可以停止頻道。

以下程式碼範例說明如何停止接收通知：

POST https://www.googleapis.com/admin/directory_v1/channels/stop
  
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

{
  "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a66",
  "resourceId": "ret08u3rv24htgh289g"
}