Google menggunakan teknologi AI untuk menerjemahkan konten ke dalam bahasa pilihan Anda. Terjemahan AI mungkin mengandung kesalahan.

Konfigurasi

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

Mengonfigurasi library saat runtime

Cara yang direkomendasikan untuk mengonfigurasi library klien adalah dengan menginisialisasi objek GoogleAdsConfig saat runtime:

using Google.Ads.Gax.Config;
using Google.Ads.GoogleAds.Config;
using Google.Ads.GoogleAds.Lib;

GoogleAdsConfig config = new GoogleAdsConfig()
{
    OAuth2Mode = OAuth2Flow.APPLICATION,
    OAuth2ClientId = "INSERT_CLIENT_ID.apps.googleusercontent.com",
    OAuth2ClientSecret = "INSERT_CLIENT_SECRET",
    OAuth2RefreshToken = "INSERT_REFRESH_TOKEN",
    LoginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"
};

GoogleAdsClient client = new GoogleAdsClient(config);

Opsi konfigurasi alternatif

Library ini juga menyediakan opsi tambahan untuk memuat setelan konfigurasi dari appsettings.json, file JSON kustom, variabel lingkungan, atau App.config. Untuk mengaktifkannya, instal paket NuGet Google.Ads.GoogleAds.Extensions di project Anda:

dotnet add package Google.Ads.GoogleAds.Extensions

Jika Anda menggunakan salah satu opsi ini, setelan konfigurasi tidak akan diambil secara otomatis; Anda harus memuatnya secara eksplisit seperti yang ditunjukkan di bagian berikut. Pastikan untuk menangani pengecualian I/O file (seperti FileNotFoundException atau UnauthorizedAccessException) saat memuat setelan dari file atau aliran data eksternal.

Menggunakan appsettings.json atau settings.json

Di aplikasi .NET 8.0 dan ASP.NET Core, tempatkan kunci konfigurasi Anda di dalam bagian GoogleAdsApi di appsettings.json (atau settings.json):

{
  "GoogleAdsApi": {
    "LoginCustomerId": "INSERT_LOGIN_CUSTOMER_ID_HERE",
    "OAuth2Mode": "APPLICATION",
    "OAuth2ClientId": "INSERT_CLIENT_ID.apps.googleusercontent.com",
    "OAuth2ClientSecret": "INSERT_CLIENT_SECRET",
    "OAuth2RefreshToken": "INSERT_REFRESH_TOKEN"
  }
}

Selanjutnya, ekstrak bagian GoogleAdsApi dari instance IConfiguration aplikasi Anda (misalnya, yang dimasukkan oleh ASP.NET Core atau dibuat dengan ConfigurationBuilder) dan muat dengan LoadFromConfigurationSection:

using Google.Ads.GoogleAds.Config;
using Google.Ads.GoogleAds.Extensions.Config;
using Google.Ads.GoogleAds.Lib;
using Microsoft.Extensions.Configuration;

IConfigurationSection section = configuration.GetSection("GoogleAdsApi");
GoogleAdsConfig config = new GoogleAdsConfig();
config.LoadFromConfigurationSection(section);
GoogleAdsClient client = new GoogleAdsClient(config);

Atau, Anda dapat memuat file appsettings.json atau settings.json secara langsung berdasarkan jalur menggunakan LoadFromSettingsJson:

using Google.Ads.GoogleAds.Config;
using Google.Ads.GoogleAds.Extensions.Config;
using Google.Ads.GoogleAds.Lib;

GoogleAdsConfig config = new GoogleAdsConfig();
config.LoadFromSettingsJson("appsettings.json", "GoogleAdsApi");
GoogleAdsClient client = new GoogleAdsClient(config);

Anda juga dapat memuat jalur dari variabel lingkungan GOOGLE_ADS_CONFIGURATION_FILE_PATH (EnvironmentVariableNames.CONFIG_FILE_PATH) dengan memanggil config.TryLoadFromEnvironmentFilePath.

Menggunakan file JSON kustom

Anda juga dapat menggunakan instance IConfigurationRoot untuk memuat file JSON datar tanpa bagian GoogleAdsApi level teratas.

Membuat file JSON

Buat file JSON bernama GoogleAdsApi.json yang menentukan kunci konfigurasi di level root:

{
  "Timeout": "2000",
  "ProxyServer": "http://localhost:8888",
  "ProxyUser": "",
  "ProxyPassword": "",
  "ProxyDomain": "",
  "LoginCustomerId": "INSERT_LOGIN_CUSTOMER_ID_HERE",
  "OAuth2Mode": "APPLICATION",
  "OAuth2ClientId": "INSERT_CLIENT_ID.apps.googleusercontent.com",
  "OAuth2ClientSecret": "INSERT_CLIENT_SECRET",
  "OAuth2RefreshToken": "INSERT_REFRESH_TOKEN"
}

Memuat konfigurasi

Selanjutnya, muat file JSON ke dalam IConfigurationRoot:

using System.IO;
using Google.Ads.GoogleAds.Config;
using Google.Ads.GoogleAds.Extensions.Config;
using Google.Ads.GoogleAds.Lib;
using Microsoft.Extensions.Configuration;

ConfigurationBuilder builder = new ConfigurationBuilder()
    .SetBasePath(Directory.GetCurrentDirectory())
    .AddJsonFile("GoogleAdsApi.json");
IConfigurationRoot configRoot = builder.Build();

GoogleAdsConfig config = new GoogleAdsConfig();
config.LoadFromConfigurationRoot(configRoot);
GoogleAdsClient client = new GoogleAdsClient(config);

Menggunakan variabel lingkungan

Anda juga dapat melakukan inisialisasi GoogleAdsClient menggunakan variabel lingkungan:

using Google.Ads.GoogleAds.Config;
using Google.Ads.GoogleAds.Extensions.Config;
using Google.Ads.GoogleAds.Lib;

GoogleAdsConfig config = new GoogleAdsConfig();
config.LoadFromEnvironmentVariables();
GoogleAdsClient client = new GoogleAdsClient(config);

Lihat daftar lengkap variabel lingkungan yang didukung.

Menggunakan App.config

Dalam aplikasi .NET Framework, semua setelan khusus untuk Google Ads API disimpan di node GoogleAdsApi pada file App.config. Konfigurasi App.config standar adalah sebagai berikut:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <configSections>
    <section name="GoogleAdsApi"
             type="System.Configuration.DictionarySectionHandler" />
  </configSections>
  <GoogleAdsApi>
    <!-- Set the service timeout in milliseconds. -->
    <add key="Timeout" value="2000" />

    <!-- Proxy settings for library. -->
    <add key="ProxyServer" value="http://localhost:8888" />
    <add key="ProxyUser" value="" />
    <add key="ProxyPassword" value="" />
    <add key="ProxyDomain" value="" />

    <!-- Google Ads API settings. -->
    <add key="LoginCustomerId" value="INSERT_LOGIN_CUSTOMER_ID_HERE" />

    <!-- OAuth2 settings -->
    <add key="OAuth2Mode" value="APPLICATION" />
    <add key="OAuth2ClientId"
         value="INSERT_CLIENT_ID.apps.googleusercontent.com" />
    <add key="OAuth2ClientSecret" value="INSERT_CLIENT_SECRET" />
    <add key="OAuth2RefreshToken" value="INSERT_REFRESH_TOKEN" />
  </GoogleAdsApi>
  <startup>
    <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.7.2" />
  </startup>
</configuration>

Untuk memuat setelan konfigurasi dari file App.config, panggil metode LoadFromDefaultAppConfigSection pada objek GoogleAdsConfig:

using Google.Ads.GoogleAds.Config;
using Google.Ads.GoogleAds.Extensions.Config;
using Google.Ads.GoogleAds.Lib;

GoogleAdsConfig config = new GoogleAdsConfig();
config.LoadFromDefaultAppConfigSection();
GoogleAdsClient client = new GoogleAdsClient(config);

Menentukan file konfigurasi App.config terpisah

Jika tidak ingin App.config berantakan, Anda dapat memindahkan konfigurasi khusus library ke file konfigurasinya sendiri menggunakan properti configSource:

Tentukan configSource di App.config Anda. Ubah App.config Anda untuk mereferensikan file konfigurasi eksternal:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <configSections>
    <section name="GoogleAdsApi"
             type="System.Configuration.DictionarySectionHandler" />
  </configSections>
  <GoogleAdsApi configSource="GoogleAdsApi.config" />
</configuration>

Tentukan konten file konfigurasi Anda. Buat file konfigurasi lain dengan nama yang Anda tentukan di configSource (GoogleAdsApi.config), dan pindahkan node konfigurasi GoogleAdsApi dari App.config ke file ini:
```
<?xml version="1.0" encoding="utf-8" ?>
<GoogleAdsApi>
  
</GoogleAdsApi>
```
Perbarui aturan build di .csproj. Sertakan file konfigurasi baru dalam project Anda dan tetapkan properti Copy to Output Directory ke Copy always. Bangun ulang dan jalankan project Anda agar aplikasi mengambil nilai dari file konfigurasi baru.

Menggunakan streaming generik

Anda juga dapat memuat konfigurasi, atau bagian-bagiannya, dari aliran data umum, termasuk yang dienkripsi:

GoogleAdsConfig config = new GoogleAdsConfig()
{
    // Set some configuration properties in code.
    OAuth2Mode = OAuth2Flow.SERVICE_ACCOUNT,
};

// Load your encrypted data from a file and dispose of the streams properly.
using (CryptoStream strm = GetEncryptedCredentialsStream())
using (StreamReader rdr = new StreamReader(strm))
{
    // Configure the OAuth credentials from the encrypted stream.
    config.LoadOAuth2SecretsFromStream(rdr);
}

GoogleAdsClient client = new GoogleAdsClient(config);

Kolom konfigurasi

Bagian berikut mencantumkan setelan yang didukung oleh library .NET Google Ads.

Setelan konektivitas

Timeout: Gunakan kunci ini untuk menetapkan waktu tunggu layanan dalam milidetik. Nilai default ditetapkan berdasarkan setelan method_config/timeout di googleads_grpc_service_config.json. Tetapkan nilai yang lebih rendah jika Anda perlu menerapkan batas yang lebih singkat pada waktu maksimum untuk panggilan API. Anda dapat menetapkan waktu tunggu ke 2 jam atau lebih, tetapi API mungkin masih akan mengalami waktu tunggu pada permintaan yang berjalan sangat lama dan menampilkan error DEADLINE_EXCEEDED.
ProxyServer: Tetapkan ini ke URL server proxy HTTP jika Anda menggunakan proxy untuk terhubung ke internet.
ProxyUser: Tetapkan ini ke nama pengguna yang Anda perlukan untuk melakukan autentikasi terhadap server proxy. Biarkan kosong jika nama pengguna tidak diperlukan.
ProxyPassword: Tetapkan ini ke sandi ProxyUser jika Anda menetapkan nilai untuk ProxyUser.
ProxyDomain: Tetapkan ini ke domain untuk ProxyUser jika server proxy Anda memerlukan penetapan domain.
MaxReceiveMessageLengthInBytes: Gunakan setelan ini untuk meningkatkan ukuran maksimum respons API yang dapat ditangani oleh library klien. Nilai defaultnya adalah 64 MB.
MaxMetadataSizeInBytes: Gunakan setelan ini untuk meningkatkan ukuran maksimum respons error API yang dapat ditangani library klien. Nilai defaultnya adalah 16 MB.

Sesuaikan setelan MaxReceiveMessageLengthInBytes dan MaxMetadataSizeInBytes untuk memperbaiki error ResourceExhausted tertentu. Setelan ini mengatasi error dalam bentuk:

Status(StatusCode="ResourceExhausted",Detail="Received
message larger than max (423184132 versus 67108864)"

Dalam contoh ini, error terjadi karena ukuran pesan (423184132 bytes) lebih besar dari yang dapat ditangani library (67108864 bytes). Tingkatkan MaxReceiveMessageLengthInBytes ke 500000000 untuk menghindari error ini. Perhatikan bahwa error ini juga menunjukkan bahwa kode Anda menangani objek respons yang sangat besar (seperti SearchGoogleAdsResponse yang besar). Hal ini dapat berdampak pada performa kode Anda karena Large Object Heap .NET. Jika hal ini menjadi masalah performa, Anda mungkin harus mempelajari cara mengatur ulang panggilan API atau mendesain ulang bagian-bagian aplikasi Anda.

Setelan OAuth2

Saat menggunakan OAuth 2.0 untuk mengizinkan panggilan Anda terhadap server Google Ads API, Anda harus menetapkan kunci konfigurasi berikut:

Tetapkan AuthorizationMethod ke OAuth2.
OAuth2Mode: Tetapkan ke APPLICATION atau SERVICE_ACCOUNT.
OAuth2ClientId: Tetapkan nilai ini ke client ID OAuth 2.0 Anda.
OAuth2ClientSecret: Tetapkan nilai ini ke rahasia klien OAuth 2.0 Anda.
OAuth2Scope: Tetapkan nilai ini ke cakupan yang berbeda jika Anda ingin mengizinkan token OAuth 2.0 untuk beberapa API. Setelan ini bersifat opsional.
UseApplicationDefaultCredentials: Tetapkan nilai ini ke true untuk melakukan autentikasi menggunakan Kredensial Default Aplikasi (didukung di Google.Ads.GoogleAds v24.1.0 dan yang lebih baru; config.LoadFromEnvironmentVariables() membaca variabel lingkungan USE_APPLICATION_DEFAULT_CREDENTIALS tanpa awalan).
Credentials: (Hanya runtime, didukung di v27.0.0 dan yang lebih baru) Memasukkan instance ICredential atau GoogleCredential yang telah dibuat sebelumnya langsung di GoogleAdsConfig saat runtime.

Jika menggunakan OAuth2Mode == APPLICATION, Anda perlu menetapkan kunci konfigurasi tambahan berikut:

OAuth2RefreshToken: Tetapkan nilai ini ke token refresh OAuth 2.0 yang telah dibuat sebelumnya jika Anda ingin menggunakan kembali token OAuth 2.0. Setelan ini bersifat opsional.
OAuth2RedirectUri: Tetapkan nilai ini ke URL pengalihan OAuth 2.0. Setelan ini bersifat opsional.

Lihat panduan berikut untuk mengetahui detail selengkapnya:

Jika menggunakan OAuth2Mode == SERVICE_ACCOUNT, Anda harus menetapkan kunci konfigurasi tambahan berikut:

OAuth2SecretsJsonPath: Tetapkan nilai ini ke jalur file kunci JSON OAuth 2.0.
OAuth2PrnEmail: Tetapkan nilai ini ke alamat email akun yang Anda tiru saat menggunakan delegasi di seluruh domain Google Workspace. Setelan ini bersifat opsional.

Lihat panduan alur akun layanan OAuth untuk mengetahui detail selengkapnya.

Setelan transportasi

UseGrpcCore: Tetapkan setelan ini ke true untuk menggunakan library Grpc.Core sebagai lapisan transport yang mendasarinya. Lihat Menggunakan library Grpc.Core.

Setelan Google Ads API

Setelan berikut khusus untuk Google Ads API:

LoginCustomerId: Ini adalah ID pelanggan yang diotorisasi untuk digunakan dalam permintaan, tanpa tanda hubung (-).
LinkedCustomerId: Header ini hanya diperlukan untuk metode yang memperbarui resource entity saat diberi izin melalui Akun Tertaut di UI Google Ads (resource AccountLink di Google Ads API). Tetapkan nilai ini ke ID pelanggan penyedia data yang memperbarui resource ID pelanggan yang ditentukan. ID ini harus ditetapkan tanpa tanda hubung (-). Pelajari Akun Tertaut lebih lanjut.