Google Ads API 개발자 어시스턴트 설치 및 사용

Google Ads API 개발자 어시스턴트는 AI 코딩 환경에 직접 심층적인 Google Ads API 도메인 전문 지식을 제공합니다. 자연어 프롬프트와 기본 제공 슬래시 명령어를 사용하여 쿼리를 구성하고, 클라이언트 라이브러리 코드를 생성하고, 읽기 전용 API 호출을 실행하고, 임시 보고서를 스트리밍하고, 통합 문제를 해결합니다.

어시스턴트는 모듈식 플러그인으로 Google Antigravity 및 Claude Code 에이전트 프레임워크 (v4.0.0)를 위해 빌드됩니다. 지속적인 컨텍스트, 강력한 안전 경계, 자동화된 유효성 검사 파이프라인을 유지하기 위해 AGENTS.md 및 CLAUDE.md 계약, 기본 제공 슬래시 명령어, 전문 도메인 기술을 사용합니다.

기본 요건

시작하기 전에 다음과 같은 항목이 필요합니다.

  1. Google Ads API 액세스:

    • Google Ads API 개발자 토큰
    • 개발자 토큰, OAuth 2.0 사용자 인증 정보, 고객 ID로 구성된 Google Ads 구성 파일 (예: Python의 경우 google-ads.yaml)이 홈 디렉터리에 있습니다. 클라이언트 라이브러리 구성 가이드 를 참고하세요.
    • Google Ads API 개념 및 인증에 대한 숙련도

  2. 소프트웨어:

    • Python 3.10 이상이 설치되어 있고 시스템 PATH에 있습니다. Python은 생성된 코드를 실행하고 로컬 유효성 검사 사이드카를 실행하는 데 사용됩니다.
    • 호스트 Agent Platform:
    • Git 시스템 PATH에 설치되어 있습니다.

시작하기

다음 단계에 따라 저장소를 클론하고, 플랫폼별 설치 스크립트를 실행하고, 사용자 인증 정보를 구성하고, 플러그인을 활성화합니다.

1. 저장소 복제

저장소를 로컬 머신에 클론하고 프로젝트 디렉터리로 이동합니다.

git clone https://github.com/googleads/google-ads-api-developer-assistant
cd google-ads-api-developer-assistant

2. 설치 스크립트 실행

타겟 플랫폼의 설치 스크립트를 실행합니다. 기본적으로 Python 클라이언트 라이브러리가 포함됩니다. 선택적으로 추가 클라이언트 라이브러리 (--php, --ruby, --java, --dotnet 또는 --all)를 포함할 수 있습니다.

Antigravity

Linux / macOS: ```bash ./install.sh agy

또는 추가 클라이언트 라이브러리 포함:

./install.sh agy --java --dotnet ```

Windows (PowerShell): ```powershell .\install.ps1 -Type agy

또는 추가 클라이언트 라이브러리 포함:

.\install.ps1 -Type agy -Java -Dotnet ```

Claude Code

Linux / macOS: ```bash ./install.sh claude

또는 추가 클라이언트 라이브러리 포함:

./install.sh claude --php --dotnet ```

Windows (PowerShell): ```powershell .\install.ps1 -Type claude

또는 추가 클라이언트 라이브러리 포함:

.\install.ps1 -Type claude -Php -Dotnet ```

3. 사용자 인증 정보 구성

API 구성 파일 (예: google-ads.yaml, google_ads_php.ini 또는 google_ads_config.rb)이 $HOME 디렉터리에 있는지 확인합니다.

(선택사항) 기본 고객 ID를 구성하려면 config/customer_id.txt (예: 1234567890)에 고객 ID 번호를 직접 입력합니다. config/api_version.txt에서 활성 API 버전을 검사하거나 고정할 수도 있습니다.

4. 플러그인 활성화

  • Antigravity: Antigravity / agy 호스트 세션을 다시 시작하여 플러그인을 로드합니다.
  • Claude Code: 활성 Claude Code 세션에서 /reload-plugins를 실행하거나 claude를 다시 시작합니다.

5. 어시스턴트와 상호작용

터미널에서 직접 자연어 프롬프트 또는 전용 슬래시 명령어를 사용하여 어시스턴트와 상호작용할 수 있습니다.

주요 특징

  • 자연어 Q&A 및 개념 안내: Google Ads API 기능, 아키텍처 규칙 또는 특정 리소스에 관해 질문합니다. 어시스턴트는 일반 LLM 학습에만 의존하는 것이 아니라 공식 API 정의를 기반으로 응답합니다.

    • "사용 가능한 캠페인 유형은 무엇인가요?"
    • "GAQL에서 날짜별로 필터링하려면 어떻게 해야 하나요?"
    • " click_view와 impression_view의 차이점을 설명해 주세요."
    • "공유 집합이란 무엇이며 어떻게 사용하나요?"
    • Claude Code 슬래시 명령어: /explain, /step-by-step, /assistant-tutorial

  • 기반 클라이언트 라이브러리 코드 생성: 공식 Google Ads 클라이언트 라이브러리 (Python, Java, PHP, .NET, Ruby)를 사용하여 테스트된 관용적 코드를 생성합니다.

    • "지난 30일 동안 전환수가 가장 많은 캠페인을 보여주세요."
    • "고객 123-456-7890의 사용 설정된 모든 광고 그룹 이름을 가져옵니다."
    • "실적 최대화 캠페인을 만드는 코드를 작성합니다." 생성된 코드는 saved/code/ 디렉터리에 저장됩니다.

  • 프로그래매틱 GAQL 쿼리 유효성 검사: 실행 전에 API 메타데이터, 필드 호환성, 노출수 0 규칙, 날짜 세분화를 기준으로 복잡한 쿼리를 자동으로 드라이 실행하고 검증합니다.

    • Claude Code: /validate-gaql
    • 자연어: validate: SELECT campaign.id FROM campaign

  • 객체 및 Protobuf 스키마 검사: 원격 메타데이터 오버헤드 없이 활성 API 버전의 리소스 구조, 중첩된 필드, 데이터 유형, enum 값을 동적으로 검사합니다.

    • Claude Code: /inspect-object <resource_or_enum>
    • 자연어: "캠페인 리소스 검사"

  • 임시 실시간 보고 및 CSV 내보내기: 일반 영어로 실적 데이터를 요청합니다. 어시스턴트는 계정을 기준으로 GAQL 쿼리를 직접 구성, 검증, 실행하여 실시간으로 형식화된 테이블을 터미널로 스트리밍합니다.

    • "고객 123-456-7890의 지난달 비용 기준 상위 5개 키워드를 보여주세요."
    • "결과를 CSV 파일로 저장합니다." (saved/csv/로 내보내기)

  • 직접 API 실행 및 변경 안전성: 관리형 가상 환경 내에서 생성된 읽기 전용 스크립트를 직접 실행합니다.

    • 어시스턴트에게 "코드 실행" 또는 "스크립트 실행"이라고 말하기만 하면 됩니다.
    • 변경 안전성: 안전을 위해 변경 작업 (생성, 업데이트, 삭제)은 saved/code/에 생성되지만 어시스턴트가 직접 실행하지는 않습니다. 어시스턴트 외부에서 수동으로 검토하고 실행합니다.

  • 고급 진단 및 전환 문제 해결: 오프라인 전환 업로드 실패를 조사하고, 업로드 파일을 사전 검증하고, 자세한 진단 보고서를 생성합니다.

    • Claude Code: /troubleshoot-conversions
    • 자연어: "고객 123-456-7890의 전환 문제 해결" (보고서는 saved/data/에 저장됨)

  • MCC 계정 계층 구조 매핑: 하위 계정 고객 ID를 가져오고 관리자 계정에서 계정 계층 구조를 매핑합니다.

    • Claude Code: /get-cids <manager_cid>
    • 자연어: "관리자 123-456-7890의 모든 클라이언트 고객 ID 가져오기"

  • 실적 최대화 등록정보 필터 및 제외: 애셋 그룹의 제품 파티션 트리 및 웹페이지 URL 제외를 생성합니다.

    • Claude Code: /pmax-filter
    • 자연어: "실적 최대화 캠페인의 웹페이지 제외 필터 만들기"

  • 추가 코드베이스 컨텍스트: 애플리케이션 로직과 커스텀 아키텍처를 어시스턴트의 추론에 등록합니다.

    • Linux / macOS: bash ./update.sh agy --context_dir /path/to/your/codebase # Or for Claude Code: ./update.sh claude --context_dir /path/to/your/codebase
    • Windows (PowerShell): powershell .\update.ps1 -Type agy -ContextDir C:\path\to\your\codebase

Claude Code 슬래시 명령어 참조

Claude Code를 사용하는 경우 다음 기본 제공 슬래시 명령어를 사용할 수 있습니다. Google Antigravity에서는 자연어 프롬프트 또는 validate_gaql 및 inspect_object와 같은 스킬 도구 이름을 사용하여 이러한 동일한 기능을 호출합니다. 이는 주요 특징에 설명되어 있습니다.

슬래시 명령어 목적 예
/validate-gaql GAQL 구문, 호환성, 규칙을 검증합니다. /validate-gaql
/inspect-object Protobuf 필드, 유형, enum을 검사합니다. /inspect-object Campaign
/get-cids MCC 계층 구조 및 클라이언트 CID를 확인합니다. /get-cids 1234567890
/troubleshoot-conversions 오프라인 전환 업로드 진단을 실행합니다. /troubleshoot-conversions
/pmax-filter 실적 최대화 등록정보 필터 및 제외를 생성합니다. /pmax-filter
/explain 4단계 구조화된 설명을 제공합니다. /explain shared set
/step-by-step 다단계 작업 실행 계획을 공식화합니다. /step-by-step upload conversions
/assistant-tutorial 대화형 11단계 안내를 실행합니다. /assistant-tutorial

유지보수 및 업데이트

저장소, 플러그인 설치, 클라이언트 라이브러리를 업데이트하려면 다음 단계를 따르세요.

Antigravity

Linux / macOS: bash ./update.sh agy # Update Antigravity plugin ./update.sh agy --all # Include all client libraries

Windows (PowerShell): powershell .\update.ps1 -Type agy .\update.ps1 -Type agy -All

Claude Code

Linux / macOS: bash ./update.sh claude # Update Claude Code plugin ./update.sh claude --all # Include all client libraries

Windows (PowerShell): powershell .\update.ps1 -Type claude .\update.ps1 -Type claude -All

제거

어시스턴트 플러그인을 제거하려면 다음 단계를 따르세요.

Antigravity

Linux / macOS: bash rm -rf ~/.gemini/config/plugins/google-ads-api-developer-assistant

Windows (PowerShell): powershell Remove-Item -Recurse -Force "$HOME\.gemini\config\plugins\google-ads-api-developer-assistant"

그런 다음 Antigravity 호스트 세션을 다시 시작합니다.

Claude Code

활성 Claude Code 세션에서 다음을 실행합니다. none /plugin uninstall google-ads-api-developer-assistant@google-ads-assistant-local

또는 터미널에서 다음을 실행합니다. bash claude plugin uninstall google-ads-api-developer-assistant@google-ads-assistant-local

(선택사항) 로컬 마켓플레이스 레지스트리를 삭제합니다. bash claude plugin marketplace remove google-ads-assistant-local

커뮤니티 및 지원

참여 가이드라인

참여를 환영합니다. 가이드라인은 GitHub 저장소의 CONTRIBUTING.md 파일을 참고하세요.

이전
Google Ads API 개발자 어시스턴트란 무엇인가요?