use_proto_plus yapılandırma parametresiyle, kitaplığın proto-plus iletileri mi yoksa protobuf iletileri mi 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, hangi ileti türlerinin kullanılacağının seçilmesinin performans üzerindeki etkileri açıklanmaktadır. Bu nedenle, bilinçli bir karar vermek için seçenekleri okumanızı ve anlamanızı öneririz.
Proto-plus ve protobuf mesajları
Kod oluşturucu işlem hattı, protobuf ileti arayüzünün ergonomisini iyileştirmek için proto-plus'ı entegre eder. Bu sayede, arayüzün yerel Python nesneleri gibi davranması sağlanır. Ancak bu, proto-plus kullanmanın performans 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 yerel 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 (ör. 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 şö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 Python nesnelerinde olduğu gibi erişebilirsiniz:
dog = Dog()
dog.name = "Scruffy"
print(dog.name)
name alanı okunup ayarlanırken değer, yerel bir 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.
Performans analizlerimize göre, bu tür dönüşümlerin yapılması için harcanan sürenin performansı yeterince etkilediğini ve kullanıcıların, ihtiyaçlarına göre protobuf mesajlarını kullanıp kullanmamaya karar vermesi gerektiğini belirledik.
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, bakımı kolay ve okunabilir kod yazmak için idealdir. Yerel 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ı hızlı bir şekilde işlemesi gereken veya çok sayıda işlem içeren mutasyon istekleri oluşturan uygulamalarda (ör.
BatchJobServiceveyaOfflineUserDataJobServiceile) 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 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. Ancak burada, Google Ads istemci kitaplığının yaygın kullanım alanlarını etkileyen bazı temel 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 kullanmak üzere tasarlanmıştır. Bu nedenle, 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 enumarasyonlar, Python'ın yerel enum türünün örnekleridir ve bu nedenle bir dizi kolaylık yöntemini devralır.
Enum türü alma
Numaralandırılmış değerleri almak için GoogleAdsClient.get_type yöntemi kullanılırken döndürülen mesajlar, proto-plus veya protobuf mesajlarını 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, CampaignStatusEnum üzerindeki PAUSED, 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 # To read the value of campaign status print(status_enum.CampaignStatus.Value(campaign.status))
Enum adı alma
Bazen bir enum alanının adını bilmek yararlı olabilir. Örneğin, API'den nesneleri okurken 3 int 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 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
Tekrarlanan scalar
type alanlarına (örneğin, string veya int64 alanları) değer eklerken mesaj türünden bağımsız olarak aynı arayüz kullanılır:
- Proto-plus mesajları
ad.final_urls.append("https://www.example.com")
- Protobuf mesajları
ad.final_urls.append("https://www.example.com")
Bu, list gibi diğer tüm yaygın yöntemleri de içerir. Ö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"])
Tekrarlanan alanlara mesaj türleri ekleme
Tekrarlanan alan skaler türde değilse tekrarlanan alanlara eklenirken 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 herhangi bir 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 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 copy_from
yardımcı yöntemini GoogleAdsClient üzerinde kullanmanızı öneririz:
client.copy_from(campaign, other_campaign)
Boş mesaj alanları
Boş mesaj alanları ayarlama süreci, 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ünün yanı sıra Boş İleti Alanları rehberine de göz atı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-plus mesajları kullanılırken, ad Python'da ayrılmış bir kelimeyse alan adları otomatik olarak sondaki alt çizgiyle birlikte görünür. Asset örneğiyle çalışma örneğini aşağıda görebilirsiniz:
asset = client.get_type("Asset")
asset.type_ = client.enums.AssetTypeEnum.IMAGE
Ayrılmış adların tam listesi, gapic generator modülünde oluşturulur. 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 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 mesajdaki alanın varsayılan bir değere ayarlanmış olsa bile ayarlanıp ayarlanmadığını belirleyen bir HasField yöntemi bulunur.
Protobuf mesaj yöntemleri
Protobuf ileti arayüzü, proto-plus arayüzünün parçası olmayan bazı kolaylık yöntemleri içerir. Ancak, proto-plus iletisini protobuf karşılığına dönüştürerek bu yöntemlere 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 en yeni sürümüne geçişle ilgili herhangi bir sorunuz ya da sorununuz varsa izleyicimizde sorun kaydı oluşturun.