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 phải 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 Google Ads. Tham khảo hướng dẫn về mô hình truy cập Google Ads.

Quy trình OAuth

Có 3 quy trình công việc phổ biến 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 làm việc được đề xuất nếu quy trình làm việc của bạn không yêu cầu bất kỳ hoạt động tương tác nào của con người. Quy trình làm việc này yêu cầu một bước thiết lập, 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 xác thực của tài khoản dịch vụ để quản lý tài khoản Google Ads của người dùng. Để định cấu hình, hãy tạo và tải tệp khoá JSON xuống trong Google Cloud Console, sau đó sao chép google_ads_config.rb vào thư mục gốc và sửa đổi để chỉ định vị trí tệp khoá của tài khoản dịch vụ (và địa chỉ email không bắt buộc của người dùng 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):

# You can also authenticate using a service account. If "keyfile" is
# specified below, then service account authentication will be assumed and
# the above authentication fields ignored. Read more about service account
# authentication here:
# https://developers.google.com/google-ads/api/docs/oauth/service-accounts
c.keyfile = 'path/to/keyfile.json'
# Optional unless using Google Workspace domain-wide delegation:
c.impersonate = 'INSERT_EMAIL_ADDRESS_TO_IMPERSONATE_HERE'

Nếu không muốn lưu trữ thông tin này trong tệp mà muốn sử dụng biến môi trường, bạn có thể đặt GOOGLE_ADS_JSON_KEY_FILE_PATH (và GOOGLE_ADS_IMPERSONATED_EMAIL không bắt buộc):

export GOOGLE_ADS_JSON_KEY_FILE_PATH="/path/to/your/service-account-key.json"
# Optional unless using Google Workspace domain-wide delegation:
export GOOGLE_ADS_IMPERSONATED_EMAIL="your_email@email.com"

Bạn cũng có thể truyền đường dẫn tệp khoá tài khoản dịch vụ (và email mạo danh không bắt buộc) theo phương thức lập trình trong thời gian chạy:

require 'google/ads/google_ads'

client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  config.keyfile = '/path/to/your/service-account-key.json'
  # Optional unless using Google Workspace domain-wide delegation:
  config.impersonate = 'INSERT_EMAIL_ADDRESS_TO_IMPERSONATE_HERE'
end

Ngoài ra, bạn có thể sử dụng gem googleauth để tạo thông tin đăng nhập tài khoản dịch vụ và truyền credentials.updater_proc đến config.authentication:

require 'googleauth'
require 'google/ads/google_ads'

# Path to your service account key file.
key_file = '/path/to/your/service-account-key.json'

# Define the scopes needed for the Google Ads API.
scopes = ['https://www.googleapis.com/auth/adwords']

# Create service account credentials.
credentials = File.open(key_file) do |io|
  Google::Auth::ServiceAccountCredentials.make_creds(
    json_key_io: io,
    scope: scopes
  )
end

# Initialize the Google Ads API client with these credentials.
client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  # Inject the service account credential updater proc.
  config.authentication = credentials.updater_proc
end

Hãy tham khảo hướng dẫn về quy trình làm việc của 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 thể sử dụng tài khoản dịch vụ. Quy trình này yêu cầu hai 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ả 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ụ dòng lệnh, chẳng hạn như công cụ dòng lệnh của Google Cloud hoặc ví dụ về mã GenerateUserCredentials để cho phép ứng dụng của bạn thay mặt họ quản lý tất cả tài khoản Google Ads của họ.

Bạn có thể định cấu hình thông tin xác thực OAuth 2.0 cho Ruby bằng cách sao chép tệp google_ads_config.rb vào thư mục gốc và sửa đổi tệp đó để thêm mã ứng dụng khách, khoá bí mật của ứng dụng khách và mã làm mới:

# Authentication tells the API that you are allowed to make changes to the
# specific account you're trying to access.
# The default method of authentication is to use a refresh token, client id,
# and client secret to generate an access token.
c.client_id = 'INSERT_CLIENT_ID_HERE'
c.client_secret = 'INSERT_CLIENT_SECRET_HERE'
c.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'

Ứng dụng tự động đọc tệp cấu hình từ thư mục gốc nếu được tạo thực thể mà không có đối số:

client = Google::Ads::GoogleAds::GoogleAdsClient.new

Ngoài ra, nếu muốn lưu trữ tệp ở nơi khác, bạn có thể tạo thực thể cho ứng dụng bằng cách truyền đường dẫn đến nơi bạn lưu giữ tệp này:

client = Google::Ads::GoogleAds::GoogleAdsClient.new(
  'path/to/google_ads_config.rb'
)

Nếu không muốn lưu trữ thông tin này trong tệp mà muốn sử dụng biến môi trường, bạn có thể đặt từng biến:

export GOOGLE_ADS_CLIENT_ID="INSERT_CLIENT_ID_HERE"
export GOOGLE_ADS_CLIENT_SECRET="INSERT_CLIENT_SECRET_HERE"
export GOOGLE_ADS_REFRESH_TOKEN="INSERT_REFRESH_TOKEN_HERE"

Bạn cũng có thể truyền thông tin theo phương thức lập trình trong thời gian chạy:

client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  config.client_id = 'INSERT_CLIENT_ID_HERE'
  config.client_secret = 'INSERT_CLIENT_SECRET_HERE'
  config.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'
end

Hãy 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 làm việc đượ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 quản lý tài khoản Google Ads thay mặt họ. Ứng dụng của bạn sẽ tạo và quản lý thông tin xác thực người dùng OAuth 2.0. Bạn có thể định cấu hình quy trình công việc này tương tự như quy trình một người dùng, đồng thời chỉ định login_customer_id.

Bạn nên sử dụng tệp cấu hình. Sao chép tệp google_ads_config.rb vào thư mục gốc và sửa đổi tệp đó để thêm mã ứng dụng khách, khoá bí mật của ứng dụng khách, mã làm mới và mã khách hàng:

# Authentication tells the API that you are allowed to make changes to the
# specific account you're trying to access.
# The default method of authentication is to use a refresh token, client id,
# and client secret to generate an access token.
c.client_id = 'INSERT_CLIENT_ID_HERE'
c.client_secret = 'INSERT_CLIENT_SECRET_HERE'
c.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'

# Required for manager accounts only: Specify the login customer ID used to
# authenticate API calls. This will be the customer ID of the authenticated
# manager account. If you need to use different values for this field, then
# make sure to fetch a new copy of the service after each time you change the
# value.
c.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'

Ứng dụng tự động đọc tệp cấu hình từ thư mục gốc nếu được tạo thực thể mà không có đối số:

client = Google::Ads::GoogleAds::GoogleAdsClient.new

Ngoài ra, nếu muốn lưu trữ tệp ở nơi khác, bạn có thể tạo thực thể cho ứng dụng bằng cách truyền đường dẫn đến nơi bạn lưu giữ tệp này:

client = Google::Ads::GoogleAds::GoogleAdsClient.new(
  'path/to/google_ads_config.rb'
)

Nếu không muốn lưu trữ thông tin này trong tệp mà muốn sử dụng biến môi trường, bạn có thể đặt từng biến:

export GOOGLE_ADS_CLIENT_ID="INSERT_CLIENT_ID_HERE"
export GOOGLE_ADS_CLIENT_SECRET="INSERT_CLIENT_SECRET_HERE"
export GOOGLE_ADS_REFRESH_TOKEN="INSERT_REFRESH_TOKEN_HERE"
export GOOGLE_ADS_LOGIN_CUSTOMER_ID="INSERT_LOGIN_CUSTOMER_ID_HERE"

Bạn cũng có thể truyền thông tin theo phương thức lập trình trong thời gian chạy:

client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  config.client_id = 'INSERT_CLIENT_ID_HERE'
  config.client_secret = 'INSERT_CLIENT_SECRET_HERE'
  config.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'
  config.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'
end

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. Thư viện ứng dụng Ruby có một đoạn mã mẫu để bạn tham khảo. Ví dụ về mã dòng lệnh GenerateUserCredentials minh hoạ cách lấy thông tin xác thực người dùng trong thời gian chạy để thay mặt họ quản lý tài khoản Google Ads. Bạn có thể sử dụng mã ví dụ này làm tài liệu tham khảo để xây dựng các ứng dụng dành cho máy tính yêu cầu xác thực người dùng.

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 Ruby 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ã GetAccountHierarchy 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ã ListAccessibleCustomers 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.

Thông tin đăng nhập mặc định của ứng dụng

Thư viện ứng dụng Ruby (phiên bản 36.1.0 trở lên) cũng hỗ trợ xác thực bằng thông tin xác thực mặc định của ứng dụng (ADC). Thư viện này cho phép bạn đặt thông tin xác thực mặc định cho ứng dụng mà không cần định cấu hình thông tin OAuth 2.0 trong cấu hình ứng dụng.

Điều này đặc biệt hữu ích cho việc phát triển cục bộ hoặc phát triển dựa trên các API khác nhau của Google, vì bạn có thể sử dụng lại cùng một thông tin xác thực, miễn là thông tin xác thực đó có thể truy cập vào các phạm vi OAuth 2.0 bắt buộc.

Đối với Google Ads API, hãy đảm bảo thông tin xác thực mặc định của ứng dụng có thể truy cập vào phạm vi OAuth 2.0 https://www.googleapis.com/auth/adwords.

Để sử dụng thông tin xác thực mặc định của ứng dụng, hãy dùng công cụ dòng lệnh của Google Cloud và xác thực cho ADC:

gcloud auth application-default login

Lệnh này sẽ mở một trình duyệt web để hoàn tất quy trình xác thực cho Tài khoản Google của bạn. Sau khi được uỷ quyền, công cụ này sẽ lưu trữ thông tin xác thực ở một vị trí chuẩn. Sau đó, bạn cần cập nhật ứng dụng để sử dụng ADC.

Sao chép tệp google_ads_config.rb vào thư mục gốc và đặt use_application_default_credentials thành true:

# You can also authenticate using Application Default Credentials (ADC).
# To understand how ADC discovers credentials in a given environment, see:
# https://developers.google.com/identity/protocols/application-default-credentials
c.use_application_default_credentials = true

Nếu không muốn lưu trữ thông tin này trong tệp mà muốn sử dụng biến môi trường, bạn có thể đặt GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS:

export GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS="true"

Bạn cũng có thể truyền thông tin theo phương thức lập trình trong thời gian chạy. Khi bạn khởi chạy ứng dụng trong mã Ruby, hãy đặt config.use_application_default_credentials = true và không cung cấp thông tin xác thực OAuth 2.0 rõ ràng. Thư viện sẽ tự động phát hiện và sử dụng thông tin xác thực do công cụ dòng lệnh của Google Cloud thiết lập:

# Initialize the client using Application Default Credentials.
client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  config.use_application_default_credentials = true

  # Optional: Specify a login customer ID if you are accessing accounts
  # through a manager account.
  # config.login_customer_id = 'YOUR_LOGIN_CUSTOMER_ID'

  # Do NOT include client_id, client_secret, or refresh_token here.
end

Hãy tham khảo trang cấu hình để biết thêm thông tin chi tiết về các lựa chọn có sẵn để định cấu hình thư viện ứng dụng Ruby.