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 헤더 | 설명 |
|---|---|---|
Authorization |
사용자 인증 정보 자세한 내용은 인증 개요를 참조하세요. | |
$alt,alt |
대체 응답 형식입니다. 지원되는 값은 json(기본값), media, proto, sse(JSON 스트림)입니다. |
|
$.xgafv |
JSON 오류 형식입니다. 지원되는 값은 1, 2(기본값)입니다. Google API 클라이언트 라이브러리에서만 오류 형식 1을 사용해야 합니다. |
|
$callback,callback |
JSONP 콜백 매개변수입니다. | |
$ct |
Content-Type |
HTTP Content-Type 요청 헤더 재정의입니다. |
$fields,fields |
X-Goog-FieldMask |
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입니다. |
|
quotaUser |
X-Goog-Quota-User |
사용자별 할당량 요금에 대한 의사 사용자 식별자입니다. 지정하지 않으면 인증된 주 구성원이 사용됩니다. 인증된 주 구성원이 없으면 클라이언트 IP 주소가 사용됩니다. 지정된 경우 서비스 제한이 있는 유효한 API 키를 사용하여 할당량 프로젝트를 식별해야 합니다. 그렇지 않으면 이 매개변수는 무시됩니다. |
$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이 됩니다. |
|
X-Goog-Request-Reason |
감사 로그에 기록되는 요청 이유가 포함됩니다. 예를 들어 지원 기록 티켓 번호 역시 이유가 될 수 있습니다. | |
$userProject |
X-Goog-User-Project |
할당량 및 결제 목적으로 호출자가 지정한 프로젝트입니다. 호출자는 프로젝트에 대한 serviceusage.services.use 권한이 있어야 합니다. |
X-Server-Timeout |
요청 처리를 완료하기 위한 서버의 제한 시간(초, 부동 소수점 값)입니다. 이 시스템 매개변수는 클라이언트 측 제한 시간을 적용할 수 없는 REST API에만 적용됩니다. | |
x-goog-request-params |
gRPC 요청의 추가 매개변수를 URL 쿼리 형식으로 전달합니다. 예를 들면 x-goog-request-params: service=pubsub.googleapis.com&release=2021-11-01r0입니다. |
변경 로그
- 2021-11
x-goog-request-params관련 문서를 게시했습니다. - 2021-02
quotaUser관련 문서를 게시했습니다. - 2020-07 OAuth 2.0 쿼리 매개변수가 지원 중단되었습니다.
- 2019-10
X-Server-Timeout시스템 매개변수가 도입되었습니다. - 2017-10
X-Goog-User-Project시스템 매개변수가 도입되었습니다.