Google sử dụng công nghệ AI để dịch nội dung sang ngôn ngữ bạn ưu tiên. Bản dịch bằng AI có thể có lỗi.

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

Giống như các API khác của Google, API Google Ads 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 Google Ads API của bạn 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 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 làm việc phổ biến được sử dụng khi làm việc với Google Ads API.

Luồng 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ỳ hoạt động tương tác nào của con người. Quy trình 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 đă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. Để định cấu hình chế độ này, 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 chính và sửa đổi tệp này để chỉ định vị trí tệp khoá 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 một tệp và muốn sử dụng các 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 được 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 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 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:

Cấp cho một người dùng duy nhất 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ý đó.
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 Google Cloud hoặc ví dụ về mã GenerateUserCredentials để 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 cho họ.

Bạn có thể định cấu hình thông tin đăng nhập OAuth 2.0 cho Ruby bằng cách sao chép tệp google_ads_config.rb vào thư mục chính 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 sẽ tự động đọc tệp cấu hình trong thư mục chính nếu được khởi tạo 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 một tệp và muốn sử dụng các 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 đượ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 thay cho 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 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 chính rồi 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 sẽ tự động đọc tệp cấu hình trong thư mục chính nếu được khởi tạo 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 một tệp và muốn sử dụng các 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

Hãy 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 ví dụ về mã để 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 ví dụ về mã này làm tài liệu tham khảo để tạo các ứng dụng dành cho máy tính cần 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ý những trường hợp như vậy:

Ví dụ về mã GetAccountHierarchy cho thấy 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.
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ể 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 đăng nhập mặc định của ứng dụng (ADC). Thao tác này cho phép bạn đặt thông tin đăng nhập 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 quá trình 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 đó 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 https://www.googleapis.com/auth/adwords OAuth 2.0.

Để sử dụng thông tin đăng nhập mặc định của ứng dụng, hãy dùng công cụ dòng lệnh 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, ứng dụng sẽ lưu trữ thông tin đăng nhập ở một vị trí tiêu 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 chính của bạn 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 một tệp và muốn sử dụng các 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 động ứng dụng trong mã Ruby, hãy đặt config.use_application_default_credentials = true và không cung cấp thông tin đăng nhập OAuth 2.0 rõ ràng. Thư viện này tự động phát hiện và sử dụng thông tin đăng nhập do công cụ dòng lệnh 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.