API 호출 구조

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

클라이언트 라이브러리를 사용하여 API와 상호작용하는 경우 기본 요청 세부정보에 대해 신경 써야 합니다 하지만 이것에 대해 조금 알면 테스트와 디버깅에 도움이 될 수 있습니다.

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

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

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

를 통해 개인정보처리방침을 정의할 수 있습니다.

참고: 이 가이드에서는 두 플랫폼의 공통된 구조와 전송 헤더를 설명합니다. gRPC 및 REST 프로토콜입니다.

리소스 이름

API에서 대부분의 객체는 리소스 이름 문자열로 식별됩니다. 이러한 문자열은 REST 인터페이스를 사용할 때 URL로도 사용됩니다. REST 보기 리소스 이름을 있습니다.

핵심사항: 리소스 문서를 확인하세요. 을 사용합니다 (resource_name). 다른 서비스에도 동일한 형식이 사용됩니다.

복합 ID

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

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

• AdGroupId/123 + ~ + AdGroupAdId/45678 = 복합 광고 123~45678의 그룹 광고 ID입니다.

요청 헤더

HTTP 헤더 (또는 grpc)는 메타데이터)입니다. 다음과 같습니다.

승인

OAuth2 액세스 토큰을 다음과 같은 형식으로 포함해야 합니다. Authorization: Bearer YOUR_ACCESS_TOKEN는 고객 또는 광고주를 직접 대리하는 관리자 계정 직접 관리할 수 있습니다. 액세스 토큰을 가져오는 방법 OAuth2 가이드에서 확인할 수 있습니다. 액세스 토큰은 받은 후 1시간 동안 유효합니다. 언제 액세스 토큰을 새로고침하여 새 토큰을 가져옵니다. 참고: 클라이언트 라이브러리는 자동으로 만료된 토큰을 새로고침합니다.

developer-token

개발자 토큰은 개발자 토큰을 고유하게 식별하는 22자 Google Ads API 개발자입니다. 개발자 토큰 문자열의 예는 다음과 같습니다. ABcdeFGH93KL-NOPQ_STUv 개발자 토큰은 developer-token : ABcdeFGH93KL-NOPQ_STUv 형태입니다.

login-customer-id

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

핵심 용어: 운영 중인 고객은 요청 페이로드의 고객 ID입니다. 예를 들어 CampaignBudgetService 요청이 1234567890입니다.

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

login-customer-id를 설정하는 것은 로그인하거나 상단의 프로필 이미지를 클릭한 후 표시되는 Google Ads UI 맞습니다. 이 헤더를 포함하지 않으면 기본적으로 operating 고객을 선택합니다.

참고: 다음을 사용하여 직접 액세스할 수 있는 계정 목록을 가져올 수 있습니다. 사용자 인증 정보를 발급하여 CustomerService.ListAccessibleCustomers 합니다. 이 요청 유형에는 login-customer-id가 필요하지 않습니다. 반환되는 고객 목록에 영향을 미치지 않습니다.

linked-customer-id

이 헤더는 타사 앱 분석 서비스 제공업체에서만 연결된 Google Ads에 전환 업로드 계정을 선택합니다.

A 계정의 사용자가 읽기 및 수정 액세스 권한을 제공하는 경우를 생각해 보세요. 을(를) 통해 B 계정에 ThirdPartyAppAnalyticsLink 연결되면 B 계정의 사용자가 A 계정에 대해 API 호출을 할 수 있습니다. 링크에서 제공하는 권한에 따라 달라질 수 있습니다. 이 경우 API 호출은 A 계정에 대한 권한은 B 계정에 대한 타사 링크에 의해 결정됩니다. 다른 API 호출에서 사용되는 관리자-계정 관계가 아닙니다.

서드 파티 앱 분석 서비스 제공업체는 다음과 같이 API를 호출합니다.

• linked-customer-id: 데이터를 업로드하는 서드 파티 앱 애널리틱스 계정입니다. 데이터 (계정 B)
• customer-id: 데이터가 업로드되는 Google Ads 계정 (계정 A).
• login-customer-id 및 Authorization 헤더: B 계정에 액세스할 수 있는 사용자를 식별합니다.

응답 헤더

다음 헤더 (또는 gRPC 후행-메타데이터) 응답 본문과 함께 반환됩니다. 이러한 항목은 값을 포함하는 것이 좋습니다.

요청 ID

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