Cấu hình

Thư viện ứng dụng Google Ads API PHP 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.

Tệp cấu hình

Bạn có thể lưu trữ hầu hết các chế độ cài đặt cấu hình này trong tệp cấu hình INI và sử dụng chúng khi tạo thực thể cho các ứng dụng, ví dụ: google_ads_php.ini.

Trình tạo thông tin đăng nhập và trình tạo ứng dụng đều cung cấp các phương thức fromFile để tải chế độ cài đặt từ các tệp như vậy:

$oAuth2Credential = (new OAuth2TokenBuilder())
    ->fromFile('/path/to/google_ads_php.ini')
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->fromFile('/path/to/google_ads_php.ini')
    ->withOAuth2Credential($oAuth2Credential)
    ->build();

Nếu không có đường dẫn cấu hình nào được cung cấp dưới dạng đối số, thì các phương thức fromFile sẽ tải từ đường dẫn cấu hình mặc định, đó là:

  1. Giá trị của biến môi trường có tên là GOOGLE_ADS_CONFIGURATION_FILE_PATH (nếu được đặt).
  2. Nếu không, tệp google_ads_php.ini sẽ nằm trong thư mục HOME.
$oAuth2Credential = (new OAuth2TokenBuilder())
    ->fromFile()
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->fromFile()
    ->withOAuth2Credential($oAuth2Credential)
    ->build();

Cấu hình động

Bạn có thể đặt các chế độ cài đặt cấu hình này một cách linh động khi tạo thực thể cho các ứng dụng:

$oAuth2Credential = (new OAuth2TokenBuilder())
    ->withClientId('INSERT_CLIENT_ID_HERE')
    ->withClientSecret('INSERT_CLIENT_SECRET_HERE')
    ->withRefreshToken('INSERT_REFRESH_TOKEN_HERE')
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->withOAuth2Credential($oAuth2Credential)
    ->build();

Biến môi trường cấu hình

Bạn có thể đặt một số chế độ cài đặt cấu hình từ các biến môi trường khi khởi tạo các ứng dụng (xem các biến môi trường tiêu chuẩn).

Cả trình tạo thông tin đăng nhập và trình tạo ứng dụng đều cung cấp các phương thức fromEnvironmentVariables để tải chế độ cài đặt từ các biến môi trường.

$oAuth2Credential = (new OAuth2TokenBuilder())
    // ...
    ->fromEnvironmentVariables()
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->withOAuth2Credential($oAuth2Credential)
    // ...
    ->fromEnvironmentVariables()
    ->build();

Trường cấu hình

Chế độ cài đặt cấu hình hỗ trợ một số trường được sắp xếp theo danh mục:

  1. Các trường mà OAuth2TokenBuilder sử dụng:
    • Chế độ ứng dụng:
      • [OAUTH2] clientId: Mã ứng dụng OAuth2 của bạn.
      • [OAUTH2] clientSecret: Khoá bí mật của ứng dụng OAuth2.
      • [OAUTH2] refreshToken: Mã làm mới OAuth2 của bạn.
    • Chế độ tài khoản dịch vụ:
      • [OAUTH2] jsonKeyFilePath: Đường dẫn khoá JSON.
      • [OAUTH2] scopes: Các phạm vi OAuth2 (mặc định là https://www.googleapis.com/auth/adwords trong v32.1.0 trở lên; bắt buộc trong các phiên bản trước v32.1.0 hoặc khi sử dụng các phạm vi tuỳ chỉnh; fromEnvironmentVariables() không đọc từ biến môi trường).
      • [OAUTH2] impersonatedEmail: Địa chỉ email không bắt buộc để mạo danh khi sử dụng tính năng uỷ quyền trên toàn miền của Google Workspace.
    • Chế độ Thông tin xác thực mặc định của ứng dụng:
      • Khi bạn không đặt trường Chế độ ứng dụng và trường Chế độ tài khoản dịch vụ, OAuth2TokenBuilder sẽ tự động quay lại Thông tin đăng nhập mặc định của ứng dụng (ADC).
  2. Các trường mà GoogleAdsClientBuilder sử dụng:
    • [GOOGLE_ADS] developerToken: (Ngừng hoạt động vào ngày 9 tháng 9 năm 2026) Mã thông báo nhà phát triển Google Ads API. Không bắt buộc, máy chủ API sẽ bỏ qua bất kể phiên bản thư viện ứng dụng và sẽ bị từ chối trong phiên bản lớn sau này của Google Ads API.
      • v35.0.0 trở lên: Không bắt buộc khi khởi động ứng dụng (GoogleAdsClientBuilder đã xoá quy trình xác thực mã của nhà phát triển phía máy khách cục bộ).
      • Các phiên bản trước v35.0.0: Bắt buộc phải có quy trình xác thực cấu hình phía máy khách cục bộ.
    • [GOOGLE_ADS] loginCustomerId: Mã nhận dạng của khách hàng được uỷ quyền để sử dụng trong yêu cầu.
    • [GOOGLE_ADS] linkedCustomerId: Mã khách hàng được liên kết.
    • [GOOGLE_ADS] endpoint: Điểm cuối máy chủ Google Ads API thay thế (không bắt buộc).
    • [LOGGING] logFilePath: Đường dẫn cho đầu ra ghi nhật ký.
    • [LOGGING] logLevel: Cấp ghi nhật ký.
    • [CONNECTION] proxy: URL của máy chủ proxy dùng để kết nối Internet.
    • [CONNECTION] transport: Phương thức truyền tải mạng (grpc hoặc rest).
    • [CONNECTION] grpcChannelIsSecure: Liệu kênh gRPC có an toàn hay không.
    • [CONNECTION] grpcChannelCredential: Thông tin đăng nhập kênh gRPC.
    • [CONNECTION] unaryMiddlewares: Các phần mềm trung gian đơn nguyên.
    • [CONNECTION] streamingMiddlewares: Các phần mềm trung gian truyền phát trực tiếp.
    • [CONNECTION] grpcInterceptors: Trình chặn gRPC.

Xác thực cấu hình

Các chế độ cài đặt cấu hình sẽ được kiểm tra khi khởi tạo các ứng dụng và ngoại lệ sẽ được đưa ra khi không hợp lệ. Các quy tắc xác thực như sau:

  1. Bạn không được đặt các trường [OAUTH2] cho cả chế độ Ứng dụng và chế độ Tài khoản dịch vụ cùng một lúc.
  2. Bạn phải đặt [OAUTH2] jsonKeyFilePath khi sử dụng chế độ Tài khoản dịch vụ (trong các phiên bản trước v32.1.0, bạn cũng phải đặt [OAUTH2] scopes; trong v32.1.0 trở lên, scopes mặc định là https://www.googleapis.com/auth/adwords).
  3. Bạn phải đặt [OAUTH2] clientId, [OAUTH2] clientSecret và [OAUTH2] refreshToken khi sử dụng chế độ Ứng dụng.
  4. Trong các phiên bản trước v35.0.0, [GOOGLE_ADS] developerToken được kiểm tra bằng quy trình xác thực phía máy khách cục bộ (trong v35.0.0 trở lên, [GOOGLE_ADS] developerToken không bắt buộc).
  5. Nếu được đặt, [GOOGLE_ADS] loginCustomerId và [GOOGLE_ADS] linkedCustomerId phải là số dương.
  6. Nếu được đặt, [CONNECTION] proxy phải là một URL hợp lệ (xem bộ lọc FILTER_VALIDATE_URL).
  7. Nếu được đặt, [LOGGING] logLevel phải là một cấp nhật ký PSR hợp lệ bằng chữ in hoa, chẳng hạn như INFO.
  8. Nếu được đặt, [CONNECTION] transport phải là grpc hoặc rest.
  9. Nếu [CONNECTION] transport được đặt thành grpc, thì môi trường phải hỗ trợ phương thức truyền tải gRPC (xem Hướng dẫn về phương thức truyền tải).
  10. [CONNECTION] grpcChannelIsSecure phải là true khi [CONNECTION] transport không được đặt thành grpc (các kết nối REST luôn yêu cầu HTTPS).
  11. Bạn chỉ có thể đặt [CONNECTION] grpcChannelCredential khi [CONNECTION] transport được đặt thành grpc.
  12. Bạn chỉ có thể đặt [CONNECTION] grpcChannelCredential khi [CONNECTION] grpcChannelIsSecure là true.