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ể dùng để tuỳ chỉnh hoạt động 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 đối tượng GoogleAdsConfig trong thời gian chạy:

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

GoogleAdsClient client = new GoogleAdsClient(config);

Tuỳ 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 thư viện này, hãy thêm nội dung tham chiếu Nuget đến gói Google.Ads.GoogleAds.Extensions trong dự án của bạn.

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

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

Tất 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 thông thường của App.config có dạ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ừ mộ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 của mình 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 thuộc tính configSource.

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

Sửa đổi App.config của bạn 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 của bạn

Cuối cùng, hãy thêm tệp cấu hình mới vào dự án. Thay đổi thuộc tính của tệp này thành 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 nhận các giá trị từ tệp cấu hình mới.

Cấu hình bằng một 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 cách sử dụng tệp settings.json

Quá trình nà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 một 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:

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

Cấu hình bằng cách 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ách sử dụ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ợ.

Trường cấu hình

Sau đây là danh sách các chế độ cài đặt mà thư viện .NET của Google Ads 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. 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 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ờ cho các yêu cầu chạy trong thời gian dài và trả về lỗi DEADLINE_EXCEEDED.
• ProxyServer: Thiết lập thành URL máy chủ proxy HTTP nếu bạn đang sử dụng proxy để kết nố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 với 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 thuộc tính này thành mật khẩu của ProxyUser nếu bạn đặt giá trị cho ProxyUser.
• ProxyDomain: Thiết lập 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 thiết lập.
• 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 để sửa một số lỗi ResourceExhausted. Các chế độ cài đặt này sẽ khắc phục lỗi của biểu mẫu 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 có kích thước lớn (chẳng hạn như SearchGoogleAdsResponse có kích thước 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 điều này trở thành vấn đề 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 của ứng dụng.

Cài đặt OAuth2

Khi sử dụng OAuth2 để cho phép các lệnh gọi đến các 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 của bạn.
• OAuth2ClientSecret: Đặt giá trị này thành mật khẩu ứ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 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, bạn cần đặt các khoá cấu hình bổ sung sau đây.

• 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à không bắt buộc.

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

• Quy trình đăng ký OAuth trên máy tính
• Quy trình đăng ký ứ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 đây.

• 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.

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.

Cài đặt phương tiện giao thông

• UseGrpcCore: Đặt chế độ cài đặt này thành true để dùng thư viện Grpc.Core làm lớp truyền tải cơ sở. Hãy xem hướng dẫn hỗ trợ gRPC để biết thêm thông tin chi tiết.

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). Hãy đặt giá trị này thành mã khách hàng của trình cung cấp dữ liệu để cập nhật tài nguyên của mã khách hàng đã chỉ định. Bạn phải đặt thuộc tính 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.