このドキュメントでは、Google ドライブで fields パラメータを使用する方法について説明します。
必要なフィールドを正確に返し、パフォーマンスを向上させるには、メソッド呼び出しで fields システム パラメータを使用します。
Drive API に適用される他のシステム パラメータについては、代替システム パラメータをご覧ください。
fields パラメータの仕組み
fields パラメータは、レスポンスのフィルタリングに FieldMask を使用します。フィールド マスクは、リクエストで返すフィールドのサブセットを指定するために使用されます。フィールド マスクを使用することは、不要なデータをリクエストしないようにするための優れた設計手法です。これにより、不要な処理時間を回避できます。
fields パラメータを指定しない場合、サーバーはメソッドに固有のデフォルトのフィールド セットを返します。たとえば、files リソースの list メソッドは、kind、id、name、mimeType の各フィールドのみを返します。permissions リソースの get メソッドは、デフォルトのフィールドの異なるセットを返します。
about、approvals、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（'capabilities/canDownload'など）内にネストされているフィールドbを選択します。詳細については、ネストされたリソースのフィールドを取得するをご覧ください。かっこ「()」で式を囲むことで、サブセレクタを使用して配列またはオブジェクトの特定のサブフィールドのセットをリクエストできます。たとえば、
'permissions(id)'と指定すると、permissions 配列内の各要素について、権限 ID のみが返されます。オブジェクト内のすべてのフィールドを返すには、フィールド選択でワイルドカードとしてアスタリスク（
*）を使用します。たとえば、'permissions/permissionDetails/*'は、権限ごとに使用可能なすべての権限の詳細フィールドを選択します。ワイルドカードを使用すると、リクエストのパフォーマンスに悪影響が生じる可能性があります。キーに特殊文字（スラッシュ
/やピリオド.など）が含まれている場合、マップの個々の要素を選択することはできません。たとえば、fields=exportLinks/application/pdfを使用してexportLinksで特定のエクスポート形式キーを選択しようとすると、パス パーサーが/をネストされたプロパティ区切り文字として解釈するため、HTTP 400 Bad Requestエラーが発生します。キーに特殊文字を含む Key-Value ペアを取得するには、マップ全体（fields=exportLinksなど）をリクエストし、結果をクライアントサイドでフィルタします。
リクエスト
この例では、ファイル 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、名前、ネストされた所有者の詳細（表示名とメールアドレス）を含むファイルのリストを取得し、ページネーション用の次のページトークンも取得するには、fields=nextPageToken,files(id,name,owners(displayName,emailAddress)) を使用して 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 オペレーションに適用されるクエリ パラメータについては、システム パラメータをご覧ください。