プッシュ通知

このドキュメントでは、リソースが変更されたときにアプリケーションに通知するプッシュ通知の使用方法について説明します。

概要

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

プッシュ通知を使用するには、次の 2 つの作業を行う必要があります。

  • 受信 URL（「Webhook」コールバック レシーバー）を設定します。

    これは、リソースが変更されたときにトリガーされる API 通知メッセージを処理する HTTPS サーバーです。

  • 監視するリソース エンドポイントごとに（通知チャンネル）を設定します。

    チャンネルは、通知メッセージのルーティング情報を指定します。チャンネル設定の一環として、通知を受け取る URL を確認する必要があります。チャンネルのリソースが変更されると、Admin SDK API は通知メッセージを POST リクエストとして、その URL に送信します。

現在、Admin SDK API は Activities リソースに対する変更の通知をサポートしています。

通知チャンネルを作成する

プッシュ通知をリクエストするには、モニタリングするリソースごとに通知チャンネルを設定する必要があります。通知チャンネルの設定後、監視対象リソースが変更されると、Admin SDK API がアプリケーションに通知します。

監視リクエストを行う

監視可能な Admin SDK API のリソースには、次の形式の URI に関連付けられた watch メソッドがあります。

https://www.googleapis.com/API_NAME/API_VERSION/RESOURCE_PATH/watch

特定のリソースに対する変更に関するメッセージの通知チャンネルを設定するには、そのリソースの watch メソッドに POST リクエストを送信します。

各通知チャンネルは、特定のユーザーと特定のリソース（またはリソースのセット）に関連付けられています。watch リクエストは、現在のユーザーまたはサービス アカウントがこのリソースを所有しているか、このリソースへのアクセス権を持たない限り、成功しません。

例

Activities リソースに対するすべての監視リクエストの一般的な形式は次のとおりです。

POST https://admin.googleapis.com/admin/reports/v1/activity/users/userKey or all/applications/applicationName/watch
Authorization: Bearer auth_token_for_current_user
Content-Type: application/json

{
  "id": "01234567-89ab-cdef-0123456789ab",
  "type": "web_hook",
  "address": "https://mydomain.com/notifications",
  ...
  "token": "target=myApp-myFilesChannelDest",
  "payload": true,
  "expiration": 3600
}

リクエスト本文には次のプロパティがあります。

  • id: このチャンネルを識別する UUID または類似の一意の文字列。
  • type: 配信メカニズムのタイプ。このフィールドの値は web_hook である必要があります。
  • address: 通知が送信される URL。
  • token: 通知が信頼できる送信元から送信されたことを確認するために、各通知とともにターゲット アドレスに配信される任意の文字列。
  • payload: ペイロードを通知に含めるかどうかを示すブール値のフラグ。
  • expiration: 通知チャネルの有効期間（秒）。

userKey、applicationName、eventName、filters パラメータを使用すると、特定のイベント、ユーザー、アプリケーションの通知のみを受信できます。

注: 次の例では、わかりやすくするためにリクエスト本文を省略しています。

すべての管理アクティビティを監視します。

POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin/watch

すべてのドキュメント アクティビティを監視します。

POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/docs/watch

特定のユーザーの管理者アクティビティを監視する:

POST https://admin.googleapis.com/admin/reports/v1/activity/users/liz@example.com/applications/admin/watch

ユーザーのパスワードの変更など、特定のイベントを監視します。

POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin/watch?eventName=CHANGE_PASSWORD

特定のドキュメントの変更を監視します。

POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/docs/watch?eventName=EDIT&filters==doc_id=123456abcdef

必須プロパティ

個々の watch リクエストで、次のフィールドを指定する必要があります。

  • この新しい通知チャンネルをプロジェクト内で一意に識別する id プロパティ文字列。UUID（Universally Unique Identifier）または同様の一意の文字列を使用することをおすすめします。最大 64 文字。

    設定した ID 値は、このチャンネルで受信するすべての通知メッセージの X-Goog-Channel-Id HTTP ヘッダーにそのまま使用されます。

  • 値 web_hook に設定された type プロパティ文字列。

  • この通知チャンネルの通知をリッスンして応答する URL に設定された address プロパティ文字列。これは Webhook コールバック URL であり、HTTPS を使用する必要があります。

    Admin SDK API がこの HTTPS アドレスに通知を送信できるのは、ウェブサーバーに有効な SSL 証明書がインストールされている場合にのみです。次のような証明書は無効です。

    • 自己署名証明書。
    • 信頼できない提供元によって署名された証明書。
    • 失効した証明書。
    • サブジェクトがターゲット ホスト名と一致しない証明書。

省略可能なプロパティ

watch リクエストでは、以下のフィールドを指定することもできます。

  • チャンネル トークンとして使用する任意の文字列値を指定する token プロパティ。通知チャンネル トークンは、さまざまな目的に使用できます。たとえば、このトークンを使用して、受信メッセージがアプリケーションで作成したチャンネル宛てであることを確認し、通知がスプーフィングされていないことを確認したり、このチャンネルの目的に基づいてアプリケーション内の適切な宛先にメッセージを転送したりできます。最大 256 文字を設定できます。

    このトークンは、アプリケーションがこのチャンネルで受信するすべての通知メッセージの X-Goog-Channel-Token HTTP ヘッダーに含まれます。

    通知チャンネル トークンを使用するにあたっては、次のことをおすすめします。

    • URL クエリ パラメータなどの拡張可能なエンコード形式を使用します例: forwardTo=hr&createdBy=mobile

    • OAuth トークンなどの機密データは含めないでください。

  • Admin SDK API がこの通知チャンネルへのメッセージ送信を停止する日時を Unix タイムスタンプ（ミリ秒単位）で設定する expiration プロパティ文字列。

    チャンネルに有効期限が設定されている場合、このチャンネルでアプリケーションが受け取るすべての通知メッセージの X-Goog-Channel-Expiration HTTP ヘッダーの値（人が読める形式の有効期限）として含まれます。

リクエストの詳細については、API リファレンスの Activities リソースの watch メソッドをご覧ください。

レスポンスの監視

watch リクエストで通知チャンネルが正常に作成されると、HTTP 200 OK ステータス コードが返されます。

下記の例に示すように、監視レスポンスのメッセージ本文には、作成した通知チャンネルに関する情報が入っています。

{
  "kind": "api#channel",
  "id": "reportsApiId",
  "resourceId": "o3hgv1538sdjfh",
  "resourceUri": "https://admin.googleapis.com/admin/reports/v1/activity/userKey/applications/applicationName",
  "token": "target=myApp-myFilesChannelDest",
  "expiration": 3600
}

返される情報には、リクエストの一部として送信したプロパティに加えて、この通知チャンネルで監視されているリソースを識別するための resourceId と resourceUri も含まれています。

返された情報は、通知の受信を停止するときなど、他の通知チャンネル操作に渡すことができます。

レスポンスの詳細については、API リファレンスの Activities リソースの watch メソッドをご覧ください。

メッセージの同期

リソースを監視する通知チャンネルを作成すると、Admin SDK API は通知が開始されていることを示す sync メッセージを送信します。このメッセージの X-Goog-Resource-State HTTP ヘッダー値は sync です。ネットワークのタイミングの問題により、watch メソッドのレスポンスを受け取る前に、sync メッセージを受信することがあります。

sync の通知は無視しても問題ありませんが、使用することもできます。たとえば、チャンネルを保持しない場合は、X-Goog-Channel-ID と X-Goog-Resource-ID の値を、通知の受信を停止する呼び出しに使うことができます。また、sync 通知を使用して、後のイベントに備える初期化を行うこともできます。

Admin SDK API が受信 URL に送信する sync メッセージの形式を以下に示します。

POST https://mydomain.com/notifications // Your receiving URL.
X-Goog-Channel-ID: channel-ID-value
X-Goog-Channel-Token: channel-token-value
X-Goog-Channel-Expiration: expiration-date-and-time // In human-readable format. Present only if the channel expires.
X-Goog-Resource-ID: identifier-for-the-watched-resource
X-Goog-Resource-URI: version-specific-URI-of-the-watched-resource
X-Goog-Resource-State: sync
X-Goog-Message-Number: 1

同期メッセージの X-Goog-Message-Number HTTP ヘッダー値は、常に 1 になります。このチャンネルの後続の通知には、前の通知よりも大きなメッセージ番号が付与されます（ただし連続にはなりません）。

通知チャンネルを更新する

通知チャンネルには有効期限を設定でき、その値は、リクエスト、または Admin SDK API の内部制限とデフォルトとのより限定的な方によって決まります。チャンネルの有効期限（設定されている場合）は、watch メソッドによって返される情報に Unix タイムスタンプ（ミリ秒単位）で含まれています。また、このチャンネルでアプリケーションが受信するすべての通知メッセージの X-Goog-Channel-Expiration HTTP ヘッダーにも、人が読める形式で有効期限の日時が含まれています。

現時点では、通知チャンネルを自動的に更新する方法はありません。チャンネルの有効期限が近づいたら、watch メソッドを呼び出して新しいチャンネルに置き換える必要があります。通常どおり、新しいチャンネルの id プロパティには一意の値を使用する必要があります。なお、同じリソースに 2 つの通知チャンネルがアクティブになっていると、「重複」期間が発生する可能性があります。

受け取るお知らせの種類

監視対象リソースが変更されるたびに、変更内容を伝える通知メッセージがアプリケーションに送信されます。Admin SDK API は、この通知チャンネルの address プロパティとして指定された URL に、HTTPS POST リクエストとして、これらのメッセージを送信します。

通知メッセージの形式を解釈する

すべての通知メッセージには、X-Goog- 接頭辞を持つ一連の HTTP ヘッダーが含まれます。 通知のタイプによっては、メッセージ本文も含まれる場合があります。

ヘッダー

Admin SDK API によって受信 URL に送信される通知メッセージには、次の HTTP ヘッダーが含まれます。

ヘッダー 説明
常に存在
X-Goog-Channel-ID 通知チャンネルを識別するために指定した UUID またはその他の一意の文字列。
X-Goog-Message-Number この通知チャンネルでこのメッセージを識別する整数。sync メッセージの場合、値は常に 1 です。チャンネルの後続のメッセージごとにメッセージ番号が増加しますが、連続ではありません。
X-Goog-Resource-ID 監視対象のリソースを識別する不透明値。この ID は、API バージョンが変わっても同じです。
X-Goog-Resource-State 通知をトリガーした新しいリソースの状態。有効な値は、sync またはイベント名です。
X-Goog-Resource-URI 監視対象リソースの API バージョン固有の ID。
存在する場合がある
X-Goog-Channel-Expiration 通知チャンネルの有効期限の日時（人が読める形式）。定義されている場合にのみ存在します。
X-Goog-Channel-Token アプリケーションによって設定され、通知元の確認に使用できる通知チャンネル トークン。定義されている場合にのみ存在します。

アクティビティの通知メッセージのリクエスト本文には次の情報が含まれます。

プロパティ 説明
kind Activity リソースであることを示します。値: 固定文字列 "admin#reports#activity"。
id アクティビティ レコードの一意の識別子。
id.time アクティビティの発生時刻。値は ISO 8601 の日付と時刻の形式です。時間は、完全な日付と時、分、秒を YYYY-MM-DDThh:mm:ssTZD の形式で表したものです。例: 2010-04-05T17:30:04+01:00。
id.uniqueQualifier 複数のイベントが同じ時間の場合の一意の修飾子。
id.applicationName イベントが属するアプリケーションの名前。有効な値は次のとおりです。
id.customerId Google Workspace アカウントの一意の識別子。
actor 操作を行うユーザー。
actor.callerType レポートに記載されているアクティビティを実行した作成者のタイプ。このバージョンの API では、callerType は、レポートに記載されているアクションを実行した USER または OAuth 2LO エンティティ リクエストです。
actor.email アクティビティが報告されているユーザーのメインのメールアドレス。
actor.profileId ユーザーの一意の Google Workspace プロファイル ID。
ownerDomain 管理コンソールまたはドキュメント アプリケーションのドキュメント所有者のドメイン。レポートのイベントの影響を受けるドメインです。
ipAddress 操作を行ったユーザーの IP アドレス。これは、Google Workspace にログインしたときのユーザーのインターネット プロトコル（IP）アドレスです。ユーザーの物理的な場所を反映している場合もあれば、反映していない場合もあります。たとえば、IP アドレスはユーザーのプロキシ サーバーのアドレスや仮想プライベート ネットワーク（VPN）のアドレスである可能性があります。この API は IPv4 と IPv6 をサポートしています。
events[] レポート内のアクティビティ イベント。
events[].type イベントの種類。管理者が変更した Google Workspace のサービスまたは機能は、eventName プロパティを使用してイベントを識別する type プロパティで識別されます。
events[].name イベントの名前。これは、API によって報告されたアクティビティの具体的な名前です。各 eventName は、API がイベントのタイプに分類する特定の Google Workspace サービスまたは機能に関連付けられています。
一般的な eventName リクエスト パラメータの場合:
  • eventName が指定されていない場合、レポートは eventName の可能なすべてのインスタンスを返します。
  • eventName をリクエストすると、API のレスポンスで、その eventName を含むすべてのアクティビティが返されます。リクエストされたプロパティに加えて、返されるアクティビティに他の eventName プロパティが含まれる可能性があります。
events[].parameters[] さまざまなアプリケーションのパラメータ値のペア。
events[].parameters[].name パラメータの名前。
events[].parameters[].value パラメータの文字列値。
events[].parameters[].intValue パラメータの整数値。
events[].parameters[].boolValue パラメータのブール値。

例

Activity リソース イベントの通知メッセージの一般的な形式を次に示します。

POST https://mydomain.com/notifications
Content-Type: application/json; utf-8
Content-Length: 0
X-Goog-Channel-ID: reportsApiId
X-Goog-Channel-Token: 398348u3tu83ut8uu38
X-Goog-Channel-Expiration: Tue, 29 Oct 2013 20:32:02 GMT
X-Goog-Resource-ID:  ret08u3rv24htgh289g
X-Goog-Resource-URI: https://admin.googleapis.com/admin/reports/v1/activity/userKey/applications/applicationName
X-Goog-Resource-State:  eventName
X-Goog-Message-Number: 10

{
  "kind": "admin#reports#activity",
  "id": {
    "time": datetime,
    "uniqueQualifier": long,
    "applicationName": string,
    "customerId": string
  },
  "actor": {
    "callerType": string,
    "email": string,
    "profileId": long
  },
  "ownerDomain": string,
  "ipAddress": string,
  "events": [
    {
      "type": string,
      "name": string,
      "parameters": [
        {
          "name": string,
          "value": string,
          "intValue": long,
          "boolValue": boolean
        }
      ]
    }
  ]
}

管理アクティビティ イベントの例を次に示します。

POST https://mydomain.com/notifications
Content-Type: application/json; utf-8
Content-Length: 596
X-Goog-Channel-ID: reportsApiId
X-Goog-Channel-Token: 245t1234tt83trrt333
X-Goog-Channel-Expiration: Tue, 29 Oct 2013 20:32:02 GMT
X-Goog-Resource-ID:  ret987df98743md8g
X-Goog-Resource-URI: https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin?alt=json
X-Goog-Resource-State:  CREATE_USER
X-Goog-Message-Number: 23

{
  "kind": "admin#reports#activity",
  "id": {
    "time": "2013-09-10T18:23:35.808Z",
    "uniqueQualifier": "-0987654321",
    "applicationName": "admin",
    "customerId": "ABCD012345"
  },
  "actor": {
    "callerType": "USER",
    "email": "admin@example.com",
    "profileId": "0123456789987654321"
  },
  "ownerDomain": "apps-reporting.example.com",
  "ipAddress": "192.0.2.0",
  "events": [
    {
      "type": "USER_SETTINGS",
      "name": "CREATE_USER",
      "parameters": [
        {
          "name": "USER_EMAIL",
          "value": "liz@example.com"
        }
      ]
    }
  ]
}

お知らせに対応する

成功を示すには、200、201、202、204、102 のいずれかのステータス コードを返します。

サービスが Google の API クライアント ライブラリを使用していて、500、502、503、または 504 を返した場合、Admin SDK API は指数バックオフで再試行します。その他の戻りステータス コードはすべて、メッセージ失敗とみなされます。

Admin SDK API 通知イベントについて

このセクションでは、Admin SDK API でプッシュ通知を使用する際に受信できる通知メッセージについて詳しく説明します。

Reports API のプッシュ通知には、同期メッセージとイベント通知の 2 種類のメッセージが含まれています。メッセージ タイプは X-Goog-Resource-State HTTP ヘッダーで示されます。イベント通知に指定できる値は、activities.list メソッドと同じです。各アプリケーションには固有のイベントがあります。

通知を停止する

expiration プロパティは、通知が自動的に停止するタイミングを制御します。特定のチャンネルの通知の受信を期限切れになる前に停止するには、次の URI で stop メソッドを呼び出します。

https://www.googleapis.com/admin/reports_v1/channels/stop

このメソッドでは、次の例に示すように、少なくともチャンネルの id プロパティと resourceId プロパティを指定する必要があります。Admin SDK API に watch メソッドを持つ複数のタイプのリソースがある場合でも、stop メソッドは 1 つのみです。

チャンネルの停止は適切な権限を持つユーザーのみが行えます。具体的には、次のとおりです。

  • 通常のユーザー アカウントによってチャンネルが作成された場合、チャンネルを停止できるのは、同じクライアント（認証トークンの OAuth 2.0 クライアント ID で識別）の同じユーザーのみです。
  • サービス アカウントによってチャンネルが作成された場合、同じクライアントのすべてのユーザーがそのチャンネルを停止できます。

次のコードサンプルは、通知の受信を停止する方法を示しています。

POST https://www.googleapis.com/admin/reports_v1/channels/stop
  
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

{
  "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a66",
  "resourceId": "ret08u3rv24htgh289g"
}