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를 만듭니다.

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

이전
리소스 메타데이터