プッシュ通知

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

概要

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

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

受信 URL のドメインを登録します。
たとえば、https://mydomain.com/notifications を受信 URL として使用するには、https://mydomain.com を登録する必要があります。
受信 URL（「Webhook」コールバックレシーバー）を設定します。
これは、リソースが変更されたときにトリガーされる API 通知メッセージを処理する HTTPS サーバーです。
監視するリソースエンドポイントごとに通知チャンネルを設定します。
チャンネルは、通知メッセージのルーティング情報を指定します。チャンネル設定の一環として、通知を受け取る URL を確認します。チャンネルのリソースが変更されると、Admin SDK API は通知メッセージを POST リクエストとして、その URL に送信します。

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

ドメインの登録

プッシュ通知チャンネルを設定する前に、プッシュ通知メッセージを受信するために使用する URL のドメインを登録する必要があります。さらに、ドメインを登録する前には、ドメインの所有権を証明する必要があります。この手順は、何者かがプッシュを使用して別の誰かのドメインにメッセージを送信することを防止するための不正行為防止策です。

ステップ 1: ドメインの所有権を証明する

ドメインを登録するには、そのドメインの所有権を証明する必要があります。Search Console を使用して、サイト確認プロセスを完了します。詳細については、サイトの所有権確認についてのヘルプページをご覧ください。

ステップ 2: ドメインを登録する

証明済みのドメイン名をプロジェクトで許可されたドメインの 1 つとして登録するには、次のようにします。

API Console の [ドメインの確認] ページに移動します。
[ドメインを追加] をクリックします。
フォームに入力し、もう一度 [ドメインを追加] をクリックします。

この時点で、Google API Console は、リスト内のすべてのドメインを Search Console で確認済みのドメインと照合します。すべてのドメインが間違いなく確認されると、ページが更新され、許可されるドメインの新しいリストが表示されます。これらのドメインのいずれかを使用してプッシュ通知を受信できるようになりました。

通知チャンネルの作成

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

監視リクエストの要求

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

https://www.googleapis.com/apiName/apiVersion/resourcePath/watch

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

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

例

1 つのドメインの User リソースに対するすべての監視リクエストの一般的な形式は次のとおりです。

POST https://admin.googleapis.com/admin/directory/v1/users/watch?domain=domain&event=event
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.
  "params": {
    "ttl": 3600 // (Optional) Your requested time-to-live for this channel.
  }
}

domain パラメータと event パラメータを使用して、通知を受け取るドメインのタイプと種類を指定します。

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

POST https://admin.googleapis.com/admin/directory/users/v1/watch?customer=customer&event=event
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.
  "params": {
    "ttl": 3600 // (Optional) Your requested time-to-live for this channel.
  }
}

customer パラメータと event パラメータを使用して、顧客の Google アカウントの一意の ID と、通知を受け取るイベントの種類を指定します。

event に指定できる値は次のとおりです。

add: ユーザー作成イベント
delete: ユーザー削除イベント
makeAdmin: ユーザー管理ステータス変更イベント
undelete: ユーザー削除取り消しイベント
update: ユーザー更新イベント

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

ドメイン mydomain.com のユーザー作成イベントを監視:

POST https://admin.googleapis.com/admin/directory/v1/users/watch?domain=mydomain.com&event=add

顧客 my_customer のユーザー作成イベントを監視:

POST https://admin.googleapis.com/admin/directory/v1/users/watch?customer=my_customer&event=add

必須プロパティ

個々の 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 証明書がインストールされている場合にのみです。次のような証明書は無効です。
- 自己署名証明書。
- 信頼できない提供元によって署名された証明書。
- 失効した証明書。
- サブジェクトがターゲットホスト名と一致しない証明書。

重要: URL を address 値として使用する前に、Google API Console でドメインの登録を行う必要があります。

省略可能なプロパティ

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 リファレンスの Users リソースの watch メソッドをご覧ください。

レスポンスの監視

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

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

{
  "kind": "api#channel",
  "id": "01234567-89ab-cdef-0123456789ab", // ID you specified for this channel.
  "resourceId": "B4ibMJiIhTjAQd7Ff2K2bexk8G4", // ID of the watched resource.
  "resourceUri": "https://admin.googleapis.com/admin/directory/v1/users?domain=domain&event=event", // Version-specific ID of the watched resource.
  "token": "target=myApp-myFilesChannelDest", // Present only if one was provided.
  "expiration": 1384823632000, // Actual expiration time as Unix timestamp (in ms), if applicable.
}

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

注: resourceId プロパティは、リソースのバージョンに依存しない安定した ID です。resourceUri プロパティは、現在の API バージョンのコンテキストで監視されるリソースの正規 URI であり、バージョン固有です。

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

レスポンスの詳細については、API リファレンスの Users リソースの 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 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 は、この通知チャンネルの「アドレス」として指定された URL に、HTTPS POST リクエストとして、これらのメッセージを送信します。

注: これらの通知配信 HTTPS リクエストは、APIs-Google というユーザーエージェントを指定し、robots.txt ディレクティブに従います。詳細については、APIs 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 バージョン固有の ID。
存在する場合がある
`X-Goog-Channel-Expiration`	通知チャンネルの有効期限の日時（人が読める形式）。定義されている場合にのみ存在します。
`X-Goog-Channel-Token`	アプリケーションによって設定され、通知元の確認に使用できる通知チャンネルトークン。定義されている場合にのみ存在します。

Users に対する通知メッセージのリクエスト本文には次の情報が含まれます。

プロパティ	説明
`kind`	User リソースであることを示します。値: 固定文字列 "`admin#directory#user`"。
`id`	ユーザーリソースの一意の識別子。
`etag`	通知メッセージの ETag。User リソースの ETag とは異なります。
`primaryEmail`	ユーザーのメインのメールアドレス。

例

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

POST https://mydomain.com/notifications // Your receiving URL.
Content-Type: application/json; utf-8
Content-Length: 0
X-Goog-Channel-ID: directoryApiId
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/directory/v1/users?domain=domain&event=event
X-Goog-Resource-State:  event
X-Goog-Message-Number: 10

{
  "kind": "admin#directory#user",
  "id": long,
  "etag": string,
  "primaryEmail": string
}

ユーザー削除イベントの例を次に示します。

POST https://mydomain.com/notifications // Your receiving URL.
Content-Type: application/json; utf-8
Content-Length: 189
X-Goog-Channel-ID: deleteChannel
X-Goog-Channel-Token: 245t1234tt83trrt333
X-Goog-Channel-Expiration: Mon, 09 Dec 2013 22:24:23 GMT
X-Goog-Resource-ID:  B4ibMJiIhTjAQd7Ff2K2bexk8G4
X-Goog-Resource-URI: https://admin.googleapis.com/admin/directory/v1/users?domain=mydomain.com&event=delete&alt=json
X-Goog-Resource-State:  delete
X-Goog-Message-Number: 236440

{
  "kind": "admin#directory#user",
  "id": "111220860655841818702",
  "etag": "\"Mf8RAmnABsVfQ47MMT_18MHAdRE/evLIDlz2Fd9zbAqwvIp7Pzq8UAw\"",
  "primaryEmail": "user@mydomain.com"
}

通知への応答

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

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

通知の停止

有効期限とは、いつ通知が自動的に停止するかを表すものです。特定チャンネルの通知の受信を期限切れになる前に停止するには、次の URI で stop メソッドを呼び出します。

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

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

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

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

POST https://www.googleapis.com/admin/directory_v1/channels/stop

Authorization: Bearer {auth_token_for_current_user}
Content-Type: application/json

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