Cấu hình

Thư viện ứng dụng API Google Ads cung cấp một số chế độ cài đặt cấu hình mà bạn có thể sử 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 tạo đố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 các tuỳ chọn này, hãy thêm tệp tham chiếu Nuget vào gói Google.Ads.GoogleAds.Extensions trong dự án.

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

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

Tất cả các chế độ cài đặt dành riêng cho Google Ads API đều được lưu trữ trong nút GoogleAdsApi của tệp App.config. Cấu hình App.config thông thường như 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 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

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

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

Sửa đổi App.config 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: Sửa quy tắc bản dựng trong csproj

Cuối cùng, hãy đư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 thành Always copy to output folder (Luôn sao chép vào thư mục đầu ra).

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

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

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

Tạo tệp JSON

Tạo một 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 tệp settings.json

Quy trình ở đây tương tự như việc sử dụng 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 trong trang của mình:

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

Định cấu hình bằng 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 biến môi trường được hỗ trợ.

Các trường cấu hình

Sau đây là danh sách các chế độ cài đặt được 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ờ dịch vụ tính bằng mili giây. Giá trị mặc định được đặt dựa trên chế độ cài đặt method_config/timeout trong googleads_grpc_service_config.json. Đặ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 một lệnh gọi API. Bạn có thể đặt thời gian chờ thành 2 giờ trở lên, nhưng API vẫn có thể hết thời gian chờ đối với các yêu cầu chạy trong thời gian cực dài và trả về lỗi DEADLINE_EXCEEDED.
• ProxyServer: Đặt giá trị 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 giá trị này thành tên người dùng mà bạn cần để xác thực với máy chủ proxy. Hãy để trống trường này nếu không bắt buộc phải có tên người dùng.
• ProxyPassword: Đặt giá trị này thành mật khẩu của ProxyUser nếu bạn đặt giá trị cho ProxyUser.
• ProxyDomain: Đặt giá trị này thành miền cho ProxyUser nếu máy chủ proxy của bạn yêu cầu phải đặt miền.
• MaxReceiveMessageLengthInBytes: Sử dụng chế độ cài đặt này để tăng kích thước tối đa của phản hồi API mà thư viện ứng dụng có thể xử lý. Giá trị mặc định là 64 MB.
• MaxMetadataSizeInBytes: Sử dụng chế độ cài đặt này để tăng kích thước tối đa của phản hồi lỗi API mà thư viện ứng dụng có thể xử lý. Giá trị mặc định là 16 MB.

Điều chỉnh chế độ cài đặt MaxReceiveMessageLengthInBytes và MaxMetadataSizeInBytes để khắc phục một số lỗi ResourceExhausted nhất định. Các chế độ cài đặt này giải quyết lỗi ở dạng Status(StatusCode="ResourceExhausted",Detail="Received message larger than max (423184132 versus 67108864)".

Trong ví dụ này, lỗi xảy ra do kích thước thông báo (423184132 bytes) lớn hơn kích thước mà thư viện có thể xử lý (67108864 bytes). Hãy tăng MaxReceiveMessageLengthInBytes lên 500000000 để tránh lỗi này.

Xin lưu ý rằng lỗi này cũng cho biết mã của bạn đã xử lý một đối tượng Phản hồi lớn đáng kể (chẳng hạn như một SearchGoogleAdsResponse lớn). Điều này có thể ảnh hưởng đến hiệu suất của mã do Vùng nhớ khối xếp đối tượng lớn của .NET. Nếu vấn đề 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 một số phần của ứng dụng.

Cài đặt OAuth2

Khi sử dụng OAuth2 để uỷ quyền cho các lệnh gọi của bạn đối với 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 OAuth2.
• OAuth2ClientSecret: Đặt giá trị này thành bí mật ứng dụng khách 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 cho mã thông báo OAuth2 cho nhiều API. Bạn không bắt buộc phải sử dụng chế độ cài đặt này.

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

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

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

• Quy trình ứng dụng OAuth trên máy tính
• Quy trình ứng dụng web OAuth

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

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

Hãy xem hướng dẫn về quy trình tài khoản dịch vụ OAuth để biết thêm thông tin chi tiết.

Chế độ cài đặt phương tiện

• UseGrpcCore: Đặt chế độ cài đặt này thành true để sử dụng thư viện Grpc.Core làm lớp truyền tải cơ bản. Xem phần Sử dụng thư viện Grpc cũ.

Chế độ 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 đối với các phương thức cập nhật tài nguyên của một thực thể 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 tài nguyên của mã khách hàng được chỉ định. Bạn nên đặt giá trị này mà không có dấu gạch nối (-). Tìm hiểu thêm về Tài khoản được liên kết.