Python istemci kitaplığının 14.0.0
sürümünde, kitaplığın proto-plus mesajları mı yoksa protobuf mesajları mı döndürmesini istediğinizi belirten use_proto_plus
adlı yeni bir gerekli yapılandırma parametresi kullanıma sunulmuştur. Bu parametrenin nasıl ayarlanacağıyla ilgili ayrıntılar için yapılandırma belgelerine göz atın.
Bu bölümde, kullanılacak mesaj türlerini seçmenin performans üzerindeki etkileri açıklanmaktadır. Bu nedenle, bilinçli bir karar verebilmek için seçenekleri okuyup anlamanız önerilir. Ancak kodda değişiklik yapmadan 14.0.0
sürümüne geçmek isterseniz arayüz değişikliklerinin zarar görmesini önlemek için use_proto_plus
değerini True
olarak ayarlayabilirsiniz.
Proto-plus ile protobuf mesajlarının karşılaştırması
Python istemci kitaplığı, 10.0.0
sürümünde, protobuf mesaj arayüzünün ergonomisini iyileştirmek ve yerel Python nesnelerine benzer davranışlar sergilemesini sağlamak için proto-plus özelliğini entegre eden yeni bir kod oluşturma aracı ardışık düzenine geçti. Bu iyileştirmenin telafisi, "protoplus"ın performans
yüklenmesine yol açmasıdır.
Proto-plus performansı
Protoplus'ın temel avantajlarından biri, tür çalıştırma adlı bir süreç aracılığıyla protobuf mesajlarını ve iyi bilinen türleri yerel Python türlerine dönüştürmesidir.
Sıralandırma, bir proto-artı mesaj örneğinde bir alana erişildiğinde, özellikle de bir alan, örneğin bir protobuf tanımında okunduğunda veya ayarlandığında meydana gelir:
syntax = "proto3";
message Dog {
string name = 1;
}
Bu tanım, proto-artı sınıfa dönüştürüldüğünde şöyle görünür:
import proto
class Dog(proto.Message):
name = proto.Field(proto.STRING, number=1)
Ardından Dog
sınıfını başlatabilir ve name
alanına diğer herhangi bir Python nesnesinde olduğu gibi erişebilirsiniz:
dog = Dog()
dog.name = "Scruffy"
print(dog.name)
name
alanı okunurken ve ayarlanırken değer, yerel Python str
türünden string
türüne dönüştürülür. Böylece değer, protobuf çalışma zamanıyla uyumlu olur.
10.0.0
sürümünün kullanıma sunulmasından bu yana yaptığımız analizde, bu tür dönüşümleri gerçekleştirmek için harcanan zamanın, kullanıcılara protobuf mesajları kullanma seçeneği sunmanın önemli olduğu kadar büyük bir performans etkisine sahip olduğunu belirledik.
Proto-plus ve protobuf mesajları için kullanım örnekleri
- Proto-plus mesaj kullanım alanları
- Proto-plus, protobuf mesajlarına kıyasla bazı ergonomik iyileştirmeler sunduğundan sürdürülebilir, okunabilir kod yazmak için idealdir. Yerel Python nesnelerini kullanıma sunduktan bunların kullanımı ve anlaşılması daha kolaydır.
- Protobuf mesajlarının kullanım alanları
- Özellikle büyük raporları hızlı bir şekilde işlemesi gereken veya çok sayıda işlemle değişiklik istekleri oluşturan uygulamalarda (ör.
BatchJobService
veyaOfflineUserDataJobService
) performans açısından hassas kullanım alanları için protobuf'ları kullanın.
Mesaj türlerini dinamik olarak değiştirme
Uygulamanız için uygun mesaj türünü seçtikten sonra, belirli bir iş akışı için diğer türü kullanmanız gerektiğini fark edebilirsiniz. Bu durumda, istemci kitaplığının sunduğu yardımcı programları kullanarak iki tür arasında dinamik olarak geçiş yapmak kolaydır. Yukarıdaki Dog
ileti sınıfının aynısı kullanılıyor:
from google.ads.googleads import util
# Proto-plus message type
dog = Dog()
# Protobuf message type
dog = util.convert_proto_plus_to_protobuf(dog)
# Back to proto-plus message type
dog = util.convert_protobuf_to_proto_plus(dog)
Protobuf mesaj arayüzü farklılıkları
Proto-plus arayüzü ayrıntılı olarak belgelenmiştir, ancak burada Google Ads istemci kitaplığının yaygın kullanım alanlarını etkileyen bazı önemli farklılıkları vurgulayacağız.
Bayt serileştirme
- Proto-plus mesajları
serialized = type(campaign).serialize(campaign) deserialized = type(campaign).deserialize(serialized)
- Protobuf mesajları
serialized = campaign.SerializeToString() deserialized = campaign.FromString(serialized)
JSON serileştirme
- Proto-plus mesajları
serialized = type(campaign).to_json(campaign) deserialized = type(campaign).from_json(serialized)
- Protobuf mesajları
from google.protobuf.json_format import MessageToJson, Parse serialized = MessageToJson(campaign) deserialized = Parse(serialized, campaign)
Alan maskeleri
api-core tarafından sağlanan alan maskesi yardımcı yöntemi, protobuf mesaj örneklerini kullanacak şekilde tasarlanmıştır. Bu nedenle, proto-plus mesajları kullanırken yardımcıdan yararlanmak için bunları protobuf mesajlarına dönüştürün:
- Proto-plus mesajları
from google.api_core.protobuf_helpers import field_mask campaign = client.get_type("Campaign") protobuf_campaign = util.convert_proto_plus_to_protobuf(campaign) mask = field_mask(None, protobuf_campaign)
- Protobuf mesajları
from google.api_core.protobuf_helpers import field_mask campaign = client.get_type("Campaign") mask = field_mask(None, campaign)
Sıralamalar
Proto-artı mesajları tarafından sunulan enum'lar, Python'un yerel enum
türünün örnekleridir ve bu nedenle çeşitli kolaylık yöntemlerini devralır.
Enum türü alımı
Sıralamaları almak için GoogleAdsClient.get_type
yöntemi kullanılırken döndürülen mesajlar, proto-plus veya protobuf mesajları kullanıp kullanmadığınıza bağlı olarak biraz farklılık gösterir. Örneğin:
- Proto-plus mesajları
val = client.get_type("CampaignStatusEnum").CampaignStatus.PAUSED
- Protobuf mesajları
val = client.get_type("CampaignStatusEnum").PAUSED
Sıralamaları daha basit hale getirmek için GoogleAdsClient
örneklerinde, kullandığınız mesaj türünden bağımsız olarak tutarlı bir arayüze sahip olan bir kolaylık özelliği bulunur:
val = client.enums.CampaignStatusEnum.PAUSED
Sıralama değeri alımı
Bazen belirli bir enumun değerini veya alan kimliğini bilmek yararlı olur. Örneğin, CampaignStatusEnum
üzerindeki PAUSED
, 3
değerine karşılık gelir:
- Proto-plus mesajları
campaign = client.get_type("Campaign") campaign.status = client.enums.CampaignStatusEnum.PAUSED # To read the value of campaign status print(campaign.status.value)
- Protobuf mesajları
campaign = client.get_type("Campaign") status_enum = client.enums.CampaignStatusEnum campaign.status = status_enum.PAUSED # To read the value of campaign status print(status_enum.CampaignStatus.Value(campaign.status))
Sıralama adı alma
Bazen bir numaralandırma alanının adını bilmek yararlı olur. Örneğin, API'den nesneleri okurken int 3
değerinin hangi kampanya durumuna karşılık geldiğini bilmek isteyebilirsiniz:
- Proto-plus mesajları
campaign = client.get_type("Campaign") campaign.status = client.enums.CampaignStatusEnum.PAUSED # To read the name of campaign status print(campaign.status.name)
- Protobuf mesajları
campaign = client.get_type("Campaign") status_enum = client.enums.CampaignStatusEnum # Sets the campaign status to the int value for PAUSED campaign.status = status_enum.PAUSED # To read the name of campaign status status_enum.CampaignStatus.Name(campaign.status)
Yinelenen alanlar
proto-plus belgelerinde açıklandığı gibi, tekrarlanan alanlar genellikle yazılan listelere eşdeğerdir. Diğer bir deyişle, bunların bir list
ile neredeyse aynı şekilde davrandığı anlamına gelir.
Tekrarlanan skaler alanlara ekleme
Yinelenen skaler tür alanlarına (ör. string
veya int64
) değer eklenirken arayüz, mesaj türünden bağımsız olarak aynı olur:
- Proto-plus mesajları
ad.final_urls.append("https://www.example.com")
- Protobuf mesajları
ad.final_urls.append("https://www.example.com")
Buna, diğer tüm yaygın list
yöntemleri de dahildir (örneğin, extend
):
- Proto-plus mesajları
ad.final_urls.extend(["https://www.example.com", "https://www.example.com/2"])
- Protobuf mesajları
ad.final_urls.extend(["https://www.example.com", "https://www.example.com/2"])
Yinelenen alanlara mesaj türleri ekleme
Tekrarlanan alan skaler tür değilse bunları yinelenen alanlara ekleme davranışı biraz farklı olur:
- Proto-plus mesajları
frequency_cap = client.get_type("FrequencyCapEntry") frequency_cap.cap = 100 campaign.frequency_caps.append(frequency_cap)
- Protobuf mesajları
# The add method initializes a message and adds it to the repeated field frequency_cap = campaign.frequency_caps.add() frequency_cap.cap = 100
Yinelenen alanları atama
Hem skaler hem de skaler olmayan tekrarlanan alanlar için, listeleri alana farklı şekillerde atayabilirsiniz:
- Proto-plus mesajları
# In proto-plus it's possible to use assignment. urls = ["https://www.example.com"] ad.final_urls = urls
- Protobuf mesajları
# Protobuf messages do not allow assignment, but you can replace the # existing list using slice syntax. urls = ["https://www.example.com"] ad.final_urls[:] = urls
Boş mesajlar
Bazen bir mesaj örneğinin herhangi bir bilgi içerip içermediğini veya alanlarından herhangi birinin ayarlanıp ayarlanmadığını bilmek yararlı olur.
- Proto-plus mesajları
# When using proto-plus messages you can simply check the message for # truthiness. is_empty = bool(campaign) is_empty = not campaign
- Protobuf mesajları
is_empty = campaign.ByteSize() == 0
Mesaj kopyası
Hem proto-plus hem de protobuf mesajları için GoogleAdsClient
üzerinde copy_from
yardımcı yöntemini kullanmanızı öneririz:
client.copy_from(campaign, other_campaign)
Boş mesaj alanları
Boş mesaj alanlarını ayarlama işlemi, kullandığınız mesaj türünden bağımsız olarak aynıdır. Söz konusu alana boş bir mesaj kopyalamanız yeterlidir. İleti kopyası bölümüne ve Boş Mesaj Alanları kılavuzuna bakın. Boş mesaj alanının nasıl ayarlanacağına dair bir örnek:
client.copy_from(campaign.manual_cpm, client.get_type("ManualCpm"))
Ayrılmış kelimeler olan alan adları
Proto-artı mesajları kullanırken, alan adı Python'da ayrılmış bir kelimeyse alan adları otomatik olarak sondaki bir alt çizgiyle görünür. Aşağıda, Asset
örneğiyle çalışmayla ilgili bir örnek verilmiştir:
asset = client.get_type("Asset")
asset.type_ = client.enums.AssetTypeEnum.IMAGE
Ayrılmış adların tam listesi gapic oluşturucu modülünde oluşturulur. Bu araca programatik olarak da erişilebilir.
İlk olarak modülü yükleyin:
python -m pip install gapic-generator
Ardından, bir Python REPL veya komut dosyası içinde:
import gapic.utils
print(gapic.utils.reserved_names.RESERVED_NAMES)
Alan varlığı
Protobuf mesaj örneklerindeki alanlar varsayılan değerlere sahip olduğundan, bir alanın ayarlanıp ayarlanmadığını anlamak her zaman kolay değildir.
- Proto-plus mesajları
# Use the "in" operator. has_field = "name" in campaign
- Protobuf mesajları
campaign = client.get_type("Campaign") # Determines whether "name" is set and not just an empty string. campaign.HasField("name")
Protobuf Message
sınıfı arayüzünde, varsayılan değere ayarlanmış olsa bile iletideki alanın ayarlanıp ayarlanmadığını belirleyen bir HasField
yöntemi bulunur.
Protobuf mesaj yöntemleri
Protobuf mesaj arayüzünde, proto-plus arayüzünün parçası olmayan bazı kolaylık yöntemleri yer alır. Bununla birlikte, bir proto-artı mesajını protobuf karşılığına dönüştürerek bu mesajlara kolayca erişebilirsiniz:
# Accessing the ListFields method
protobuf_campaign = util.convert_protobuf_to_proto_plus(campaign)
print(campaign.ListFields())
# Accessing the Clear method
protobuf_campaign = util.convert_protobuf_to_proto_plus(campaign)
print(campaign.Clear())
Sorun izleyici
Bu değişiklikler veya kitaplığın 14.0.0
sürümüne geçiş yaparken herhangi bir sorun yaşarsanız izleyicimizde sorun bildirin.