use_proto_plus yapılandırma parametresi ile kitaplığın proto-plus mesajları mı yoksa protobuf mesajları mı döndürmesini istediğinizi belirtebilirsiniz. Bu parametrenin nasıl ayarlanacağıyla ilgili ayrıntılar için yapılandırma dokümanlarına bakın.
Bu bölümde, kullanılacak ileti türlerinin performans üzerindeki etkileri açıklanmaktadır. Bu nedenle, bilinçli bir karar vermek için seçenekleri okuyup anlamanızı öneririz.
Proto-plus ve protobuf mesajları
Kod oluşturucu ardışık düzeni, protobuf mesaj arayüzünün ergonomisini iyileştirmek için proto-plus'ı entegre eder. Bu sayede, protobuf mesaj arayüzü yerel Python nesnelerine daha çok benzeyecek şekilde davranır. Ancak bu, proto-plus'ı kullanmanın performans yükü oluşturduğu anlamına gelir.
Proto-plus performansı
Proto-plus'ın temel avantajlarından biri, protobuf mesajlarını ve tanınmış türleri tür birleştirme adı verilen bir işlemle yerel Python türlerine dönüştürmesidir.
Marshaling, proto-plus mesaj örneğinde bir alana erişildiğinde, özellikle de bir 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-plus 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)
Ardından Dog sınıfını başlatabilir ve diğer Python nesnelerinde yaptığınız gibi name alanına erişebilirsiniz:
dog = Dog()
dog.name = "Scruffy"
print(dog.name)
name alanı okunup ayarlandığında değer, protobuf çalışma zamanında uyumlu olması için yerel bir Python str türünden string türüne dönüştürülür.
Performans analizlerimize göre, bu tür dönüşümleri gerçekleştirmek için harcanan sürenin performans üzerinde yeterince büyük bir etkisi olduğunu ve kullanıcıların protobuf mesajlarını kullanıp kullanmayacaklarına ihtiyaçlarına göre karar vermeleri 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 ergonomik açıdan bir dizi iyileştirme sunar. Bu nedenle, bakımı yapılabilir ve okunabilir kod yazmak için idealdir. Yerel Python nesnelerini kullandıkları için daha kolay kullanılır ve anlaşılır.
- Protobuf mesajı kullanım alanları
- Performansa duyarlı kullanım alanları için protobuf'leri kullanın. Özellikle büyük raporları hızlı bir şekilde işlemesi gereken veya çok sayıda işlemle (ör.
BatchJobServiceveyaOfflineUserDataJobService) mutasyon istekleri oluşturan uygulamalarda bu yöntemi tercih edin.
Dinamik olarak değişen mesaj türleri
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ığı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ı 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 açıklanmıştır. 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 kullanmak için 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 sunulan enum'lar, Python'un yerel enum türündeki örneklerdir ve bu nedenle çeşitli kolaylık yöntemlerini devralır.
Enum türü alma
Listeleri almak için GoogleAdsClient.get_type yöntemi kullanıldığında, döndürülen mesajlar proto-plus mı yoksa protobuf mesajları mı kullandığınıza bağlı olarak biraz farklıdır. Örneğin:
- Proto-plus mesajları
val = client.get_type("CampaignStatusEnum").CampaignStatus.PAUSED- Protobuf mesajları
val = client.get_type("CampaignStatusEnum").PAUSED
Listeleri daha kolay almak için GoogleAdsClient örneklerinde, kullandığınız mesaj türüne bakılmaksızın tutarlı bir arayüze sahip 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 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, yinelenen alanlar genellikle yazılmış listelere eşdeğerdir. Yani neredeyse bir list ile aynı şekilde çalışırlar.
Yinelenen skaler alanlara değer ekleme
Tekrarlanan skalar türünde alanlara (ö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")
Buna diğer tüm yaygın list yöntemleri de dahildir (ör. 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 skalar tür değilse bu alanları tekrarlanan alanlara ekleme 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 atayın
Hem skaler hem de skaler olmayan yinelenen alanlar için alana listeleri 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ının 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 metni
Hem proto-plus hem de protobuf mesajları için copy_from üzerinde GoogleAdsClient yardımcı yöntemini kullanmanızı öneririz:
client.copy_from(campaign, other_campaign)
Boş mesaj alanları
Boş mesaj alanları ayarlama işlemi, kullandığınız mesaj türüne bakılmaksızın aynıdır. Bunun için söz konusu alana boş bir mesaj kopyalamanız yeterlidir. Mesaj kopyası bölümünün yanı sıra Boş Mesaj Alanları kılavuzuna bakın. Boş bir mesaj alanı ayarlama örneğini aşağıda bulabilirsiniz:
client.copy_from(campaign.manual_cpm, client.get_type("ManualCpm"))
Ayrılmış kelime olan alan adları
Proto-plus mesajları kullanılırken, alan adları Python'da ayrılmış bir kelimeyse otomatik olarak sonuna alt çizgi eklenir. Asset örneğiyle çalışma örneğini aşağıda bulabilirsiniz:
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, bir Python REPL'de veya komut dosyasında:
import gapic.utils
print(gapic.utils.reserved_names.RESERVED_NAMES)
Sahada bulunma
Protobuf mesaj örneklerindeki alanların varsayılan değerleri olduğundan, bir alanın ayarlanıp ayarlanmadığını bilmek 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")
protobufMessage 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 vardır.
Protobuf mesaj yöntemleri
Protobuf mesaj arayüzü, proto-plus arayüzünün bir parçası olmayan bazı kolaylık yöntemleri içerir. Ancak bir proto-plus mesajını protobuf eşdeğerine 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şikliklerle ilgili sorularınız veya kitaplığın en yeni sürümüne geçişle ilgili sorununuz varsa takip aracımızda sorun kaydı oluşturun.