Gmail API を使用してプッシュ通知を構成する

このドキュメントでは、Gmail 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 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 を同期するを参照してください。

また、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 を同期するで説明されているように、history.list メソッドを使用して、ユーザーの最後に認識された historyId 以降の変更の詳細を取得できます。

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

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

お知らせに対応する

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

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

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

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

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

制限事項

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

通知の最大レート

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

信頼性

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

Cloud Pub/Sub の制限事項

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