リソースの変更に関する通知

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

概要

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

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

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

現在、Google ドライブ API は files メソッドと changes メソッドに対する変更の通知をサポートしています。

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

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

監視リクエストの要求

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

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

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

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

例

次のコードサンプルは、channels リソースを使用して、files.watch メソッドで単一の files リソースの変更の監視を開始する方法を示しています。

POST https://www.googleapis.com/drive/v3/files/fileId/watch
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

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

リクエストの本文で、チャンネルの id、type を web_hook、受信 URL を address に指定します。必要に応じて、次の情報を指定することもできます。

チャンネルトークンとして使用する token。
リクエストしたチャンネルの有効期限（ミリ秒単位）の expiration。

次のコードサンプルは、channels リソースを使用して、changes.watch メソッドで changes をすべて監視する方法を示しています。

POST https://www.googleapis.com/drive/v3/changes/watch
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

{
  "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a77",
  "type": "web_hook",
  "address": "https://mydomain.com/notifications",
  ...
  "token": "target=myApp-myChangesChannelDest",
  "expiration": 1426325213000
}

リクエストの本文で、チャンネルの id、type を web_hook、受信 URL を address に指定します。必要に応じて、次の情報を指定することもできます。

チャンネルトークンとして使用する token。
リクエストしたチャンネルの有効期限（ミリ秒単位）の expiration。

必須プロパティ

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

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

設定した ID 値は、このチャンネルで受信するすべての通知メッセージの X-Goog-Channel-Id HTTP ヘッダーにそのまま使用されます。
値 web_hook に設定された type プロパティ文字列。
この通知チャンネルの通知をリッスンして応答する URL に設定された address プロパティ文字列。これは Webhook コールバック URL であり、HTTPS を使用する必要があります。

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

省略可能なプロパティ

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

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

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

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

注: Google ドライブ API の場合、最大有効期限は、 files リソースの場合は現在時刻から 86,400 秒（1 日）、 changes の場合は 604,800 秒（1 週間）です。リクエストで expiration プロパティを設定しない場合、有効期限はデフォルトで現在時刻から 3, 600 秒になります。

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

レスポンスの監視

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

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

{
  "kind": "api#channel",
  "id": "01234567-89ab-cdef-0123456789ab",
  "resourceId": "o3hgv1538sdjfh",
  "resourceUri": "https://www.googleapis.com/drive/v3/files/o3hgv1538sdjfh",
  "token": "target=myApp-myFilesChannelDest",
  "expiration": 1426325213000
}

レスポンス本文には、次のようなチャンネルの詳細が記載されます。

kind: これが API チャンネルリソースであることを示します。
id: このチャンネルに指定した ID。
resourceId: 監視対象リソースの ID。
resourceUri: 監視対象リソースのバージョン固有の ID。
token: リクエスト本文で指定されたトークン。
expiration: チャンネルの有効期限（Unix タイムスタンプ、ミリ秒単位）。

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

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

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

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

メッセージの同期

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

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

Google ドライブ 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 になります。このチャネルの後続の通知には、前の通知よりも大きなメッセージ番号が付与されます（ただし連続にはなりません）。

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

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

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

受け取るお知らせの種類

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

APIs-Google

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

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

ヘッダー

Google Drive 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`、`add`、`remove`、`update`、 `trash`、`untrash`、`change` のいずれかです。
`X-Goog-Resource-URI`	監視対象リソースの API バージョン固有の ID。
存在する場合がある
`X-Goog-Changed`	変更に関する追加情報。値は `content`、 `parents`、 `children`、または `permissions` のいずれかです。 `sync` メッセージでは指定されません。
`X-Goog-Channel-Expiration`	通知チャンネルの有効期限の日時（人が読める形式）。定義されている場合にのみ存在します。
`X-Goog-Channel-Token`	アプリケーションによって設定され、通知元の確認に使用できる通知チャンネルトークン。定義されている場合にのみ存在します。

files と changes の通知メッセージは空です。

例

files リソースの変更通知メッセージ（リクエスト本文は含まれません）:

POST https://mydomain.com/notifications
Content-Type: application/json; utf-8
Content-Length: 0
X-Goog-Channel-ID: 4ba78bf0-6a47-11e2-bcfd-0800200c9a66
X-Goog-Channel-Token: 398348u3tu83ut8uu38
X-Goog-Channel-Expiration: Tue, 19 Nov 2013 01:13:52 GMT
X-Goog-Resource-ID:  ret08u3rv24htgh289g
X-Goog-Resource-URI: https://www.googleapis.com/drive/v3/files/ret08u3rv24htgh289g
X-Goog-Resource-State:  update
X-Goog-Changed: content,properties
X-Goog-Message-Number: 10

changes リソースの変更通知メッセージ（リクエスト本文が含まれます）:

POST https://mydomain.com/notifications
Content-Type: application/json; utf-8
Content-Length: 118
X-Goog-Channel-ID: 8bd90be9-3a58-3122-ab43-9823188a5b43
X-Goog-Channel-Token: 245t1234tt83trrt333
X-Goog-Channel-Expiration: Tue, 19 Nov 2013 01:13:52 GMT
X-Goog-Resource-ID:  ret987df98743md8g
X-Goog-Resource-URI: https://www.googleapis.com/drive/v3/changes
X-Goog-Resource-State:  changed
X-Goog-Message-Number: 23

{
  "kind": "drive#changes"
}

お知らせに対応する

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

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

Google ドライブ API の通知イベントについて

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

X-Goog-Resource-State	適用対象	配信されるタイミング
`sync`	`files`、`changes`	チャンネルが作成されました。通知の受信を開始できます。
`add`	`files`	リソースが作成または共有されました。
`remove`	`files`	既存のリソースが削除または共有解除されました。
`update`	`files`	リソースの 1 つ以上のプロパティ（メタデータ）が更新されました。
`trash`	`files`	リソースがゴミ箱に移動されました。
`untrash`	`files`	リソースがゴミ箱から削除されました。
`change`	`changes`	1 つ以上の変更履歴項目が追加されました。

update イベントの場合、X-Goog-Changed HTTP ヘッダーが指定されることがあります。このヘッダーには、発生した変更のタイプを説明するカンマ区切りのリストが含まれています。

変更タイプ	内容
`content`	リソースコンテンツが更新されました。
`properties`	1 つ以上のリソースプロパティが更新されました。
`parents`	1 つ以上のリソースの親が追加または削除されました。
`children`	1 つ以上のリソースの子が追加または削除されました。
`permissions`	リソースの権限が更新されました。

X-Goog-Changed ヘッダーを使用した例:

X-Goog-Resource-State: update
X-Goog-Changed: content, permissions

通知を停止する

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

https://www.googleapis.com/drive/v3/channels/stop

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

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

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

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

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

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