API 호출 구조

이 가이드에서는 모든 API 호출의 일반적인 구조를 설명합니다.

클라이언트 라이브러리를 사용하여 API와 상호작용하는 경우 기본 요청 세부정보에 대해 걱정할 필요가 없습니다. 하지만 테스트와 디버깅을 할 때 이러한 도구에 관해 약간 알고 있으면 도움이 될 수 있습니다.

Google Ads API는 REST API가 포함된 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를 만듭니다.

  • 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는 이 요청을 고유하게 식별하는 문자열입니다.

이전
리소스 메타데이터