การกำหนดค่า

ไลบรารีของไคลเอ็นต์ Google Ads API มีการตั้งค่าการกำหนดค่าหลายอย่างที่คุณใช้เพื่อปรับแต่งลักษณะการทำงานของไลบรารีได้

กำหนดค่าไลบรารีที่รันไทม์

วิธีที่แนะนำในการกำหนดค่าไลบรารีของไคลเอ็นต์คือการเริ่มต้นออบเจ็กต์ GoogleAdsConfig ที่รันไทม์ ดังนี้

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);

ตัวเลือกการกำหนดค่าสำรอง

นอกจากนี้ ไลบรารียังมีตัวเลือกเพิ่มเติมในการโหลดการตั้งค่าการกำหนดค่าจาก appsettings.json, ไฟล์ JSON ที่กำหนดเอง, ตัวแปรสภาพแวดล้อม หรือ App.config หากต้องการเปิดใช้ ให้ติดตั้งแพ็กเกจ Google.Ads.GoogleAds.Extensions NuGet ในโปรเจ็กต์โดยทำดังนี้

dotnet add package Google.Ads.GoogleAds.Extensions

หากคุณใช้ตัวเลือกใดตัวเลือกหนึ่งเหล่านี้ ระบบจะไม่เลือกการตั้งค่าการกำหนดค่าโดยอัตโนมัติ คุณต้องโหลดการตั้งค่าอย่างชัดเจนตามที่แสดงในส่วนต่อไปนี้ อย่าลืมจัดการข้อยกเว้น I/O ของไฟล์ (เช่น FileNotFoundException หรือ UnauthorizedAccessException) เมื่อโหลดการตั้งค่าจากไฟล์หรือสตรีมภายนอก

ใช้ appsettings.json หรือ settings.json

ในแอปพลิเคชัน .NET 8.0 และ ASP.NET Core ให้วางคีย์การกำหนดค่าไว้ในส่วน GoogleAdsApi ใน appsettings.json (หรือ 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"
  }
}

จากนั้นแยกส่วน GoogleAdsApi ออกจากอินสแตนซ์ IConfiguration ของแอปพลิเคชัน (เช่น แทรกโดย ASP.NET Core หรือสร้างด้วย ConfigurationBuilder) แล้วโหลดด้วย 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);

หรือจะโหลดไฟล์ appsettings.json หรือ settings.json โดยตรงตามเส้นทางโดยใช้ 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);

นอกจากนี้ คุณยังโหลดเส้นทางจากตัวแปรสภาพแวดล้อม GOOGLE_ADS_CONFIGURATION_FILE_PATH (EnvironmentVariableNames.CONFIG_FILE_PATH) ได้โดยเรียกใช้ config.TryLoadFromEnvironmentFilePath

ใช้ไฟล์ JSON ที่กำหนดเอง

นอกจากนี้ คุณยังใช้อินสแตนซ์ IConfigurationRoot เพื่อโหลดไฟล์ JSON แบบแฟลตที่ไม่มีส่วน GoogleAdsApi ระดับบนสุดได้ด้วย

สร้างไฟล์ JSON

สร้างไฟล์ JSON ชื่อ GoogleAdsApi.json ที่กำหนดคีย์การกำหนดค่าที่ระดับรูท ดังนี้

{
  "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"
}

โหลดการกำหนดค่า

จากนั้นโหลดไฟล์ JSON ลงใน 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);

ใช้ตัวแปรสภาพแวดล้อม

นอกจากนี้ คุณยังเริ่มต้น GoogleAdsClient โดยใช้ตัวแปรสภาพแวดล้อมได้ด้วย ดังนี้

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);

ดูรายการตัวแปรสภาพแวดล้อมที่รองรับทั้งหมด

ใช้ App.config

ในแอปพลิเคชัน .NET Framework การตั้งค่าทั้งหมดที่เจาะจงสำหรับ Google Ads API จะจัดเก็บไว้ในโหนด GoogleAdsApi ของไฟล์ App.config การกำหนดค่า App.config โดยทั่วไปมีดังนี้

<?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>

หากต้องการโหลดการตั้งค่าการกำหนดค่าจากไฟล์ App.config ให้เรียกใช้เมธอด LoadFromDefaultAppConfigSection ในออบเจ็กต์ 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);

ระบุไฟล์การกำหนดค่า App.config แยกต่างหาก

หากไม่ต้องการให้ App.config ดูรก คุณสามารถย้ายการกำหนดค่าเฉพาะไลบรารีไปยังไฟล์การกำหนดค่าของไลบรารีเองได้โดยใช้พร็อพเพอร์ตี้ configSource ดังนี้

  1. ระบุ configSource ใน App.config แก้ไข App.config เพื่ออ้างอิงไฟล์การกำหนดค่าภายนอก:

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

  2. ระบุเนื้อหาของไฟล์การกำหนดค่า สร้างไฟล์การกำหนดค่าอีกไฟล์หนึ่งโดยใช้ชื่อที่คุณระบุใน configSource (GoogleAdsApi.config) และย้ายโหนดการกำหนดค่า GoogleAdsApi จาก App.config ไปยังไฟล์นี้

    <?xml version="1.0" encoding="utf-8" ?>
<GoogleAdsApi>
  <!-- More settings. -->
</GoogleAdsApi>

  3. อัปเดตกฎการสร้างใน .csproj รวมไฟล์การกำหนดค่าใหม่ในโปรเจ็กต์และตั้งค่าพร็อพเพอร์ตี้คัดลอกไปยังไดเรกทอรีเอาต์พุตเป็นคัดลอกเสมอ สร้างและเรียกใช้โปรเจ็กต์อีกครั้งเพื่อให้แอปพลิเคชันรับค่าจากไฟล์การกำหนดค่าใหม่

ใช้สตรีมทั่วไป

นอกจากนี้ คุณยังโหลดการกำหนดค่าหรือบางส่วนของการกำหนดค่าจากสตรีมทั่วไปได้ด้วย ซึ่งรวมถึงสตรีมที่เข้ารหัส ดังนี้

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);

ฟิลด์กำหนดค่า

ส่วนต่อไปนี้แสดงการตั้งค่าที่ไลบรารี .NET ของ Google Ads รองรับ

การตั้งค่าการเชื่อมต่อ

  • Timeout: ใช้คีย์นี้เพื่อตั้งค่าระยะหมดเวลาของบริการเป็นมิลลิวินาที ระบบจะตั้งค่าเริ่มต้นตามการตั้งค่า method_config/timeout ใน googleads_grpc_service_config.json ตั้งค่าให้ต่ำลงหากคุณต้องการบังคับใช้ขีดจำกัดที่สั้นลงสำหรับเวลาสูงสุดในการเรียก API คุณสามารถตั้งค่าระยะหมดเวลาเป็น 2 ชั่วโมงขึ้นไปได้ แต่ API อาจยังคงหมดเวลาสำหรับคำขอที่ใช้เวลานานมากและแสดงข้อผิดพลาด DEADLINE_EXCEEDED
  • ProxyServer: ตั้งค่านี้เป็น URL ของพร็อกซีเซิร์ฟเวอร์ HTTP หากคุณใช้พร็อกซีเพื่อเชื่อมต่ออินเทอร์เน็ต
  • ProxyUser: ตั้งค่านี้เป็นชื่อผู้ใช้ที่คุณต้องการใช้ตรวจสอบสิทธิ์กับพร็อกซีเซิร์ฟเวอร์ เว้นว่างไว้หากไม่จำเป็นต้องใช้ชื่อผู้ใช้
  • ProxyPassword: ตั้งค่านี้เป็นรหัสผ่านของ ProxyUser หากคุณตั้งค่าสำหรับ ProxyUser
  • ProxyDomain: ตั้งค่านี้เป็นโดเมนสำหรับ ProxyUser หากพร็อกซีเซิร์ฟเวอร์ของคุณกำหนดให้ต้องตั้งค่า
  • MaxReceiveMessageLengthInBytes: ใช้การตั้งค่านี้เพื่อเพิ่มขนาดสูงสุดของการตอบกลับจาก API ที่ไลบรารีของไคลเอ็นต์สามารถจัดการได้ ค่าเริ่มต้นคือ 64 MB
  • MaxMetadataSizeInBytes: ใช้การตั้งค่านี้เพื่อเพิ่มขนาดสูงสุดของการตอบกลับข้อผิดพลาดของ API ที่ไลบรารีของไคลเอ็นต์สามารถจัดการได้ ค่าเริ่มต้นคือ 16 MB

ปรับการตั้งค่า MaxReceiveMessageLengthInBytes และ MaxMetadataSizeInBytes เพื่อแก้ไขข้อผิดพลาด ResourceExhausted บางอย่าง การตั้งค่าเหล่านี้จะแก้ไขข้อผิดพลาดของแบบฟอร์มต่อไปนี้

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

ในตัวอย่างนี้ ข้อผิดพลาดเกิดจากขนาดข้อความ (423184132 bytes) ใหญ่กว่าที่ไลบรารีจะจัดการได้ (67108864 bytes) โปรดเพิ่ม MaxReceiveMessageLengthInBytes เป็น 500000000 เพื่อหลีกเลี่ยงข้อผิดพลาดนี้ โปรดทราบว่าข้อผิดพลาดนี้ยังระบุด้วยว่าโค้ดของคุณจัดการออบเจ็กต์การตอบกลับที่มีขนาดใหญ่มาก (เช่น SearchGoogleAdsResponse ขนาดใหญ่) ซึ่งอาจส่งผลต่อประสิทธิภาพของโค้ดเนื่องจาก Large Object Heap ของ .NET หากปัญหานี้ส่งผลต่อประสิทธิภาพ คุณอาจต้องพิจารณาวิธีจัดระเบียบการเรียก API ใหม่หรือออกแบบบางส่วนของแอปใหม่

การตั้งค่า OAuth2

เมื่อใช้ OAuth 2.0 เพื่อให้สิทธิ์การเรียกเซิร์ฟเวอร์ Google Ads API คุณควรกำหนดคีย์การกำหนดค่าต่อไปนี้

  • AuthorizationMethod: ตั้งค่าเป็น OAuth2
  • OAuth2Mode: ตั้งค่าเป็น APPLICATION หรือ SERVICE_ACCOUNT
  • OAuth2ClientId: ตั้งค่านี้เป็นรหัสไคลเอ็นต์ OAuth 2.0
  • OAuth2ClientSecret: ตั้งค่านี้เป็นรหัสลับไคลเอ็นต์ OAuth 2.0
  • OAuth2Scope: ตั้งค่านี้เป็นขอบเขตต่างๆ หากต้องการให้สิทธิ์โทเค็น OAuth 2.0 สำหรับ API หลายรายการ การตั้งค่านี้ไม่บังคับ
  • UseApplicationDefaultCredentials: ตั้งค่านี้เป็น true เพื่อตรวจสอบสิทธิ์โดยใช้ข้อมูลรับรองเริ่มต้นของแอปพลิเคชัน (รองรับใน Google.Ads.GoogleAds v24.1.0 และใหม่กว่า โดย config.LoadFromEnvironmentVariables() จะอ่านตัวแปรสภาพแวดล้อม USE_APPLICATION_DEFAULT_CREDENTIALS ที่ไม่มีคำนำหน้า)
  • Credentials: (รันไทม์เท่านั้น รองรับใน v27.0.0 ขึ้นไป) แทรกอินสแตนซ์ ICredential หรือ GoogleCredential ที่สร้างไว้ล่วงหน้าโดยตรงใน GoogleAdsConfig ขณะรันไทม์

หากใช้ OAuth2Mode == APPLICATION คุณจะต้องตั้งค่าคีย์การกำหนดค่าเพิ่มเติมต่อไปนี้

  • OAuth2RefreshToken: ตั้งค่านี้เป็นโทเค็นการรีเฟรช OAuth 2.0 ที่สร้างไว้ล่วงหน้าหากต้องการใช้โทเค็น OAuth 2.0 ซ้ำ การตั้งค่านี้ไม่บังคับ
  • OAuth2RedirectUri: ตั้งค่านี้เป็น URL เปลี่ยนเส้นทาง OAuth 2.0 การตั้งค่านี้ไม่บังคับ

ดูรายละเอียดเพิ่มเติมได้ที่คำแนะนำต่อไปนี้

หากใช้ OAuth2Mode == SERVICE_ACCOUNT คุณจะต้องตั้งค่าคีย์การกำหนดค่าเพิ่มเติมต่อไปนี้

  • OAuth2SecretsJsonPath: ตั้งค่านี้เป็นเส้นทางของไฟล์คีย์ JSON ของ OAuth 2.0
  • OAuth2PrnEmail: ตั้งค่านี้เป็นอีเมลของบัญชีที่คุณกำลังแอบอ้างเมื่อใช้การมอบสิทธิ์ทั่วทั้งโดเมนของ Google Workspace การตั้งค่านี้ไม่บังคับ

ดูรายละเอียดเพิ่มเติมได้ที่คู่มือขั้นตอนการใช้บัญชีบริการ OAuth

การตั้งค่าการขนส่ง

  • UseGrpcCore: ตั้งค่านี้เป็น true เพื่อใช้ไลบรารี Grpc.Core เป็นเลเยอร์การรับส่งข้อมูลที่สำคัญ ดูหัวข้อใช้ไลบรารี Grpc.Core

การตั้งค่า Google Ads API

การตั้งค่าต่อไปนี้ใช้กับ Google Ads API โดยเฉพาะ

  • LoginCustomerId: รหัสลูกค้าของลูกค้าที่ได้รับอนุญาตให้ใช้ในคำขอ โดยไม่มีขีดกลาง (-)
  • LinkedCustomerId: ส่วนหัวนี้จำเป็นสำหรับเมธอดที่อัปเดตทรัพยากรของเอนทิตีเมื่อได้รับสิทธิ์ผ่านบัญชีที่ลิงก์ใน UI ของ Google Ads (ทรัพยากร AccountLink ใน Google Ads API) เท่านั้น ตั้งค่านี้เป็นรหัสลูกค้าของผู้ให้บริการข้อมูลที่อัปเดตทรัพยากรของรหัสลูกค้าที่ระบุ โดยควรตั้งค่าโดยไม่มีขีดกลาง (-) ดูข้อมูลเพิ่มเติมเกี่ยวกับบัญชีที่ลิงก์