プッシュ通知

このドキュメントでは、プッシュ通知を使用して、 アプリケーションを変更する必要はありません。

概要

Google Calendar API のプッシュ通知を使用すると、 おすすめします。この機能を使用すると、キャンペーンの 説明します。これにより、余分なネットワークやコンピューティング リソースを リソースのポーリングに関連するコストも削減できます。 監視対象のリソースが変更されると、Google Calendar API が 説明します。

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

  • 受信 URL（Webhook）を設定するコールバック レシーバとして渡されます。

    この 通知メッセージを処理する HTTPS サーバーです。 トリガーされます。

  • 必要なリソース エンドポイントごとに（通知チャンネル）を設定する 。

    チャネルは通知のルーティング情報を指定する ブロックすることもできます。チャネル設定の一環として、そのチャネルの URL を を選択します。チャンネルのリソースが変更されると Google Calendar API が通知メッセージを POST として送信します。 リクエストをその URL に送信します。

現在、Google Calendar API では、 Acl、CalendarList、予定、設定のリソース。

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

プッシュ通知をリクエストするには、通知チャンネルを設定する必要があります リソースごとに最大 100 個の IP アドレスが必要です。通知チャンネルを設定した後 監視対象のリソースがある場合、Google Calendar API は できます。

監視のリクエストを行う

監視可能な Google Calendar API リソースには、それぞれ 次の形式の URI で watch メソッドを使用します。

https://www.googleapis.com/API_NAME/API_VERSION/RESOURCE_PATH/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 プロパティ文字列 通知チャンネルを作成します。Google Cloud コンソールの ユニバーサルな固有識別子 （UUID）など 使用します。最大文字数: 64 文字。

    設定した ID 値が すべての通知の X-Goog-Channel-Id HTTP ヘッダー メッセージが届きます。

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

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

    なお、Google Calendar API は、 有効な SSL 証明書がインストールされている場合にのみ、この HTTPS アドレスを使用できます。 作成します。次のような証明書は無効です。

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

省略可能なプロパティ

これらのオプション フィールドを、 watch リクエスト:

  • 任意の文字列を指定する token プロパティ 値を渡します。通知チャンネルを使用すると、 使用できます。たとえば、 認証トークンを使用して、各受信メッセージが 作成され、通知が送信されていないことを または、メールを内部の正しい宛先に このチャネルの目的に応じてアプリケーションを設計します。最大文字数: 256 文字。

    トークンは すべての通知の X-Goog-Channel-Token HTTP ヘッダー アプリケーションがこのチャンネル用に受信するメッセージです。

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

    • URL クエリなどの拡張可能なエンコード形式を使用する あります。例: forwardTo=hr&createdBy=mobile

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

    で確認できます。

  • 設定された expiration プロパティ文字列。 Unix タイムスタンプ Google Calendar API に対してリクエストを行う日時（ミリ秒単位） この通知チャンネルへのメッセージの送信を停止します。

    チャネルに有効期限がある場合は、 X-Goog-Channel-Expiration HTTP ヘッダー（人が読める形式） すべての通知メッセージに 受信するメッセージの数を表します。

リクエストの詳細については、watch メソッドをご覧ください。 API リファレンスの Acl、CalendarList、イベント、Settings リソースをご覧ください。

スマートウォッチのレスポンス

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 で監視対象のリソースを識別 通知チャンネル。

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

レスポンスの詳細については、watch を参照してください。 メソッドをご覧ください。API リファレンスの Acl、CalendarList、イベント、Settings リソースのメソッドをご覧ください。

メッセージを同期

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

sync の通知は無視してもかまいませんが、 使用しています。たとえば、特定のメッセージを保持せずに 作成するには、X-Goog-Channel-ID と 呼び出し内の X-Goog-Resource-ID の値 通知の受信を停止します。また、 初期化を行うための sync 通知 できます。

Google Calendar API から送信される sync メッセージの形式 受信側の URL は次のとおりです。

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 の内部制限により決定されます またはデフォルト（より制限の厳しい値が使用されます）チャンネルの有効期限 時刻がある場合は、Unix タイムスタンプとして含めます。 （ミリ秒単位）。watch メソッドによって返される情報。また、 有効期限の日時を人間が読み取れる形式で このチャネルに関してアプリケーションが受信する通知メッセージを X-Goog-Channel-Expiration HTTP ヘッダー。

現時点では、通知チャンネルを自動的に更新する方法はありません。日時 チャネルの有効期限が近づいている場合は、次を呼び出して新しいチャネルに置き換える必要があります。 watch メソッドを使用します。他のケースと同様に、名前には一意の値を使用する必要があります。 新しいチャンネルの id プロパティ。なお、 「重なり」であると言えます。2 つの通知チャンネルが通知される期間を 同じリソースがアクティブになります。

通知を受け取る

監視対象のリソースが変更されると、アプリケーションは 変更を説明する通知メッセージが送信されます。Google Calendar API はこれらのカレンダーを HTTPS POST リクエストとして、 この通知の address プロパティ 。

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

すべての通知メッセージには、一連の HTTP ヘッダーが X-Goog- 接頭辞。 通知の種類によっては、 あります。

ヘッダー

Google Calendar API によって受信側に送信された通知メッセージ URL には次の HTTP ヘッダーを含めます。

ヘッダー 説明
常に表示
X-Goog-Channel-ID この ID を識別するために指定した UUID またはその他の一意の文字列 通知チャンネル。
X-Goog-Message-Number この通知のメッセージを識別する整数 。sync メッセージの場合、値は常に 1 です。メッセージ 後続のメッセージの数が増えますが 順序ではありません。
X-Goog-Resource-ID 監視対象のリソースを識別する不透明な値。この ID は API バージョン間で安定している。
X-Goog-Resource-State 通知をトリガーした新しいリソースの状態。 可能な値: sync、exists、または 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

お知らせに対応する

成功を示すために、次のいずれかのステータス コードが返されます。 200、201、202、204、または 102。

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

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

このセクションでは、送信できる通知メッセージの詳細を 通知を受け取る方法について学習します。

X-Goog-Resource-State 適用対象 配信日時
sync ACL、カレンダー リスト、予定、設定。 新しいチャンネルを作成しました。通知が届くようになるはずです。
exists ACL、カレンダー リスト、予定、設定。 リソースに変更があった。考えられる変更には、新しいリソースの作成、既存のリソースの変更または削除などがあります。

通知を停止する

expiration プロパティは、通知を自動的に停止するタイミングを制御します。Google Chat では 通知を受け取らないように設定することもできます。 次の URL にある stop メソッドを呼び出して期限切れにします。 次の URI を使用します。

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

この方法では、少なくともチャンネルの id プロパティと resourceId プロパティ。次のサンプルをご覧ください。 見てみましょう。Google Calendar API に複数の種類のカレンダーがある場合は、 watch メソッドを持つリソースは 1 つだけ stop メソッドを使用します。

チャンネルの停止は、適切な権限を持つユーザーのみが行えます。具体的には、次のとおりです。

  • チャンネルが通常のユーザー アカウントで作成された場合は、 の 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"
}