推播通知

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

總覽

Google Calendar API 提供推播通知，方便您查看資源變更情形。您可以使用這項功能改善應用程式的效能。可讓您排除輪詢資源產生的額外網路和運算費用，藉此判斷資源是否已變更。每當有檢視的資源發生變更，Google Calendar API 就會通知您的應用程式。

如要使用推播通知，您必須完成以下兩項操作：

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

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

  • 針對您要監控的每個資源端點設定通知管道。

    管道可指定通知訊息的轉送資訊。在頻道設定過程中，您會指定要接收通知的特定網址。每當有頻道資源有所變更，Google Calendar API 都會傳送通知訊息做為該網址的 POST 要求。

Google Calendar API 目前支援對 Acl、CalendarList、Events 和 Settings 資源的變更通知。

建立通知管道

如要要求推送通知，您必須為每項想觀看的資源設定通知管道。設定通知管道之後，Google 日曆 API 會在發現任何觀測資源變更時，通知您的應用程式。

提出智慧手錶要求

每個可觀察 Google Calendar API 資源在 URI 都有以下的 watch 方法，其格式如下：

https://www.googleapis.com/apiName/apiVersion/resourcePath/watch

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

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

範例

開始觀看指定日曆上的活動集異動：

POST https://www.googleapis.com/calendar/v3/calendars/my_calendar@gmail.com/events/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-myCalendarChannelDest", // (Optional) Your channel token.
  "expiration": 1426325213000 // (Optional) Your requested channel expiration time.
}

必要屬性

您必須為每項 watch 要求提供：

  • id 屬性字串，可用於識別專案中的這個新通知管道。建議您使用通用唯一識別碼 (UUID) 或任何類似的不重複字串。長度上限：64 個半形字元。

    您設定的 ID 值會透過您針對這個頻道收到的通知訊息，於 X-Goog-Channel-Id HTTP 標頭中回應。

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

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

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

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

選用屬性

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

  • token 屬性，用於指定可做為管道權杖的任意字串值。您可以將通知管道權杖用於各種用途。例如，您可以使用這個符記來確認每則傳入訊息是否適用於應用程式所建立的管道，以確保通知不會遭到假冒，或根據管道的用途將訊息轉送至應用程式中的正確目的地。長度上限：256 個半形字元。

    您應用程式針對這個頻道收到的每則通知訊息，都會包含在 X-Goog-Channel-Token 的 HTTP 標頭中。

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

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

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

  • 在 Google 日曆 API 停止通知這個通知管道郵件的日期和時間時，您可以將 expiration 屬性字串設為 Unix 時間戳記 (以毫秒為單位)。

    如果管道設有到期時間，則會在應用程式針對此管道收到的每則通知訊息中，加入為 X-Goog-Channel-Expiration HTTP 標頭的值 (這次以使用者可理解的格式)。

如要進一步瞭解該要求，請參閱 API 參考資料中 Acl、CalendarList、活動和設定資源的 watch 方法。

智慧手錶回應

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

智慧手錶回應的訊息內文會提供您剛剛建立的通知管道相關資訊，如下方範例所示。

{
  "kind": "api#channel",
  "id": "01234567-89ab-cdef-0123456789ab"", // ID you specified for this channel.
  "resourceId": "o3hgv1538sdjfh", // ID of the watched resource.
  "resourceUri": "https://www.googleapis.com/calendar/v3/calendars/my_calendar@gmail.com/events", // Version-specific ID of the watched resource.
  "token": "target=myApp-myCalendarChannelDest", // Present only if one was provided.
  "expiration": 1426325213000, // Actual expiration time as Unix timestamp (in ms), if applicable.
}

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

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

如要進一步瞭解回應，請參閱 API 參考資料中的 Acl、CalendarList、活動和設定資源的 watch 方法。

同步處理訊息

在您建立新的通知管道以觀看資源之後，Google Calendar API 會傳送 sync 訊息，表示已開始接收通知。這些訊息的 X-Goog-Resource-State HTTP 標頭值為 sync。由於網路時間發生問題，您甚至能在收到 watch 方法回應前收到 sync 訊息。

您可以忽略 sync 通知，但也可以充分運用該通知。例如，如果您決定不要保留頻道，則可以在呼叫中使用 X-Goog-Channel-ID 和 X-Goog-Resource-ID 值來停止接收通知。您也可以使用 sync 通知執行一些初始化作業，為日後的事件做好準備。

Google Calendar 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 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。此管道後續每收到的通知就會包含一組比前一個訊息更大的訊息訊息，但訊息編號不會依序顯示。

續購通知管道

通知管道會有到期時間，該值會依照要求、任何 Google Calendar API 的內部限製或預設值 (數值越嚴格) 決定。管道的到期時間 (如有) 則以 Unix 時間戳記 (以毫秒為單位) 納入 watch 方法傳回的資訊。此外，系統會在 X-Goog-Channel-Expiration HTTP 標頭中，應用程式針對此管道收到的每則通知訊息中，加入到期時間 (以使用者可理解的格式)。

目前無法自動續購通知管道。如果管道即將到期，則必須呼叫 watch 方法建立新的管道。一如既往，您必須為新管道的 id 屬性使用不重複的值。請注意，同一個資源中的兩個通知管道啟用時，可能會「重疊」的時間範圍。

接收通知

只要觀察到的資源發生變更，應用程式就會收到說明異動的通知訊息。Google Calendar API 會將這些訊息以 HTTPS POST 要求傳送至您在這個通知管道中指定為「地址」的網址。

瞭解通知訊息格式

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

標頭

Google Calendar API 張貼到接收網址的通知訊息包含下列 HTTP 標頭：

標題 說明
一律顯示
X-Goog-Channel-ID 您用於識別這個通知管道的 UUID 或其他專屬字串。
X-Goog-Message-Number 識別這個通知管道這則訊息的整數。sync 訊息的值一律為 1。管道中的每個後續訊息訊息數量都會增加，但不會依序顯示。
X-Goog-Resource-ID 識別已查看資源的不透明值。這個 API 在各個 API 版本中皆保持穩定。
X-Goog-Resource-State 觸發通知的新資源狀態。可能的值包括：sync、exists 或 not_exists。
X-Goog-Resource-URI 所查看資源的 API 版本專屬 ID。
偶爾
X-Goog-Channel-Expiration 通知管道到期日的日期與時間，以使用者可理解的格式表示。只有在已定義時才會顯示。
X-Goog-Channel-Token 由應用程式所設定的通知管道權杖，可用於驗證通知來源。只有在已定義時才會顯示。

Google Calendar API 張貼到您接收網址的通知訊息不含訊息內文。這些訊息未包含更新資源的特定資訊，您必須再次呼叫 API 才能查看完整的變更詳細資料。

範例

更改已修改事件的通知通知訊息：

POST https://mydomain.com/notifications // Your receiving URL.
Content-Type: application/json; utf-8
Content-Length: 0
X-Goog-Channel-ID: 4ba78bf0-6a47-11e2-bcfd-0800200c9a66
X-Goog-Channel-Token: 398348u3tu83ut8uu38
X-Goog-Channel-Expiration: Tue, 19 Nov 2013 01:13:52 GMT
X-Goog-Resource-ID:  ret08u3rv24htgh289g
X-Goog-Resource-URI: https://www.googleapis.com/calendar/v3/calendars/my_calendar@gmail.com/events
X-Goog-Resource-State:  exists
X-Goog-Message-Number: 10

回應通知

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

如果您的服務使用 Google 的 API 用戶端程式庫，並傳回 500、502、503 或 504，Google Calendar API 會透過指數輪詢重試。其他退貨狀態碼都會構成訊息失敗。

瞭解 Google Calendar API 通知事件

本節詳細說明透過 Google Calendar API 使用推播通知時，可以收到的通知訊息。

X-Goog-Resource-State 套用至 提交時間：
sync ACL、日曆清單、活動、設定。 已成功建立新頻道。您將會開始收到通知。
exists ACL、日曆清單、活動、設定。 資源有所變更。可能的變更包括建立新資源，或修改現有資源。

停止通知

到期時間是指通知自動停止的時間。如果不想在特定管道到期前接收通知，請呼叫下列 URI 的 stop 方法：

https://www.googleapis.com/calendar/v3/channels/stop

這個方法需要您至少提供頻道的 id 和 resourceId 屬性，如以下範例所示。請注意，即使 Google Calendar API 提供多種類型的資源，都有 watch 方法，只有一個 stop 方法。

只有具備適當權限的使用者才能停止頻道。我們特別建議你採取以下做法：

  • 如果頻道是由一般使用者帳戶建立，則只有建立該頻道的同一用戶端 (由 OAuth 2.0 用戶端驗證憑證 ID 所識別) 所建立的使用者可以停止該頻道。
  • 如果管道是由服務帳戶建立，同一個用戶端中的任何使用者都可以停止執行管道。
POST https://www.googleapis.com/calendar/v3/channels/stop
  
Authorization: Bearer {auth_token_for_current_user}
Content-Type: application/json

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