Autentikasi dan otorisasi

Seperti Google API lainnya, Google Ads API menggunakan protokol OAuth 2.0 untuk autentikasi dan otorisasi. OAuth 2.0 memungkinkan aplikasi klien Google Ads API Anda mengakses akun Google Ads pengguna tanpa harus menangani atau menyimpan info login pengguna.

Memahami model akses Google Ads

Untuk menggunakan Google Ads API secara efektif, pahami cara kerja model akses Google Ads. Lihat panduan model akses Google Ads.

Alur kerja OAuth

Ada tiga alur kerja umum yang digunakan saat bekerja dengan Google Ads API.

Alur akun layanan

Ini adalah alur kerja yang direkomendasikan jika alur kerja Anda tidak memerlukan interaksi manusia. Alur kerja ini memerlukan langkah konfigurasi, di mana pengguna menambahkan akun layanan ke akun Google Ads-nya. Kemudian, aplikasi dapat menggunakan kredensial akun layanan untuk mengelola akun Google Ads pengguna. Library Python dikonfigurasi sebagai berikut:

  • Jika menggunakan file google-ads.yaml atau string YAML, tambahkan hal berikut ke konfigurasi Anda untuk menetapkan jalur ke file JSON kunci pribadi di lingkungan lokal Anda (bersama dengan impersonated_email opsional jika menggunakan delegasi di seluruh domain):

    json_key_file_path: JSON_KEY_FILE_PATH
# Optional: only set if using Google Workspace domain-wide delegation:
# impersonated_email: IMPERSONATED_EMAIL

    Kemudian, panggil metode load_from_storage atau load_from_string:

    from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage()

  • Jika Anda menggunakan dict untuk mengonfigurasi library, sertakan pasangan nilai kunci berikut dan panggil metode load_from_dict, dengan meneruskan dict konfigurasi:

    from google.ads.googleads.client import GoogleAdsClient

configuration = {
    # ...
    "json_key_file_path": JSON_KEY_FILE_PATH,
    # ...
}

client = GoogleAdsClient.load_from_dict(configuration)

  • Jika Anda menggunakan variabel lingkungan, tambahkan kode berikut ke konfigurasi atau lingkungan bash Anda:

    export GOOGLE_ADS_JSON_KEY_FILE_PATH=JSON_KEY_FILE_PATH

    Kemudian, panggil metode load_from_env:

    from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_env()

Jika opsi konfigurasi json_key_file_path ada di salah satu metode konfigurasi ini, opsi use_application_default_credentials adalah False atau tidak disetel, dan kunci kredensial pengguna OAuth (client_id, client_secret, dan refresh_token) tidak disetel atau diberi komentar, library akan otomatis memberikan otorisasi menggunakan alur akun layanan.

Lihat panduan alur kerja akun layanan untuk mempelajari lebih lanjut.

Alur autentikasi pengguna tunggal

Alur kerja ini dapat digunakan jika Anda tidak dapat menggunakan akun layanan. Alur kerja ini memerlukan dua langkah konfigurasi:

  1. Memberi satu pengguna akses ke semua akun yang akan dikelola menggunakan Google Ads API. Pendekatan umum adalah memberi pengguna akses ke akun pengelola Google Ads API, dan menautkan semua akun Google Ads di akun pengelola tersebut.

  2. Pengguna menjalankan alat seperti gcloud CLI atau contoh kode generate_user_credentials untuk mengizinkan aplikasi Anda mengelola semua akun Google Ads mereka atas nama mereka.

Library dapat diinisialisasi menggunakan kredensial OAuth 2.0 pengguna sebagai berikut:

Jika menggunakan alat gcloud CLI (direkomendasikan)

  1. Ikuti dokumentasi Membuat kredensial untuk menyiapkan kredensial default aplikasi (ADC) di lingkungan lokal Anda.

  2. Tambahkan konfigurasi berikut ke string google-ads.yaml atau YAML Anda:

    use_application_default_credentials: true

    Kemudian, panggil metode load_from_storage atau load_from_string:

    from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage()

    Jika Anda menggunakan dict untuk mengonfigurasi library, sertakan key-value pair berikut dan panggil metode load_from_dict:

    from google.ads.googleads.client import GoogleAdsClient

configuration = {
    # ...
    "use_application_default_credentials": True,
    # ...
}

client = GoogleAdsClient.load_from_dict(configuration)

    Jika Anda menggunakan variabel lingkungan, tambahkan kode berikut ke konfigurasi atau lingkungan bash Anda:

    export GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS=true

    Kemudian, panggil metode load_from_env:

    from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_env()

Jika menangani token OAuth secara langsung

  1. Ikuti langkah-langkah untuk menyiapkan project konsol dan mendownload file JSON yang menyertakan client ID dan rahasia klien project Anda.

  2. Clone library klien Python ke mesin Anda dan ubah ke direktori tersebut:

    git clone https://github.com/googleads/google-ads-python.git
cd google-ads-python

  3. Jalankan contoh, dengan memberikan jalur absolut ke file JSON yang didownload pada langkah 1:

    python examples/authentication/generate_user_credentials.py \
    -c PATH_TO_CREDENTIALS_JSON

    Setelah selesai, token refresh akan dicetak ke konsol Anda. Salin dan simpan untuk langkah berikutnya.

  4. Konfigurasi library dengan menambahkan setelan berikut ke konfigurasi pilihan Anda:

    Tambahkan konfigurasi berikut ke string google-ads.yaml atau YAML Anda:

    client_id: INSERT_OAUTH2_CLIENT_ID_HERE
client_secret: INSERT_OAUTH2_CLIENT_SECRET_HERE
refresh_token: INSERT_REFRESH_TOKEN_HERE

    Kemudian, panggil metode load_from_storage atau load_from_string:

    from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage()

    Jika Anda menggunakan dict untuk mengonfigurasi library, sertakan key-value pair berikut dan panggil metode load_from_dict:

    from google.ads.googleads.client import GoogleAdsClient

configuration = {
    # ...
    "client_id": INSERT_OAUTH2_CLIENT_ID_HERE,
    "client_secret": (
        INSERT_OAUTH2_CLIENT_SECRET_HERE
    ),
    "refresh_token": INSERT_REFRESH_TOKEN_HERE,
    # ...
}

client = GoogleAdsClient.load_from_dict(configuration)

    Jika Anda menggunakan variabel lingkungan, tambahkan kode berikut ke konfigurasi atau lingkungan bash Anda:

    export GOOGLE_ADS_CLIENT_ID=\
INSERT_OAUTH2_CLIENT_ID_HERE
export GOOGLE_ADS_CLIENT_SECRET=\
INSERT_OAUTH2_CLIENT_SECRET_HERE
export GOOGLE_ADS_REFRESH_TOKEN=\
INSERT_REFRESH_TOKEN_HERE

    Kemudian, panggil metode load_from_env:

    from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_env()

Lihat panduan alur kerja autentikasi pengguna tunggal untuk mempelajari lebih lanjut.

Alur autentikasi multi-pengguna

Alur kerja ini direkomendasikan jika aplikasi Anda mengizinkan pengguna untuk login dan mengizinkan aplikasi Anda mengelola akun Google Ads mereka atas nama mereka. Aplikasi Anda membuat dan mengelola kredensial pengguna OAuth 2.0. Library dapat diinisialisasi menggunakan kredensial pengguna sebagai berikut, yang mengasumsikan bahwa aplikasi Anda mendapatkan kredensial saat runtime, baik dengan menjalankan alur otorisasi atau dengan memuatnya dari datastore:

dict adalah mekanisme konfigurasi paling sederhana yang dapat digunakan saat mendapatkan kredensial saat runtime:

from google.ads.googleads.client import GoogleAdsClient

configuration = {
    # ...
    "client_id": client_id,
    "client_secret": client_secret,
    "refresh_token": refresh_token,
    # ...
}

client = GoogleAdsClient.load_from_dict(configuration)

Lihat panduan alur kerja autentikasi multi-pengguna untuk mempelajari lebih lanjut.

Autentikasi manual

Anda dapat membuat kredensial autentikasi dengan pendekatan apa pun dan memberikannya ke GoogleAdsClient secara manual dengan membuat instance class klien secara langsung. Dengan asumsi objek kredensial yang Anda buat adalah instance dari google.auth.credentials.Credentials, Anda dapat meneruskannya sebagai berikut:

from google.ads.googleads.client import GoogleAdsClient
from google.auth import default

# This line retrieves ADCs from the environment. You can use any authentication
# approach as long as the `credentials` variable is an instance of
# `google.auth.credentials.Credentials`.
credentials, _ = default(scopes=["https://www.googleapis.com/auth/adwords"])

client = GoogleAdsClient(
    credentials=credentials,
    use_proto_plus=True,
)

Mengelola beberapa akun

Pengguna biasanya mengelola lebih dari satu akun Google Ads, baik melalui akses langsung ke akun, atau melalui akun pengelola Google Ads. Library klien Python menyediakan contoh kode berikut yang mengilustrasikan cara menangani kasus tersebut:

  1. Contoh kode get_account_hierarchy menunjukkan cara mengambil daftar semua akun di akun pengelola Google Ads.
  2. Contoh kode list_accessible_customers menunjukkan cara mengambil daftar semua akun yang akses langsungnya dimiliki pengguna. Akun ini kemudian dapat digunakan sebagai nilai yang valid untuk setelan login_customer_id.