特定のフィールドを返す

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

必要なフィールドのみを返し、パフォーマンスを向上させるには、メソッド呼び出しで fields system parameterを使用します。

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

fields パラメータの仕組み

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

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

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/*' は 権限ごとに使用可能なすべての権限の詳細フィールドを選択します。ワイルドカードを使用すると、リクエストのパフォーマンスに悪影響が生じる可能性があります。

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)))。

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

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 ドライブ API オペレーションに適用されるクエリ パラメータについては、 システム パラメータをご覧ください。

関連トピック

• エラーを解決する
• 認証と認可に関する問題のトラブルシューティング
• パフォーマンスの改善