このページは 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 の制限があるため、アプリケーションのすべての Gmail API プッシュ通知に単一のトピックを使用することをおすすめします。

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

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

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

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

これを行うには、gmail-api-push@system.gserviceaccount.com に publish 権限を付与する必要があります。これを行うには、リソースレベルのアクセス制御の手順に沿って、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 以降のユーザーの変更の詳細を取得できます。

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

通知への対応

すべての通知は承認する必要があります。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 にも独自の制限があります。詳しくは、料金と割り当てのドキュメントをご覧ください。