このページは Cloud Translation API によって翻訳されました。

プッシュ通知

概要

Gmail API は、Gmail メールボックスの変更を監視できるサーバープッシュ通知を提供します。この機能を使用すると、アプリケーションのパフォーマンスを改善できます。これにより、リソースが変更されたかどうかを判断するためのポーリングに関連する余分なネットワークコストとコンピューティングコストを省くことができます。メールボックスが変更されるたびに、Gmail API がバックエンドサーバーアプリケーションに通知します。

Cloud Pub/Sub の初期設定

Gmail API は、Cloud Pub/Sub API を使用してプッシュ通知を配信します。これにより、1 つの定期購入エンドポイントでの Webhook やポーリングなど、さまざまな方法による通知が可能になります。

前提条件

このセットアップの残りを完了するには、Cloud Pub/Sub の前提条件を満たしていることを確認し、Cloud Pub/Sub クライアントを設定します。

トピックを作成する

Cloud Pub/Sub クライアントを使用して、Gmail API からの通知送信先のトピックを作成します。トピック名には、プロジェクトで選択した任意の名前を使用できます（たとえば、projects/myproject/topics/* に一致します。myproject は、Google Developers Console でプロジェクトに対して一覧表示されているプロジェクト ID です）。

トピック数に Cloud Pub/Sub の制限があるため、アプリケーションの Gmail API プッシュ通知にはすべて 1 つのトピックを使用することをおすすめします。

サブスクリプションを作成する

Cloud Pub/Sub サブスクライバーガイドに沿って、作成したトピックへのサブスクリプションを設定します。サブスクリプションタイプを Webhook push（HTTP POST コールバック）または pull（アプリによって開始）のいずれかに設定します。これは、アプリケーションが更新の通知を受信する方法です。

トピックに関する公開権限の付与

Cloud Pub/Sub では、トピックに通知をパブリッシュする権限を Gmail に付与する必要があります。

これを行うには、publish 権限を gmail-api-push@system.gserviceaccount.com に付与する必要があります。これを行うには、Cloud Pub/Sub デベロッパーコンソールの権限インターフェースを使用して、リソースレベルのアクセス制御の手順を行います。

Gmail メールボックスの更新の取得

Cloud Pub/Sub の初期設定が完了したら、メールボックスの更新の通知を送信するように Gmail アカウントを構成します。

ウォッチリクエスト

Cloud Pub/Sub トピックに通知を送信するように Gmail アカウントを構成するには、他の Gmail API 呼び出しと同様に、Gmail API クライアントを使用して Gmail ユーザーのメールボックスで watch を呼び出すだけです。そのためには、上記で作成したトピック名と、フィルタする他のオプション（labels など）を watch リクエストで指定します。たとえば、受信トレイに変更が加えられたときに通知を受け取るには、次のように指定します。

プロトコル

POST "https://www.googleapis.com/gmail/v1/users/me/watch"
Content-type: application/json

{
  topicName: "projects/myproject/topics/mytopic",
  labelIds: ["INBOX"],
  labelFilterBehavior: "INCLUDE",
}

Python

request = {
  'labelIds': ['INBOX'],
  'topicName': 'projects/myproject/topics/mytopic',
  'labelFilterBehavior': 'INCLUDE'
}
gmail.users().watch(userId='me', body=request).execute()

ウォッチのレスポンス

watch リクエストが成功すると、次のようなレスポンスが返されます。

{
  historyId: 1234567890
  expiration: 1431990098200
}

ユーザーの現在のメールボックス historyId 。その後の変更はすべて historyId に通知されます。この historyId の前に変更を処理する必要がある場合は、同期ガイドをご覧ください。

また、watch の呼び出しが成功すると、すぐに Cloud Pub/Sub トピックに通知が送信されます。

watch 呼び出しでエラーが発生した場合は、問題の原因が詳細に記載されています。通常は、Cloud Pub/Sub トピックとサブスクリプションの設定が原因です。Cloud Pub/Sub のドキュメントを参照して、設定が正しいことを確認し、トピックとサブスクリプションの問題をデバッグしてください。

メールボックスの監視を更新しています

少なくとも 7 日ごとに watch を呼び出してください。そうしないと、ユーザーへの最新情報を受け取れなくなります。watch は 1 日に 1 回呼び出すことをおすすめします。watch レスポンスには、watch 有効期限のタイムスタンプを含む有効期限フィールドもあります。

通知の受信

メールボックスの更新が watch と一致するたびに、アプリケーションに変更を説明する通知メッセージが届きます。

push サブスクリプションを構成した場合、サーバーへの Webhook 通知は PubsubMessage に準拠します。

POST https://yourserver.example.com/yourUrl
Content-type: application/json

{
  message:
  {
    // This is the actual notification data, as base64url-encoded JSON.
    data: "eyJlbWFpbEFkZHJlc3MiOiAidXNlckBleGFtcGxlLmNvbSIsICJoaXN0b3J5SWQiOiAiMTIzNDU2Nzg5MCJ9",

    // This is a Cloud Pub/Sub message id, unrelated to Gmail messages.
    "messageId": "2070443601311540",

    // This is the publish time of the message.
    "publishTime": "2021-02-26T19:13:55.749Z",
  }

  subscription: "projects/myproject/subscriptions/mysubscription"
}

HTTP POST の本文は JSON であり、実際の Gmail 通知ペイロードは message.data フィールドにあります。この message.data フィールドは base64url でエンコードされた文字列で、ユーザーのメールアドレスと新しいメールボックス履歴 ID を含む JSON オブジェクトにデコードされます。

{"emailAddress": "user@example.com", "historyId": "9876543210"}

次に history.list を使用して、同期ガイドに沿って、最後に確認された historyId 以降のユーザーの変更の詳細を取得します。

pull サブスクリプションを構成している場合は、Cloud Pub/Sub サブスクライバー pull ガイドのコードサンプルでメッセージの受信の詳細をご覧ください。

通知への対応

すべての通知は確認応答する必要があります。Webhook push 配信を使用する場合、正常に応答（HTTP 200 など）すると通知の確認応答が行われます。

pull 配信（REST pull、RPC pull、または RPC StreamingPull）を使用している場合は、確認応答呼び出し（REST または RPC）でフォローアップする必要があります。正式な RPC ベースのクライアントライブラリを使用してメッセージの確認を非同期または同期で行う方法の詳細については、Cloud Pub/Sub サブスクライバー pull ガイドのコードサンプルをご覧ください。

通知が確認応答されない場合（Webhook コールバックがエラーを返した場合やタイムアウトした場合など）、Cloud Pub/Sub は後で通知を再試行します。

メールボックスの更新を停止しています

メールボックスでの更新の受信を停止するには、stop を呼び出します。すべての新しい通知が数分以内に停止します。

制限事項

最大通知レート

監視対象の Gmail ユーザーごとに最大通知速度は 1 イベント/秒です。この速度を超えるユーザー通知はすべて破棄されます。通知を処理するときは、別の通知をトリガーして通知ループが発生しないように注意してください。

信頼性

通常、すべての通知は数秒以内に確実に配信される必要があります。ただし、極端な状況では、通知が遅延したり破棄されたりすることがあります。プッシュメッセージを受信しなくてもアプリが同期するように、この可能性に適切に対処してください。たとえば、ユーザーへの通知がない期間の後で history.list を定期的に呼び出すようにフォールバックします。

Cloud Pub/Sub の制限事項

Cloud Pub/Sub API には独自の制限事項もあります。具体的には、pricingとquotasに関するドキュメントをご覧ください。