Konfigurasi

Library klien PHP Google Ads API menyediakan beberapa setelan konfigurasi yang dapat Anda gunakan untuk menyesuaikan perilaku library.

File konfigurasi

Anda dapat menyimpan sebagian besar setelan konfigurasi ini dalam file konfigurasi INI dan menggunakannya saat membuat instance klien, misalnya, google_ads_php.ini.

Builder kredensial dan klien menyediakan metode fromFile untuk memuat setelan dari file tersebut:

$oAuth2Credential = (new OAuth2TokenBuilder())
    ->fromFile('/path/to/google_ads_php.ini')
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->fromFile('/path/to/google_ads_php.ini')
    ->withOAuth2Credential($oAuth2Credential)
    ->build();

Jika tidak ada jalur konfigurasi yang diberikan sebagai argumen, metode fromFile akan dimuat dari jalur konfigurasi default, yaitu:

  1. Nilai variabel lingkungan bernama GOOGLE_ADS_CONFIGURATION_FILE_PATH jika ditetapkan.
  2. Jika tidak, file google_ads_php.ini di direktori HOME Anda.
$oAuth2Credential = (new OAuth2TokenBuilder())
    ->fromFile()
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->fromFile()
    ->withOAuth2Credential($oAuth2Credential)
    ->build();

Konfigurasi dinamis

Anda dapat menetapkan setelan konfigurasi ini secara dinamis saat membuat instance klien:

$oAuth2Credential = (new OAuth2TokenBuilder())
    ->withClientId('INSERT_CLIENT_ID_HERE')
    ->withClientSecret('INSERT_CLIENT_SECRET_HERE')
    ->withRefreshToken('INSERT_REFRESH_TOKEN_HERE')
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->withOAuth2Credential($oAuth2Credential)
    ->build();

Variabel lingkungan konfigurasi

Anda dapat menetapkan beberapa setelan konfigurasi dari variabel lingkungan saat membuat instance klien (lihat variabel lingkungan standar).

Pembangun kredensial dan klien menyediakan metode fromEnvironmentVariables untuk memuat setelan dari variabel lingkungan.

$oAuth2Credential = (new OAuth2TokenBuilder())
    // ...
    ->fromEnvironmentVariables()
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->withOAuth2Credential($oAuth2Credential)
    // ...
    ->fromEnvironmentVariables()
    ->build();

Kolom konfigurasi

Setelan konfigurasi mendukung beberapa kolom yang disusun dalam kategori:

  1. Kolom yang digunakan oleh OAuth2TokenBuilder:
    • Mode aplikasi:
      • [OAUTH2] clientId: Client ID OAuth2 Anda.
      • [OAUTH2] clientSecret: Rahasia klien OAuth2 Anda.
      • [OAUTH2] refreshToken: Token refresh OAuth2 Anda.
    • Mode akun layanan:
      • [OAUTH2] jsonKeyFilePath: Jalur kunci JSON.
      • [OAUTH2] scopes: Cakupan OAuth2 (secara default https://www.googleapis.com/auth/adwords di v32.1.0 dan yang lebih baru; diperlukan dalam versi sebelum v32.1.0 atau saat menggunakan cakupan kustom; tidak dibaca dari variabel lingkungan oleh fromEnvironmentVariables()).
      • [OAUTH2] impersonatedEmail: Alamat email opsional yang akan ditiru identitasnya saat menggunakan delegasi di seluruh domain Google Workspace.
    • Mode Kredensial Default Aplikasi:
      • Jika kolom mode Aplikasi maupun mode Akun layanan tidak ditetapkan, OAuth2TokenBuilder akan otomatis beralih kembali ke Kredensial Default Aplikasi (ADC).
  2. Kolom yang digunakan oleh GoogleAdsClientBuilder:
    • [GOOGLE_ADS] developerToken: (Penghentian pada 9 September 2026) Token developer Google Ads API Anda. Opsional, diabaikan oleh server API terlepas dari versi library klien, dan akan ditolak dalam versi utama Google Ads API mendatang.
      • v35.0.0 dan yang lebih baru: Tidak diperlukan saat inisialisasi klien (GoogleAdsClientBuilder menghapus validasi token developer sisi klien lokal).
      • Versi sebelum v35.0.0: Diperlukan oleh validasi konfigurasi sisi klien lokal.
    • [GOOGLE_ADS] loginCustomerId: ID pelanggan yang diberi otorisasi untuk digunakan dalam permintaan.
    • [GOOGLE_ADS] linkedCustomerId: ID pelanggan tertaut.
    • [GOOGLE_ADS] endpoint: Endpoint server Google Ads API alternatif opsional.
    • [LOGGING] logFilePath: Jalur untuk output logging.
    • [LOGGING] logLevel: Level logging.
    • [CONNECTION] proxy: URL server proxy yang digunakan untuk konektivitas internet.
    • [CONNECTION] transport: Transportasi jaringan (grpc atau rest).
    • [CONNECTION] grpcChannelIsSecure: Apakah saluran gRPC aman.
    • [CONNECTION] grpcChannelCredential: Kredensial saluran gRPC.
    • [CONNECTION] unaryMiddlewares: Middleware unary.
    • [CONNECTION] streamingMiddlewares: Middleware streaming.
    • [CONNECTION] grpcInterceptors: Interceptor gRPC.

Validasi konfigurasi

Setelan konfigurasi diperiksa saat membuat instance klien dan pengecualian dibuat jika tidak valid. Aturan validasi adalah sebagai berikut:

  1. Kolom [OAUTH2] tidak boleh ditetapkan untuk mode Aplikasi dan mode Akun layanan secara bersamaan.
  2. [OAUTH2] jsonKeyFilePath harus ditetapkan saat menggunakan mode Akun layanan (pada versi sebelum v32.1.0, [OAUTH2] scopes juga harus ditetapkan; pada v32.1.0 dan yang lebih baru, scopes secara default adalah https://www.googleapis.com/auth/adwords).
  3. [OAUTH2] clientId, [OAUTH2] clientSecret, dan [OAUTH2] refreshToken harus ditetapkan saat menggunakan mode Aplikasi.
  4. Pada versi sebelum v35.0.0, [GOOGLE_ADS] developerToken diperiksa oleh validasi sisi klien lokal (di v35.0.0 dan yang lebih baru, [GOOGLE_ADS] developerToken tidak diperlukan).
  5. Jika disetel, [GOOGLE_ADS] loginCustomerId dan [GOOGLE_ADS] linkedCustomerId harus berupa bilangan positif.
  6. Jika disetel, [CONNECTION] proxy harus berupa URL yang valid (lihat filter FILTER_VALIDATE_URL).
  7. Jika disetel, [LOGGING] logLevel harus berupa tingkat log PSR yang valid dalam huruf kapital, seperti INFO.
  8. Jika ditetapkan, [CONNECTION] transport harus berupa grpc atau rest.
  9. Jika [CONNECTION] transport disetel ke grpc, transportasi gRPC harus didukung oleh lingkungan (lihat Panduan transportasi).
  10. [CONNECTION] grpcChannelIsSecure harus berupa true jika [CONNECTION] transport tidak disetel ke grpc (koneksi REST selalu memerlukan HTTPS).
  11. [CONNECTION] grpcChannelCredential hanya dapat ditetapkan jika [CONNECTION] transport ditetapkan ke grpc.
  12. [CONNECTION] grpcChannelCredential hanya dapat ditetapkan jika [CONNECTION] grpcChannelIsSecure adalah true.