必要なフィールドを正確に返し、パフォーマンスを向上させるには、メソッド呼び出しで fields
クエリ パラメータを使用します。
デフォルトでは、サーバーはクエリ対象のリソースに固有の一連のフィールドを返します。たとえば、files.get
メソッドは、files
リソースの id
、name
、mimeType
のみを返す場合があります。permissions.get
メソッドは、permissions
リソースに関する別のデフォルト フィールドのセットを返します。
サーバーは、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
リソースのドキュメントをご覧ください。
フィールド パラメータの形式ルール
フィールド リクエストのパラメータ値の形式は、XPath 構文に大まかに準拠しています。fields
パラメータの形式ルールは次のとおりです。以下のルールはすべて、files.get
メソッドに関連する例を使用しています。
カンマ区切りのリストを使用して、複数のフィールド(
'name, mimeType'
など)を選択します。a/b
を使用して、フィールドa
内にネストされているフィールドb
('capabilities/canDownload'
など)を選択します。詳細については、ネストされたリソースのフィールドを取得するをご覧ください。配列またはオブジェクトの特定のサブフィールド セットをリクエストするには、サブセレクタを使用します。そのためには、式をかっこ「()」で囲みます。たとえば、
'permissions(id)'
は、権限配列内の各要素の権限 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
またはfields=*
に置き換えます。files.get
はfields=permissions(role)
またはfields=permissions/role
に置き換えます。files.get
はfields=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" } ] }