이 가이드에서는 모든 API 호출의 일반적인 구조를 설명합니다.
클라이언트 라이브러리를 사용하여 API와 상호작용하는 경우 기본 요청 세부정보에 대해 걱정할 필요가 없습니다. 하지만 테스트와 디버깅을 할 때 이러한 도구에 관해 약간 알고 있으면 도움이 될 수 있습니다.
Google Ads API는 REST API가 포함된 gRPC API입니다. 즉, API를 호출하는 방법에는 두 가지가 있습니다.
[권장] 요청 본문을 프로토콜 버퍼로 만들고, HTTP/2를 사용하여 서버에 전송하고, 응답을 프로토콜 버퍼로 역직렬화하고, 결과를 해석합니다. 대부분의 문서에서는 gRPC 사용에 대해 설명합니다.
[선택사항] JSON 객체로 요청 본문을 만들고 HTTP 1.1을 사용해 서버에 전송하고 응답을 JSON 객체로 역직렬화한 후 결과를 해석합니다. REST 사용에 대한 자세한 내용은 REST 인터페이스 가이드를 참조하세요.
리소스 이름
API에 있는 대부분의 객체는 리소스 이름 문자열로 식별됩니다. 이러한 문자열은 REST 인터페이스를 사용할 때 URL로도 사용됩니다. 구조는 REST 인터페이스의 리소스 이름을 참조하세요.
복합 ID
객체의 ID가 전역적으로 고유하지 않은 경우 상위 ID와 물결표 (~)를 추가하여 객체의 복합 ID가 생성됩니다.
예를 들어 광고그룹 광고 ID는 전역적으로 고유하지 않으므로 고유한 객체 (광고그룹) ID를 앞에 추가하여 고유한 복합 ID를 만듭니다.
123
의AdGroupId
+~
+45678
의AdGroupAdId
=123~45678
의 복합 광고그룹 광고 ID.
요청 헤더
다음은 요청의 본문과 함께 제공되는 HTTP 헤더 (또는 grpc 메타데이터)입니다.
승인
클라이언트를 대신하는 관리자 계정 또는 자체 계정을 직접 관리하는 광고주를 식별하는 Authorization: Bearer YOUR_ACCESS_TOKEN
형식의 OAuth2 액세스 토큰을 포함해야 합니다. 액세스 토큰을 검색하는 방법은 OAuth2 가이드를 참조하세요. 액세스 토큰은 받은 후 1시간 동안 유효합니다. 만료 시 액세스 토큰을 새로고침하여 새 토큰을 가져오세요. 클라이언트 라이브러리는 만료된 토큰을 자동으로 새로고침합니다.
개발자 토큰
개발자 토큰은 Google Ads API 개발자를 고유하게 식별하는 22자 문자열입니다. 개발자 토큰 문자열의 예는 ABcdeFGH93KL-NOPQ_STUv
입니다. 개발자 토큰은 developer-token : ABcdeFGH93KL-NOPQ_STUv
형식으로 포함해야 합니다.
로그인-고객-ID
하이픈 (-
) 없이 요청에서 사용할 승인된 고객의 고객 ID입니다. 고객 계정에 대한 액세스 권한이 관리자 계정을 통해 액세스되는 경우 이 헤더는 필수이며 관리자 계정의 고객 ID로 설정해야 합니다.
https://googleads.googleapis.com/v13/customers/1234567890/campaignBudgets:mutate
login-customer-id
설정은 로그인 또는 오른쪽 상단의 프로필 이미지 클릭 후 Google Ads UI에서 계정을 선택하는 것과 같습니다. 이 헤더를 포함하지 않으면 기본값은 운영 고객입니다.
연결된 고객 ID
이 헤더는 연결된 Google Ads 계정에 전환을 업로드할 때 서드 파티 앱 분석 서비스 제공업체만 사용합니다.
A
계정의 사용자가 ThirdPartyAppAnalyticsLink
를 통해 B
계정에 대한 항목 읽기 및 수정 액세스 권한을 제공하는 시나리오를 생각해 보세요.
연결된 후에는 계정 B
에서 사용자가 링크에 제공된 권한에 따라 계정 A
을 대상으로 API를 호출할 수 있습니다. 이 경우 A
계정에 대한 API 호출 권한은 다른 API 호출에 사용되는 관리자 계정 관계가 아닌 B
계정에 대한 서드 파티 연결에 의해 결정됩니다.
서드 파티 앱 분석 서비스 제공업체는 다음과 같이 API를 호출합니다.
linked-customer-id
: 데이터를 업로드하는 서드 파티 앱 애널리틱스 계정 (계정B
)입니다.customer-id
: 데이터가 업로드되는 Google Ads 계정 (계정A
)입니다.login-customer-id
및Authorization
헤더:B
계정에 액세스할 수 있는 사용자를 식별하는 값의 조합.
응답 헤더
다음 헤더 (또는 grpc 후속 메타데이터)는 응답 본문과 함께 반환됩니다. 디버깅을 위해 이러한 값을 로깅하는 것이 좋습니다.
요청 ID
request-id
는 이 요청을 고유하게 식별하는 문자열입니다.