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

プッシュ通知

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

概要

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 リクエストは成功しません。

例

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

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", // Your channel ID.
  "type": "web_hook",
  "address": "https://mydomain.com/notifications", // Your receiving URL.
  ...
  "token": "target=myApp-myFilesChannelDest", // (Optional) Your channel token.
  "payload": true, // (Optional) Whether to include the payload (message body) in notifications.
  "expiration": 3600 // (Optional) Your requested channel expiration time.
}

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 ヘッダーにエコーバックされます。
type プロパティ文字列。値 web_hook に設定されています。
この通知チャンネルの通知をリッスンして応答する URL に設定された address プロパティ文字列。これは Webhook コールバック URL で、HTTPS を使用する必要があります。

ウェブサーバーに有効な SSL 証明書がインストールされている場合にのみ、Admin SDK API がこの HTTPS アドレスに通知を送信できます。次のような証明書は無効です。
- 自己署名証明書。
- 信頼できない提供元によって署名された証明書。
- 失効した証明書。
- ターゲットのホスト名と一致しないサブジェクトを持つ証明書。

省略可能なプロパティ

watch リクエストで次のオプションフィールドを指定することもできます。

チャネルトークンとして使用する任意の文字列値を指定する token プロパティ。通知チャンネルトークンはさまざまな目的で使用できます。たとえば、トークンを使用して、各受信メッセージがアプリケーションによって作成されたチャネルのものであることを確認できます。これにより、通知が偽装されていないことを確認できます。また、このチャネルの目的に基づいて、アプリケーション内の適切な宛先にメッセージをルーティングすることもできます。最大文字数: 256 文字。
このトークンは、このチャネルについてアプリケーションが受信するすべての通知メッセージの X-Goog-Channel-Token HTTP ヘッダーに含まれます。

通知チャンネルトークンを使用する場合は、次のことをおすすめします。
- URL クエリパラメータなど、拡張可能なエンコード形式を使用します。例: forwardTo=hr&createdBy=mobile
- OAuth トークンなどのセンシティブデータは含めないでください。
注: 機密性の高いデータを送信する必要がある場合は、データをトークンに追加する前に暗号化してください。
expiration プロパティ文字列。Admin SDK API がこの通知チャネルのメッセージの送信を停止する日時の Unix タイムスタンプ（ミリ秒単位）に設定します。

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

注: Admin SDK API の場合、最大有効期限は 21, 600 秒です。リクエストに expiration プロパティを設定しない場合、有効期限はデフォルトで現在の時刻から 21, 600 秒後に設定されます。

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

回答を監視

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

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

{
  "kind": "api#channel",
  "id": "reportsApiId", // ID you specified for this channel.
  "resourceId": "o3hgv1538sdjfh", // ID of the watched resource.
  "resourceUri": "https://admin.googleapis.com/admin/reports/v1/activity/userKey/applications/applicationName", // Version-specific ID of the watched resource.
  "token": "target=myApp-myFilesChannelDest", // Present only if one was provided.
  "expiration": 3600, // Actual expiration time as Unix timestamp (in ms), if applicable.
}

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

注: resourceId プロパティは、バージョンに依存しない安定したリソース識別子です。resourceUri プロパティは、現在の API バージョンのコンテキストにおける監視対象リソースの正規 URI であるため、バージョン固有です。

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

レスポンスについて詳しくは、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

同期メッセージには常に 1 の X-Goog-Message-Number HTTP ヘッダー値が含まれます。このチャンネルの後続の通知はそれぞれ、前の通知より大きいメッセージ番号を持ちますが、メッセージ番号は連続しません。

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

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

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

お知らせを受け取る

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

注: 通知配信の HTTPS リクエストでは、ユーザーエージェントを APIs-Google に指定し、robots.txt ディレクティブを遵守します。詳細については、API の Google ユーザーエージェントをご覧ください。

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

すべての通知メッセージには、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 バージョン固有の識別子。
時々ある
`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`	イベントが属するアプリケーション名。可能な値は次のとおりです。 admin カレンダードライブグループ groups_enterprise login モバイル saml token user_accounts
`id.customerId`	Google Workspace アカウントの一意の識別子。
`actor`	アクションを行っているユーザー。
`actor.callerType`	レポートにリストされているアクティビティを実行した作成者のタイプ。このバージョンの API では、`callerType` は、レポートにリストされているアクションを実行した `USER` または OAuth 2LO エンティティリクエストです。
`actor.email`	アクティビティが報告されるユーザーのメインのメールアドレス。
`actor.profileId`	ユーザーの一意の Google Workspace プロフィール ID。
`ownerDomain`	管理コンソールのドメイン、または Google ドキュメントアプリケーションのドキュメントオーナーレポートのイベントによって影響を受けるドメインです。
`ipAddress`	操作を行ったユーザーの IP アドレス。これは、Google Workspace にログインする際のユーザーのインターネットプロトコル（IP）アドレスです。ユーザーの物理的な場所を反映する場合もあれば、そうでない場合もあります。IP アドレスは、ユーザーのプロキシサーバーのアドレスやバーチャルプライベートネットワーク（VPN）のアドレスなどです。API は IPv4 と IPv6 をサポートしています。
`events[]`	レポート内のアクティビティイベント。
`events[].type`	イベントの種類。管理者が変更する Google Workspace のサービスまたは機能は、`eventName` プロパティを使用してイベントを識別する `type` プロパティに示されます。
`events[].name`	イベントの名前。これは、API によって報告されるアクティビティの具体的な名前です。各 `eventName` は特定の Google Workspace サービスまたは機能に関連付けられており、これらは API がイベントのタイプに整理したものです。 `eventName` リクエストパラメータの一般的な例: `eventName` が指定されていない場合、レポートは `eventName` に該当するすべてのインスタンスを返します。 `eventName` をリクエストすると、API のレスポンスで、その `eventName` を含むすべてのアクティビティが返されます。返されるアクティビティには、リクエストされたプロパティだけでなく、他の `eventName` プロパティが含まれることもあります。
`events[].parameters[]`	さまざまな用途に対応するパラメータ値のペア。
`events[].parameters[].name`	パラメータの名前。
`events[].parameters[].value`	パラメータの文字列値。
`events[].parameters[].intValue`	パラメータの整数値。
`events[].parameters[].boolValue`	パラメータのブール値。

例

アクティビティリソースイベントの通知メッセージの一般的な形式は次のとおりです。

POST https://mydomain.com/notifications // Your receiving URL.
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 // Your receiving URL.
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"
}