API 호출 구조

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

클라이언트 라이브러리를 사용하여 API와 상호작용하는 경우 기본 요청 세부정보를 알 필요가 없습니다. 하지만 테스트 및 디버깅 시 API 호출 구조에 관한 지식이 유용할 수 있습니다.

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

권장:

  1. 요청 본문을 프로토콜 버퍼로 만듭니다.

  2. HTTP/2를 사용하여 서버로 전송합니다.

  3. 프로토콜 버퍼에 대한 응답을 역직렬화합니다.

  4. 결과를 해석합니다.

대부분의 문서에서는 gRPC 사용을 설명합니다.

선택사항:

  1. 요청 본문을 JSON 객체로 만듭니다.

  2. HTTP 1.1을 사용하여 서버로 전송합니다.

  3. 응답을 JSON 객체로 역직렬화합니다.

  4. 결과를 해석합니다.

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시간 동안 유효합니다. 만료되면 액세스 토큰을 새로고침하여 새 토큰을 가져오세요. 클라이언트 라이브러리는 만료된 토큰을 자동으로 새로고침합니다.

승인 오류가 발생하면 올바른 사용자 인증 정보를 사용하고 있으며 충분한 권한이 있는지 확인하세요. USER_PERMISSION_DENIED 오류는 인증된 사용자에게 요청에 지정된 고객 계정에 대한 액세스 권한이 없을 수 있음을 나타냅니다. 권한 관리에 관한 자세한 내용은 Google Ads 액세스 수준을 참고하세요.

developer-token

개발자 토큰은 Google Ads API 개발자를 고유하게 식별하는 22자리 문자열입니다. 개발자 토큰 문자열의 예는 ABcdeFGH93KL-NOPQ_STUv입니다. 개발자 토큰은 developer-token : ABcdeFGH93KL-NOPQ_STUv 형식으로 포함되어야 합니다.

login-customer-id

요청에 사용할 승인된 고객의 고객 ID입니다 (하이픈 제외, -). 관리자 계정을 통해 고객 계정에 액세스하는 경우 이 헤더가 필수이며 관리자 계정의 고객 ID로 설정해야 합니다. 관리자 계정을 통해 인증할 때 login-customer-id를 포함하지 않으면 AuthorizationError.USER_PERMISSION_DENIED 오류가 발생합니다. 이 오류 유형에 관한 자세한 내용은 일반적인 오류를 검토하세요. 계정 액세스가 해결되는 방식에 관한 자세한 설명은 OAuth 액세스 모델 가이드를 참고하세요.

https://googleads.googleapis.com/v24/customers/1234567890/campaignBudgets:mutate

login-customer-id을 설정하는 것은 로그인 후 Google Ads UI에서 계정을 선택하거나 오른쪽 상단에서 프로필 이미지를 클릭하는 것과 같습니다. 이 헤더를 포함하지 않으면 기본적으로 운영 고객으로 설정됩니다.

linked-customer-id

이 헤더는 연결된 Google Ads 계정에 대해 조치를 취할 때 파트너 (예: 서드 파티 앱 분석 제공업체 또는 데이터 파트너)가 필요로 하며 사용합니다. 이 헤더는 제품 링크가 있는 Google Ads 계정의 고객 ID를 지정해야 합니다.

제품 링크를 기반으로 파트너가 Google Ads 계정에 API 호출을 해야 하는 시나리오를 생각해 보세요.

  • 광고주: API 호출에 의해 관리되거나 업데이트되는 Google Ads 계정입니다. 광고주 계정의 ID가 요청에 지정됩니다. REST에서는 customerId 경로 매개변수 (예: customers/1111111111/...)이고 gRPC에서는 요청의 customer_id 필드입니다.
  • 파트너: 파트너 계정 (예: 서드 파티 앱 분석 제공업체 또는 데이터 파트너)입니다.
  • 연결된 계정: 파트너와 제품 링크가 설정되어 파트너에게 광고주에 대한 액세스 권한을 부여하는 Google Ads 계정입니다.

파트너에 액세스할 수 있는 사용자가 광고주의 항목에 대해 작업을 수행하기 위해 API를 호출합니다 (예: 전환을 업로드하거나 사용자 목록을 관리). 연결된 계정은 광고주 자체일 수도 있고 광고주의 관리자 계정일 수도 있습니다.

요청 헤더는 다음과 같이 설정해야 합니다.

  • Authorization: 파트너에 액세스할 수 있는 사용자의 OAuth2 토큰입니다.
  • developer-token: API 애플리케이션의 개발자 토큰으로, 일반적으로 파트너와 연결됩니다.
  • login-customer-id: 파트너의 고객 ID입니다. 인증된 사용자가 이 계정에 액세스할 수 있어야 합니다.
  • linked-customer-id: 연결된 계정의 고객 ID입니다. 이 헤더는 이 요청의 승인이 연결된 계정과 파트너 간의 제품 연결에 의존함을 나타냅니다.

연결 시나리오에는 두 가지가 있습니다.

  • 광고주가 파트너와 직접 제품 링크를 보유한 경우 연결된 계정은 광고주이며 linked-customer-id는 광고주의 고객 ID로 설정해야 합니다.
  • 광고주가 파트너와 제품 링크가 있는 관리자 계정으로 관리되는 경우 연결된 계정은 관리자 계정이며 linked-customer-id은 관리자의 고객 ID로 설정해야 합니다.

예 1: 직접 링크

광고주 1111111111가 파트너 2222222222와 직접 연결되어 있고 API 호출이 customers/1111111111/...를 타겟팅하는 경우:

Authorization: Bearer YOUR_ACCESS_TOKEN
developer-token: YOUR_DEVELOPER_TOKEN
login-customer-id: 2222222222
linked-customer-id: 1111111111

예 2: 관리자 링크

광고주 1111111111가 관리자 3333333333에 의해 관리되고, 관리자 3333333333가 파트너 2222222222와 연결되어 있으며, API 호출이 customers/1111111111/...을 타겟팅하는 경우:

Authorization: Bearer YOUR_ACCESS_TOKEN
developer-token: YOUR_DEVELOPER_TOKEN
login-customer-id: 2222222222
linked-customer-id: 3333333333

응답 헤더

다음 헤더 (또는 grpc trailing-metadata)는 응답 본문과 함께 반환됩니다. 디버깅 목적으로 이러한 값을 로깅하는 것이 좋습니다.

request-id

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

이전
리소스 메타데이터