특정 필드 반환

필요한 정확한 필드를 반환하고 성능을 개선하려면 메서드 호출에서 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' 오류를 발생시킵니다. 이 예시의 올바른 필드 매개변수는 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/*'는 권한별로 사용 가능한 모든 권한 세부정보 필드를 선택합니다. 와일드 카드를 사용하면 요청에 부정적인 성능 영향이 미칠 수 있습니다.

예 보기

요청

이 예에서는 파일 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로 permissions.get() 호출
  • permissions.get()와 fields=*를 사용하여 모든 permissions 필드를 표시합니다.
  • fields=permissions(role) 또는 fields=permissions/role로 files.get().
  • files.get()와 fields=permissions를 사용하여 모든 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"
    }
  ]
}