プッシュ通知

このドキュメントでは、リソースが変更されたときにアプリケーションに通知するプッシュ通知を使用する方法について説明します。

概要

Google Calendar API は、リソースの変更をモニタリングするためのプッシュ通知を提供します。この機能を使用すると、アプリケーションのパフォーマンスを改善できます。これにより、リソースが変更されたかどうかを判断するためのポーリングに関連する余分なネットワークとコンピューティングの費用を削減できます。監視対象のリソースが変更されるたびに、Google Calendar API がアプリケーションに通知します。

プッシュ通知を使用するには、次の 2 つのことを行う必要があります。

  • 受信 URL または「Webhook」コールバック レシーバを設定します。

    これは、リソースが変更されたときにトリガーされる API 通知メッセージを処理する HTTPS サーバーです。

  • 監視するリソース エンドポイントごとに通知チャンネルを設定します。

    チャネルで、通知メッセージのルーティング情報を指定します。チャンネル設定の一環として、通知を受け取る特定の URL を指定する必要があります。チャンネルのリソースが変更されると、Google Calendar API がその URL に通知メッセージを POST リクエストとして送信します。

現在、Google Calendar API は、AclCalendarListEventsSettings の各リソースの変更に関する通知をサポートしています。

通知チャンネルを作成する

プッシュ通知をリクエストするには、モニタリングするリソースごとに通知チャンネルを設定する必要があります。通知チャンネルを設定すると、監視対象のリソースが変更されると、Google Calendar API からアプリに通知されます。

監視リクエストを実行する

監視可能な各 Google Calendar API リソースには、次の形式の URI で watch メソッドが関連付けられています。

https://www.googleapis.com/API_NAME/API_VERSION/RESOURCE_PATH/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-Id HTTP ヘッダーにエコーバックされます。

  • type プロパティ文字列。値 web_hook に設定されます。

  • この通知チャンネルの通知をリッスンして応答する URL に設定された address プロパティ文字列。これは Webhook コールバック URL で、HTTPS を使用する必要があります。

    Google Calendar API からこの HTTPS アドレスに通知を送信できるのは、ウェブサーバーに有効な SSL 証明書がインストールされている場合のみです。次のような証明書は無効です。

    • 自己署名証明書。
    • 信頼できない提供元によって署名された証明書。
    • 失効した証明書。
    • サブジェクトがターゲット ホスト名と一致しない証明書。

省略可能なプロパティ

watch リクエストで次のオプション フィールドを指定することもできます。

  • チャネル トークンとして使用する任意の文字列値を指定する token プロパティ。通知チャンネル トークンはさまざまな目的で使用できます。たとえば、トークンを使用して、各受信メッセージがアプリケーションによって作成されたチャネルのものであることを確認できます。これにより、通知のなりすましを防止できます。また、このチャネルの目的に基づいて、アプリケーション内の適切な宛先にメッセージをルーティングすることもできます。最大長: 256 文字。

    このトークンは、アプリケーションがこのチャネルについて受け取るすべての通知メッセージの X-Goog-Channel-Token HTTP ヘッダーに含まれます。

    通知チャンネル トークンを使用する場合は、次のことをおすすめします。

    • URL クエリ パラメータなど、拡張可能なエンコード形式を使用します。例: forwardTo=hr&createdBy=mobile

    • OAuth トークンなどのセンシティブ データは含めないでください。

  • expiration プロパティ文字列。Google Calendar API がこの通知チャネルのメッセージの送信を停止する日時の Unix タイムスタンプ(ミリ秒単位)に設定します。

    チャネルに有効期限が設定されている場合、アプリケーションがこのチャネルについて受信するすべての通知メッセージに、X-Goog-Channel-Expiration HTTP ヘッダー(人が読める形式)の値として含まれます。

リクエストの詳細については、API リファレンスの AclCalendarListEventsSettings のリソースの 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.
}

リクエストの一部として送信したプロパティに加えて、返される情報には resourceIdresourceUri も含まれます。これにより、この通知チャンネルで監視されているリソースを識別できます。

返された情報は、通知の受信を停止したい場合など、他の通知チャンネル オペレーションに渡すことができます。

レスポンスの詳細については、API リファレンスの AclCalendarListEventsSettings の各リソースの watch メソッドをご覧ください。

メッセージを同期する

リソースを監視するための通知チャンネルを作成すると、Google Calendar API は、通知が開始されたことを示す sync メッセージを送信します。これらのメッセージの X-Goog-Resource-State HTTP ヘッダー値は sync です。ネットワークのタイミングの問題により、watch メソッドのレスポンスを受け取る前に sync メッセージを受信する可能性があります。

sync 通知は無視してかまいませんが、使用することもできます。たとえば、チャンネルを保持しない場合は、呼び出しで X-Goog-Channel-IDX-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 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 です。このチャンネルの後続の各通知には、前の通知よりも大きいメッセージ番号が付けられます。ただし、メッセージ番号は連続していません。

通知チャンネルを更新する

通知チャンネルには有効期限を設定できます。有効期限は、リクエストまたは Google Calendar API の内部制限またはデフォルト(より制限の厳しい値が使用されます)によって決定されます。チャネルの有効期限(設定されている場合)は、watch メソッドから返される情報に Unix タイムスタンプ(ミリ秒単位)として含まれています。また、有効期限の日付と時刻は、アプリがこのチャネルについて受け取るすべての通知メッセージの X-Goog-Channel-Expiration HTTP ヘッダーに、人が読める形式で記載されます。

現在のところ、通知チャンネルを自動的に更新する方法はありません。チャネルの有効期限が近づいたら、watch メソッドを呼び出して、チャネルを新しいチャネルに置き換える必要があります。通常どおり、新しいチャンネルの id プロパティには一意の値を使用する必要があります。同じリソースの 2 つの通知チャンネルがアクティブな場合でも、「オーバーラップ」期間が生じる可能性があることにご注意ください。

お知らせを受け取る

監視対象リソースが変更されるたびに、アプリは変更を説明する通知メッセージを受信します。Google Calendar API は、これらのメッセージを HTTPS POST リクエストとして、この通知チャンネルの address プロパティとして指定した URL に送信します。

通知メッセージの形式を解釈する

すべての通知メッセージには、X-Goog- という接頭辞を持つ一連の HTTP ヘッダーが含まれます。通知のタイプによっては、メッセージ本文を含めることもできます。

ヘッダー

Google Calendar API から受信 URL に送信される通知メッセージには、次の HTTP ヘッダーが含まれます。

ヘッダー 説明
常に存在する
X-Goog-Channel-ID この通知チャンネルを識別するために指定した UUID などの一意の文字列。
X-Goog-Message-Number この通知チャネルのこのメッセージを識別する整数。sync メッセージの場合、値は常に 1 です。チャネル上の後続のメッセージごとにメッセージ番号は増加しますが、連続ではありません。
X-Goog-Resource-ID 監視対象リソースを識別する不透明な値。この ID は API のバージョンが変わりません。
X-Goog-Resource-State 通知をトリガーした新しいリソースの状態。 有効な値: syncexists、または not_exists
X-Goog-Resource-URI 監視対象リソースの API バージョン固有の識別子。
ときどきあった
X-Goog-Channel-Expiration 通知チャンネルの有効期限。人が読める形式で表されます。定義されている場合にのみ存在します。
X-Goog-Channel-Token アプリによって設定され、通知ソースの検証に使用できる通知チャネル トークン。定義されている場合にのみ存在します。

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

お知らせに対応する

成功を示すには、200201202204、または 102 のいずれかのステータス コードを返します。

サービスが Google の API クライアント ライブラリを使用していて、500502503、または 504 を返す場合、Google Calendar API は指数バックオフで再試行します。その他の戻りステータス コードはすべて、メッセージの失敗とみなされます。

Google Calendar API の通知イベントについて

このセクションでは、Google Calendar API でプッシュ通知を使用する際に受信できる通知メッセージについて詳しく説明します。

X-Goog-Resource-State 適用対象 配信のタイミング
sync ACL、カレンダー リスト、イベント、設定。 新しいチャンネルが正常に作成されました。通知が届くようになる予定です。
exists ACL、カレンダー リスト、イベント、設定。 リソースに変更がありました。変更の例としては、新しいリソースの作成、既存のリソースの変更や削除などがあります。

通知を停止する

expiration プロパティは、通知を自動的に停止するタイミングを制御します。有効期限が切れる前に特定のチャンネルに関する通知の受信を停止するには、次の 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 CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

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