API 호출 구조

이 가이드에서는 모든 API 호출의 공통 구조를 설명합니다.

클라이언트 라이브러리를 사용하여 API와 상호작용하는 경우 기본 요청 세부정보에 신경 쓸 필요가 없습니다. 그러나 테스트와 디버깅에 관해 조금이라도 알아두면 도움이 될 수 있습니다.

Google Ads API는 REST 바인딩이 포함된 gRPC API입니다. 즉, API를 호출하는 방법에는 두 가지가 있습니다.

  1. [권장] 요청 본문을 프로토콜 버퍼로 만들어 HTTP/2를 사용하여 서버에 전송하고, 응답을 프로토콜 버퍼로 역직렬화하고 결과를 해석합니다. 대부분의 문서에서는 gRPC 사용에 대해 설명합니다.

  2. [선택사항] 요청 본문을 JSON 객체로 만들고 HTTP 1.1을 사용하여 서버에 전송한 후 응답을 JSON 객체로 역직렬화하고 결과를 해석합니다. REST 사용에 대한 자세한 내용은 REST 인터페이스 가이드를 참조하세요.

리소스 이름

API의 객체는 대부분 리소스 이름 문자열로 식별됩니다. 또한 이러한 문자열은 REST 인터페이스를 사용할 때 URL 역할을 합니다. 구조는 REST 인터페이스의 리소스 이름을 참조하세요.

복합 ID

객체의 ID가 전역적으로 고유하지 않은 경우 상위 ID와 물결표 (~)를 앞에 붙여서 해당 객체의 복합 ID를 구성합니다.

예를 들어 광고그룹 광고 ID는 전역적으로 고유하지 않으므로 다음과 같이 상위 객체 (광고그룹) ID를 앞에 붙여 고유한 복합 ID를 만듭니다.

  • AdGroupId/123 + ~ + 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 형식으로 포함되어야 합니다.

login-customer-id

하이픈 (-) 없이 요청에 사용할 승인된 고객의 고객 ID입니다. 관리자 계정을 통해 고객 계정에 액세스하는 경우 이 헤더는 필수이며 관리자 계정의 고객 ID로 설정해야 합니다.

https://googleads.googleapis.com/v16/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 후행 메타데이터)가 응답 본문과 함께 반환됩니다. 디버깅 목적으로 이러한 값을 로깅하는 것이 좋습니다.

request-id

request-id는 이 요청을 고유하게 식별하는 문자열입니다.

이전
리소스 메타데이터