Protokol Arabelleği Mesajları

Python istemci kitaplığının 14.0.0 sürümünde, kitaplığın proto artı mesajları mı yoksa protobuf mesajları mı döndürmesini istediğinizi belirten use_proto_plus adında yeni bir gerekli yapılandırma parametresi kullanıma sunuluyor. Bu parametreyi ayarlamayla ilgili ayrıntılar için yapılandırma belgelerine bakın.

Bu bölümde, kullanılacak mesaj türlerini seçmenin performans üzerindeki etkileri açıklanmaktadır. Bu nedenle, bilinçli bir karar vermek için seçenekleri okuyup anlamanızı öneririz. Ancak kod değişikliği yapmadan 14.0.0 sürümüne geçmek istiyorsanız arayüz değişikliklerinin bozulmasını önlemek için use_proto_plus değerini True olarak ayarlayabilirsiniz.

Proto+ ve protobuf mesajları karşılaştırması

10.0.0 sürümünde Python istemci kitaplığı, yeni bir kod oluşturma aracı ardışık düzenine geçirildi. Bu ardışık düzende, protobuf mesaj arayüzünün ergonomisini iyileştirmek ve yerel Python nesneleri gibi davranmalarını sağlamak için proto-plus'u entegre ettik. Bu iyileştirmenin karşılığında, proto-plus yönteminin performans ek yükü getirmesi gerekir.

Proto+ performansı

Proto Plus'ın temel avantajlarından biri, protobuf mesajlarını ve iyi bilinen türleri türleri karıştırma adı verilen bir işlemle yerel Python türlerine dönüştürmesidir.

Sıralandırma, proto+ mesaj örneğinde bir alana erişildiğinde ve özellikle de 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+ 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)

Daha sonra Dog sınıfını başlatabilir ve diğer herhangi bir Python nesnesinde olduğu gibi name alanına 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 yayınlanmasından bu yana gerçekleştirdiğimiz analizde, bu tür dönüşümleri gerçekleştirmek için harcanan sürenin yeterince büyük bir performans etkisine sahip olduğunu ve kullanıcılara protobuf mesajları kullanma seçeneğinin sunulmasının önemli olduğunu belirledik.

Proto+ ve protobuf mesajlarının kullanım alanları

Proto+ mesaj kullanım alanları
Proto-plus, protobuf mesajlarına kıyasla birçok ergonomik iyileştirme sunduğundan sürdürülebilir, okunabilir kod yazmak için idealdir. Yerel Python nesnelerini gösterdiği için bunları kullanmak ve anlamak daha kolaydır.
Protokol arabelleği mesajının kullanım alanları
Özellikle büyük raporları hızlı bir şekilde işlemesi gereken ya da çok sayıda işlemle değişiklik istekleri oluşturan uygulamalarda (ör. BatchJobService veya OfflineUserDataJobService) performansa duyarlı 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 gerekebilir. Bu durumda, istemci kitaplığı tarafından sunulan 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)

Protokol arabelleği mesaj arayüzü farklılıkları

Proto+ 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 farkları ele alacağız.

Bayt serileştirme

Proto+ iletileri
serialized = type(campaign).serialize(campaign)
deserialized = type(campaign).deserialize(serialized)
Protokol arabelleği mesajları
serialized = campaign.SerializeToString()
deserialized = campaign.FromString(serialized)

JSON serileştirme

Proto+ iletileri
serialized = type(campaign).to_json(campaign)
deserialized = type(campaign).from_json(serialized)
Protokol arabelleği 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+ mesajlarını kullanırken yardımcıdan faydalanmak için bunları protobuf mesajlarına dönüştürün:

Proto+ iletileri
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)
Protokol arabelleği mesajları
from google.api_core.protobuf_helpers import field_mask

campaign = client.get_type("Campaign")
mask = field_mask(None, campaign)

Sıralamalar

Proto+ mesajları tarafından gösterilen numaralandırmalar, Python'un yerel enum türünün örnekleridir ve bu nedenle bir dizi kolaylık yöntemini devralır.

Sıralama türü alma

Numaralandırmaları almak için GoogleAdsClient.get_type yöntemini kullanırken, döndürülen mesajlar proto++ veya protobuf mesajları kullanmanıza bağlı olarak biraz farklılık gösterir. Örneğin:

Proto+ iletileri
val = client.get_type("CampaignStatusEnum").CampaignStatus.PAUSED
Protokol arabelleği mesajları
val = client.get_type("CampaignStatusEnum").PAUSED

Numaralandırmaları daha basit hale getirmek için, kullandığınız mesaj türünden bağımsız olarak tutarlı bir arayüze sahip GoogleAdsClient örneklerinde bir kolaylık özelliği bulunur:

val = client.enums.CampaignStatusEnum.PAUSED

Sıralama değeri alma

Bazen belirli bir numaralandırmanın değerini veya alan kimliğini bilmek yararlıdır. Örneğin, CampaignStatusEnum üzerindeki PAUSED, 3 değerine karşılık gelir:

Proto+ iletileri
campaign = client.get_type("Campaign")
campaign.status = client.enums.CampaignStatusEnum.PAUSED
# To read the value of campaign status
print(campaign.status.value)
Protokol arabelleği 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 enum alanının adını bilmek yararlı olur. Örneğin, API'den nesneleri okurken entegre 3 değerinin hangi kampanya durumuna karşılık geldiğini bilmek isteyebilirsiniz:

Proto+ iletileri
campaign = client.get_type("Campaign")
campaign.status = client.enums.CampaignStatusEnum.PAUSED
# To read the name of campaign status
print(campaign.status.name)
Protokol arabelleği 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ılan listelere eşdeğerdir. Diğer bir deyişle, list ile neredeyse aynı şekilde davranırlar.

Tekrarlanan skaler alanlara ekleme

string veya int64 alanları gibi yinelenen skalar tür alanlarına değer eklerken mesaj türü ne olursa olsun arayüz aynı kalır:

Proto+ iletileri
ad.final_urls.append("https://www.example.com")
Protokol arabelleği mesajları
ad.final_urls.append("https://www.example.com")

Bu, extend gibi yaygın kullanılan diğer tüm list yöntemlerini de içerir:

Proto+ iletileri
ad.final_urls.extend(["https://www.example.com", "https://www.example.com/2"])
Protokol arabelleği mesajları
ad.final_urls.extend(["https://www.example.com", "https://www.example.com/2"])

Yinelenen alanlara mesaj türleri ekleme

Yinelenen alan skalar tür değilse bu alanları tekrarlanan alanlara ekleme davranışı biraz farklı olur:

Proto+ iletileri
frequency_cap = client.get_type("FrequencyCapEntry")
frequency_cap.cap = 100
campaign.frequency_caps.append(frequency_cap)
Protokol arabelleği 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 atanıyor

Hem skaler hem de skaler olmayan tekrarlanan alanlar için listeleri alana farklı şekillerde atayabilirsiniz:

Proto+ iletileri
# In proto-plus it's possible to use assignment.
urls = ["https://www.example.com"]
ad.final_urls = urls
Protokol arabelleği 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ş iletiler

Bazen bir mesaj örneğinin herhangi bir bilgi içerip içermediğini veya herhangi bir alanının ayarlanmış olup olmadığını bilmek yararlı olur.

Proto+ iletileri
# When using proto-plus messages you can simply check the message for
# truthiness.
is_empty = bool(campaign)
is_empty = not campaign
Protokol arabelleği mesajları
is_empty = campaign.ByteSize() == 0

Mesaj kopyası

Hem protoplus 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 ileti kopyalamanız yeterlidir. İleti kopyası bölümünün yanı sıra Boş İleti Alanları kılavuzuna bakı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+ mesajları kullanılırken, aynı zamanda Python'da ayrılmış bir kelimeyse alan adları otomatik olarak alt çizgiyle birlikte görünür. Asset örneğiyle çalışmaya ilişkin bir örneği aşağıda bulabilirsiniz:

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. Bunlara programatik olarak da erişilebilir.

İlk olarak modülü yükleyin:

python -m pip install gapic-generator

Daha sonra, bir Python REPL veya komut dosyasında:

import gapic.utils
print(gapic.utils.reserved_names.RESERVED_NAMES)

Saha varlığı

Protobuf mesaj örneklerindeki alanların varsayılan değerleri olduğundan, alanın ayarlanıp ayarlanmadığını bilmek her zaman kolay değildir.

Proto+ iletileri
# Use the "in" operator.
has_field = "name" in campaign
Protokol arabelleği 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 bulunur.

Protokol arabelleği mesaj yöntemleri

Protobuf mesaj arayüzü, proto-plus arayüzünün parçası olmayan bazı kullanım kolaylığı yöntemlerini içerir. Ancak bir proto-plus mesajını protobuf mesajına dönüştürerek bunlara 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 hakkında sorularınız varsa veya kitaplığın 14.0.0 sürümüne geçiş yaparken herhangi bir sorun yaşarsanız izleyicimizde sorun bildirin.