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

プッシュ通知

概要

Gmail API には、Gmail メールボックスの変更を監視できるサーバーのプッシュ通知が用意されています。この機能を使用して、アプリケーションのパフォーマンスを向上させることができます。リソースが変更済みかどうかを判断するためにリソースをポーリングすることによってネットワークとコンピューティングのコストが増加することを避けることができます。メールボックスが変更されるたびに、Gmail API がバックエンドサーバーアプリケーションに通知します。

Cloud Pub/Sub の初期設定

Gmail API は、Cloud Pub/Sub API を使用してプッシュ通知を配信します。これにより、単一のサブスクリプションエンドポイントで、Webhook やポーリングなど、さまざまな方法で通知を受け取ることができます。

前提条件

この設定の残りの部分を完了するには、Cloud Pub/Sub の前提条件を満たし、Cloud Pub/Sub クライアントを設定してください。

トピックの作成

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

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

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

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

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

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

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

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

監視リクエスト

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

プロトコル

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 に一致するメールボックスの更新が発生するたびに、変更内容を説明する通知メッセージがアプリケーションに送信されます。

プッシュサブスクリプションを構成している場合、サーバーへの 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 以降の変更の詳細を取得できます。

たとえば、history.list を使用して、最初の watch 呼び出しと、前の例で共有した通知メッセージの受信との間に発生した変更を特定するには、1234567890 を history.list の startHistoryId として渡します。その後、9876543210 は、将来のユースケースで使用するために、最後に認識された 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 にも独自の制限があります。詳細については、料金と割り当てに関するドキュメントをご覧ください。