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

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

概要

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

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

  • 受信 URL または「Webhook」コールバック レシーバーを設定します。

    これは、リソースが変更されたときにトリガーされる API 通知メッセージを処理する HTTPS サーバーです。

  • 監視するリソース エンドポイントごとに（通知チャンネル）を設定します。

    チャンネルは、通知メッセージのルーティング情報を指定します。チャンネル設定の一環として、通知を受け取る URL を確認する必要があります。チャンネルのリソースが変更されると、Google Drive API は通知メッセージを POST リクエストとして、その URL に送信します。

現在、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 がこの HTTPS アドレスに通知を送信できるのは、ウェブサーバーに有効な SSL 証明書がインストールされている場合にのみです。次のような証明書は無効です。

    • 自己署名証明書。
    • 信頼できない提供元によって署名された証明書。
    • 失効した証明書。
    • サブジェクトがターゲット ホスト名と一致しない証明書。

省略可能なプロパティ

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

同期メッセージの 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 に送信します。

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

すべての通知メッセージには、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 // 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"
}