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

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

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

概要

Google Drive API には、リソースの変更をモニタリングするためのプッシュ通知が用意されています。この機能を使用すると、アプリケーションのパフォーマンスを改善できます。これにより、リソースが変更されたかどうかを判断するためのポーリングに関連する余分なネットワークとコンピューティングの費用を削減できます。監視対象のリソースが変更されるたびに、Google Drive API がアプリケーションに通知します。

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

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

現在、Google Drive 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", // Your channel ID.
  "type": "web_hook",
  "address": "https://mydomain.com/notifications", // Your receiving URL.
  ...
  "token": "target=myApp-myFilesChannelDest", // (Optional) Your files channel token.
  "expiration": 1426325213000 // (Optional) Your requested channel expiration date and time.
}

次のコードサンプルは、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", // Your channel ID.
  "type": "web_hook",
  "address": "https://mydomain.com/notifications", // Your receiving URL.
  ...
  "token": "target=myApp-myChangesChannelDest", // (Optional) Your changes channel token.
  "expiration": 1426325213000 // (Optional) Your requested channel expiration date and time.
}

必須プロパティ

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

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

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

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

省略可能なプロパティ

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

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

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

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

注: Google Drive 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"", // ID you specified for this channel.
  "resourceId": "o3hgv1538sdjfh", // ID of the watched resource.
  "resourceUri": "https://www.googleapis.com/drive/v3/files/o3hgv1538sdjfh", // Version-specific ID of the watched resource.
  "token": "target=myApp-myFilesChannelDest", // Present only if one was provided.
  "expiration": 1426325213000, // Actual expiration date and time as UNIX timestamp (in milliseconds), if applicable.
}

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

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

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

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

メッセージを同期する

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

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

Google Drive 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 Drive API の内部制限またはデフォルト（より制限の厳しい値が使用されます）によって決定されます。チャネルの有効期限（設定されている場合）は、watch メソッドから返される情報に Unix タイムスタンプ（ミリ秒単位）として含まれています。また、有効期限の日付と時刻は、アプリがこのチャネルについて受け取るすべての通知メッセージの X-Goog-Channel-Expiration HTTP ヘッダーに、人が読める形式で記載されます。

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

お知らせを受け取る

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

注: 通知配信の HTTPS リクエストでは、ユーザーエージェントを APIs-Google に指定し、robots.txt ディレクティブに従います（API 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 バージョン固有の識別子。
ときどきあった
`X-Goog-Changed`	変更に関する詳細情報。有効な値: `content`、`parents`、`children`、または `permissions`。`sync` メッセージでは提供されません。
`X-Goog-Channel-Expiration`	通知チャンネルの有効期限。人が読める形式で表されます。定義されている場合にのみ存在します。
`X-Goog-Channel-Token`	アプリによって設定され、通知ソースの検証に使用できる通知チャネルトークン。定義されている場合にのみ存在します。

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

例

リクエスト本文を含まない files リソースの通知メッセージを変更します。

POST https://mydomain.com/notifications // Your receiving URL.
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 // Your receiving URL.
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 Drive API の通知イベントについて

このセクションでは、Google Drive 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 Drive API に watch メソッドを持つ複数のタイプのリソースがある場合、stop メソッドは 1 つだけです。

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

チャネルが通常のユーザーアカウントで作成された場合は、そのチャネルを作成した同じクライアント（認証トークンの 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"
}