Pengambil layanan dan jenis

Mengambil referensi ke semua berbagai class proto yang diperlukan untuk menggunakan API di Python bisa jadi panjang dan mengharuskan Anda memiliki pemahaman intrinsik tentang API atau sering beralih konteks untuk mereferensikan proto atau dokumentasi.

Metode get_service dan get_type klien

Kedua metode pengambil ini memungkinkan Anda mengambil objek layanan atau jenis apa pun di API. Metode get_service digunakan untuk mengambil klien layanan. get_type digunakan untuk objek lainnya. Class klien layanan ditentukan dalam kode di jalur versi google/ads/googleads/v*/services/ dan semua jenis ditentukan di berbagai kategori objek google/ads/googleads/v*/common|enums|errors|resources|services/types/. Semua kode di bawah direktori versi dibuat, jadi sebaiknya gunakan metode ini daripada mengimpor objek secara langsung, jika struktur codebase berubah.

Contoh berikut menunjukkan cara menggunakan metode get_service untuk mengambil instance klien GoogleAdsService (atau GoogleAdsServiceAsyncClient asinkron di google-ads v28.4.0 dan yang lebih baru dengan meneruskan 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)

Contoh berikut menunjukkan cara menggunakan metode get_type untuk mengambil instance Campaign:

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage(version="v26")
campaign = client.get_type("Campaign")

Enum

Meskipun Anda dapat menggunakan metode get_type untuk mengambil enum, setiap instance GoogleAdsClient juga memiliki atribut enums yang secara dinamis memuat enum menggunakan mekanisme yang sama dengan metode get_type. Antarmuka ini lebih sederhana dan lebih mudah dibaca daripada menggunakan 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

Kolom objek proto yang merupakan enum direpresentasikan dalam Python oleh jenis enum bawaan. Artinya, Anda dapat membaca nilai anggota secara langsung. Bekerja dengan instance campaign dari contoh sebelumnya di REPL Python:

>>> print(campaign.status)
CampaignStatus.PAUSED
>>> type(campaign.status)
<enum 'CampaignStatus'>
>>> print(campaign.status.value)
3

Terkadang, mengetahui nama kolom yang sesuai dengan nilai enum akan berguna. Anda dapat mengakses informasi ini menggunakan atribut name:

>>> print(campaign.status.name)
'PAUSED'
>>> type(campaign.status.name)
<class 'str'>

Berinteraksi dengan enum berbeda-beda, bergantung pada apakah Anda telah menetapkan konfigurasi use_proto_plus ke true atau false. Untuk mengetahui detail tentang kedua antarmuka tersebut, lihat dokumentasi pesan protobuf.

Pembuatan Versi

Beberapa versi API dipertahankan secara bersamaan. Meskipun v26 adalah versi terbaru, versi sebelumnya masih dapat diakses hingga dihentikan. Library ini menyertakan class pesan proto terpisah yang sesuai dengan setiap versi API yang aktif. Untuk mengakses class pesan untuk versi tertentu, berikan parameter kata kunci version saat melakukan inisialisasi klien sehingga selalu menampilkan instance dari versi yang diberikan:

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")

Jika tidak menentukan version saat melakukan inisialisasi klien, Anda dapat menentukan versi per panggilan saat memanggil metode get_service dan get_type (perhatikan bahwa jika version ditetapkan saat melakukan inisialisasi GoogleAdsClient, argumen version apa pun yang diteruskan ke get_service atau get_type akan diganti):

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")

Jika tidak ada parameter kata kunci version yang diberikan, library akan ditetapkan secara default ke versi API tertinggi yang didukung oleh paket google-ads yang Anda instal ("v26" dalam rilis terbaru). Perhatikan bahwa rilis API minor (seperti v25.1) diakses menggunakan string versi utamanya (version="v25"). Daftar terbaru dari versi terbaru dan versi lain yang tersedia dapat ditemukan di bagian navigasi sebelah kiri dokumentasi Referensi API.