特定のフィールドを返す

このドキュメントでは、Google ドライブで fields パラメータを使用する方法について説明します。

必要なフィールドを正確に返し、パフォーマンスを向上させるには、メソッド呼び出しで fields システム パラメータを使用します。

ドライブ API に適用されるその他のシステム パラメータについては、代替システム パラメータをご覧ください。

fields パラメータの仕組み

fields パラメータは、レスポンスのフィルタリングに FieldMask を使用します。フィールド マスクは、リクエストで返すフィールドのサブセットを指定するために使用されます。フィールド マスクを使用することは、不要なデータをリクエストしないようにするための優れた設計手法です。これにより、不要な処理時間を回避できます。

fields パラメータを指定しない場合、サーバーはメソッドに固有のデフォルトのフィールド セットを返します。たとえば、files メソッドの list メソッドは、kind、id、name、mimeType の各フィールドのみを返します。permissions リソースの get メソッドは、デフォルトのフィールドの異なるセットを返します。

about、comments（delete を除く）、replies（delete を除く）リソースのすべてのメソッドで、fields パラメータを設定する必要があります。これらのメソッドは、フィールドのデフォルト セットを返しません。

サーバーは、fields パラメータを含む有効なリクエストを処理した後、リクエストされたデータとともに、HTTP 200 OK ステータス コードを返します。fields パラメータにエラーがある場合、またはパラメータが無効な場合、サーバーは HTTP 400 Bad Request ステータス コードとフィールド選択の問題箇所を示すエラー メッセージを返します。たとえば、files.list(fields='files(id,capabilities,canAddChildren)') は「Invalid field selection canAddChildren.」というエラーを返します。この例の正しい fields パラメータは files.list(fields='files(id,capabilities/canAddChildren)') です。

fields パラメータを使用して返すことができるフィールドを確認するには、クエリを実行するリソースのドキュメント ページをご覧ください。たとえば、ファイルに対して返せるフィールドを確認するには、files リソースのドキュメントをご覧ください。ファイル固有のクエリ用語について詳しくは、検索クエリの用語と演算子をご覧ください。

フィールド パラメータの形式ルール

fields リクエスト パラメータの形式は、XPath の構文に基づいています。fields パラメータの形式ルールは次のとおりです。これらのルールでは、files.get メソッドに関連する例を使用します。

  • 複数のフィールドを選択する場合は、'name, mimeType' などのカンマ区切りのリストを使用します。

  • a/b を使用して、a フィールド内にネストされている b フィールド（'capabilities/canDownload' など）を選択します。詳細については、ネストされたリソースのフィールドを取得するをご覧ください。

  • かっこ「()」で式を囲むことで、サブセレクタを使用して配列またはオブジェクトの特定のサブフィールドのセットをリクエストできます。たとえば、'permissions(id)' と指定すると、permissions 配列内の各要素について、権限 ID のみが返されます。

  • オブジェクト内のすべてのフィールドを返すには、フィールド選択でワイルドカードとしてアスタリスク（*）を使用します。たとえば、'permissions/permissionDetails/*' は、権限ごとに使用可能なすべての権限の詳細フィールドを選択します。ワイルドカードを使用すると、リクエストのパフォーマンスに悪影響が生じる可能性があります。

リクエスト

この例では、ファイル ID パス パラメータと複数のフィールドをリクエストのクエリ パラメータとして指定します。レスポンスは、ファイル ID のフィールド値を返します。

GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=name,starred,shared

レスポンス

{
  "name": "File1",
  "starred": false,
  "shared": true
  }
}

ネストされたリソースのフィールドを取得する

フィールドが別のリソースを参照している場合は、ネストされたリソースのどのフィールドを取得するかを指定できます。

たとえば、permissions リソースの role フィールド（ネストされたリソース）を取得するには、次のいずれかのオプションを使用します。

  • permissions.get: fields=role。
  • permissions.get と fields=* を使用して、すべての permissions フィールドを表示します。
  • files.get と fields=permissions(role) または fields=permissions/role。
  • files.get と fields=permissions を使用して、すべての permissions フィールドを表示します。
  • changes.list: fields=changes(file(permissions(role)))。

複数のフィールドを取得するには、カンマ区切りのリストを使用します。たとえば、fields=files(id,name,createdTime,modifiedTime,size) を含む files.list。

リクエスト

この例では、ファイル ID パス パラメータと、ネストされた権限リソースの特定のフィールドを含む複数のフィールドを、リクエストのクエリ パラメータとして指定します。レスポンスは、ファイル ID のフィールド値を返します。

GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=name,starred,shared,permissions(kind,type,role)

レスポンス

{
  "name": "File1",
  "starred": false,
  "shared": true,
  "permissions": [
    {
      "kind": "drive#permission",
      "type": "user",
      "role": "owner"
    }
  ]
}

代替システム パラメータ

すべての Google Drive API オペレーションに適用されるクエリ パラメータについては、システム パラメータをご覧ください。