use_proto_plus कॉन्फ़िगरेशन पैरामीटर की मदद से, यह तय किया जा सकता है कि
लाइब्रेरी से प्रोटो-प्लस मैसेज दिखाए या
प्रोटोबफ़ मैसेज दिखाए जाएं. इस पैरामीटर को सेट करने के तरीके के बारे में जानकारी पाने के लिए, कॉन्फ़िगरेशन दस्तावेज़ देखें.
इस सेक्शन में, किस तरह के मैसेज का इस्तेमाल करना है, यह चुनने से परफ़ॉर्मेंस पर पड़ने वाले असर के बारे में बताया गया है. इसलिए, हमारा सुझाव है कि आप सही फ़ैसला लेने के लिए, इन विकल्पों को पढ़ें और समझें.
Proto-plus बनाम protobuf मैसेज
कोड जनरेटर पाइपलाइन प्रोटो-प्लस को भी इंटिग्रेट करती है, ताकि प्रोटोबफ़ मैसेज इंटरफ़ेस के एर्गोनॉमिक्स को बेहतर बनाया जा सके. इसके लिए, ये नेटिव Python ऑब्जेक्ट की तरह काम करते हैं. हालांकि, इसका मतलब है कि proto-plus का इस्तेमाल करने पर, परफ़ॉर्मेंस में कमी आती है.
प्रोटो-प्लस की परफ़ॉर्मेंस
proto-plus का एक मुख्य फ़ायदा यह है कि यह protobuf मैसेज और पहचाने जाने वाले टाइप को टाइप मार्शल करने की प्रोसेस की मदद से, नेटिव Python टाइप में बदल देता है.
मार्शलिंग तब होता है, जब किसी फ़ील्ड को प्रोटो-प्लस मैसेज इंस्टेंस पर ऐक्सेस किया जाता है. खास तौर पर, ऐसा तब होता है, जब किसी फ़ील्ड को या तो पढ़ा गया हो या सेट किया गया हो. उदाहरण के लिए, प्रोटोबफ़ डेफ़िनिशन में:
syntax = "proto3";
message Dog {
string name = 1;
}
इस परिभाषा को प्रोटो-प्लस क्लास में बदलने पर, यह कुछ ऐसा दिखेगा:
import proto
class Dog(proto.Message):
name = proto.Field(proto.STRING, number=1)
इसके बाद, Dog क्लास को शुरू किया जा सकता है और इसके name फ़ील्ड को ऐक्सेस किया जा सकता है, जैसे कि किसी दूसरे Python ऑब्जेक्ट को:
dog = Dog()
dog.name = "Scruffy"
print(dog.name)
name फ़ील्ड को पढ़ने और सेट करने पर, वैल्यू को नेटिव
Python str टाइप से string टाइप में बदल दिया जाता है, ताकि वैल्यू, protobuf रनटाइम के साथ काम कर सके.
परफ़ॉर्मेंस के विश्लेषण के आधार पर, हमने पाया है कि इस तरह के कन्वर्ज़न में लगने वाले समय का परफ़ॉर्मेंस पर काफ़ी असर पड़ता है. इसलिए, उपयोगकर्ताओं को अपनी ज़रूरतों के हिसाब से यह तय करना चाहिए कि उन्हें protobuf मैसेज का इस्तेमाल करना है या नहीं.
प्रोटो-प्लस और प्रोटोबफ़ मैसेज के लिए केस इस्तेमाल करें
- प्रोटो-प्लस मैसेज के इस्तेमाल के उदाहरण
- प्रोटो-प्लस, प्रोटोबफ़ मैसेज की तुलना में कई आसान सुधार करता है. इसलिए, प्रोटो-प्लस, बनाए जा सकने वाले और आसानी से पढ़े जा सकने वाले कोड लिखने के लिए बिलकुल सही होते हैं. ये नेटिव Python ऑब्जेक्ट दिखाते हैं, इसलिए इन्हें इस्तेमाल करना और समझना आसान होता है.
- Protobuf मैसेज के इस्तेमाल के उदाहरण
- परफ़ॉर्मेंस पर असर डालने वाले इस्तेमाल के उदाहरणों के लिए, प्रोटोबस का इस्तेमाल करें. खास तौर पर, उन ऐप्लिकेशन में जिनमें बड़ी रिपोर्ट को तेज़ी से प्रोसेस करने की ज़रूरत होती है या जो बड़ी संख्या में ऑपरेशन के साथ, डेटा में बदलाव करने के अनुरोध बनाते हैं. उदाहरण के लिए,
BatchJobServiceयाOfflineUserDataJobServiceके साथ.
डाइनैमिक तौर पर बदलने वाले मैसेज टाइप
अपने ऐप्लिकेशन के लिए सही मैसेज टाइप चुनने के बाद, आपको किसी खास वर्कफ़्लो के लिए, दूसरे टाइप का इस्तेमाल करना पड़ सकता है. इस मामले में, क्लाइंट लाइब्रेरी से मिलने वाली सुविधाओं का इस्तेमाल करके, डाइनैमिक तौर पर दो तरह की सुविधाओं के बीच स्विच करना आसान हो जाता है. ऊपर दी गई Dog मैसेज क्लास का इस्तेमाल करके:
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 मैसेज इंटरफ़ेस में अंतर
प्रोटो-प्लस इंटरफ़ेस के बारे में ज़्यादा जानकारी दी गई है. हालांकि, यहां हम कुछ ऐसे मुख्य अंतरों को हाइलाइट करेंगे जिनका असर Google Ads क्लाइंट लाइब्रेरी के सामान्य इस्तेमाल के उदाहरणों पर पड़ता है.
बाइट को क्रम से लगाना
- प्रोटो-प्लस मैसेज
serialized = type(campaign).serialize(campaign) deserialized = type(campaign).deserialize(serialized)
- प्रोटोबफ़ मैसेज
serialized = campaign.SerializeToString() deserialized = campaign.FromString(serialized)
JSON को क्रम से लगाना
- प्रोटो-प्लस मैसेज
serialized = type(campaign).to_json(campaign) deserialized = type(campaign).from_json(serialized)
- प्रोटोबफ़ मैसेज
from google.protobuf.json_format import MessageToJson, Parse serialized = MessageToJson(campaign) deserialized = Parse(serialized, campaign)
फ़ील्ड मास्क
api-core से मिलने वाला फ़ील्ड मास्क हेल्पर तरीका, protobuf मैसेज इंस्टेंस का इस्तेमाल करने के लिए डिज़ाइन किया गया है. इसलिए, हेल्पर का इस्तेमाल करने के लिए, proto-plus मैसेज को protobuf मैसेज में बदलें:
- प्रोटो-प्लस मैसेज
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)
- प्रोटोबफ़ मैसेज
from google.api_core.protobuf_helpers import field_mask campaign = client.get_type("Campaign") mask = field_mask(None, campaign)
Enums
प्रोटो-प्लस मैसेज से एक्सपोज़ किए गए Enums, Python के नेटिव enum टाइप के इंस्टेंस होते हैं. इसलिए, इनमें कई सुविधाजनक तरीके इनहेरिट होते हैं.
Enum टाइप को वापस लाना
एनम को वापस पाने के लिए GoogleAdsClient.get_type तरीके का इस्तेमाल करने पर, आपको जो मैसेज मिलते हैं वे इस बात पर निर्भर करते हैं कि प्रोटो-प्लस या प्रोटोबुक मैसेज में से किसका इस्तेमाल किया जा रहा है. उदाहरण के लिए:
- प्रोटो-प्लस मैसेज
val = client.get_type("CampaignStatusEnum").CampaignStatus.PAUSED
- प्रोटोबफ़ मैसेज
val = client.get_type("CampaignStatusEnum").PAUSED
ईनम को आसानी से वापस पाने के लिए, GoogleAdsClient इंस्टेंस पर एक सुविधा एट्रिब्यूट दिया गया है. इसका इंटरफ़ेस एक जैसा है, चाहे आप किसी भी तरह के मैसेज का इस्तेमाल कर रहे हों:
val = client.enums.CampaignStatusEnum.PAUSED
Enum वैल्यू वापस पाना
कभी-कभी, किसी एनम की वैल्यू या फ़ील्ड आईडी जानना फ़ायदेमंद होता है. उदाहरण के लिए, CampaignStatusEnum पर मौजूद PAUSED, 3 से मेल खाता है:
- प्रोटो-प्लस मैसेज
campaign = client.get_type("Campaign") campaign.status = client.enums.CampaignStatusEnum.PAUSED # To read the value of campaign status print(campaign.status.value)
- प्रोटोबफ़ मैसेज
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 नाम वापस लाना
कभी-कभी, किसी एनम फ़ील्ड का नाम जानना फ़ायदेमंद होता है. उदाहरण के लिए, एपीआई से ऑब्जेक्ट पढ़ते समय, हो सकता है कि आपको यह जानना हो कि int 3 किस कैंपेन स्टेटस से जुड़ा है:
- प्रोटो-प्लस मैसेज
campaign = client.get_type("Campaign") campaign.status = client.enums.CampaignStatusEnum.PAUSED # To read the name of campaign status print(campaign.status.name)
- प्रोटोबफ़ मैसेज
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)
दोहराए गए फ़ील्ड
जैसा कि प्रोटो-प्लस दस्तावेज़ों में बताया गया है, दोहराए गए फ़ील्ड आम तौर पर टाइप की गई सूचियों की तरह होते हैं. इसका मतलब है कि वे list की तरह ही काम करते हैं.
दोहराए गए स्केलर फ़ील्ड में वैल्यू जोड़ना
दोहराए गए स्केलर टाइप फ़ील्ड, जैसे कि string या int64 फ़ील्ड में वैल्यू जोड़ते समय, इंटरफ़ेस एक जैसा होता है. भले ही, मैसेज का टाइप कुछ भी हो:
- प्रोटो-प्लस मैसेज
ad.final_urls.append("https://www.example.com")
- प्रोटोबफ़ मैसेज
ad.final_urls.append("https://www.example.com")
इसमें, list के अन्य सभी सामान्य तरीके भी शामिल हैं, जैसे कि extend:
- प्रोटो-प्लस मैसेज
ad.final_urls.extend(["https://www.example.com", "https://www.example.com/2"])
- प्रोटोबफ़ मैसेज
ad.final_urls.extend(["https://www.example.com", "https://www.example.com/2"])
दोहराए गए फ़ील्ड में मैसेज टाइप जोड़ना
अगर दोहराया गया फ़ील्ड स्केलर टाइप नहीं है, तो उन्हें दोहराए गए फ़ील्ड में जोड़ने पर काम करने का तरीका थोड़ा अलग होता है:
- प्रोटो-प्लस मैसेज
frequency_cap = client.get_type("FrequencyCapEntry") frequency_cap.cap = 100 campaign.frequency_caps.append(frequency_cap)
- प्रोटोबफ़ मैसेज
# The add method initializes a message and adds it to the repeated field frequency_cap = campaign.frequency_caps.add() frequency_cap.cap = 100
दोहराए गए फ़ील्ड असाइन करना
स्केलर और नॉन-स्केलर, दोनों तरह के दोहराए गए फ़ील्ड के लिए, फ़ील्ड में सूचियों को अलग-अलग तरीकों से असाइन किया जा सकता है:
- प्रोटो-प्लस मैसेज
# In proto-plus it's possible to use assignment. urls = ["https://www.example.com"] ad.final_urls = urls
- प्रोटोबफ़ मैसेज
# 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
खाली मैसेज
कभी-कभी यह जानना फ़ायदेमंद होता है कि मैसेज इंस्टेंस में कोई जानकारी है या नहीं या उसका कोई फ़ील्ड सेट है या नहीं.
- प्रोटो-प्लस मैसेज
# When using proto-plus messages you can simply check the message for # truthiness. is_empty = bool(campaign) is_empty = not campaign
- प्रोटोबफ़ मैसेज
is_empty = campaign.ByteSize() == 0
मैसेज की कॉपी
हमारा सुझाव है कि proto-plus और protobuf, दोनों मैसेज के लिए GoogleAdsClient पर copy_from
हेल्पर तरीके का इस्तेमाल करें:
client.copy_from(campaign, other_campaign)
मैसेज फ़ील्ड खाली हैं
मैसेज के खाली फ़ील्ड सेट करने की प्रोसेस एक जैसी होती है. भले ही, आपने मैसेज का कोई भी टाइप इस्तेमाल किया हो. आपको सिर्फ़ उस फ़ील्ड में कोई खाली मैसेज कॉपी करना होगा. मैसेज कॉपी सेक्शन के साथ-साथ, मैसेज के खाली फ़ील्ड से जुड़ी गाइड देखें. यहां खाली मैसेज फ़ील्ड को सेट करने के तरीके का एक उदाहरण दिया गया है:
client.copy_from(campaign.manual_cpm, client.get_type("ManualCpm"))
फ़ील्ड के ऐसे नाम जो रिज़र्व किए गए शब्द हैं
proto-plus मैसेज का इस्तेमाल करने पर, फ़ील्ड के नाम अपने-आप अंडरस्कोर के साथ दिखते हैं. ऐसा तब होता है, जब नाम Python में भी रिज़र्व किया गया शब्द हो. यहां Asset इंस्टेंस के साथ काम करने का उदाहरण दिया गया है:
asset = client.get_type("Asset")
asset.type_ = client.enums.AssetTypeEnum.IMAGE
रिज़र्व किए गए नामों की पूरी सूची गैपिक जनरेटर मॉड्यूल में बनाई जाती है. इसे प्रोग्राम के हिसाब से ऐक्सेस किया जा सकता है.
सबसे पहले, मॉड्यूल इंस्टॉल करें:
python -m pip install gapic-generator
इसके बाद, Python REPL या स्क्रिप्ट में:
import gapic.utils
print(gapic.utils.reserved_names.RESERVED_NAMES)
फ़ील्ड में मौजूदगी
protobuf मैसेज इंस्टेंस के फ़ील्ड में डिफ़ॉल्ट वैल्यू होती हैं. इसलिए, यह जानना हमेशा आसान नहीं होता कि कोई फ़ील्ड सेट किया गया है या नहीं.
- प्रोटो-प्लस मैसेज
# Use the "in" operator. has_field = "name" in campaign
- प्रोटोबफ़ मैसेज
campaign = client.get_type("Campaign") # Determines whether "name" is set and not just an empty string. campaign.HasField("name")
protobufMessage क्लास इंटरफ़ेस में HasField तरीका होता है. इससे यह पता चलता है कि मैसेज में फ़ील्ड सेट किया गया है या नहीं. भले ही, उसे डिफ़ॉल्ट वैल्यू पर सेट किया गया हो.
प्रोटोबफ़ मैसेज के तरीके
प्रोटोबफ़ मैसेज इंटरफ़ेस में सुविधा के कुछ तरीके शामिल हैं जो प्रोटो-प्लस इंटरफ़ेस का हिस्सा नहीं हैं; हालांकि, एक प्रोटो-प्लस मैसेज को इसके प्रोटोबफ़ मैसेज में बदल कर इन्हें ऐक्सेस करना आसान है:
# 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())
सॉफ़्टवेयर वर्शन ट्रैकर
अगर आपको इन बदलावों के बारे में कोई सवाल पूछना है या लाइब्रेरी के सबसे नए वर्शन पर माइग्रेट करने में कोई समस्या आ रही है, तो हमारे ट्रैकर पर समस्या दर्ज करें.