파일의 특정 필드 반환하기

필요한 필드를 정확하게 반환하고 성능을 개선하려면 메서드 호출에 fields 쿼리 매개변수를 사용하세요.

기본적으로 서버는 쿼리되는 리소스와 관련된 필드 집합을 반환합니다. 예를 들어 files.get 메서드는 files 리소스의 id, name, mimeType만 반환할 수도 있습니다. permissions.get 메서드는 permissions 리소스에 대해 다른 기본 필드 집합을 반환합니다.

서버는 fields 쿼리 매개변수가 포함된 유효한 요청을 처리한 후 요청된 데이터와 함께 HTTP 200 OK 상태 코드를 반환합니다. 필드 쿼리 매개변수에 오류가 있거나 유효하지 않은 경우 서버는 HTTP 400 Bad Request 상태 코드와 함께 필드 선택에 어떤 문제가 있는지 설명하는 오류 메시지를 반환합니다. 예를 들어 files.list(fields='files(id,capabilities,canAddChildren)')에서는 'Invalid field selection canAddChildren'이라는 오류가 발생합니다. 이 예시에서 올바른 필드 쿼리 매개변수는 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 필드 (중첩된 리소스)를 검색하려면 다음 옵션 중 하나를 사용합니다.

  • fields=role 또는 fields=*permissions.get.
  • fields=permissions(role) 또는 fields=permissions/rolefiles.get.
  • 중첩된 리소스의 모든 필드를 암시하는 files.getfields=permissions
  • fields=changes(file(permissions(role)))changes.list 호출

여러 필드를 검색하려면 쉼표로 구분된 목록을 사용합니다. 예를 들어 files.listfields=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"
    }
  ]
}