Việc tìm nạp tệp đối chiếu cho 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à yêu cầu bạn phải hiểu rõ về API hoặc thường xuyên chuyển đổi ngữ cảnh để tham chiếu đến 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 bất kỳ đối tượng dịch vụ hoặc loại nào trong API. Phương thức get_service được dùng để truy xuất ứ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 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 đượ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ã trong 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, phòng 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 thực thể của ứng dụng GoogleAdsService (hoặc GoogleAdsServiceAsyncClient không đồng bộ trong google-ads v28.4.0 trở lên 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 v26 version of GoogleAdsService will
# be returned.
client = GoogleAdsClient.load_from_storage(version="v26")
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="v26")
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 enum, nhưng mỗi thực thể GoogleAdsClient cũng có một thuộc tính enums tải động enum bằng cơ chế tương tự 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="v26")
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 sẵn. Đ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 từ ví dụ trước trong Python REPL:
>>> 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 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 enum sẽ khác nhau tuỳ thuộc vào việc bạn đặt cấu hình use_proto_plus thành true hay false. Để biết thông tin chi tiết về hai giao diện, 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ù v26 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 các phiên bản đó 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="v26")
# The Campaign instance will be from the v26 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 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 v26 version of the GoogleAdsService.
googleads_service = client.get_service(
"GoogleAdsService", version="v26"
)
# This loads a specific supported API version (such as v23) of a Campaign.
campaign = client.get_type("Campaign", version="v23")
Nếu bạn không cung cấp tham số từ khoá version, thì thư viện sẽ mặc định sử dụng phiên bản API cao nhất mà gói google-ads đã cài đặt hỗ trợ ("v26" trong bản phát hành mới nhất). Xin lưu ý rằng bạn có thể truy cập vào các bản phát hành API nhỏ (chẳng hạn như v25.1) bằng chuỗi phiên bản lớn (version="v25"). Bạn có thể xem danh sách cập nhật về các phiên bản 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.