必要なフィールドのみを返してパフォーマンスを向上させるには、メソッド呼び出しで fields システム パラメータを使用します。
このドキュメントでは、Google ドライブで fields パラメータを使用する方法について説明します。
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)') は「無効なフィールド選択 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)))。
複数のフィールドを取得するには、カンマ区切りのリストを使用します。たとえば、files.list を fields=files(id,name,createdTime,modifiedTime,size) に置き換えます。
例を表示
リクエスト
この例では、ファイル 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" } ] }