推播通知

必要屬性

每個 watch 要求都必須提供下列欄位：

• 專門用於識別此項目的 id 屬性字串 新的通知管道建議您使用通用專屬 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 屬性字串設為 Unix 時間戳記 您希望 Admin SDK API 發送的日期和時間 (以毫秒為單位) 停止傳送這個通知管道的訊息。

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

觀看回應

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

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

解讀通知訊息格式

所有通知訊息都包含一組含有 X-Goog- 前置字串的 HTTP 標頭。某些類型的通知也可以包含訊息主體。

活動的通知訊息在要求主體中包含以下資訊：

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 方法相同。每個應用程式都有獨特的事件：

• 管理員
• calendar
• 雲端硬碟
• groups
• login
• mobile
• saml
• 符記
• user_accounts