このドキュメントでは、リソースが変更されたときにアプリケーションに通知するプッシュ通知を使用する方法について説明します。
概要
Admin SDK API は、リソースの変更をモニタリングするためのプッシュ通知を提供します。この機能を使用すると、アプリケーションのパフォーマンスを改善できます。これにより、リソースが変更されたかどうかを判断するためのポーリングに関連する余分なネットワークとコンピューティングの費用を削減できます。監視対象リソースが変更されるたびに、Admin SDK API がアプリに通知します。
プッシュ通知を使用するには、次の 2 つのことを行う必要があります。
受信 URL または「Webhook」コールバック レシーバを設定します。
これは、リソースが変更されたときにトリガーされる API 通知メッセージを処理する HTTPS サーバーです。
監視するリソース エンドポイントごとに通知チャンネルを設定します。
チャネルで、通知メッセージのルーティング情報を指定します。チャンネル設定の一環として、通知を受け取る特定の URL を指定する必要があります。チャンネルのリソースが変更されると、Admin SDK API が通知メッセージを
POST
リクエストとしてその URL に送信します。
現在、Admin SDK API は、アクティビティ リソースの変更に関する通知をサポートしています。
通知チャンネルを作成する
プッシュ通知をリクエストするには、モニタリングするリソースごとに通知チャンネルを設定する必要があります。通知チャンネルを設定すると、監視対象リソースが変更されると、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 を使用する必要があります。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", // 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
も含まれます。これにより、この通知チャンネルで監視されているリソースを識別できます。
返された情報は、通知の受信を停止したい場合など、他の通知チャンネル オペレーションに渡すことができます。
レスポンスの詳細については、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 は、これらのメッセージを HTTPS POST
リクエストとして、この通知チャンネルの address
プロパティとして指定した URL に送信します。
通知メッセージの形式を解釈する
すべての通知メッセージには、X-Goog-
という接頭辞を持つ一連の HTTP ヘッダーが含まれます。通知のタイプによっては、メッセージ本文を含めることもできます。
ヘッダー
Admin SDK API から受信 URL に送信される通知メッセージには、次の HTTP ヘッダーが含まれます。
ヘッダー | 説明 |
---|---|
常に存在する | |
|
この通知チャンネルを識別するために指定した UUID などの一意の文字列。 |
|
この通知チャネルのこのメッセージを識別する整数。sync メッセージの場合、値は常に 1 です。チャネル上の後続のメッセージごとにメッセージ番号は増加しますが、連続ではありません。 |
|
監視対象リソースを識別する不透明な値。この ID は API のバージョンが変わりません。 |
|
通知をトリガーした新しいリソースの状態。
有効な値: sync またはイベント名。 |
|
監視対象リソースの API バージョン固有の識別子。 |
ときどきあった | |
|
通知チャンネルの有効期限。人が読める形式で表されます。定義されている場合にのみ存在します。 |
|
アプリによって設定され、通知ソースの検証に使用できる通知チャネル トークン。定義されている場合にのみ存在します。 |
アクティビティの通知メッセージでは、リクエスト本文に次の情報が含まれます。
プロパティ | 説明 |
---|---|
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 |
管理コンソールまたは Google ドキュメント アプリケーションのドキュメント オーナーのドメイン。これは、レポートのイベントの影響を受けるドメインです。 |
ipAddress |
操作を行ったユーザーの IP アドレス。これは、Google Workspace にログインする際のユーザーのインターネット プロトコル(IP)アドレスです。ユーザーの物理的な場所を反映する場合もあれば、そうでない場合もあります。IP アドレスは、ユーザーのプロキシ サーバーのアドレスや、バーチャル プライベート ネットワーク(VPN)のアドレスなどです。API は IPv4 と IPv6 をサポートしています。 |
events[] |
レポート内のアクティビティ イベント。 |
events[].type |
イベントのタイプ。管理者が変更する Google Workspace のサービスまたは機能は、type プロパティに示されます。イベントは、eventName プロパティを使用して識別されます。 |
events[].name |
イベントの名前。これは、API によって報告されるアクティビティの固有の名前です。各 eventName は特定の Google Workspace サービスまたは機能に関連付けられており、API によりイベントのタイプ別に整理されます。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" }