Drive API v2 と v3 の比較ガイド

Google Drive API の最新バージョンは v3 です。v3 では、検索ではフィールドのサブセットのみが返されるため、パフォーマンスが向上しています。v2 コレクションが不要な場合を除き、現在のバージョンを使用してください。v2 を使用している場合は、v3 への移行を検討してください。移行するには、Drive API v3 に移行するをご覧ください。バージョンの違いの一覧については、Drive API v2 と v3 の比較リファレンスをご覧ください。

v2 を引き続き使用する場合は、修正条項 Drive API v2 ガイドを参照して、v3 ガイドに記載されている手順の一部を v2 デベロッパー向けに修正する方法をご確認ください。

Drive API v3 の改善点について詳しくは、新しい API 設計について Google のエンジニアが解説している次の動画をご覧ください。

V3 の改善点

パフォーマンスを最適化し、API の動作の複雑さを軽減するために、v3 では以前の API バージョンから次の改善が行われています。

  • デフォルトでは、ファイルと共有ドライブを検索しても、リソース全体が返されるわけではなく、よく使用されるフィールドのサブセットのみが返されます。fields の詳細については、files.list メソッドと drives.list メソッドをご覧ください。
  • レスポンスを返すほぼすべてのメソッドで、fields パラメータが必要になりました。fields を必要とするすべてのメソッドの一覧については、 Drive API リファレンスをご覧ください。
  • 機能が重複しているリソースが削除されました。例:
    • files.list メソッドは、Children および Parents コレクションと同じ機能を実現するため、v3 から削除されました。
    • Realtime.* メソッドが削除されました。
  • デフォルトでは、アプリデータは検索で返されません。v2 では、drive.appdata スコープを設定できます。これにより、files.list メソッドと changes.list メソッドからアプリデータが返されますが、パフォーマンスが低下します。v3 では、drive.appdata スコープを設定し、アプリケーション データをリクエストするためにクエリ パラメータ spaces=appDataFolder も設定します。
  • すべての更新オペレーションで、PUT ではなく PATCH が使用されます。
  • Google ドキュメントをエクスポートするには、files.export メソッドを使用します。
  • changes.list メソッドの動作は異なります。変更 ID ではなく、不透明なページトークンを使用します。変更コレクションをポーリングするには、まず初期値に対して changes.getStartPageToken メソッドを呼び出します。後続のクエリでは、changes.list メソッドは newStartPageToken 値を返します。
  • update メソッドで、書き込み不可能なフィールドを指定するリクエストが拒否されるようになりました。
  • about リソースの v2 の exportFormats フィールドと importFormats フィールドは、使用可能なインポート形式またはエクスポート形式のリストです。v3 では、サポートされているすべてのインポートまたはエクスポートに対する可能なターゲットの MIME タイプマップです。
  • v2 の appdata エイリアスと appfolder エイリアスは、v3 では appDataFolder になりました。
  • properties リソースは v3 から削除されました。files リソースには、true の Key-Value ペアを含む properties フィールドがあります。properties フィールドには公開プロパティが含まれ、appProperties フィールドには非公開プロパティが含まれているため、公開設定フィールドは必要ありません。
  • files リソースの modifiedTime フィールドによって、誰かが最後にファイルを変更した時刻が更新されます。v2 では、modifiedDate フィールドは、setModifiedDate フィールドを設定した場合のみ、更新時にのみ変更可能でした。
  • files リソースの viewedByMeTime フィールドは自動更新されません。
  • Google ドキュメント形式をインポートするには、リソースの本文に適切なターゲット mimeType を設定します。v2 では、?convert=true を設定します。
  • サポートされていない形式の場合、インポート オペレーションで 400 エラーが返されます。
  • 閲覧者とコメント投稿者は権限を表示できません。
  • 権限の me エイリアスは削除されます。
  • 一部の機能はリクエスト リソースの一部として利用できましたが、代わりにリクエスト パラメータとして使用できます。例:
    • v2 では、children.delete を使用して親フォルダから子ファイルを削除できます。
    • v3 では、URL に ?removeParents=parent_id がある子に対して files.update を使用します。

その他の相違点

v3 ではフィールドとパラメータ名が異なります。以下にいくつか例を示します。

  • name プロパティは、files リソースの title に代わるものです。
  • Time は、Date ではなく、すべての日時フィールドの接尾辞です。
  • リスト オペレーションでは、結果セットを格納するために items フィールドは使用されません。リソースタイプは結果のフィールド（files や changes など）を提供します。