Gmail API でプッシュ通知を構成する

このドキュメントでは、Gmail API でプッシュ通知を管理する方法について説明します。

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

Cloud Pub/Sub の初期設定

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

前提条件

この設定を完了するには、Cloud Pub/Sub の前提条件を満たし、Cloud Pub/Sub クライアントを設定します。

トピックの作成

Cloud Pub/Sub クライアントを使用して、Gmail API が通知を送信するトピックを作成します。トピック名は、プロジェクトで選択した任意の名前（projects/myproject/topics/* など。myproject は Google Cloud コンソールでプロジェクトに表示されるプロジェクト ID）にできます。

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

作成したトピックのサブスクリプションを設定するには、Cloud Pub/Sub サブスクリプションタイプのガイドに従ってください。サブスクリプションタイプを Webhook プッシュ（HTTP POST コールバック）またはプル（アプリによって開始される）のいずれかに構成します。アプリケーションが更新の通知を受け取る仕組みは次のとおりです。

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

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

これを行うには、gmail-api-push@system.gserviceaccount.com に publish 権限を付与します。これを行うには、Google Cloud コンソールの Cloud Pub/Sub 権限コンソールで、アクセス制御の手順に沿って操作します。

組織のドメイン制限付き共有の構成により、公開権限を付与できない場合があります。この問題を解決するには、このサービスアカウントの例外を構成します。

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

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

監視リクエスト

Cloud Pub/Sub トピックに通知を送信するように Gmail アカウントを構成するには、Gmail API クライアントを使用して、Gmail ユーザーメールボックスで watch メソッドを呼び出します。これは、他の Gmail API 呼び出しと同様です。作成したトピック名と、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 より前に変更を処理する必要がある場合は、Gmail API とクライアントを同期するをご覧ください。

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

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

メールボックスの監視を更新する

watch を少なくとも 7 日に 1 回呼び出す必要があります。呼び出さないと、ユーザーの更新の受信が停止します。watch は 1 日に 1 回呼び出すことをおすすめします。watch メソッドのレスポンスには、watch の有効期限のタイムスタンプを含む expiration フィールドもあります。

受け取るお知らせの種類

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"}

Gmail API とクライアントを同期するで説明されているように、history.list メソッドを使用して、ユーザーの最後に確認された historyId 以降の変更の詳細を取得できます。

たとえば、history.list メソッドを使用して、最初の watch リクエストと、前の例で共有した通知メッセージの受信との間に発生した変更を特定します。1234567890 を history.list に startHistoryId として渡します。その後、9876543210 を最後に認識された historyId として保持し、今後のユースケースで使用できます。

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

お知らせに対応する

すべての通知を確認する必要があります。Webhook プッシュ配信を使用している場合、正常に応答（HTTP 200 など）すると、通知が確認されます。

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

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

メールボックスの更新を停止する

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

制限事項

サーバープッシュ通知の操作には、次の制限があります。

通知の最大レート

モニタリング対象の Gmail ユーザーごとに、最大通知レートは 1 秒あたり 1 つのイベントです。このレートを超えるユーザー通知は破棄されます。通知を処理する際は、別の通知をトリガーして通知ループが開始されないように注意してください。

信頼性

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

Cloud Pub/Sub の制限事項

Cloud Pub/Sub API にも独自の制限があります。詳細については、料金と割り当てに関するドキュメントをご覧ください。