Protokol Arabelleği Mesajları

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ğı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 okumanızı ve anlamanızı öneririz.

Proto-plus ve protobuf mesajları

Kod oluşturucu ardışık düzeni, protobuf mesaj arayüzünün yerel Python nesneleri gibi davranmasını sağlayarak ergonomisini iyileştirmenin bir yolu olarak proto-plus öğesini entegre eder. 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, bir 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, sürdürülebilir ve okunabilir kod yazmak için idealdir. Yerel Python nesnelerini kullanıma sunduktan bunların kullanımı ve anlaşılması daha kolaydır.
Protobuf mesajı 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.

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 kullanacak şekilde 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

Sıralama değeri alımı

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 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.

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 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ı 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ını ayarlama işlemi, kullandığınız mesaj türünden bağımsız olarak 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ış kelimeler olan alan adları

Proto-plus mesajları kullanılırken, alan adları Python'da ayrılmış bir kelimeyse otomatik olarak sonuna alt çizgi eklenir. 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 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 veya komut dosyası içinde:

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ı 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")

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 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.