Cấu hình

Bạn có thể định cấu hình thư viện ứng dụng Python bằng tệp YAML, biến môi trường, chuỗi YAML hoặc dict.

Cấu hình xác thực

Có nhiều cách để quản lý thông tin đăng nhập OAuth cần thiết để truy cập vào API Google Ads. Phương pháp bạn chọn sẽ ảnh hưởng đến những trường cấu hình mà bạn sử dụng. Để biết thêm thông tin, hãy xem hướng dẫn xác thực.

Định cấu hình bằng tệp YAML

Bạn có thể chỉ định một tệp YAML để sử dụng khi khởi tạo ứng dụng khách chứa thông tin cần thiết để đưa ra yêu cầu cho Google Ads API. Tệp này được truy cập khi một ứng dụng được khởi tạo bằng phương thức load_from_storage. Cách dễ nhất để tạo tệp này là sao chép ví dụ google-ads.yaml từ kho lưu trữ GitHub rồi sửa đổi để thêm thông tin đăng nhập của bạn, bao gồm cả mã làm mới, mã ứng dụng và khoá bí mật của ứng dụng.

Nếu bạn không cung cấp đường dẫn, thư viện sẽ tìm tệp trong thư mục $HOME của bạn:

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage()

Để chỉ định vị trí của tệp google-ads.yaml, bạn có thể truyền đường dẫn dưới dạng một chuỗi đến phương thức khi gọi phương thức đó:

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage("path/to/google-ads.yaml")

Bạn cũng có thể chỉ định đường dẫn bằng cách xác định một biến môi trường cụ thể:

import os
from google.ads.googleads.client import GoogleAdsClient

os.environ["GOOGLE_ADS_CONFIGURATION_FILE_PATH"] = "path/to/google-ads.yaml"
client = GoogleAdsClient.load_from_storage()

Nếu cả hai giá trị đều được cung cấp (một đường dẫn được truyền vào phương thức và biến môi trường xuất hiện), thì thư viện sẽ ưu tiên đường dẫn được truyền vào phương thức.

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

Bạn có thể lưu trữ tất cả cấu hình ứng dụng dưới dạng các biến môi trường. Các biến này sẽ được đọc khi bạn sử dụng phương thức load_from_env của ứng dụng. Các biến môi trường phải có cùng tên với các biến được xác định trong tệp google-ads.yaml, nhưng phải viết hoa toàn bộ và có tiền tố là không gian tên GOOGLE_ADS_. Ví dụ: client_id phải được lưu trữ dưới dạng GOOGLE_ADS_CLIENT_ID.

Các biến môi trường thường được xác định trong tệp cấu hình bash, chẳng hạn như tệp .bashrc hoặc .bash_profile nằm trong thư mục $HOME. Bạn cũng có thể xác định các tham số này bằng dòng lệnh.

Dưới đây là một số bước cơ bản để xác định một biến môi trường bằng cách sử dụng tệp .bashrc trong một thiết bị đầu cuối:

# Append the line "export GOOGLE_ADS_CLIENT_ID=1234567890" to
# the bottom of your .bashrc file.
echo "export GOOGLE_ADS_CLIENT_ID=1234567890" >> ~/.bashrc
# Update your bash environment to use the most recently updated
# version of your .bashrc file.
source ~/.bashrc

Bạn cũng có thể thiết lập các biến môi trường trong phiên bản thiết bị đầu cuối ngay từ dòng lệnh:

export GOOGLE_ADS_CLIENT_ID=1234567890
echo $GOOGLE_ADS_CLIENT_ID

Phương thức load_from_env tải dữ liệu cấu hình từ thuộc tính environ trên mô-đun os tích hợp của Python. Ví dụ: os.environ["GOOGLE_ADS_CLIENT_ID"]

Dưới đây là ví dụ về cách khởi tạo một phiên bản ứng dụng bằng cấu hình từ các biến môi trường:

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_env()

Để định cấu hình logging thông qua các biến môi trường, giá trị cấu hình phải là một đối tượng JSON khớp với cấu trúc của các khoá YAML trong tệp cấu hình google-ads.yaml mẫu.

Sau đây là ví dụ về cách thiết lập bằng tệp .bashrc:

export GOOGLE_ADS_LOGGING='{
  "version": 1,
  "disable_existing_loggers": false,
  "formatters": {
    "default_fmt": {
      "format": "[%(asctime)s - %(levelname)s] %(message).5000s",
      "datefmt": "%Y-%m-%d %H:%M:%S"
    }
  },
  "handlers": {
    "default_handler": {
      "class": "logging.StreamHandler",
      "formatter": "default_fmt"
    }
  },
  "loggers": {
    "": {
      "handlers": ["default_handler"],
      "level": "INFO"
    }
  }
}'

Điểm mấu chốt: Nếu biến môi trường GOOGLE_ADS_CONFIGURATION_FILE_PATH được đặt khi phương thức load_from_env được gọi, thì các giá trị cấu hình sẽ được truy xuất từ tệp google-ads.yaml nằm ở đường dẫn đã chỉ định, chứ không phải từ các biến môi trường được mô tả trước đó.

Cấu hình bằng chuỗi YAML

Nếu đã đọc một tệp YAML vào bộ nhớ, bạn có thể cung cấp tệp đó trực tiếp cho ứng dụng khi khởi tạo. Để thực hiện việc này, hãy sử dụng phương thức load_from_string:

from google.ads.googleads.client import GoogleAdsClient

with open("/path/to/yaml", "r", encoding="utf-8") as handle:
    yaml_content = handle.read()

client = GoogleAdsClient.load_from_string(yaml_content)

Định cấu hình bằng dict

Bạn có thể chuyển trực tiếp một dict đến phương thức load_from_dict. Ví dụ:

from google.ads.googleads.client import GoogleAdsClient

credentials = {
    "refresh_token": "YOUR_REFRESH_TOKEN",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "use_proto_plus": True,
}

client = GoogleAdsClient.load_from_dict(credentials)

Trường cấu hình

Cấu hình thư viện ứng dụng hỗ trợ các trường sau.

Xác thực

Chỉ sử dụng một trong các nhóm trường này, tuỳ thuộc vào phương pháp xác thực mà bạn đang sử dụng:

  • Một người dùng có thông tin đăng nhập mặc định của ứng dụng (tài liệu)
    • use_application_default_credentials: Thư viện có nên sử dụng thông tin đăng nhập mặc định của ứng dụng (ADC) để xác thực hay không (được hỗ trợ trong google-ads v28.3.0 trở lên).
  • Một người dùng có mã thông báo OAuth (tài liệu)
    • client_id: Mã ứng dụng OAuth của bạn.
    • client_secret: Khoá bí mật của ứng dụng OAuth.
    • refresh_token: Mã làm mới OAuth của bạn.
  • Tài khoản dịch vụ (tài liệu)
    • json_key_file_path: Đường dẫn đến một tệp khoá riêng tư cục bộ. Khoá này được dùng để xác thực bằng tài khoản dịch vụ.
    • impersonated_email: Địa chỉ email không bắt buộc của tài khoản cần mạo danh khi sử dụng tính năng uỷ quyền trên toàn miền của Google Workspace.

Hành vi của thư viện

Các trường này quy định hành vi của thư viện:

Cấu hình cấp yêu cầu

Biến môi trường

Để định cấu hình thư viện bằng các biến môi trường, hãy sử dụng như sau:

  • GOOGLE_ADS_ADS_ASSISTANT
  • GOOGLE_ADS_CLIENT_ID
  • GOOGLE_ADS_CLIENT_SECRET
  • GOOGLE_ADS_CONFIGURATION_FILE_PATH
  • GOOGLE_ADS_ENDPOINT
  • GOOGLE_ADS_HTTP_PROXY
  • GOOGLE_ADS_IMPERSONATED_EMAIL
  • GOOGLE_ADS_JSON_KEY_FILE_PATH
  • GOOGLE_ADS_LINKED_CUSTOMER_ID
  • GOOGLE_ADS_LOGIN_CUSTOMER_ID
  • GOOGLE_ADS_LOGGING
  • GOOGLE_ADS_REFRESH_TOKEN
  • GOOGLE_ADS_USE_PROTO_PLUS
  • GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS (được hỗ trợ trong v28.3.0 trở lên)

Cấu hình nhật ký

Các trường nhật ký (là các trường nằm bên dưới trường cấu hình logging) được lấy trực tiếp từ mô-đun tích hợp logging.config vì thư viện sẽ truyền tất cả các trường trong không gian tên logging trực tiếp đến phương thức logging.config.dictConfig. Hãy xem hướng dẫn ghi nhật ký để biết thông tin chi tiết đầy đủ.

  • version: Một giá trị số nguyên đại diện cho phiên bản lược đồ.
  • disable_existing_loggers: Có nên tắt các trình ghi nhật ký được định cấu hình ở nơi khác trong ứng dụng hay không.
  • formatters: Từ điển xác định các loại trình định dạng.
  • handlers: Từ điển xác định các trình xử lý khác nhau, kiểm soát vị trí ghi nhật ký và trình định dạng nào sẽ được sử dụng.
  • loggers: Từ điển xác định các loại trình ghi nhật ký, bao gồm một trình xử lý và một cấp độ nhật ký.