Việc tìm nạp các thông tin tham chiếu đến tất cả các lớp proto cần thiết để sử dụng API trong Python có thể dài dòng và đòi hỏi bạn phải có hiểu biết sâu sắc về API hoặc thường xuyên chuyển đổi ngữ cảnh để tham chiếu đến các proto hoặc tài liệu.
Các phương thức get_service và get_type của ứng dụng
Hai phương thức getter này cho phép bạn truy xuất mọi đối tượng dịch vụ hoặc đối tượng loại trong API. Phương thức get_service được dùng để truy xuất các ứng dụng dịch vụ. get_type được dùng cho mọi đối tượng khác. Các lớp ứng dụng khách dịch vụ được xác định trong mã theo đường dẫn phiên bản google/ads/googleads/v*/services/ và tất cả các loại đều được xác định theo nhiều danh mục đối tượng google/ads/googleads/v*/common|enums|errors|resources|services/types/. Tất cả mã bên dưới thư mục phiên bản đều được tạo, vì vậy, bạn nên sử dụng các phương thức này thay vì nhập trực tiếp các đối tượng, trong trường hợp cấu trúc của toàn bộ mã nguồn thay đổi.
Ví dụ sau đây cho thấy cách sử dụng phương thức get_service để truy xuất một phiên bản của ứng dụng GoogleAdsService (hoặc GoogleAdsServiceAsyncClient không đồng bộ trong google-ads v28.4.0 và sau đó bằng cách truyền is_async=True):
from google.ads.googleads.client import GoogleAdsClient
# "load_from_storage" loads your API credentials from disk so they
# can be used for service initialization. Providing the optional `version`
# parameter means that the v25 version of GoogleAdsService will
# be returned.
client = GoogleAdsClient.load_from_storage(version="v25")
googleads_service = client.get_service("GoogleAdsService")
# Supported in google-ads v28.4.0 and later: retrieve an async service client.
googleads_async_service = client.get_service("GoogleAdsService", is_async=True)
Ví dụ sau đây cho thấy cách sử dụng phương thức get_type để truy xuất một thực thể Campaign:
from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage(version="v25")
campaign = client.get_type("Campaign")
Enum
Mặc dù bạn có thể sử dụng phương thức get_type để truy xuất các enum, nhưng mỗi thực thể GoogleAdsClient cũng có một thuộc tính enums giúp tải các enum một cách linh động bằng cùng một cơ chế như phương thức get_type. Giao diện này đơn giản và dễ đọc hơn so với việc sử dụng get_type:
from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage(version="v25")
campaign = client.get_type("Campaign")
campaign.status = client.enums.CampaignStatusEnum.PAUSED
Các trường đối tượng Proto là enum được biểu thị trong Python bằng loại enum tích hợp. Điều đó có nghĩa là bạn có thể đọc trực tiếp giá trị của thành viên. Làm việc với thực thể campaign trong ví dụ trước trong REPL Python:
>>> print(campaign.status)
CampaignStatus.PAUSED
>>> type(campaign.status)
<enum 'CampaignStatus'>
>>> print(campaign.status.value)
3
Đôi khi, bạn nên biết tên của trường tương ứng với giá trị enum. Bạn có thể truy cập vào thông tin này bằng thuộc tính name:
>>> print(campaign.status.name)
'PAUSED'
>>> type(campaign.status.name)
<class 'str'>
Cách tương tác với các enum sẽ khác nhau, tuỳ thuộc vào việc bạn có đặt cấu hình use_proto_plus thành true hay false hay không. Để biết thông tin chi tiết về 2 giao diện này, hãy xem tài liệu về thông báo protobuf.
Lập phiên bản
Nhiều phiên bản của API được duy trì cùng một lúc. Mặc dù v25 là phiên bản mới nhất, nhưng bạn vẫn có thể truy cập vào các phiên bản cũ hơn cho đến khi chúng ngừng hoạt động. Thư viện này bao gồm các lớp thông báo proto riêng biệt tương ứng với từng phiên bản API đang hoạt động. Để truy cập vào một lớp thông báo cho một phiên bản cụ thể, hãy cung cấp tham số từ khoá version khi khởi chạy một ứng dụng để ứng dụng đó luôn trả về một thực thể từ phiên bản đã cho:
from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage(version="v25")
# The Campaign instance will be from the v25 version of the API.
campaign = client.get_type("Campaign")
Nếu không chỉ định version khi khởi chạy ứng dụng, bạn có thể chỉ định phiên bản cho mỗi lệnh gọi khi gọi các phương thức get_service và get_type (lưu ý rằng nếu version được đặt khi khởi chạy GoogleAdsClient, thì phiên bản này sẽ ghi đè mọi đối số version được truyền đến get_service hoặc get_type):
from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage()
# This loads the v25 version of the GoogleAdsService.
googleads_service = client.get_service(
"GoogleAdsService", version="v25"
)
# This loads a specific supported API version (such as v23) of a Campaign.
campaign = client.get_type("Campaign", version="v23")
Nếu không có tham số từ khoá version nào được cung cấp, thì thư viện sẽ mặc định là phiên bản API cao nhất mà gói google-ads đã cài đặt của bạn hỗ trợ ("v25" trong bản phát hành mới nhất). Xin lưu ý rằng các bản phát hành API phụ (chẳng hạn như v25.1) được truy cập bằng chuỗi phiên bản chính (version="v25"). Bạn có thể xem danh sách mới nhất và các phiên bản khác hiện có trong phần điều hướng bên trái của tài liệu Tài liệu tham khảo API.