시스템 매개변수

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

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

HTTP 매핑

HTTP 프로토콜의 경우, 시스템 매개변수가 HTTP URL 쿼리 매개변수와 HTTP 헤더로 매핑됩니다. 아래를 참조하세요. 예를 들어 $foo라는 시스템 매개변수는 URL에서 ?$foo=xxx에 매핑되며, 전송 시 URL에 ?%24foo=xxx로 인코딩됩니다.

참고: '$' 프리픽스가 추가되는 이유는 일반적인 요청 매개변수와 충돌하는 일을 방지하기 위해서입니다.

gRPC 매핑

gRPC의 경우, 시스템 매개변수가 일반적인 HTTP 요청 헤더를 통해 전송됩니다. 자세한 내용은 아래 표를 참조하세요.

정의

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

URL 쿼리 매개변수 HTTP/gRPC 헤더 설명
access_token,
oauth_token
Authorization OAuth 2.0 액세스 토큰입니다. 자세한 내용은 Cloud 플랫폼 인증 가이드를 참조하세요.
$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)입니다. 이 매개변수가 비어있으면 모든 필드가 반환됩니다.
$httpMethod X-HTTP-Method-Override 요청에 사용하려고 의도한 HTTP 메소드입니다. 네트워크 프록시에 따라 허용하지 않는 HTTP 메소드가 있습니다.
$key,
key
X-Goog-Api-Key Google API 키입니다. 자세한 내용은 https://developers.google.com/console/help/#generatingdevkeys를 참조하세요.
passwd,
password
비밀번호를 URL에 포함시키지 못하도록 하는 데 사용됩니다.
$prettyPrint,
prettyPrint
JSON 응답을 읽기 쉽게 출력합니다. 지원되는 값은 truefalse입니다.
$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 권한이 있어야 합니다.