このドキュメントでは、プッシュ通知を使用して、 アプリケーションを変更する必要はありません。
概要
Google Drive API のプッシュ通知を使用すると、Google の おすすめします。この機能を使用すると、キャンペーンの 説明します。これにより、余分なネットワークやコンピューティング リソースを リソースのポーリングに関連するコストも削減できます。 監視対象のリソースが変更されるたびに、Google Drive API は 説明します。
プッシュ通知を使用するには、次の 2 つのことを行う必要があります。
受信 URL(Webhook)を設定するコールバック レシーバとして渡されます。
この 通知メッセージを処理する HTTPS サーバーです。 トリガーされます。
必要なリソース エンドポイントごとに(通知チャンネル)を設定する 。
チャネルは通知のルーティング情報を指定する ブロックすることもできます。チャネル設定の一環として、そのチャネルの URL を を選択します。チャンネルのリソースが変更されると Google Drive API は、通知メッセージを
POST
として送信します。 リクエストをその URL に送信します。
通知チャンネルを作成する
プッシュ通知をリクエストするには、通知チャンネルを設定する必要があります リソースごとに最大 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 ヘッダーを含めます。
ヘッダー | 説明 |
---|---|
常に表示 | |
|
この ID を識別するために指定した 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 クライアント ライブラリを使用している場合
Google Drive API の 500
、502
、503
、または 504
を返します。
指数バックオフによる再試行。
それ以外の戻りステータス コードは、すべてメッセージ失敗とみなされます。
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
プロパティは、通知を自動的に停止するタイミングを制御します。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" }