Konfigurasi

Anda dapat mengonfigurasi library klien Python menggunakan file YAML, variabel lingkungan, string YAML, atau dict.

Konfigurasi autentikasi

Ada beberapa cara untuk mengelola kredensial OAuth yang diperlukan untuk mengakses Google Ads API. Pendekatan yang Anda pilih akan memengaruhi kolom konfigurasi yang Anda gunakan. Untuk mengetahui informasi selengkapnya, lihat panduan autentikasi.

Konfigurasi menggunakan file YAML

Anda dapat menentukan file YAML yang akan digunakan saat melakukan inisialisasi klien yang berisi informasi yang diperlukan untuk membuat permintaan ke Google Ads API. File ini diakses saat klien diinisialisasi menggunakan metode load_from_storage. Cara termudah untuk membuat file ini adalah dengan menyalin contoh google-ads.yaml dari repositori GitHub dan mengubahnya untuk menyertakan kredensial Anda, termasuk token refresh, client ID, dan rahasia klien.

Jika Anda tidak memberikan jalur, library akan mencari file di direktori $HOME Anda:

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage()

Untuk menentukan lokasi file google-ads.yaml, Anda dapat meneruskan jalur sebagai string ke metode saat memanggilnya:

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage("path/to/google-ads.yaml")

Anda juga dapat menentukan jalur dengan menentukan variabel lingkungan tertentu:

import os
from google.ads.googleads.client import GoogleAdsClient

os.environ["GOOGLE_ADS_CONFIGURATION_FILE_PATH"] = "path/to/google-ads.yaml"
client = GoogleAdsClient.load_from_storage()

Jika kedua nilai diberikan—jalur diteruskan ke metode, dan variabel lingkungan ada—library akan memprioritaskan jalur yang diteruskan ke metode.

Konfigurasi menggunakan variabel lingkungan

Anda dapat menyimpan semua konfigurasi klien sebagai variabel lingkungan, yang dibaca saat menggunakan metode load_from_env klien. Variabel lingkungan harus memiliki nama yang sama dengan yang ditentukan dalam file google-ads.yaml, tetapi harus menggunakan huruf besar dan diawali dengan namespace GOOGLE_ADS_. Misalnya, client_id harus disimpan sebagai GOOGLE_ADS_CLIENT_ID.

Variabel lingkungan biasanya ditentukan dalam file konfigurasi bash seperti file .bashrc atau .bash_profile yang terletak di direktori $HOME. Variabel lingkungan juga dapat ditentukan menggunakan command line.

Berikut beberapa langkah dasar untuk menentukan variabel lingkungan menggunakan file .bashrc di terminal:

# Append the line "export GOOGLE_ADS_CLIENT_ID=1234567890" to
# the bottom of your .bashrc file.
echo "export GOOGLE_ADS_CLIENT_ID=1234567890" >> ~/.bashrc
# Update your bash environment to use the most recently updated
# version of your .bashrc file.
source ~/.bashrc

Variabel lingkungan juga dapat ditetapkan di instance terminal Anda langsung dari command line:

export GOOGLE_ADS_CLIENT_ID=1234567890
echo $GOOGLE_ADS_CLIENT_ID

Metode load_from_env memuat data konfigurasi dari atribut environ pada modul os bawaan Python. Contoh: os.environ["GOOGLE_ADS_CLIENT_ID"]

Berikut contoh cara melakukan inisialisasi instance klien dengan konfigurasi dari variabel lingkungan:

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_env()

Untuk mengonfigurasi logging melalui variabel lingkungan, nilai konfigurasi harus berupa objek JSON yang cocok dengan struktur kunci YAML dalam file konfigurasi google-ads.yaml contoh.

Berikut contoh cara menetapkannya menggunakan file .bashrc:

export GOOGLE_ADS_LOGGING='{
  "version": 1,
  "disable_existing_loggers": false,
  "formatters": {
    "default_fmt": {
      "format": "[%(asctime)s - %(levelname)s] %(message).5000s",
      "datefmt": "%Y-%m-%d %H:%M:%S"
    }
  },
  "handlers": {
    "default_handler": {
      "class": "logging.StreamHandler",
      "formatter": "default_fmt"
    }
  },
  "loggers": {
    "": {
      "handlers": ["default_handler"],
      "level": "INFO"
    }
  }
}'

Poin penting: Jika variabel lingkungan GOOGLE_ADS_CONFIGURATION_FILE_PATH ditetapkan saat metode load_from_env dipanggil, nilai konfigurasi akan diambil dari file google-ads.yaml yang terletak di jalur yang ditentukan, bukan dari variabel lingkungan yang dijelaskan sebelumnya.

Konfigurasi menggunakan string YAML

Jika telah membaca file YAML ke dalam memori, Anda dapat memberikannya langsung ke klien saat inisialisasi. Untuk melakukannya, gunakan metode load_from_string:

from google.ads.googleads.client import GoogleAdsClient

with open("/path/to/yaml", "r", encoding="utf-8") as handle:
    yaml_content = handle.read()

client = GoogleAdsClient.load_from_string(yaml_content)

Konfigurasi menggunakan dict

Anda dapat meneruskan dict langsung ke metode load_from_dict. Contoh:

from google.ads.googleads.client import GoogleAdsClient

credentials = {
    "refresh_token": "YOUR_REFRESH_TOKEN",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "use_proto_plus": True,
}

client = GoogleAdsClient.load_from_dict(credentials)

Kolom konfigurasi

Konfigurasi library klien mendukung kolom berikut.

Autentikasi

Gunakan hanya salah satu grup kolom ini, bergantung pada pendekatan autentikasi yang Anda gunakan:

  • Pengguna tunggal dengan kredensial default aplikasi (dokumentasi)
    • use_application_default_credentials: Apakah library harus menggunakan kredensial default aplikasi (ADC) untuk autentikasi (didukung di google-ads v28.3.0 dan yang lebih baru).
  • Pengguna tunggal dengan token OAuth (dokumentasi)
    • client_id: Client ID OAuth Anda.
    • client_secret: Rahasia klien OAuth Anda.
    • refresh_token: Token refresh OAuth Anda.
  • Akun layanan (dokumentasi)
    • json_key_file_path: Jalur ke file kunci pribadi lokal. Jalur ini digunakan untuk autentikasi menggunakan akun layanan.
    • impersonated_email: Alamat email opsional akun yang akan di-impersonate saat menggunakan delegasi seluruh domain Google Workspace.

Perilaku library

Kolom ini menentukan perilaku library:

Konfigurasi tingkat permintaan

  • linked_customer_id: Lihat dokumentasi linked-customer-id.
  • login_customer_id: Lihat dokumentasi login-customer-id.
  • endpoint: Alamat endpoint Google Ads API alternatif opsional.
  • ads_assistant: ID opsional untuk header Asisten Google Ads API.

Variabel lingkungan

Untuk mengonfigurasi library menggunakan variabel lingkungan, gunakan hal berikut:

  • GOOGLE_ADS_ADS_ASSISTANT
  • GOOGLE_ADS_CLIENT_ID
  • GOOGLE_ADS_CLIENT_SECRET
  • GOOGLE_ADS_CONFIGURATION_FILE_PATH
  • GOOGLE_ADS_ENDPOINT
  • GOOGLE_ADS_HTTP_PROXY
  • GOOGLE_ADS_IMPERSONATED_EMAIL
  • GOOGLE_ADS_JSON_KEY_FILE_PATH
  • GOOGLE_ADS_LINKED_CUSTOMER_ID
  • GOOGLE_ADS_LOGIN_CUSTOMER_ID
  • GOOGLE_ADS_LOGGING
  • GOOGLE_ADS_REFRESH_TOKEN
  • GOOGLE_ADS_USE_PROTO_PLUS
  • GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS (didukung di v28.3.0 dan yang lebih baru)

Konfigurasi log

Kolom log, yang merupakan kolom di bawah kolom konfigurasi logging, berasal langsung dari modul bawaan logging.config karena library meneruskan semua kolom di bawah namespace logging langsung ke metode logging.config.dictConfig. Lihat panduan logging untuk mengetahui detail selengkapnya.

  • version: Nilai bilangan bulat yang mewakili versi skema.
  • disable_existing_loggers: Apakah logger yang dikonfigurasi di tempat lain dalam aplikasi harus dinonaktifkan.
  • formatters: Kamus yang menentukan berbagai jenis pemformat.
  • handlers: Kamus yang menentukan berbagai pengendali, yang mengontrol tempat log ditulis dan pemformat mana yang harus digunakan.
  • loggers: Kamus yang menentukan berbagai jenis logger, yang mencakup pengendali dan tingkat log.