このドキュメントでは、リソースが変更されたときにアプリケーションに通知するプッシュ通知を使用する方法について説明します。
概要
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 ヘッダーにエコーバックされます。 -
値
web_hook
に設定されたtype
プロパティ文字列。 -
この通知チャンネルの通知をリッスンして応答する URL に設定された
address
プロパティ文字列。これは Webhook コールバック URL であり、HTTPS を使用する必要があります。Google Drive API は、有効な SSL 証明書がウェブサーバーにインストールされている場合にのみ、この HTTPS アドレスに通知を送信できます。次のような証明書は無効です。
- 自己署名証明書。
- 信頼できない提供元によって署名された証明書。
- 失効した証明書。
- ターゲット ホスト名と一致しないサブジェクトを持つ証明書。
省略可能なプロパティ
watch
リクエストでは、次のオプション フィールドを指定することもできます。
-
チャネル トークンとして使用する任意の文字列値を指定する
token
プロパティ。通知チャンネル トークンは、さまざまな目的で使用できます。たとえば、トークンを使用して、各受信メッセージがアプリケーションによって作成されたチャネルに対するものであることを確認したり(通知のなりすましを防ぐため)、このチャネルの目的に基づいてアプリケーション内の適切な宛先にメッセージをルーティングしたりできます。最大文字数: 256 文字。このトークンは、アプリケーションがこのチャンネルで受信するすべての通知メッセージの
X-Goog-Channel-Token
HTTP ヘッダーに含まれています。通知チャンネル トークンを使用する場合は、次のことをおすすめします。
URL クエリ パラメータなどの拡張可能なエンコード形式を使用する。例:
forwardTo=hr&createdBy=mobile
OAuth トークンなどのセンシティブ データは含めないでください。
-
Google Drive API でこの通知チャンネルへのメッセージの送信を停止する日時の Unix タイムスタンプ(ミリ秒単位)に設定された
expiration
プロパティ文字列。チャネルに有効期限がある場合、アプリケーションがこのチャネルに対して受け取るすべての通知メッセージに、
X-Goog-Channel-Expiration
HTTP ヘッダーの値として(人が読める形式)含めます。
リクエストの詳細については、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
も含まれています。
返された情報を、通知の受信を停止するときなど、他の通知チャンネル オペレーションに渡すことができます。
レスポンスの詳細については、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
同期メッセージは常に 1
の X-Goog-Message-Number
HTTP ヘッダー値を持ちます。このチャンネルの後続の通知には、前の通知よりも大きなメッセージ番号がありますが、メッセージ番号は連続していません。
通知チャンネルを更新する
通知チャンネルには有効期限を設定できます。その値は、ユーザーのリクエストまたは Google Drive API の内部制限またはデフォルト(より制限の厳しい値が使用されます)によって決定されます。チャンネルの有効期限(存在する場合)は、watch
メソッドによって返される情報に Unix タイムスタンプ(ミリ秒単位)として含まれます。また、このチャネルに対してアプリケーションが受信するすべての通知メッセージには、X-Goog-Channel-Expiration
HTTP ヘッダーで有効期限の日時(人が読める形式)が含まれています。
現時点では、通知チャンネルを自動的に更新する方法はありません。チャネルの有効期限が近づいたら、watch
メソッドを呼び出して新しいチャネルに置き換える必要があります。通常どおり、新しいチャンネルの id
プロパティには一意の値を使用する必要があります。同じリソースの 2 つの通知チャネルがアクティブになっている間は、「オーバーラップ」期間が生じる可能性があるので注意してください。
お知らせを受け取る
監視対象のリソースが変更されるたびに、その変更を説明する通知メッセージがアプリケーションに送信されます。Google Drive API は、これらのメッセージを HTTPS POST
リクエストとして、この通知チャンネルの address
プロパティとして指定した URL に送信します。
通知メッセージの形式を解釈する
すべての通知メッセージには、X-Goog-
接頭辞を持つ一連の HTTP ヘッダーが含まれます。通知の種類によっては、メッセージ本文が含まれる場合もあります。
ヘッダー
Google Drive API から受信 URL に投稿される通知メッセージには、次の HTTP ヘッダーが含まれます。
ヘッダー | 説明 |
---|---|
常に表示 | |
|
この通知チャンネルを識別するために指定した UUID または一意の文字列。 |
|
この通知チャンネルのメッセージを識別する整数。sync メッセージの場合、値は常に 1 です。チャネル上の後続のメッセージごとにメッセージ番号が増加しますが、連続ではありません。 |
|
監視対象のリソースを識別する不透明な値。この ID は API バージョン間で不変です。 |
|
通知をトリガーした新しいリソースの状態。有効な値: sync 、add 、remove 、update 、trash 、untrash 、change 。 |
|
監視対象リソースの API バージョン固有の識別子。 |
ときどき存在する | |
|
変更に関する補足情報。有効な値: content 、parents 、children 、または permissions 。sync メッセージでは提供されません。 |
|
通知チャンネルの有効期限の日時。人が読める形式で表記されます。定義されている場合のみ存在します。 |
|
アプリケーションによって設定され、通知ソースの確認に使用できる通知チャンネル トークン。定義されている場合のみ存在します。 |
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 でプッシュ通知を使用する際に受信できる通知メッセージについて詳しく説明します。
配信日時 | ||
---|---|---|
sync |
files 、changes |
チャンネルを作成しました。通知が届くようになるはずです。 |
add |
files |
リソースが作成または共有されました。 |
|
files |
既存のリソースが削除されたか、共有が停止されました。 |
|
files |
リソースの 1 つ以上のプロパティ(メタデータ)が更新されました。 |
|
files |
リソースをゴミ箱に移動しました。 |
|
files |
リソースをゴミ箱から削除しました。 |
|
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" }