시스템 매개변수

Google의 API 플랫폼은 플랫폼을 사용해 작성되는 모든 Google API에게 공통 기능 집합을 제공합니다. 플랫폼은 이러한 기능을 사용하고 제어할 수 있도록 시스템 매개변수라고 하는 요청 매개변수 집합을 사전 정의합니다. 모든 Google REST API와 gRPC API에서 이러한 매개변수를 사용할 수 있습니다. HTTP 쿼리 매개변수 또는 HTTP 헤더를 사용하여 시스템 매개변수를 지정할 수 있습니다. Google gRPC API의 경우에는 HTTP 헤더만 지원됩니다.

대부분 사용자들은 이러한 매개변수를 직접 사용할 필요 없지만 Google에서 제공하는 클라이언트 라이브러리에서 사용되는 경우가 종종 있습니다. Google API에 직접 액세스할 목적으로 커스텀 코드를 작성해야 한다면 JSON 출력(pretty-printing)을 제어하거나 API 키를 지정하는 등의 경우에 시스템 매개변수가 유용할 수 있습니다.

HTTP 매핑

HTTP 요청의 경우 시스템 매개변수는 URL 쿼리 매개변수 또는 HTTP 요청 헤더로 전송됩니다. 예를 들어 $foo라는 시스템 매개변수가 있으면 URL에서 ?$foo=xxx로 전송되거나 URL 인코딩된 경우 ?%24foo=xxx로 전송됩니다. 자세한 내용은 아래 표를 참고하세요.

gRPC 매핑

gRPC 요청의 경우 시스템 매개변수는 키가 소문자인 HTTP 요청 헤더로 전송됩니다. 자세한 내용은 아래 표를 참고하세요.

정의

다음 표는 모든 시스템 매개변수와 각 정의를 나열한 것입니다.

URL 쿼리 매개변수 HTTP/gRPC 헤더 설명
승인 사용자 인증 정보 자세한 내용은 인증 개요를 참조하세요.
$alt,
alt
대체 응답 형식입니다. 지원되는 값은 json(기본값), media, proto(바이너리 protobuf)입니다.
$.xgafv JSON 오류 형식입니다. 지원되는 값은 1, 2(기본값)입니다. 오류 형식 1은 기존 클라이언트에서만 사용되어야 합니다.
$callback,
callback
JSONP 콜백 매개변수입니다.
$ct Content-Type HTTP Content-Type 헤더 재정의입니다.
$fields,
fields
X-Goog-FieldMask 응답 필터링에 사용되는 FieldMask(google.protobuf.FieldMask)입니다. 이 매개변수가 비어있으면 모든 필드가 반환됩니다.
X-HTTP-Method-Override 요청에 사용하려고 의도한 HTTP 메서드입니다. 네트워크 프록시에 따라 허용하지 않는 HTTP 메서드가 있습니다.
$key,
key
X-Goog-Api-Key Google API 키에 대한 자세한 내용은 https://cloud.google.com/docs/authentication/api-keys를 참조하세요.
passwd,
password
비밀번호를 URL에 포함시키지 못하도록 하는 데 사용됩니다.
$prettyPrint,
prettyPrint
JSON 응답을 읽기 쉽게 출력합니다. 지원되는 값은 true(기본값), false입니다.
$outputDefaults JSON 응답에 대한 proto 기본값을 강제로 출력합니다.
$unique 요청 캐싱을 사용하지 않도록 설정하는 고유의 쿼리 매개변수입니다.
X-Goog-Api-Client API 클라이언트를 식별하는 데 사용됩니다. 값은 공백으로 구분된 NAME "/" SEMVER 문자열을 반환합니다. 여기서 NAME에는 소문자, 숫자, '-'만 포함되어야 하고 SEMVER는 시맨틱 버전 문자열이어야 합니다. 예를 들어 X-Goog-Api-Client는 python/3.5.0 grpc-google-pubsub-v1/0.1.0-beta2 linux/2.7.0이 됩니다.
$userProject X-Goog-User-Project 할당량 및 결제 목적으로 호출자가 지정한 프로젝트입니다. 호출자는 프로젝트에 대한 serviceusage.services.use 권한이 있어야 합니다.
X-Server-Timeout 요청 처리를 완료하기 위한 서버의 제한 시간(초, 부동 소수점 값)입니다. 이 시스템 매개변수는 클라이언트 측 제한 시간을 적용할 수 없는 REST API에만 적용됩니다.