Akun Layanan

Panduan ini membahas cara mengakses Google Ads API dengan akun layanan.

Akun layanan adalah akun milik aplikasi Anda, bukan milik pengguna akhir individu. Akun layanan memungkinkan interaksi server-ke-server antara aplikasi web dan layanan Google. Aplikasi Anda memanggil Google API atas nama akun layanan, sehingga pengguna tidak terlibat secara langsung.

Akun layanan menggunakan alur OAuth 2.0 yang tidak memerlukan otorisasi manusia, tetapi menggunakan file kunci yang hanya dapat diakses oleh aplikasi Anda.

Penggunaan akun layanan memberikan dua manfaat utama:

  • Otorisasi untuk akses Google API dilakukan sebagai langkah konfigurasi, sehingga menghindari komplikasi yang terkait dengan alur OAuth 2.0 lainnya yang memerlukan interaksi pengguna.

  • Alur pernyataan OAuth 2.0 memungkinkan aplikasi Anda meniru pengguna lain jika diperlukan.

Ada dua cara untuk memberikan otorisasi dengan akun layanan: secara langsung atau dengan peniruan identitas.

Otorisasi dengan akses akun langsung

Dalam opsi ini, Anda memberi akun layanan akses langsung ke akun Google Ads Anda.

Penyiapan akses akun

  1. Mulai dengan membuat akun layanan dan kredensial.

    Download kunci akun layanan dalam format JSON dan catat ID akun layanan dan email.

  2. Login ke akun Google Ads sebagai administrator. Buka Admin > Akses dan keamanan.

  3. Klik tombol + di bagian tab Pengguna.

  4. Ketik email akun layanan ke kotak input Email. Pilih tingkat akses akun yang sesuai, lalu klik tombol Tambahkan akun. Perhatikan bahwa tingkat akses Email dan Admin tidak didukung untuk akun layanan.

  5. Akun layanan akan diberi akses.

Konfigurasi library klien

Pilih tab yang sesuai dengan bahasa pemrograman Anda untuk mendapatkan petunjuk tentang cara mengonfigurasi library klien.

Java

Tetapkan jalur JSON kunci pribadi dalam konfigurasi Anda. Jika Anda menggunakan file ads.properties, tambahkan kode berikut:

api.googleads.serviceAccountSecretsPath=JSON_KEY_FILE_PATH

Lihat panduan konfigurasi untuk mengetahui detail tambahan.

.NET

Konfigurasikan kunci berikut di App.config / Web.config Anda. Lihat panduan konfigurasi untuk mengetahui detail tambahan.

<add key="OAuth2Mode" value="SERVICE_ACCOUNT" />
<add key="OAuth2SecretsJsonPath" value="JSON_KEY_FILE_PATH" />

Python

Tetapkan jalur JSON kunci pribadi dalam konfigurasi Anda. Jika Anda menggunakan google-ads.yaml file, string YAML, atau dict, tambahkan hal berikut:

json_key_file_path: JSON_KEY_FILE_PATH

Jika Anda menggunakan variabel lingkungan, tambahkan hal berikut ke konfigurasi atau lingkungan Bash:

export GOOGLE_ADS_JSON_KEY_FILE_PATH=JSON_KEY_FILE_PATH

PHP

Konfigurasikan kunci berikut di google_ads_php.ini Anda. Lihat panduan konfigurasi untuk detail tambahan.

; For service account flow.
jsonKeyFilePath = "JSON_KEY_FILE_PATH"
scopes = "https://www.googleapis.com/auth/adwords"

Ruby

Konfigurasikan kunci berikut di google_ads_config.rb Anda.

c.keyfile = 'JSON_KEY_FILE_PATH'

Perl

Tetapkan jalur JSON kunci pribadi dan delegasikan client ID dalam konfigurasi Anda. Jika Anda menggunakan file googleads.properties, tambahkan kode berikut:

jsonKeyFilePath=JSON_KEY_FILE_PATH

Jika Anda menggunakan variabel lingkungan, tambahkan hal berikut ke konfigurasi atau lingkungan Bash:

export GOOGLE_ADS_JSON_KEY_FILE_PATH=JSON_KEY_FILE_PATH

Otorisasi menggunakan peniruan identitas

Dalam opsi ini, Anda meniru identitas pengguna yang memiliki akses ke akun Google Ads Anda menggunakan akun layanan. Pendekatan ini hanya berfungsi untuk pelanggan Google Workspace. Akun layanan hanya dapat meniru identitas pengguna (alamat email) di Google Workspace yang sama.

Prasyarat

  • Domain Google Workspace yang Anda miliki seperti mydomain.com atau mybusiness.com

  • Token developer Google Ads API dan, jika perlu, akun percobaan

  • Library klien untuk bahasa yang Anda gunakan

  • Project Konsol API Google yang telah dikonfigurasi untuk Google Ads API

  • Pengguna Google Ads yang memiliki izin di akun Google Ads yang ingin Anda akses. Google Ads tidak mendukung penggunaan akun layanan tanpa peniruan identitas.

Penyiapan akses akun layanan

Karena peniruan identitas pengguna hanya dikontrol di tingkat domain, penggunaan akun layanan dan alur pernyataan dengan Google OAuth 2.0 mengharuskan Anda mendaftarkan domain Anda sendiri ke Google Workspace. Aplikasi Anda dan penggunanya kemudian dapat meniru identitas pengguna mana pun di domain.

  1. Mulai dengan membuat akun layanan dan kredensial.

    Download kunci akun layanan dalam format JSON dan catat ID akun layanan.

  2. Bagikan ID akun layanan dan cakupan Google Ads API (https://www.googleapis.com/auth/adwords) kepada administrator domain Anda.

    Minta administrator domain untuk mendelegasikan otoritas seluruh domain ke akun layanan Anda.

  3. Jika Anda adalah administrator domain, selesaikan petunjuk pusat bantuan.

Sekarang Anda dapat menggunakan akun layanan untuk mengakses akun Google Ads dengan alur pernyataan OAuth 2.0.

Konfigurasi library klien

Pilih tab yang sesuai dengan bahasa pemrograman Anda untuk mendapatkan petunjuk tentang cara mengonfigurasi library klien.

Java

Tetapkan jalur JSON kunci pribadi dan delegasikan client ID di konfigurasi Anda. Jika Anda menggunakan file ads.properties, tambahkan kode berikut:

api.googleads.serviceAccountSecretsPath=JSON_KEY_FILE_PATH
api.googleads.serviceAccountUser=IMPERSONATED_EMAIL

Lihat panduan konfigurasi untuk mengetahui detail tambahan.

.NET

Konfigurasikan kunci berikut di App.config / Web.config Anda. Lihat panduan konfigurasi untuk mengetahui detail selengkapnya.

<add key="OAuth2Mode" value="SERVICE_ACCOUNT" />
<add key="OAuth2SecretsJsonPath" value="JSON_KEY_FILE_PATH" />

<!-- Supply the email address of the user to impersonate. -->
<add key="OAuth2PrnEmail" value="IMPERSONATED_EMAIL" />

Python

Tetapkan jalur JSON kunci pribadi dan email yang disamarkan dalam konfigurasi Anda. Jika Anda menggunakan google-ads.yaml file, string YAML, atau dict, tambahkan hal berikut:

json_key_file_path: JSON_KEY_FILE_PATH
impersonated_email: IMPERSONATED_EMAIL

Jika Anda menggunakan variabel lingkungan, tambahkan hal berikut ke konfigurasi atau lingkungan Bash:

export GOOGLE_ADS_JSON_KEY_FILE_PATH=JSON_KEY_FILE_PATH
export GOOGLE_ADS_IMPERSONATED_EMAIL=IMPERSONATED_EMAIL

PHP

Konfigurasikan kunci berikut di google_ads_php.ini Anda. Lihat panduan konfigurasi untuk detail tambahan.

; For service account flow.
jsonKeyFilePath = "JSON_KEY_FILE_PATH"
scopes = "https://www.googleapis.com/auth/adwords"
impersonatedEmail = "IMPERSONATED_EMAIL"

Ruby

Konfigurasikan kunci berikut di google_ads_config.rb Anda.

c.keyfile = 'JSON_KEY_FILE_PATH'
c.impersonate = 'IMPERSONATED_EMAIL'

Perl

Tetapkan jalur JSON kunci pribadi dan delegasikan client ID dalam konfigurasi Anda. Jika Anda menggunakan file googleads.properties, tambahkan kode berikut:

jsonKeyFilePath=JSON_KEY_FILE_PATH
impersonatedEmail=IMPERSONATED_EMAIL

Jika Anda menggunakan variabel lingkungan, tambahkan hal berikut ke konfigurasi atau lingkungan Bash:

export GOOGLE_ADS_JSON_KEY_FILE_PATH=JSON_KEY_FILE_PATH
export GOOGLE_ADS_IMPERSONATED_EMAIL=IMPERSONATED_EMAIL

Masalah keamanan

Karena akun layanan memiliki kontrol delegasi tingkat domain untuk domain Google Workspace Anda, penting untuk melindungi file kunci yang memungkinkan akun layanan mengakses layanan Google yang diotorisasi. Hal ini terutama berlaku karena akun layanan tersebut memiliki kemampuan untuk meniru identitas pengguna mana pun di domain.

Praktik baik lainnya adalah mengizinkan akun layanan hanya mengakses kumpulan API minimum yang diperlukan. Ini adalah tindakan pencegahan untuk membatasi jumlah data yang dapat diakses penyerang jika file kunci akun layanan disusupi.