Cấu hình

Thư viện ứng dụng API Google Ads cung cấp nhiều chế độ cài đặt cấu hình mà bạn có thể dùng để tuỳ chỉnh hành vi của thư viện.

Định cấu hình thư viện trong thời gian chạy

Cách ưu tiên để định cấu hình thư viện ứng dụng là khởi chạy một Đối tượng GoogleAdsConfig trong thời gian chạy:

GoogleAdsConfig config = new GoogleAdsConfig()
{
    DeveloperToken = "******",
    OAuth2Mode = OAuth2Flow.APPLICATION,
    OAuth2ClientId = "******.apps.googleusercontent.com",
    OAuth2ClientSecret = "******",
    OAuth2RefreshToken = "******"
};

GoogleAdsClient client = new GoogleAdsClient(config);

Các lựa chọn cấu hình thay thế

Chúng tôi cũng cung cấp một số tuỳ chọn bổ sung để định cấu hình thư viện ứng dụng: để bật chúng, hãy thêm tham chiếu Nuget vào Google.Ads.GoogleAds.Extensions gói dữ liệu trong dự án của bạn.

Nếu bạn sử dụng một trong các lựa chọn này, các chế độ cài đặt cấu hình sẽ không được chọn tự động: bạn nên tải các quảng cáo đó một cách rõ ràng như minh hoạ dưới đây.

Định cấu hình bằng App.config

Mọi chế độ cài đặt dành riêng cho Google Ads API đều được lưu trữ trong GoogleAdsApi nút của tệp App.config. Cấu hình thông thường App.config là sau:

<?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=""/>

    <!-- API-specific settings -->
    <add key="DeveloperToken" value="******"/>

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

Để tải chế độ cài đặt cấu hình từ tệp App.config, hãy gọi phương thức Phương thức LoadFromDefaultAppConfigSection trên đối tượng GoogleAdsConfig:

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

Chỉ định một tệp App.config riêng biệt

Nếu bạn không muốn làm cho App.config của mình trở nên lộn xộn, bạn có thể di chuyển cấu hình dành riêng cho thư viện thành tệp cấu hình riêng bằng cách sử dụng configSource thuộc tính này.

Bước 1: Chỉ định một configSource trong App.config

Sửa đổi App.config của bạn thành dạng như sau:

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

Bước 2: Chỉ định nội dung của tệp cấu hình

Bây giờ, hãy tạo một tệp cấu hình khác có tên mà bạn đã chỉ định trên configSource, và di chuyển nút cấu hình từ App.config vào tệp này:

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

Bước 3: Chỉnh sửa quy tắc bản dựng trong csproj

Cuối cùng, đưa tệp cấu hình mới vào dự án của bạn. Thay đổi thuộc tính của tệp này vào Luôn sao chép vào thư mục đầu ra.

Bây giờ, hãy tạo và chạy dự án của bạn. Ứng dụng của bạn sẽ bắt đầu chọn các giá trị từ tệp cấu hình mới.

Cấu hình bằng tệp JSON tuỳ chỉnh

Bạn có thể sử dụng IConfigurationRoot thực thể để định cấu hình thư viện ứng dụng.

Tạo tệp JSON

Tạo tệp JSON có tên GoogleAdsApi.json có cấu trúc tương tự như tệp App.config.

{
    "Timeout": "2000",

    "ProxyServer": "http://localhost:8888",
    "ProxyUser": "",
    "ProxyPassword": "",
    "ProxyDomain": "",

    "DeveloperToken": "******",

    "OAuth2Mode": "APPLICATION",
    "OAuth2ClientId": "******.apps.googleusercontent.com",
    "OAuth2ClientSecret": "******",
    "OAuth2RefreshToken": "******",
}

Tải cấu hình

Tiếp theo, hãy tải tệp JSON vào IConfigurationRoot.

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

Cấu hình bằng cách sử dụng tệp settings.json

Quá trình này tương tự như khi sử dụng một JSON tuỳ chỉnh, ngoại trừ việc các khoá phải nằm trong phần có tên GoogleAdsApi:

{
    "GoogleAdsApi":
    {
        "DeveloperToken": "******",
        "OAuth2Mode": "APPLICATION",
        "OAuth2ClientId": "******.apps.googleusercontent.com",
        "OAuth2ClientSecret": "******",
        "OAuth2RefreshToken": "******",
        ...
    }
    // More settings...
}

Tiếp theo, bạn có thể sử dụng thực thể IConfiguration trên trang của mình:

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

Cấu hình sử dụng các biến môi trường

Bạn cũng có thể khởi chạy GoogleAdsClient bằng các biến môi trường:

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

Xem danh sách đầy đủ các môi trường được hỗ trợ .

Trường cấu hình

Sau đây là danh sách các chế độ cài đặt mà thư viện Google Ads .NET hỗ trợ.

Cài đặt kết nối

  • Timeout: Sử dụng khoá này để đặt thời gian chờ của dịch vụ tính bằng mili giây. Chiến lược phát hành đĩa đơn giá trị mặc định được đặt dựa trên chế độ cài đặt method_config/timeout trong googleads_grpc_service_config.json. Hãy đặt một giá trị thấp hơn nếu bạn cần thực thi giới hạn ngắn hơn về thời gian tối đa cho lệnh gọi API. Bạn có thể đặt thời gian chờ thành 2 giờ trở lên, nhưng API có thể các yêu cầu chạy cực kỳ dài và trả về một Lỗi DEADLINE_EXCEEDED.
  • ProxyServer: Đặt URL này thành URL máy chủ proxy HTTP nếu bạn đang sử dụng proxy để kết nối với Internet.
  • ProxyUser: Đặt thuộc tính này thành tên người dùng mà bạn yêu cầu để xác thực máy chủ proxy. Hãy để trống trường này nếu không bắt buộc phải nhập tên người dùng.
  • ProxyPassword: Đặt thành mật khẩu ProxyUser nếu bạn đặt giá trị trong ProxyUser.
  • ProxyDomain: Đặt thành miền này cho ProxyUser nếu máy chủ proxy của bạn bạn cần đặt một mã.
  • MaxReceiveMessageLengthInBytes: Sử dụng chế độ cài đặt này để tăng mức tối đa kích thước của phản hồi API mà thư viện ứng dụng có thể xử lý. Mặc định có giá trị là 64 MB.
  • MaxMetadataSizeInBytes: Sử dụng chế độ cài đặt này để tăng mức tối đa kích thước của phản hồi lỗi API mà thư viện ứng dụng có thể xử lý. Chiến lược phát hành đĩa đơn giá trị mặc định là 16 MB.

Điều chỉnh MaxReceiveMessageLengthInBytes và MaxMetadataSizeInBytes để sửa một số lỗi ResourceExhausted nhất định. Các chế độ cài đặt này địa chỉ lỗi trong biểu mẫu Status(StatusCode="ResourceExhausted",Detail="Received message larger than max (423184132 versus 67108864)".

Trong ví dụ này, lỗi là do kích thước thông báo (423184132 bytes) lớn hơn khả năng xử lý của thư viện (67108864 bytes). Tăng MaxReceiveMessageLengthInBytes sang 500000000 để tránh lỗi này.

Xin lưu ý rằng lỗi này cũng cho biết rằng mã của bạn đã xử lý đáng kể đối tượng Phản hồi lớn (chẳng hạn như một SearchGoogleAdsResponse). Chiến dịch này có thể ảnh hưởng đến hiệu suất mã của bạn do Đối tượng lớn của .NET Vùng nhớ khối xếp. Nếu điều này trở thành mối lo ngại về hiệu suất, thì bạn có thể phải tìm hiểu cách sắp xếp lại các lệnh gọi API hoặc thiết kế lại các phần trong ứng dụng.

Cài đặt OAuth2

Khi sử dụng OAuth2 để cho phép các lệnh gọi của bạn đến máy chủ API Google Ads, bạn nên đặt các khoá cấu hình sau:

  • AuthorizationMethod: Đặt thành OAuth2.
  • OAuth2Mode: Đặt thành APPLICATION hoặc SERVICE_ACCOUNT.
  • OAuth2ClientId: Đặt giá trị này thành mã ứng dụng khách OAuth2.
  • OAuth2ClientSecret: Đặt giá trị này thành mật khẩu ứng dụng OAuth2.
  • OAuth2Scope: Đặt giá trị này thành các phạm vi khác nhau nếu bạn muốn uỷ quyền Mã thông báo OAuth2 cho nhiều API. Đây là chế độ cài đặt không bắt buộc.

Nếu đang sử dụng OAuth2Mode == APPLICATION, thì bạn cần đặt các tham số sau khoá cấu hình bổ sung.

  • OAuth2RefreshToken: Đặt giá trị này thành mã làm mới OAuth2 được tạo trước nếu bạn muốn sử dụng lại mã thông báo OAuth2. Đây là chế độ cài đặt không bắt buộc.
  • OAuth2RedirectUri: Đặt giá trị này thành URL chuyển hướng OAuth2. Chế độ cài đặt này là tuỳ chọn.

Hãy xem các hướng dẫn sau để biết thêm thông tin chi tiết:

Nếu đang sử dụng OAuth2Mode == SERVICE_ACCOUNT, thì bạn cần đặt giá trị sau đây là các khoá cấu hình bổ sung.

  • OAuth2PrnEmail: Đặt giá trị này thành địa chỉ email của tài khoản mạo danh.
  • OAuth2SecretsJsonPath: Đặt giá trị này thành cấu hình JSON của OAuth2 đường dẫn tệp.

Xem quy trình tài khoản dịch vụ OAuth để biết thêm chi tiết.

Cài đặt phương tiện đi lại

  • UseGrpcCore: Đặt chế độ cài đặt này thành true để dùng thư viện Grpc.Core làm tầng truyền tải cơ bản. Xem phần hỗ trợ gRPC để biết thêm chi tiết.

Cài đặt API Google Ads

Các chế độ cài đặt sau đây dành riêng cho API Google Ads.

  • DeveloperToken: Đặt giá trị này thành mã của nhà phát triển.
  • LoginCustomerId: Đây là mã khách hàng của khách hàng được uỷ quyền sử dụng trong yêu cầu không có dấu gạch nối (-).
  • LinkedCustomerId: Tiêu đề này chỉ bắt buộc cho các phương thức cập nhật của một pháp nhân khi được cấp quyền thông qua Tài khoản được liên kết trong Giao diện người dùng Google Ads (tài nguyên AccountLink trong API Google Ads). Đặt giá trị này thành mã khách hàng của nhà cung cấp dữ liệu cập nhật các tài nguyên của mã khách hàng. Giá trị này phải được đặt không có dấu gạch nối (-). Tìm hiểu thêm về thẻ Được liên kết Tài khoản.