Xác thực và uỷ quyền

Giống như các API khác của Google, Google Ads API sử dụng giao thức OAuth 2.0 để xác thực và uỷ quyền. OAuth 2.0 cho phép ứng dụng khách Google Ads API truy cập vào tài khoản Google Ads của người dùng mà không cần xử lý hoặc lưu trữ thông tin đăng nhập của người dùng.

Tìm hiểu mô hình truy cập của Google Ads

Để làm việc hiệu quả với Google Ads API, hãy tìm hiểu cách hoạt động của mô hình truy cập của Google Ads. Tham khảo hướng dẫn về mô hình truy cập của Google Ads.

Quy trình OAuth

Có 3 quy trình phổ biến được sử dụng khi làm việc với Google Ads API.

Quy trình tài khoản dịch vụ

Đây là quy trình được đề xuất nếu quy trình của bạn không yêu cầu bất kỳ tương tác nào của con người. Quy trình này yêu cầu một bước định cấu hình, trong đó người dùng thêm một tài khoản dịch vụ vào tài khoản Google Ads của họ. Sau đó, ứng dụng có thể sử dụng thông tin đăng nhập của tài khoản dịch vụ để quản lý tài khoản Google Ads của người dùng. Thư viện Python được định cấu hình như sau:

  • Nếu bạn sử dụng tệp google-ads.yaml hoặc chuỗi YAML, hãy thêm nội dung sau vào cấu hình để đặt đường dẫn đến tệp JSON khoá riêng tư trong môi trường cục bộ (cùng với impersonated_email không bắt buộc nếu bạn sử dụng tính năng uỷ quyền trên toàn miền):

    json_key_file_path: JSON_KEY_FILE_PATH
# Optional: only set if using Google Workspace domain-wide delegation:
# impersonated_email: IMPERSONATED_EMAIL

    Sau đó, hãy gọi các phương thức load_from_storage hoặc load_from_string:

    from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage()

  • Nếu bạn đang sử dụng dict để định cấu hình thư viện, hãy thêm cặp khoá-giá trị sau và gọi phương thức load_from_dict, truyền vào cấu hình dict:

    from google.ads.googleads.client import GoogleAdsClient

configuration = {
    # ...
    "json_key_file_path": JSON_KEY_FILE_PATH,
    # ...
}

client = GoogleAdsClient.load_from_dict(configuration)

  • Nếu bạn đang sử dụng các biến môi trường, hãy thêm nội dung sau vào cấu hình hoặc môi trường bash:

    export GOOGLE_ADS_JSON_KEY_FILE_PATH=JSON_KEY_FILE_PATH

    Sau đó, hãy gọi phương thức load_from_env:

    from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_env()

Nếu tuỳ chọn cấu hình json_key_file_path có trong bất kỳ phương thức cấu hình nào trong số này, tuỳ chọn use_application_default_credentials sẽ là False hoặc chưa được đặt và các khoá thông tin đăng nhập người dùng OAuth (client_id, client_secret và refresh_token) sẽ chưa được đặt hoặc được đánh dấu là nội dung nhận xét, thư viện sẽ tự động uỷ quyền bằng quy trình tài khoản dịch vụ.

Tham khảo hướng dẫn về quy trình tài khoản dịch vụ để tìm hiểu thêm.

Quy trình xác thực một người dùng

Bạn có thể sử dụng quy trình này nếu không sử dụng được tài khoản dịch vụ. Quy trình này yêu cầu 2 bước định cấu hình:

  1. Cấp cho một người dùng quyền truy cập vào tất cả các tài khoản cần quản lý bằng Google Ads API. Một phương pháp phổ biến là cấp cho người dùng quyền truy cập vào tài khoản người quản lý Google Ads API và liên kết tất cả tài khoản Google Ads trong tài khoản người quản lý đó.

  2. Người dùng chạy một công cụ như gcloud CLI hoặc generate_user_credentials ví dụ về mã để uỷ quyền cho ứng dụng của bạn quản lý tất cả tài khoản Google Ads của họ thay mặt họ.

Bạn có thể khởi chạy thư viện bằng thông tin đăng nhập OAuth 2.0 của người dùng như sau:

Nếu bạn sử dụng công cụ gcloud CLI (nên dùng)

  1. Làm theo tài liệu Tạo thông tin đăng nhập để thiết lập thông tin đăng nhập mặc định của ứng dụng (ADC) trong môi trường cục bộ.

  2. Thêm cấu hình sau vào chuỗi google-ads.yaml hoặc YAML:

    use_application_default_credentials: true

    Sau đó, hãy gọi phương thức load_from_storage hoặc load_from_string:

    from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage()

    Nếu bạn sử dụng dict để định cấu hình thư viện, hãy thêm cặp khoá-giá trị sau và gọi phương thức load_from_dict

    from google.ads.googleads.client import GoogleAdsClient

configuration = {
    # ...
    "use_application_default_credentials": True,
    # ...
}

client = GoogleAdsClient.load_from_dict(configuration)

    Nếu bạn đang sử dụng các biến môi trường, hãy thêm nội dung sau vào cấu hình hoặc môi trường bash:

    export GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS=true

    Sau đó, hãy gọi phương thức load_from_env:

    from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_env()

Nếu bạn trực tiếp xử lý mã thông báo OAuth

  1. Làm theo các bước để thiết lập một dự án trên bảng điều khiển và tải tệp JSON xuống. Tệp này bao gồm mã ứng dụng khách và khoá bí mật của ứng dụng khách của dự án.

  2. Sao chép thư viện ứng dụng Python vào máy của bạn và chuyển vào thư mục của thư viện đó:

    git clone https://github.com/googleads/google-ads-python.git
cd google-ads-python

  3. Thực thi ví dụ, cung cấp đường dẫn tuyệt đối đến tệp JSON đã tải xuống ở bước 1:

    python examples/authentication/generate_user_credentials.py \
    -c PATH_TO_CREDENTIALS_JSON

    Sau khi hoàn tất, mã làm mới sẽ in ra bảng điều khiển của bạn. Sao chép mã này và lưu lại cho bước tiếp theo.

  4. Định cấu hình thư viện bằng cách thêm các chế độ cài đặt sau vào cấu hình mà bạn chọn:

    Thêm cấu hình sau vào chuỗi google-ads.yaml hoặc YAML:

    client_id: INSERT_OAUTH2_CLIENT_ID_HERE
client_secret: INSERT_OAUTH2_CLIENT_SECRET_HERE
refresh_token: INSERT_REFRESH_TOKEN_HERE

    Sau đó, hãy gọi phương thức load_from_storage hoặc load_from_string:

    from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage()

    Nếu bạn đang sử dụng một dict để định cấu hình thư viện, hãy thêm các cặp khoá-giá trị sau và gọi phương thức load_from_dict:

    from google.ads.googleads.client import GoogleAdsClient

configuration = {
    # ...
    "client_id": INSERT_OAUTH2_CLIENT_ID_HERE,
    "client_secret": (
        INSERT_OAUTH2_CLIENT_SECRET_HERE
    ),
    "refresh_token": INSERT_REFRESH_TOKEN_HERE,
    # ...
}

client = GoogleAdsClient.load_from_dict(configuration)

    Nếu bạn đang sử dụng các biến môi trường, hãy thêm nội dung sau vào cấu hình hoặc môi trường bash:

    export GOOGLE_ADS_CLIENT_ID=\
INSERT_OAUTH2_CLIENT_ID_HERE
export GOOGLE_ADS_CLIENT_SECRET=\
INSERT_OAUTH2_CLIENT_SECRET_HERE
export GOOGLE_ADS_REFRESH_TOKEN=\
INSERT_REFRESH_TOKEN_HERE

    Sau đó, hãy gọi phương thức load_from_env:

    from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_env()

Tham khảo hướng dẫn về quy trình xác thực một người dùng để tìm hiểu thêm.

Quy trình xác thực nhiều người dùng

Đây là quy trình được đề xuất nếu ứng dụng của bạn cho phép người dùng đăng nhập và uỷ quyền cho ứng dụng của bạn quản lý tài khoản Google Ads của họ thay mặt họ. Ứng dụng của bạn sẽ tạo và quản lý thông tin đăng nhập người dùng OAuth 2.0. Bạn có thể khởi chạy thư viện bằng thông tin đăng nhập của người dùng như sau. Quy trình này giả định rằng ứng dụng của bạn sẽ lấy thông tin đăng nhập trong thời gian chạy, bằng cách thực thi quy trình uỷ quyền hoặc bằng cách tải thông tin đăng nhập đó từ kho lưu trữ dữ liệu:

dict là cơ chế cấu hình đơn giản nhất để sử dụng khi lấy thông tin đăng nhập trong thời gian chạy:

from google.ads.googleads.client import GoogleAdsClient

configuration = {
    # ...
    "client_id": client_id,
    "client_secret": client_secret,
    "refresh_token": refresh_token,
    # ...
}

client = GoogleAdsClient.load_from_dict(configuration)

Tham khảo hướng dẫn về quy trình xác thực nhiều người dùng để tìm hiểu thêm.

Xác thực thủ công

Bạn có thể tạo thông tin đăng nhập xác thực bằng bất kỳ phương pháp nào và cung cấp thông tin đăng nhập đó cho GoogleAdsClient theo cách thủ công bằng cách trực tiếp tạo thực thể cho lớp ứng dụng khách. Giả sử đối tượng thông tin đăng nhập mà bạn tạo là một thực thể của google.auth.credentials.Credentials, bạn có thể truyền đối tượng đó như sau:

from google.ads.googleads.client import GoogleAdsClient
from google.auth import default

# This line retrieves ADCs from the environment. You can use any authentication
# approach as long as the `credentials` variable is an instance of
# `google.auth.credentials.Credentials`.
credentials, _ = default(scopes=["https://www.googleapis.com/auth/adwords"])

client = GoogleAdsClient(
    credentials=credentials,
    use_proto_plus=True,
)

Quản lý nhiều tài khoản

Người dùng thường quản lý nhiều tài khoản Google Ads, thông qua quyền truy cập trực tiếp vào tài khoản hoặc thông qua tài khoản người quản lý Google Ads. Thư viện ứng dụng Python cung cấp các ví dụ về mã sau đây minh hoạ cách xử lý các trường hợp như vậy:

  1. Ví dụ về mã get_account_hierarchy cho biết cách truy xuất danh sách tất cả tài khoản trong một tài khoản người quản lý Google Ads.
  2. Ví dụ về mã list_accessible_customers cho biết cách truy xuất danh sách tất cả tài khoản mà người dùng có quyền truy cập trực tiếp. Sau đó, bạn có thể sử dụng các tài khoản này làm giá trị hợp lệ cho chế độ cài đặt login_customer_id.