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 .NET Google Ads API Anda mengakses akun Google Ads pengguna tanpa harus menangani atau menyimpan info login pengguna.

Memahami model akses Google Ads

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

Alur kerja OAuth

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

Alur akun layanan

Ini adalah alur kerja yang direkomendasikan jika aplikasi Anda tidak memerlukan interaksi manusia. Alur kerja ini memerlukan langkah konfigurasi, yaitu pengguna menambahkan akun layanan ke akun Google Ads-nya. Kemudian, aplikasi dapat menggunakan kredensial akun layanan untuk mengelola akun Google Ads pengguna.

Konfigurasikan library sebagai berikut:

// Initialize a GoogleAdsConfig instance.
GoogleAdsConfig config = new GoogleAdsConfig()
{
    OAuth2Mode = OAuth2Flow.SERVICE_ACCOUNT,
    OAuth2SecretsJsonPath = "PATH_TO_CREDENTIALS_JSON",
    LoginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"
};

// Initialize a GoogleAdsClient instance.
GoogleAdsClient client = new GoogleAdsClient(config);

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. Beri satu pengguna akses ke semua akun yang akan dikelola menggunakan Google Ads API. Pendekatan yang 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 command line seperti gcloud atau contoh kode GenerateUserCredentials untuk mengizinkan aplikasi Anda mengelola semua akun Google Ads mereka atas nama mereka.

Lakukan inisialisasi library menggunakan kredensial OAuth 2.0 pengguna sebagai berikut:

GoogleAdsConfig config = new GoogleAdsConfig()
{
    LoginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE",
    OAuth2ClientId = "INSERT_OAUTH_CLIENT_ID_HERE",
    OAuth2ClientSecret = "INSERT_OAUTH_CLIENT_SECRET_HERE",
    OAuth2RefreshToken = "INSERT_REFRESH_TOKEN_HERE"
};

GoogleAdsClient client = new GoogleAdsClient(config);

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

Alur autentikasi multi-pengguna

Ini adalah alur kerja yang direkomendasikan jika aplikasi Anda mengizinkan pengguna untuk login dan memberi otorisasi kepada aplikasi Anda untuk mengelola akun Google Ads mereka atas nama mereka. Aplikasi Anda membuat dan mengelola kredensial pengguna OAuth 2.0 secara dinamis per sesi atau permintaan pengguna, lalu menginisialisasi GoogleAdsClient dengan token refresh pengguna aktif:

GoogleAdsConfig config = new GoogleAdsConfig()
{
    LoginCustomerId = userSession.LoginCustomerId,
    OAuth2ClientId = "INSERT_OAUTH_CLIENT_ID_HERE",
    OAuth2ClientSecret = "INSERT_OAUTH_CLIENT_SECRET_HERE",
    OAuth2RefreshToken = userSession.RefreshToken
};

GoogleAdsClient client = new GoogleAdsClient(config);

Mulai Google.Ads.GoogleAds v27.0.0, Anda juga dapat memasukkan objek ICredential atau GoogleCredential yang telah dikonfigurasi sebelumnya langsung di GoogleAdsConfig menggunakan properti Credentials.

Lihat panduan alur kerja autentikasi multi-pengguna untuk mempelajari lebih lanjut. Library klien .NET menyertakan dua contoh kode sebagai referensi:

  1. Contoh kode AuthenticateInAspNetCoreApplication mengilustrasikan cara membuat aplikasi web yang mendapatkan autentikasi pengguna saat runtime untuk mengelola akun Google Ads mereka atas nama mereka. Aplikasi ini menggunakan kredensial OAuth 2.0 pengguna untuk mengambil kampanye di akun Google Ads-nya.
  2. Contoh kode command line GenerateUserCredentials menggambarkan cara mendapatkan autentikasi pengguna saat runtime untuk mengelola akun Google Ads mereka atas nama mereka. Anda dapat menggunakan contoh kode ini sebagai referensi untuk membangun aplikasi desktop yang memerlukan autentikasi pengguna.

Bagaimana jika pengguna saya 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 .NET menyediakan contoh kode berikut yang menggambarkan cara menangani kasus tersebut:

  1. Contoh kode GetAccountHierarchy menunjukkan cara mengambil daftar semua akun di akun pengelola Google Ads.
  2. Contoh kode ListAccessibleCustomers menunjukkan cara mengambil daftar semua akun yang dapat diakses langsung oleh pengguna. Akun ini kemudian dapat digunakan sebagai nilai yang valid untuk setelan LoginCustomerId.

Kredensial Default Aplikasi

Library klien .NET (v24.1.0 dan yang lebih baru) juga mendukung autentikasi dengan Kredensial Default Aplikasi.

Hal ini sangat berguna untuk pengembangan lokal atau untuk pengembangan terhadap Google API yang berbeda, karena Anda dapat menggunakan kembali kredensial yang sama, asalkan kredensial tersebut dapat mengakses cakupan OAuth 2.0 yang diperlukan.

Untuk Google Ads API, pastikan Kredensial Default Aplikasi Anda dapat mengakses cakupan OAuth 2.0 https://www.googleapis.com/auth/adwords.

Untuk menggunakan Kredensial Default Aplikasi, tetapkan opsi UseApplicationDefaultCredentials ke true di GoogleAdsConfig (atau tetapkan variabel lingkungan USE_APPLICATION_DEFAULT_CREDENTIALS=true saat memuat konfigurasi dengan config.LoadFromEnvironmentVariables()):

GoogleAdsConfig config = new GoogleAdsConfig()
{
    UseApplicationDefaultCredentials = true,
    LoginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"
};
GoogleAdsClient client = new GoogleAdsClient(config);

Lihat halaman konfigurasi untuk mengetahui detail selengkapnya tentang opsi yang tersedia untuk mengonfigurasi library klien .NET.