特定のフィールドを返す

必要なフィールドを正確に返してパフォーマンスを向上させるには、メソッド呼び出しで fields システム パラメータを使用します。

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

デフォルトでは、サーバーはクエリ対象のリソースに固有のフィールド セットを返します。たとえば、files リソースの get() メソッドは、id、name、mimeType のみを返す場合があります。permissions リソースの get() メソッドは、異なるデフォルト フィールドのセットを返します。

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

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"
    }
  ]
}

関連トピック

• エラーを解決する
• 認証と認可に関する問題のトラブルシューティング