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

このドキュメントでは、プッシュ通知を使用して、 アプリケーションを変更する必要はありません。

概要

Google Drive API のプッシュ通知を使用すると、Google の おすすめします。この機能を使用すると、キャンペーンの 説明します。これにより、余分なネットワークやコンピューティング リソースを リソースのポーリングに関連するコストも削減できます。 監視対象のリソースが変更されるたびに、Google Drive API は 説明します。

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

  • 受信 URL（Webhook）を設定するコールバック レシーバとして渡されます。

    この 通知メッセージを処理する HTTPS サーバーです。 トリガーされます。

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

    チャネルは通知のルーティング情報を指定する ブロックすることもできます。チャネル設定の一環として、そのチャネルの URL を を選択します。チャンネルのリソースが変更されると Google Drive API は、通知メッセージを POST として送信します。 リクエストをその URL に送信します。

現在、Google Drive API では、 files メソッドと changes メソッド

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

プッシュ通知をリクエストするには、通知チャンネルを設定する必要があります リソースごとに最大 100 個の IP アドレスが必要です。通知チャンネルを設定した後 Google Drive API は、監視対象のリソースが検出されると できます。

監視のリクエストを行う

監視可能な Google Drive API の各リソースには、 次の形式の URI で watch メソッドを使用します。

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

アプリケーションの変更に関するメッセージの通知チャンネルを設定するには、 POST リクエストを リソースの watch メソッド。

各通知チャンネルは特定のユーザーとユーザーの両方に 特定のリソース（またはリソースセット）へのアクセスを制御します。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 プロパティ文字列 通知チャンネルを作成します。Google Cloud コンソールの ユニバーサルな固有識別子 （UUID）など 使用します。最大文字数: 64 文字。

    設定した ID 値が すべての通知の X-Goog-Channel-Id HTTP ヘッダー メッセージが届きます。

  • 値に設定された type プロパティ文字列 web_hook。

  • リッスンする URL に設定された address プロパティ文字列 この通知チャンネルの通知に応答します。これは、 HTTPS を使用する必要があります。

    なお、Google Drive API は、 有効な SSL 証明書がインストールされている場合にのみ、この HTTPS アドレスを使用できます。 作成します。次のような証明書は無効です。

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

省略可能なプロパティ

これらのオプション フィールドを、 watch リクエスト:

  • 任意の文字列を指定する token プロパティ 値を渡します。通知チャンネルを使用すると、 使用できます。たとえば、 認証トークンを使用して、各受信メッセージが 作成され、通知が送信されていないことを または、メールを内部の正しい宛先に このチャネルの目的に応じてアプリケーションを設計します。最大文字数: 256 文字。

    トークンは すべての通知の X-Goog-Channel-Token HTTP ヘッダー アプリケーションがこのチャンネル用に受信するメッセージです。

    通知チャンネル トークンを使用する場合は、次のことをおすすめします。

    • URL クエリなどの拡張可能なエンコード形式を使用する あります。例: forwardTo=hr&createdBy=mobile

    • OAuth トークンなどのセンシティブ データは含めないでください。

    で確認できます。

  • 設定された expiration プロパティ文字列。 Unix タイムスタンプ Google Drive API にリクエストを送信する日時（ミリ秒単位） この通知チャンネルへのメッセージの送信を停止します。

    チャネルに有効期限がある場合は、 X-Goog-Channel-Expiration HTTP ヘッダー（人が読める形式） すべての通知メッセージに 受信するメッセージの数を表します。

で確認できます。

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

スマートウォッチのレスポンス

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 で監視対象のリソースを識別 通知チャンネル。

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

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

メッセージを同期

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

sync の通知は無視してもかまいませんが、 使用しています。たとえば、特定のメッセージを保持せずに 作成するには、X-Goog-Channel-ID と 呼び出し内の X-Goog-Resource-ID の値 通知の受信を停止します。また、 初期化を行うための sync 通知 できます。

Google Drive API から送信される sync メッセージの形式 受信側の URL は次のとおりです。

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

現時点では、通知チャンネルを自動的に更新する方法はありません。日時 チャネルの有効期限が近づいている場合は、次を呼び出して新しいチャネルに置き換える必要があります。 watch メソッドを使用します。他のケースと同様に、名前には一意の値を使用する必要があります。 新しいチャンネルの id プロパティ。なお、 「重なり」であると言えます。2 つの通知チャンネルが通知される期間を 同じリソースがアクティブになります。

受け取るお知らせの種類

監視対象のリソースが変更されると、アプリケーションは 変更を説明する通知メッセージが送信されます。Google Drive API はこれらの情報を HTTPS POST リクエストとして、 この通知の address プロパティ 。

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

すべての通知メッセージには、一連の HTTP ヘッダーが X-Goog- 接頭辞。 通知の種類によっては、 あります。

ヘッダー

Google Drive API によって受信側に送信された通知メッセージ URL には次の HTTP ヘッダーを含めます。

ヘッダー 説明
常に表示
X-Goog-Channel-ID この 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 クライアント ライブラリを使用している場合 Google Drive API の 500、502、503、または 504 を返します。 指数バックオフによる再試行。 それ以外の戻りステータス コードは、すべてメッセージ失敗とみなされます。

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 プロパティは、通知を自動的に停止するタイミングを制御します。Google Chat では 通知を受け取らないように設定することもできます。 次の URL にある stop メソッドを呼び出して期限切れにします。 次の URI を使用します。

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

この方法では、少なくともチャンネルの id プロパティと resourceId プロパティ。次のサンプルをご覧ください。 見てみましょう。Google Drive API に複数の種類のデータがある場合、 watch メソッドを持つリソースは 1 つだけ stop メソッドを使用します。

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

  • 通常のユーザー アカウントで作成されたチャンネルの場合、 の 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"
}