Cấu hình

Thư viện ứng dụng Google Ads API cung cấp một số 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 bạn nên dùng để đị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()
{
    OAuth2Mode = OAuth2Flow.APPLICATION,
    OAuth2ClientId = "INSERT_CLIENT_ID.apps.googleusercontent.com",
    OAuth2ClientSecret = "INSERT_CLIENT_SECRET",
    OAuth2RefreshToken = "INSERT_REFRESH_TOKEN"
};

GoogleAdsClient client = new GoogleAdsClient(config);

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

Thư viện này cũng cung cấp các lựa chọn khác để tải chế độ cài đặt cấu hình. Để bật các tính năng này, hãy thêm một tham chiếu NuGet vào gói Google.Ads.GoogleAds.Extensions trong dự án của bạn.

Nếu sử dụng một trong các lựa chọn này, chế độ cài đặt cấu hình sẽ không được tự động chọn; bạn phải tải các chế độ cài đặt đó một cách rõ ràng như minh hoạ trong các phần sau. Đảm bảo xử lý các ngoại lệ I/O của tệp (chẳng hạn như FileNotFoundException hoặc UnauthorizedAccessException) khi tải các chế độ cài đặt từ tệp hoặc luồng bên ngoài.

Sử dụ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. Sau đây là một cấu hình App.config điển hình:

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

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

Để 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 biệt

Nếu không muốn App.config của bạn 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:

1. Chỉ định một configSource trong App.config. Sửa đổi App.config để tham chiếu một tệp cấu hình bên ngoài:

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

2. Chỉ định nội dung của tệp cấu hình. Tạo một tệp cấu hình khác có tên mà bạn đã chỉ định trong configSource (GoogleAdsApi.config) và di chuyển nút cấu hình GoogleAdsApi từ App.config vào tệp này:

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

3. Cập nhật các quy tắc xây dựng trong .csproj. Đưa tệp cấu hình mới vào dự án của bạn và đặt thuộc tính Copy to Output Directory (Sao chép vào thư mục đầu ra) thành Copy always (Luôn sao chép). Xây dựng lại và chạy dự án để ứng dụng của bạn nhận các giá trị từ tệp cấu hình mới.

Sử dụng tệp JSON tuỳ chỉnh

Bạn có thể 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 là GoogleAdsApi.json có cấu trúc tương tự như tệp App.config:

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

Tải cấu hình

Tiếp theo, hãy tải tệp JSON vào một 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);

Sử dụng settings.json

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

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

Tiếp theo, hãy trích xuất phần GoogleAdsApi từ thực thể IConfiguration của ứng dụng (ví dụ: được ASP.NET Core chèn hoặc được tạo bằng ConfigurationBuilder):

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

Ngoài ra, bạn có thể tải trực tiếp một tệp settings.json theo đường dẫn bằng config.LoadFromSettingsJson(filePath, "GoogleAdsApi") hoặc từ biến môi trường GOOGLE_ADS_CONFIGURATION_FILE_PATH (EnvironmentVariableNames.CONFIG_FILE_PATH) bằng config.TryLoadFromEnvironmentFilePath.

Sử dụ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ợ.

Sử dụng luồng chung

Bạn cũng có thể tải cấu hình hoặc các phần của cấu hình từ một luồng chung, bao gồm cả luồng được mã hoá:

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

Trường cấu hình

Các phần sau đây liệt kê những 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. 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ờ là 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 cực kỳ lâu và trả về lỗi DEADLINE_EXCEEDED.
• ProxyServer: Đặt giá trị này thành URL của 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. Để 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 bạn đặt mộ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. Các chế độ cài đặt này giải quyết các lỗi thuộc dạng:

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 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 đá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 Large Object Heap của .NET. Nếu điều này ảnh hưởng đến 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.

Chế độ cài đặt OAuth2

Khi sử dụng OAuth 2.0 để 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 OAuth 2.0.
• OAuth2ClientSecret: Đặt giá trị này thành khoá bí mật của ứng dụng OAuth 2.0.
• 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 OAuth 2.0 cho nhiều API. Đây là chế độ cài đặt không bắt buộc.
• UseApplicationDefaultCredentials: Đặt giá trị này thành true để xác thực bằng Thông tin xác thực mặc định của ứng dụng (được hỗ trợ trong Google.Ads.GoogleAds v24.1.0 trở lên; config.LoadFromEnvironmentVariables() đọc biến môi trường USE_APPLICATION_DEFAULT_CREDENTIALS không có tiền tố).
• Credentials: (Chỉ thời gian chạy, được hỗ trợ trong v27.0.0 trở lên) Chèn một thực thể ICredential hoặc GoogleCredential được tạo sẵn trực tiếp trên GoogleAdsConfig trong thời gian chạ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 OAuth 2.0 được tạo trước nếu bạn muốn sử dụng lại mã thông báo OAuth 2.0. Đâ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 OAuth 2.0. 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 dành cho máy tính
• Quy trình ứng dụng web OAuth

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

• OAuth2SecretsJsonPath: Đặt giá trị này thành đường dẫn của tệp khoá JSON OAuth 2.0.
• OAuth2PrnEmail: Đặt giá trị này thành địa chỉ email của tài khoản mà bạn đang mạo danh khi sử dụng tính năng uỷ quyền trên toàn miền của Google Workspace. Bạn không bắt buộc phải sử dụng chế độ cài đặt này.

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 vận tải

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

Chế độ cài đặt API Google Ads

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

• DeveloperToken: Không bắt buộc trong v27.3.0 trở lên (GOOGLE_ADS_DEVELOPER_TOKEN). Mã thông báo nhà phát triển đã ngừng hoạt động vào ngày 9 tháng 9 năm 2026; trên máy chủ API, các cấp truy cập được xác định theo dự án Google Cloud của bạn, bất kể phiên bản thư viện ứng dụng và máy chủ API bỏ qua tiêu đề developer-token (cho đến khi một phiên bản chính trong tương lai của API Google Ads từ chối tiêu đề này). Để bỏ qua hoặc xoá DeveloperToken khỏi cấu hình, hãy sử dụng Google.Ads.GoogleAds v27.3.0 trở lên. Phiên bản này đã xoá quy trình xác thực DeveloperToken phía máy khách cục bộ (các phiên bản trước yêu cầu DeveloperToken không được để trống để xác thực cục bộ).
• 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 những 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 Google Ads API). Đặ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 mã này mà không có dấu gạch ngang (-). Tìm hiểu thêm về Tài khoản được liên kết.