use_proto_plus yapılandırma parametresiyle, kitaplığın proto-plus mesajları mı yoksa protobuf mesajları mı döndürmesini istediğinizi belirtebilirsiniz. Bu parametrenin nasıl ayarlanacağı hakkında ayrıntılı bilgi için yapılandırma belgelerine bakın.
Bu bölümde, her seçeneğin performans üzerindeki etkileri açıklanmaktadır. Böylece, uygulamanız için en iyi yaklaşımı seçebilirsiniz.
Proto-plus ve protobuf mesajları
Kod oluşturucu işlem hattı, proto-plus'ı protobuf ileti arayüzünün ergonomisini iyileştirmek için standart Python nesneleri gibi davranmasını sağlayacak şekilde entegre eder. Ancak bu, proto-plus kullanmanın performans açısından ek yük getirdiği anlamına gelir.
Proto-plus performansı
Proto-plus'ın temel avantajlarından biri, protobuf mesajlarını ve iyi bilinen türleri tür sıralama adı verilen bir işlemle yerleşik Python türlerine dönüştürmesidir.
Marshaling, bir alana proto-plus ileti örneğinde erişildiğinde, özellikle de bir alan okunduğunda veya ayarlandığında (örneğin, protobuf tanımında) gerçekleşir:
syntax = "proto3";
message Dog {
string name = 1;
}
Bu tanım proto-plus sınıfına dönüştürüldüğünde şu şekilde 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 Python nesnelerinde olduğu gibi erişebilirsiniz:
dog = Dog()
dog.name = "Scruffy"
print(dog.name)
name alanı okunup ayarlanırken değer, protobuf çalışma zamanıyla uyumlu olması için yerleşik bir Python str türünden string türüne dönüştürülür.
Bu tür dönüşümleri gerçekleştirmek için harcanan süre, performans üzerinde yeterince büyük bir etkiye sahiptir. Bu nedenle, uygulamanızın ihtiyaçlarına göre proto-plus veya protobuf mesajlarını kullanıp kullanmayacağınıza karar vermeniz gerekir.
Proto-plus ve protobuf mesajlarının kullanım alanları
- Proto-plus mesaj kullanım alanları
- Proto-plus, protobuf mesajlarına kıyasla bir dizi ergonomik iyileştirme sunar. Bu nedenle, sürdürülebilir ve okunabilir kod yazmak için idealdir. Standart Python nesnelerini ortaya çıkardıkları için daha kolay kullanılır ve anlaşılırlar.
- Protobuf mesajı kullanım alanları
- Performans açısından hassas kullanım alanlarında, özellikle büyük raporların hızlı bir şekilde işlenmesi gereken veya çok sayıda işlem içeren mutasyon isteklerinin oluşturulduğu uygulamalarda (ör.
BatchJobServiceveyaOfflineUserDataJobServiceile) protobuf'ları kullanın.
Mesaj türleri arasında dinamik olarak geçiş yapma
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ş yapabilirsiniz. Öncekiyle aynı Dog mesaj sınıfını kullanarak:
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. Aşağıdaki bölümlerde, Google Ads istemci kitaplığının yaygın kullanım alanlarını etkileyen temel farklılıklar vurgulanmaktadır.
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 kullanmak üzere tasarlanmıştır. Proto-plus mesajlarını kullanırken yardımcıyı kullanmak 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-plus mesajları tarafından kullanıma sunulan enums, Python'ın yerleşik enum türünün örnekleridir ve bu nedenle çeşitli kolaylık yöntemlerini devralır.
Enum türü alma
Numaralandırılmış değerleri almak için GoogleAdsClient.get_type yöntemini kullanırken döndürülen iletiler, proto-plus veya protobuf iletilerini kullanmanı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
Numaralandırılmış değerleri almayı kolaylaştırmak için, kullandığınız mesaj türünden bağımsız olarak tutarlı bir arayüze sahip olan GoogleAdsClient örneklerinde bir kolaylık özelliği bulunur:
val = client.enums.CampaignStatusEnum.PAUSED
Enum değeri alma
Bazen belirli bir enum'un değerini veya alan kimliğini bilmek yararlı olabilir. Örneğin, PAUSED, CampaignStatusEnum üzerinde 3 ile eşleşir:
- 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 # Native protobuf enum fields already store the integer value (3): print(campaign.status) # Or look up the integer value from the enum name string: print(status_enum.CampaignStatus.Value("PAUSED"))
Numaralandırılmış değer adını alma
Bazen bir enum alanının adını bilmek yararlı olabilir. Örneğin, API'den nesneleri okurken 3 tam sayısının 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 print(status_enum.CampaignStatus.Name(campaign.status))
Yinelenen alanlar
Proto-plus dokümanlarında açıklandığı gibi, tekrarlanan alanlar genellikle türü belirlenmiş listelere eşdeğerdir. Bu nedenle, list ile neredeyse aynı şekilde davranırlar.
Yinelenen skaler alanlara değer ekleme
Yinelenen skaler tür alanlarına (ör. string veya int64 alanları) değer eklerken arayüz, mesaj türünden bağımsız olarak aynıdır:
- Proto-plus mesajları
ad.final_urls.append("https://www.example.com")
- Protobuf mesajları
ad.final_urls.append("https://www.example.com")
Bu, diğer tüm yaygın list yöntemlerini de kapsar. Ö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 bir skaler tür değilse bu alanların tekrarlanan alanlara eklenirkenki davranışı biraz farklıdır:
- 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 ileti örneğinin bilgi içerip içermediğini veya alanlarından herhangi birinin ayarlanıp ayarlanmadığını bilmek yararlı olabilir.
- Proto-plus mesajları
# When using proto-plus messages you can check the message for truthiness. is_empty = not bool(campaign)
- Protobuf mesajları
is_empty = campaign.ByteSize() == 0
Mesaj kopyası
Hem proto-plus hem de protobuf mesajları için copy_from yardımcı yöntemini GoogleAdsClient üzerinde kullanın:
client.copy_from(campaign, other_campaign)
Boş mesaj alanları
Boş mesaj alanlarını ayarlama süreci, kullandığınız mesaj türünden bağımsız olarak aynıdır. Söz konusu alana boş bir mesaj kopyaladığınızda İleti kopyası bölümünün yanı sıra Boş ileti alanları rehberine de göz atın. Aşağıdaki örnekte, boş bir mesaj alanının nasıl ayarlanacağı gösterilmektedir:
client.copy_from(campaign.manual_cpm, client.get_type("ManualCpm"))
Ayrılmış kelimeler olan alan adları
Proto-plus mesajları kullanılırken, ad Python'da ayrılmış bir kelimeyse alan adları otomatik olarak sondaki alt çizgiyle birlikte görünür. Aşağıdaki örnekte, Asset örneğiyle nasıl çalışılacağı gösterilmektedir:
asset = client.get_type("Asset")
asset.type_ = client.enums.AssetTypeEnum.IMAGE
Ayrılmış adların tam listesi, gapic generator modülünde oluşturulur. Bu özelliğe programatik olarak da erişilebilir.
Öncelikle modülü yükleyin:
python -m pip install gapic-generator
Ardından, Python REPL veya komut dosyasında:
import gapic.utils
print(gapic.utils.reserved_names.RESERVED_NAMES)
Alanın varlığı
Protobuf mesaj örneklerindeki alanların varsayılan değerleri olduğundan, bir alanın ayarlanıp ayarlanmadığını anlamak her zaman kolay olmayabilir.
- 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, bir iletideki alt ileti, oneof alanı veya optional
skaler alanın varsayılan bir değere ayarlanmış olsa bile ayarlanıp ayarlanmadığını belirleyen bir HasField
yöntemi vardır.
(proto3 içindeki zorunlu olmayan skaler alanlarda HasField çağrılması ValueError hatasına neden olur.)
Protobuf mesaj yöntemleri
Protobuf mesaj arayüzü, proto-plus arayüzünün parçası olmayan bazı kolaylık yöntemleri içerir. Ancak, proto-plus mesajını protobuf karşılığına dönüştürerek bu yöntemlere erişebilirsiniz:
# Accessing the ListFields method
protobuf_campaign = util.convert_proto_plus_to_protobuf(campaign)
print(protobuf_campaign.ListFields())
# Accessing the Clear method
protobuf_campaign = util.convert_proto_plus_to_protobuf(campaign)
protobuf_campaign.Clear()
Sorun izleyici
Bu değişikliklerle ilgili sorularınız varsa veya kitaplığın en yeni sürümüne geçişle ilgili sorun yaşıyorsanız lütfen sorun izleyicide sorun bildirin.