Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

Google Ads API 온보딩 가이드

이 가이드에서는 Google Ads API에 온보딩하고, 인증하고, 첫 번째 호출을 실행하는 엔드 투 엔드 프로세스를 자세히 설명합니다.

1. 필수 조건 및 계정 계층 구조

Google Ads API와 상호작용하기 전에 계정 계층 구조를 이해하고 올바른 최상위 계정 구조를 갖춰야 합니다.

관리자 계정 (MCC): Google Ads 관리자 계정 (이전 명칭: 내 고객센터)은 여러 고객 계정을 보고 관리하는 데 사용되는 기본 계정입니다. Google Ads API 개발자 토큰을 신청하려면 관리자 계정이 있어야 합니다.
고객 계정: 캠페인, 광고그룹, 광고가 생성되고 결제가 구성되는 표준 계정입니다.

작업 항목: 관리자 계정이 없는 경우 Google Ads 관리자 계정에서 만드세요.

2. 개발자 토큰 가져오기

개발자 토큰은 Google Ads API에서 애플리케이션을 고유하게 식별하고 호출 볼륨 액세스 등급을 제어합니다.

신청 단계

Google Ads 관리자 계정 에 로그인합니다.
도구 및 설정 > 설정 > API 센터 (또는 관리 > API 센터)로 이동합니다.
개발자 세부정보 양식을 작성하고 API 서비스 약관에 동의합니다.
신청서를 제출합니다.

액세스 수준

승인 대기 중: 새로 생성된 토큰은 즉시 '대기 중' 상태가 됩니다. 대기 중인 토큰을 사용하여 테스트 계정 에 즉시 연결할 수 있지만 프로덕션 계정에서는 작동하지 않습니다.
기본 액세스: 승인되면 하루에 최대 15,000개의 API 작업을 허용합니다.
표준 액세스: 필수 최소 기능 (RMF)을 충족하는 애플리케이션의 경우 일일 API 작업이 무제한입니다.

3. 테스트 계정 설정

프로덕션 계정에 대해 개발 및 테스트하면 원치 않는 광고비 지출 및 캠페인 수정이 발생할 위험이 있습니다. 테스트 계정에 대해 모든 활성 개발을 실행하는 것이 좋습니다.

테스트 관리자 계정 만들기

Google Ads 테스트 관리자 계정 생성 페이지로 이동합니다.
프로덕션 Google Ads 관리자 계정에 아직 연결되지 않은 Google 계정으로 로그인합니다.
설명 계정 이름 (예: MyCompany Test MCC)을 입력합니다.
기본 용도를 다른 사용자의 계정 관리로 선택합니다.
청구서 수신 국가, 시간대, 통화를 선택합니다. 저장하고 계속하기 를 클릭합니다.

테스트 고객 계정 만들기

테스트 관리자 계정이 생성되면 테스트 캠페인을 실행하기 위해 하위 고객 계정을 하나 이상 만들어야 합니다.

새로 생성된 테스트 관리자 계정 에 로그인합니다.
왼쪽 탐색 메뉴에서 계정을 클릭한 다음 하위 계정 설정 (또는 실적)을 선택합니다.
파란색 + (더하기) 버튼을 클릭하고 새 계정 만들기 를 선택합니다.
Google Ads 계정 을 선택합니다.
계정 이름 (예: Test Client Account A)을 입력합니다.
시간대와 통화를 선택한 다음 저장하고 계속하기 를 클릭합니다.
이 새 고객 계정의 10자리 고객 ID (예: 하이픈 없이 1234567890)를 적어둡니다.

테스트 계정의 중요 규칙

개발자 토큰 사용: 테스트 관리자 계정에서 개발자 토큰을 신청하지 마세요. 항상 프로덕션 관리자 계정 의 대기 중이거나 승인된 개발자 토큰을 사용하세요.
결제: 테스트 계정은 실제 광고를 게재하지 않으므로 실제 결제 정보를 입력할 필요가 없습니다.

4. Google Cloud 프로젝트 설정

모든 API 요청은 Google Ads API가 사용 설정된 Google Cloud 프로젝트를 사용하여 인증해야 합니다.

API 사용 설정 단계

Google Cloud 콘솔로 이동합니다.
새 프로젝트를 만들거나 기존 프로젝트를 선택합니다.
API 및 서비스 > 라이브러리 로 이동합니다.
Google Ads API 를 검색하고 사용 설정 을 클릭합니다.

가격 책정 및 결제

API 수수료 없음: Google Cloud 프로젝트를 만들고, Google Ads API를 사용 설정하고, OAuth 2.0 사용자 인증 정보를 생성하는 것은 100% 무료 입니다. Google은 Google Ads API 자체를 호출하거나 사용하는 데 수수료를 부과하지 않습니다.
기타 클라우드 리소스: 무료 등급 한도를 초과하여 애플리케이션을 호스팅하거나 광고 데이터를 저장하기 위해 청구 가능한 다른 Google Cloud 서비스 (예: Compute Engine, Cloud Run, BigQuery)를 적극적으로 사용하는 경우에만 Google Cloud 수수료가 발생합니다.

5. OAuth 2.0 인증 구성

Google Ads API는 OAuth 2.0을 사용하여 요청을 인증하고 승인합니다.

데스크톱 애플리케이션 흐름 단계

Google Cloud 프로젝트에서 API 및 서비스 > OAuth 동의 화면 으로 이동하여 동의 화면을 구성합니다. 애플리케이션이 테스트 상태인 동안 테스트 사용자 섹션에 이메일 주소를 추가하여 승인 중에 액세스 오류가 발생하지 않도록 합니다.
API 및 서비스 > 사용자 인증 정보 로 이동합니다.
사용자 인증 정보 만들기 > OAuth 클라이언트 ID 를 클릭합니다.
애플리케이션 유형을 데스크톱 앱 으로 선택합니다.
만들기를 클릭한 다음 OAuth 사용자 인증 정보 파일을 client_secret.json으로 다운로드하거나 Client ID과 Client Secret을 복사합니다.

갱신 토큰 생성

클라이언트 ID와 클라이언트 보안 비밀이 있으면 갱신 토큰을 생성해야 합니다. Google OAuth 2.0 Playground 또는 클라이언트 라이브러리 스크립트를 사용하여 이 작업을 실행할 수 있습니다.

방법 A: Google OAuth 2.0 Playground 사용

Google OAuth 2.0 Playground로 이동합니다.
오른쪽 상단에서 톱니바퀴 아이콘 (OAuth 2.0 구성) 을 클릭합니다.
자체 OAuth 사용자 인증 정보 사용 체크박스를 선택합니다.
OAuth2 Client ID와 Client Secret을 입력한 다음 닫기를 클릭합니다.
왼쪽의 1단계(API 선택 및 승인) 에서 '내 범위 입력' 필드에 Google Ads API 범위(https://www.googleapis.com/auth/adwords)를 입력합니다.
API 승인 을 클릭합니다. 메시지가 표시되면 Google Ads 관리자 계정 (또는 테스트 계정)에 액세스할 수 있는 Google 계정으로 로그인합니다.
동의 화면에서 계속 을 클릭합니다.
2단계 (토큰의 승인 코드 교환)에서 파란색 토큰의 승인 코드 교환 버튼을 클릭합니다.
Refresh token과 Access token이 응답 패널에 표시됩니다. Refresh token을 복사하여 저장합니다.

방법 B: 클라이언트 라이브러리 스크립트 사용 (Python 예시)

공식 Python 클라이언트 라이브러리는 사용자 인증 정보를 생성하는 기본 제공 도우미 스크립트를 제공합니다. 또는 Google Cloud 콘솔에서 client_secret.json을 다운로드하고 다음 독립형 Python 스크립트를 실행할 수 있습니다.

필요한 OAuth 라이브러리를 설치합니다.

pip install google-auth-oauthlib

client_secret.json과 동일한 디렉터리에 generate_refresh_token.py라는 스크립트를 만들고 실행합니다.

from google_auth_oauthlib.flow import InstalledAppFlow

CLIENT_SECRETS_FILE = "client_secret.json"
SCOPES = ["https://www.googleapis.com/auth/adwords"]

def main():
    flow = InstalledAppFlow.from_client_secrets_file(
        CLIENT_SECRETS_FILE, SCOPES
    )
    credentials = flow.run_local_server(port=0)
    
    print("\nAuthorization Successful!\n")
    print(f"Refresh Token: {credentials.refresh_token}")

if __name__ == "__main__":
    main()

6. 클라이언트 라이브러리 및 사용자 인증 정보 설정

Google은 gRPC 엔드포인트와의 인증, 직렬화, 통신을 처리하는 공식적으로 지원되는 클라이언트 라이브러리를 제공합니다.

지원 언어

Python: pip install google-ads
Java: Maven 또는 Gradle을 통해 사용 가능
PHP: composer require googleads/google-ads-php
.NET: Install-Package Google.Ads.GoogleAds
Ruby: gem install google-ads-googleads
Perl: cpanm Google::Ads::GoogleAds::Client

구성 파일 (`google-ads.yaml`)

사용자 인증 정보가 포함된 구성 파일을 만듭니다. 기본적으로 클라이언트 라이브러리의 초기화 메서드 (예: GoogleAdsClient.load_from_storage())는 다음 두 위치에서 google-ads.yaml을 자동으로 검색합니다.

스크립트가 실행되는 현재 작업 디렉터리.
사용자 홈 디렉터리 (Linux/macOS의 경우 ~, Windows의 경우 %HOMEPATH%).

파일을 맞춤 위치에 저장하는 경우 초기화 메서드에 경로를 명시적으로 전달할 수 있습니다 (예: load_from_storage("path/to/google-ads.yaml")).

developer_token: "INSERT_YOUR_DEVELOPER_TOKEN_HERE"
client_id: "INSERT_YOUR_OAUTH2_CLIENT_ID_HERE"
client_secret: "INSERT_YOUR_OAUTH2_CLIENT_SECRET_HERE"
refresh_token: "INSERT_YOUR_OAUTH2_REFRESH_TOKEN_HERE"
login_customer_id: "INSERT_YOUR_MANAGER_ACCOUNT_ID_HERE"

7. 첫 번째 API 호출하기

온보딩 설정을 확인하려면 빠른 시작 스크립트를 실행하여 테스트 계정에서 기존 캠페인을 가져옵니다.

Python 스크립트 예시 (`quickstart.py`)

import sys
from google.ads.googleads.client import GoogleAdsClient
from google.ads.googleads.errors import GoogleAdsException

def main(client, customer_id):
    ga_service = client.get_service("GoogleAdsService")
    query = """
        SELECT
          campaign.id,
          campaign.name
        FROM campaign
        ORDER BY campaign.id
    """
    
    # Issues a search request
    stream = ga_service.search_stream(customer_id=customer_id, query=query)
    for batch in stream:
        for row in batch.results:
            print(
                f"Campaign with ID {row.campaign.id} and name "
                f"'{row.campaign.name}' was found."
            )

if __name__ == "__main__":
    # Initialize client from google-ads.yaml
    # By default, load_from_storage() searches for 'google-ads.yaml' in the
    # current working directory or the user's home directory (~). You can
    # also pass an explicit path: load_from_storage("path/to/google-ads.yaml")
    try:
        googleads_client = GoogleAdsClient.load_from_storage()
        # Replace with your test client account ID (without hyphens) from
        # Section 3, NOT your manager account ID (which belongs in
        # google-ads.yaml).
        test_customer_id = "1234567890" 
        main(googleads_client, test_customer_id)
    except GoogleAdsException as ex:
        print(
            f"Request failed with status {ex.error.code().name} and "
            f"includes the following errors:"
        )
        for error in ex.failure.errors:
            print(f"\tError with message '{error.message}'.")
            if error.location:
                for field_path_element in error.location.field_path_elements:
                    print(f"\t\tOn field: {field_path_element.field_name}")
        sys.exit(1)

8. 권장사항 및 리소스

로깅: Google에 지원을 요청할 때 필수적인 요청 및 응답 ID (request-id)를 캡처하려면 클라이언트 라이브러리에서 상세 로깅을 사용 설정하세요.
오류 처리: GoogleAdsException에 대한 강력한 오류 처리를 구현하고 특히 속도 제한(RESOURCE_TEMPORARILY_EXHAUSTED)을 관리합니다.
공식 문서: Google Ads API 개발자 문서
클라이언트 라이브러리 및 코드 샘플: GitHub Google Ads 저장소

소개

빠른 시작

Google Ads API 온보딩 가이드 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.