Python istemci kitaplığının 14.0.0
sürümünde, kitaplığın proto artı mesajları mı yoksa protobuf mesajları mı döndürmesini istediğinizi belirten use_proto_plus
adında yeni bir gerekli yapılandırma parametresi kullanıma sunuluyor. Bu parametreyi ayarlamayla ilgili ayrıntılar için yapılandırma belgelerine bakın.
Bu bölümde, kullanılacak mesaj türlerini seçmenin performans üzerindeki etkileri açıklanmaktadır. Bu nedenle, bilinçli bir karar vermek için seçenekleri okuyup anlamanızı öneririz. Ancak kod değişikliği yapmadan 14.0.0
sürümüne geçmek istiyorsanız arayüz değişikliklerinin bozulmasını önlemek için use_proto_plus
değerini True
olarak ayarlayabilirsiniz.
Proto+ ve protobuf mesajları karşılaştırması
10.0.0
sürümünde Python istemci kitaplığı, yeni bir kod oluşturma aracı ardışık düzenine geçirildi. Bu ardışık düzende, protobuf mesaj arayüzünün ergonomisini iyileştirmek ve yerel Python nesneleri gibi davranmalarını sağlamak için proto-plus'u entegre ettik. Bu iyileştirmenin karşılığında, proto-plus yönteminin performans ek yükü getirmesi gerekir.
Proto+ performansı
Proto Plus'ın temel avantajlarından biri, protobuf mesajlarını ve iyi bilinen türleri türleri karıştırma adı verilen bir işlemle yerel Python türlerine dönüştürmesidir.
Sıralandırma, proto+ mesaj örneğinde bir alana erişildiğinde ve özellikle de protobuf tanımında bir alan okunduğunda veya ayarlandığında gerçekleşir:
syntax = "proto3";
message Dog {
string name = 1;
}
Bu tanım proto+ sınıfına dönüştürüldüğünde aşağıdaki gibi görünür:
import proto
class Dog(proto.Message):
name = proto.Field(proto.STRING, number=1)
Daha sonra Dog
sınıfını başlatabilir ve diğer herhangi bir Python nesnesinde olduğu gibi name
alanına 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 yayınlanmasından bu yana gerçekleştirdiğimiz analizde, bu tür dönüşümleri gerçekleştirmek için harcanan sürenin yeterince büyük bir performans etkisine sahip olduğunu ve kullanıcılara protobuf mesajları kullanma seçeneğinin sunulmasının önemli olduğunu belirledik.
Proto+ ve protobuf mesajlarının kullanım alanları
- Proto+ mesaj kullanım alanları
- Proto-plus, protobuf mesajlarına kıyasla birçok ergonomik iyileştirme sunduğundan sürdürülebilir, okunabilir kod yazmak için idealdir. Yerel Python nesnelerini gösterdiği için bunları kullanmak ve anlamak daha kolaydır.
- Protokol arabelleği mesajının kullanım alanları
- Özellikle büyük raporları hızlı bir şekilde işlemesi gereken ya da çok sayıda işlemle değişiklik istekleri oluşturan uygulamalarda (ör.
BatchJobService
veyaOfflineUserDataJobService
) performansa duyarlı 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 gerekebilir. Bu durumda, istemci kitaplığı tarafından sunulan 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)
Protokol arabelleği mesaj arayüzü farklılıkları
Proto+ 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 farkları ele alacağız.
Bayt serileştirme
- Proto+ iletileri
serialized = type(campaign).serialize(campaign) deserialized = type(campaign).deserialize(serialized)
- Protokol arabelleği mesajları
serialized = campaign.SerializeToString() deserialized = campaign.FromString(serialized)
JSON serileştirme
- Proto+ iletileri
serialized = type(campaign).to_json(campaign) deserialized = type(campaign).from_json(serialized)
- Protokol arabelleği 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+ mesajlarını kullanırken yardımcıdan faydalanmak için bunları protobuf mesajlarına dönüştürün:
- Proto+ iletileri
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)
- Protokol arabelleği mesajları
from google.api_core.protobuf_helpers import field_mask campaign = client.get_type("Campaign") mask = field_mask(None, campaign)
Sıralamalar
Proto+ mesajları tarafından gösterilen numaralandırmalar, Python'un yerel enum
türünün örnekleridir ve bu nedenle bir dizi kolaylık yöntemini devralır.
Sıralama türü alma
Numaralandırmaları almak için GoogleAdsClient.get_type
yöntemini kullanırken, döndürülen mesajlar proto++ veya protobuf mesajları kullanmanıza bağlı olarak biraz farklılık gösterir. Örneğin:
- Proto+ iletileri
val = client.get_type("CampaignStatusEnum").CampaignStatus.PAUSED
- Protokol arabelleği mesajları
val = client.get_type("CampaignStatusEnum").PAUSED
Numaralandırmaları daha basit hale getirmek için, kullandığınız mesaj türünden bağımsız olarak tutarlı bir arayüze sahip GoogleAdsClient
örneklerinde bir kolaylık özelliği bulunur:
val = client.enums.CampaignStatusEnum.PAUSED
Sıralama değeri alma
Bazen belirli bir numaralandırmanın değerini veya alan kimliğini bilmek yararlıdır. Örneğin, CampaignStatusEnum
üzerindeki PAUSED
, 3
değerine karşılık gelir:
- Proto+ iletileri
campaign = client.get_type("Campaign") campaign.status = client.enums.CampaignStatusEnum.PAUSED # To read the value of campaign status print(campaign.status.value)
- Protokol arabelleği 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 enum alanının adını bilmek yararlı olur. Örneğin, API'den nesneleri okurken entegre 3
değerinin hangi kampanya durumuna karşılık geldiğini bilmek isteyebilirsiniz:
- Proto+ iletileri
campaign = client.get_type("Campaign") campaign.status = client.enums.CampaignStatusEnum.PAUSED # To read the name of campaign status print(campaign.status.name)
- Protokol arabelleği 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, yinelenen alanlar genellikle yazılan listelere eşdeğerdir. Diğer bir deyişle, list
ile neredeyse aynı şekilde davranırlar.
Tekrarlanan skaler alanlara ekleme
string
veya int64
alanları gibi yinelenen skalar tür alanlarına değer eklerken mesaj türü ne olursa olsun arayüz aynı kalır:
- Proto+ iletileri
ad.final_urls.append("https://www.example.com")
- Protokol arabelleği mesajları
ad.final_urls.append("https://www.example.com")
Bu, extend
gibi yaygın kullanılan diğer tüm list
yöntemlerini de içerir:
- Proto+ iletileri
ad.final_urls.extend(["https://www.example.com", "https://www.example.com/2"])
- Protokol arabelleği mesajları
ad.final_urls.extend(["https://www.example.com", "https://www.example.com/2"])
Yinelenen alanlara mesaj türleri ekleme
Yinelenen alan skalar tür değilse bu alanları tekrarlanan alanlara ekleme davranışı biraz farklı olur:
- Proto+ iletileri
frequency_cap = client.get_type("FrequencyCapEntry") frequency_cap.cap = 100 campaign.frequency_caps.append(frequency_cap)
- Protokol arabelleği 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 atanıyor
Hem skaler hem de skaler olmayan tekrarlanan alanlar için listeleri alana farklı şekillerde atayabilirsiniz:
- Proto+ iletileri
# In proto-plus it's possible to use assignment. urls = ["https://www.example.com"] ad.final_urls = urls
- Protokol arabelleği 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ş iletiler
Bazen bir mesaj örneğinin herhangi bir bilgi içerip içermediğini veya herhangi bir alanının ayarlanmış olup olmadığını bilmek yararlı olur.
- Proto+ iletileri
# When using proto-plus messages you can simply check the message for # truthiness. is_empty = bool(campaign) is_empty = not campaign
- Protokol arabelleği mesajları
is_empty = campaign.ByteSize() == 0
Mesaj kopyası
Hem protoplus 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 ileti kopyalamanız yeterlidir. İleti kopyası bölümünün yanı sıra Boş İleti Alanları kılavuzuna bakın. Boş bir mesaj alanının nasıl ayarlanacağına dair bir örneği aşağıda bulabilirsiniz:
client.copy_from(campaign.manual_cpm, client.get_type("ManualCpm"))
Ayrılmış kelimeler olan alan adları
Proto+ mesajları kullanılırken, aynı zamanda Python'da ayrılmış bir kelimeyse alan adları otomatik olarak alt çizgiyle birlikte görünür. Asset
örneğiyle çalışmaya ilişkin bir örneği aşağıda bulabilirsiniz:
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. Bunlara programatik olarak da erişilebilir.
İlk olarak modülü yükleyin:
python -m pip install gapic-generator
Daha sonra, bir Python REPL veya komut dosyasında:
import gapic.utils
print(gapic.utils.reserved_names.RESERVED_NAMES)
Saha varlığı
Protobuf mesaj örneklerindeki alanların varsayılan değerleri olduğundan, alanın ayarlanıp ayarlanmadığını bilmek her zaman kolay değildir.
- Proto+ iletileri
# Use the "in" operator. has_field = "name" in campaign
- Protokol arabelleği 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, bir mesajdaki alanın varsayılan değere ayarlanmış olsa bile ayarlanıp ayarlanmadığını belirleyen bir HasField
yöntemi bulunur.
Protokol arabelleği mesaj yöntemleri
Protobuf mesaj arayüzü, proto-plus arayüzünün parçası olmayan bazı kullanım kolaylığı yöntemlerini içerir. Ancak bir proto-plus mesajını protobuf mesajına dönüştürerek bunlara 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 hakkında sorularınız varsa veya kitaplığın 14.0.0
sürümüne geçiş yaparken herhangi bir sorun yaşarsanız izleyicimizde sorun bildirin.