ファイルの特定のフィールドを返す

必要なフィールドを正確に返し、パフォーマンスを向上させるには、メソッド呼び出しで 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"
    }
  ]
}