Protokol Arabelleği Mesajları

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 veya OfflineUserDataJobService) 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)

Not: Adları ayrılmış kelimeler olan alanların genişletilmesi, GAQL sorgularını etkilemez. Bu nedenle, Search veya SearchStream isteğinde Asset.type alanı isteniyorsa sorgu dizesinin sonuna alt çizgi eklemeyin.

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.