Panduan aktivasi Google Ads API

Panduan ini menjelaskan proses lengkap untuk orientasi, autentikasi, dan melakukan panggilan pertama ke Google Ads API.

1. Prasyarat dan hierarki akun

Sebelum berinteraksi dengan Google Ads API, Anda harus memahami hierarki akun dan memiliki struktur akun tingkat atas yang benar.

  • Akun Pengelola (MCC): Akun Pengelola Google Ads (sebelumnya Pusat Klien Saya) adalah akun utama yang digunakan untuk melihat dan mengelola beberapa akun klien. Anda harus memiliki Akun Pengelola untuk mengajukan permohonan token developer Google Ads API.
  • Akun Klien: Akun standar tempat kampanye, grup iklan, dan iklan dibuat serta penagihan dikonfigurasi.

Item Tindakan: Jika Anda tidak memiliki Akun Pengelola, buat akun di Akun Pengelola Google Ads.

2. Mendapatkan token developer

Token developer mengidentifikasi aplikasi Anda secara unik ke Google Ads API dan mengontrol tingkat akses volume panggilan Anda.

Langkah-langkah untuk mendaftar

  1. Login ke Akun Pengelola Google Ads.
  2. Buka Alat dan setelan > Penyiapan > Pusat API (atau Admin > Pusat API).
  3. Isi formulir detail developer dan setujui Persyaratan Layanan API.
  4. Kirim permohonan Anda.

Tingkat akses

  • Menunggu Persetujuan: Token yang baru dibuat akan langsung menerima status "Menunggu". Anda dapat menggunakan token yang menunggu persetujuan untuk segera terhubung ke Akun Pengujian, tetapi token tersebut tidak akan berfungsi untuk akun produksi.
  • Akses Dasar: Memungkinkan hingga 15.000 operasi API per hari setelah disetujui.
  • Akses Standar: Operasi API harian tanpa batas untuk aplikasi yang memenuhi Fungsi Minimum yang Diperlukan (RMF).

3. Menyiapkan akun pengujian

Mengembangkan dan menguji akun produksi berisiko menyebabkan pembelanjaan iklan dan modifikasi kampanye yang tidak diinginkan. Sebaiknya lakukan semua pengembangan aktif terhadap akun pengujian.

Membuat akun pengelola pengujian

  1. Buka halaman pembuatan akun Pengelola Pengujian Google Ads.
  2. Login dengan Akun Google yang belum ditautkan ke Akun Pengelola Google Ads produksi Anda.
  3. Masukkan nama akun deskriptif (misalnya, MyCompany Test MCC).
  4. Pilih penggunaan utama sebagai Kelola akun orang lain.
  5. Pilih negara penagihan, zona waktu, dan mata uang Anda. Klik Simpan dan lanjutkan.

Membuat akun klien pengujian

Setelah Akun Pengelola Pengujian dibuat, Anda harus membuat setidaknya satu akun klien turunan untuk menjalankan kampanye pengujian.

  1. Login ke Akun Pengelola Pengujian yang baru dibuat.
  2. Dari menu navigasi kiri, klik Akun, lalu pilih Setelan sub-akun (atau Performa).
  3. Klik tombol + (plus) biru, lalu pilih Buat akun baru.
  4. Pilih Akun Google Ads.
  5. Masukkan nama akun (misalnya, Test Client Account A).
  6. Pilih zona waktu dan mata uang, lalu klik Simpan dan lanjutkan.
  7. Catat ID Pelanggan 10 digit (misalnya, 1234567890 tanpa tanda hubung) dari akun klien baru ini.

Aturan penting untuk akun pengujian

  • Penggunaan Token Developer: Jangan mengajukan permohonan token developer dari Akun Pengelola Pengujian Anda. Selalu gunakan token developer yang menunggu persetujuan atau disetujui dari Akun Pengelola Produksi Anda.
  • Penagihan: Akun pengujian tidak menayangkan iklan yang sebenarnya, jadi Anda tidak perlu memasukkan informasi penagihan yang sebenarnya.

4. Penyiapan project Google Cloud

Semua permintaan API harus diautentikasi menggunakan project Google Cloud dengan Google Ads API yang diaktifkan.

Langkah-langkah untuk mengaktifkan API

  1. Buka Konsol Google Cloud.
  2. Buat project baru atau pilih project yang sudah ada.
  3. Buka API & Layanan > Library.
  4. Telusuri Google Ads API dan klik Aktifkan.

Penetapan harga dan penagihan

  • Tidak Ada Biaya API: Membuat project Google Cloud, mengaktifkan Google Ads API, dan membuat kredensial OAuth 2.0 100% gratis. Google tidak mengenakan biaya apa pun untuk memanggil atau menggunakan Google Ads API itu sendiri.
  • Resource Cloud Lainnya: Anda hanya akan dikenai biaya Google Cloud jika aktif menggunakan layanan Google Cloud lain yang dapat ditagih (seperti Compute Engine, Cloud Run, atau BigQuery) di luar batas Paket Gratisnya untuk menghosting aplikasi atau menyimpan data iklan Anda.

5. Konfigurasi autentikasi OAuth 2.0

Google Ads API menggunakan OAuth 2.0 untuk mengautentikasi dan mengotorisasi permintaan.

Langkah-langkah untuk alur aplikasi desktop

  1. Di project Google Cloud Anda, buka API & Layanan > Layar izin OAuth dan konfigurasi layar izin. Tambahkan alamat email Anda ke bagian Pengguna pengujian saat aplikasi berstatus Pengujian untuk mencegah error akses selama otorisasi.
  2. Buka API & Layanan > Kredensial.
  3. Klik Buat Kredensial > Client ID OAuth.
  4. Pilih jenis aplikasi sebagai Aplikasi desktop.
  5. Klik Buat, lalu download file kredensial OAuth sebagai client_secret.json (atau salin Client ID dan Client Secret).

Membuat token refresh

Setelah memiliki Client ID dan Client Secret, Anda harus membuat Token Refresh. Anda dapat melakukannya menggunakan Google OAuth 2.0 Playground atau skrip library klien.

Metode A: Menggunakan Google OAuth 2.0 Playground

  1. Buka Google OAuth 2.0 Playground.
  2. Klik ikon Roda Gigi (konfigurasi OAuth 2.0) di pojok kanan atas.
  3. Centang kotak Gunakan kredensial OAuth Anda.
  4. Masukkan Client ID dan Client Secret OAuth2 Anda, lalu klik Tutup.
  5. Di Langkah 1 (Pilih & otorisasi API) di sebelah kiri, masukkan cakupan Google Ads API di kolom "Masukkan cakupan Anda": https://www.googleapis.com/auth/adwords
  6. Klik Authorize APIs. Jika diminta, login dengan Akun Google yang memiliki akses ke Akun Pengelola Google Ads (atau Akun Pengujian) Anda.
  7. Klik Lanjutkan di layar izin.
  8. Di Langkah 2 (Tukar kode otorisasi untuk token), klik tombol biru Tukar kode otorisasi untuk token.
  9. Refresh token dan Access token Anda akan ditampilkan di panel respons. Salin dan simpan Refresh token.

Metode B: Menggunakan skrip library klien (contoh Python)

Library klien Python resmi menyediakan skrip helper bawaan untuk membuat kredensial. Atau, Anda dapat mendownload client_secret.json dari Konsol Google Cloud dan menjalankan skrip Python mandiri berikut:

  1. Instal library OAuth yang diperlukan:
pip install google-auth-oauthlib
  1. Buat skrip bernama generate_refresh_token.py di direktori yang sama dengan client_secret.json dan eksekusi:
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. Penyiapan library klien dan kredensial

Google menyediakan library klien yang didukung secara resmi yang menangani autentikasi, serialisasi, dan komunikasi dengan endpoint gRPC.

Bahasa yang didukung

  • Python: pip install google-ads
  • Java: Tersedia melalui Maven atau 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

File konfigurasi (google-ads.yaml)

Buat file konfigurasi yang berisi kredensial Anda. Secara default, metode inisialisasi library klien (misalnya, GoogleAdsClient.load_from_storage()) akan otomatis menelusuri google-ads.yaml di dua lokasi:

  1. Direktori kerja saat ini tempat skrip Anda dijalankan.
  2. Direktori beranda pengguna Anda (~ di Linux/macOS atau %HOMEPATH% di Windows).

Jika menyimpan file di lokasi kustom, Anda dapat secara eksplisit meneruskan jalur ke metode inisialisasi (misalnya, 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. Melakukan panggilan API pertama

Untuk memverifikasi penyiapan orientasi, jalankan skrip panduan memulai untuk mengambil kampanye yang ada dari akun pengujian Anda.

Contoh skrip 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. Praktik terbaik dan referensi

  • Logging: Aktifkan logging mendetail di library klien Anda untuk mengambil ID permintaan dan respons (request-id), yang penting saat meminta dukungan dari Google.
  • Penanganan Error: Terapkan penanganan error yang andal untuk GoogleAdsException, khususnya mengelola batas frekuensi (RESOURCE_TEMPORARILY_EXHAUSTED).
  • Dokumentasi Resmi: Dokumen Developer Google Ads API
  • Library Klien & Contoh Kode: Repositori Google Ads GitHub
Sebelumnya
Pengantar
Berikutnya
Panduan memulai