このドキュメントでは、リソースが変更されたときにアプリケーションに通知するプッシュ通知の使用方法について説明します。
概要
Google Calendar API には、リソースの変更を監視できるプッシュ通知が用意されています。この機能を使用して、アプリケーションのパフォーマンスを向上させることができます。リソースが変更済みかどうかを判断するためにリソースをポーリングすることによってネットワークとコンピューティングのコストが増加することを避けることができます。 監視対象のリソースが変更されると、Google Calendar API がアプリケーションに通知します。
プッシュ通知を使用するには、次の 2 つの作業を行う必要があります。
受信 URL（「Webhook」コールバック レシーバー）を設定します。
これは、リソースが変更されたときにトリガーされる API 通知メッセージを処理する HTTPS サーバーです。
監視するリソース エンドポイントごとに通知チャンネルを設定します。
チャネルでは、通知メッセージのルーティング情報を指定します。チャンネル設定の一環として、通知を受け取る URL を指定します。チャンネルのリソースが変更されると、Google Calendar API は
POSTリクエストとして、その URL に通知メッセージを送信します。
現在、Google Calendar API は Acl、CalendarList、Events、Settings リソースの変更の通知をサポートしています。
通知チャンネルの作成
プッシュ通知をリクエストするには、監視するリソースごとに通知チャンネルを設定する必要があります。通知チャンネルの設定後、監視対象リソースが変更されると、Google Calendar API がアプリケーションに通知します。
監視リクエストの要求
監視可能な Google Calendar API リソースには、次の形式の URI に関連付けられた watch メソッドがあります。
https://www.googleapis.com/apiName/apiVersion/resourcePath/watch
特定のリソースに対する変更に関するメッセージの通知チャンネルを設定するには、そのリソースの watch メソッドに POST リクエストを送信します。
各通知チャンネルは、特定のユーザーと特定のリソース（またはリソースのセット）に関連付けられています。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（Universally Unique Identifier）または同様の一意の文字列を使用することをおすすめします。最大 64 文字を設定できます。設定した ID 値は、このチャンネルで受信するすべての通知メッセージの
X-Goog-Channel-IdHTTP ヘッダーにそのまま使用されます。 -
値
web_hookに設定されたtypeプロパティ文字列。 -
この通知チャンネルの通知をリッスンして応答する URL に設定された
addressプロパティ文字列。これは Webhook コールバック URL であり、HTTPS を使用する必要があります。Google Calendar API がこの HTTPS アドレスに通知を送信できるのは、ウェブサーバーに有効な SSL 証明書がインストールされている場合にのみです。次のような証明書は無効です。
- 自己署名証明書。
- 信頼できない提供元によって署名された証明書。
- 失効した証明書。
- サブジェクトがターゲット ホスト名と一致しない証明書。
省略可能なプロパティ
また、watch リクエストで次のオプション フィールドを指定することもできます。
-
チャンネル トークンとして使用する任意の文字列値を指定する
tokenプロパティ。通知チャンネル トークンは、さまざまな目的に使用できます。たとえば、このトークンを使用して、各受信メッセージがアプリケーションによって作成されたチャンネルに対するものであることを確認することで、その通知がなりすましでないことを確認することや、メッセージをこのチャンネルの目的に基づいてアプリケーション内の適切な宛先にルーティングすることが可能です。最大 256 文字を設定できます。このトークンは、アプリケーションがこのチャンネルで受信するすべての通知メッセージの
X-Goog-Channel-TokenHTTP ヘッダーに含まれます。通知チャンネル トークンを使用する際は、次のことをおすすめします。
URL クエリ パラメータなどの拡張可能なエンコード形式を使用します例:
forwardTo=hr&createdBy=mobileOAuth トークンなどの機密データは含めないでください。
-
Google Calendar API がこの通知チャンネルへのメッセージ送信を停止する日時を Unix タイムスタンプ（ミリ秒単位）で設定する
expirationプロパティ文字列。チャンネルに有効期限が設定されている場合、このチャンネルでアプリケーションが受け取るすべての通知メッセージの
X-Goog-Channel-ExpirationHTTP ヘッダーの値（人が読める形式）が値として含まれます。
リクエストの詳細については、API リファレンスの Acl、CalendarList、Events、Settings リソースの 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、Events、Settings リソースの 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 が受信 URL に送信する 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 の内部制限またはデフォルト（より制限された値が使用されます）のいずれかによって決まります。チャンネルの有効期限（設定されている場合）は、watch メソッドによって返される情報に Unix タイムスタンプ（ミリ秒単位）で含まれています。また、このチャンネルでアプリケーションが受信するすべての通知メッセージの X-Goog-Channel-Expiration HTTP ヘッダーにも、人が読める形式で有効期限の日時が含まれています。
現時点では、通知チャンネルを自動的に更新する方法はありません。チャンネルの有効期限が近づいたら、watch メソッドを呼び出して新しいチャンネルを作成する必要があります。通常どおり、新しいチャネルの id プロパティには一意の値を使用する必要があります。なお、同じリソースに 2 つの通知チャンネルがアクティブになっていると、「重複」期間が発生する可能性があります。
通知の受信
監視対象リソースが変更されるたびに、変更内容を示す通知メッセージがアプリケーションに送信されます。Google Calendar API は、この通知チャンネルの「アドレス」として指定された URL に、HTTPS POST リクエストとして、これらのメッセージを送信します。
通知メッセージの形式について
すべての通知メッセージには、X-Goog- 接頭辞を持つ一連の HTTP ヘッダーが含まれます。
通知のタイプによっては、メッセージ本文も含まれる場合があります。
ヘッダー
Google Calendar API によって受信 URL に送信される通知メッセージには、次の HTTP ヘッダーが含まれます。
| ヘッダー | 説明 |
|---|---|
| 常に存在 | |
|
この通知チャンネルを識別するために指定した UUID またはその他の一意の文字列。 |
|
この通知チャンネルでこのメッセージを識別する整数。sync メッセージの場合、値は常に 1 です。チャンネルの後続のメッセージごとにメッセージ番号が増加しますが、連続ではありません。 |
|
監視対象のリソースを識別する不透明値。この ID は、API バージョンが変わっても同じです。 |
|
通知をトリガーした新しいリソースの状態。
有効な値: sync、exists、または not_exists。 |
|
監視対象リソースの API バージョン固有の ID。 |
| ときどき表示される | |
|
通知チャンネルの有効期限の日時（人が読める形式）。定義されている場合にのみ存在します。 |
|
アプリケーションによって設定され、通知元の確認に使用できる通知チャンネル トークン。定義されている場合にのみ存在します。 |
Google Calendar API によって受信 URL に送信された通知メッセージにメッセージ本文は含まれません。これらのメッセージには、更新されたリソースに関する特定の情報は含まれていません。完全な変更の詳細を確認するには、別の 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 でプッシュ通知を使用する際に受け取る通知メッセージについて詳しく説明します。
| 配信のタイミング | ||
|---|---|---|
sync |
ACL、カレンダー リスト、予定、設定。 | 新しいチャネルを作成しました。通知が届くようになります。 |
exists |
ACL、カレンダー リスト、予定、設定。 | リソースが変更されました。変更には、新しいリソースの作成や、既存のリソースの変更または削除が含まれます。 |
通知の停止
有効期限とは、通知が自動的に停止する時間です。特定のチャンネルの通知が期限切れになる前に、その通知の受信を停止するには、次の URI で stop メソッドを呼び出します。
https://www.googleapis.com/calendar/v3/channels/stop
このメソッドでは、次の例に示すように、少なくともチャンネルの id プロパティと resourceId プロパティを指定する必要があります。Google Calendar API に watch メソッドを持つ複数のタイプのリソースがある場合でも、stop メソッドは 1 つだけです。
チャンネルを停止できるのは、適切な権限を持つユーザーのみです。具体的には、次のとおりです。
- 通常のユーザー アカウントによってチャンネルが作成された場合、チャンネルを停止できるのは、同じクライアント（認証トークンの 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"
}