파일의 특정 필드 반환하기

필요한 정확한 필드를 반환하고 성능을 개선하려면 메서드 호출에서 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)')는 '잘못된 필드 선택 canAddChildren' 오류를 반환합니다. 이 예시의 올바른 필드 쿼리 매개변수는 files.list(fields='files(id,capabilities/canAddChildren)')입니다.

fields 매개변수를 사용하여 반환할 수 있는 필드를 확인하려면 쿼리하는 리소스의 문서 페이지를 참조하세요. 예를 들어 파일에 반환할 수 있는 필드를 보려면 files 리소스 문서를 참고하세요.

필드 매개변수 형식 규칙

필드 요청 매개변수 값의 형식은 대략 XPath 구문을 기반으로 합니다. 다음은 fields 매개변수의 형식 지정 규칙입니다. 이러한 모든 규칙은 files.get 메서드와 관련된 예를 사용합니다.

  • 'name, mimeType'와 같이 여러 필드를 선택하려면 쉼표로 구분된 목록을 사용합니다.

  • a/b를 사용하여 'capabilities/canDownload'와 같이 a 필드 내에 중첩된 b 필드를 선택합니다. 자세한 내용은 중첩된 리소스의 필드 가져오기를 참조하세요.

  • 하위 선택자를 사용하여 어레이 또는 객체의 특정 하위 필드의 조합을 요청하려면 '()'와 같이 괄호 안에 표현식을 입력합니다. 예를 들어 '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/role로 files.get.
  • files.get: fields=permissions와 함께 중첩된 리소스의 모든 필드를 암시합니다.
  • fields=changes(file(permissions(role)))로 changes.list 호출

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