use_proto_plus कॉन्फ़िगरेशन पैरामीटर की मदद से, यह तय किया जा सकता है कि आपको लाइब्रेरी से proto-plus मैसेज चाहिए या protobuf मैसेज. इस पैरामीटर को सेट करने के तरीके के बारे में जानकारी पाने के लिए, कॉन्फ़िगरेशन दस्तावेज़ देखें.
इस सेक्शन में, किस तरह के मैसेज का इस्तेमाल करना है, यह चुनने से परफ़ॉर्मेंस पर पड़ने वाले असर के बारे में बताया गया है. इसलिए, हमारा सुझाव है कि आप सही फ़ैसला लेने के लिए, इन विकल्पों को पढ़ें और समझें.
Proto-plus बनाम protobuf मैसेज
कोड जनरेटर पाइपलाइन, proto-plus को इंटिग्रेट करती है. इससे protobuf मैसेज इंटरफ़ेस को इस्तेमाल करना आसान हो जाता है. ऐसा, इसे नेटिव Python ऑब्जेक्ट की तरह काम करने के लिए किया जाता है. हालांकि, इसका मतलब है कि proto-plus का इस्तेमाल करने से परफ़ॉर्मेंस में कमी आती है.
प्रोटो-प्लस की परफ़ॉर्मेंस
proto-plus का एक मुख्य फ़ायदा यह है कि यह protobuf मैसेज और पहचाने-पहचाने टाइप को टाइप मार्शल करने की प्रोसेस की मदद से, नेटिव Python टाइप में बदल देता है.
मार्शल करने की प्रोसेस तब शुरू होती है, जब किसी फ़ील्ड को प्रोटो-प्लस मैसेज इंस्टेंस पर ऐक्सेस किया जाता है. खास तौर पर, जब किसी फ़ील्ड को पढ़ा या सेट किया जाता है. उदाहरण के लिए, protobuf परिभाषा में:
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 मैसेज का इस्तेमाल करना है या नहीं.
proto-plus और protobuf मैसेज के इस्तेमाल के उदाहरण
- प्रोटो-प्लस मैसेज के इस्तेमाल के उदाहरण
- Proto-plus, 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)
दोहराए गए फ़ील्ड
proto-plus के दस्तावेज़ों में बताया गया है कि दोहराए गए फ़ील्ड, आम तौर पर टाइप की गई सूचियों के बराबर होते हैं. इसका मतलब है कि ये 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
रिज़र्व किए गए नामों की पूरी सूची, gapic generator मॉड्यूल में बनाई जाती है. इसे प्रोग्राम के हिसाब से भी ऐक्सेस किया जा सकता है.
सबसे पहले, मॉड्यूल इंस्टॉल करें:
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 तरीका होता है. इससे यह पता चलता है कि मैसेज में फ़ील्ड सेट किया गया है या नहीं. भले ही, उसे डिफ़ॉल्ट वैल्यू पर सेट किया गया हो.
प्रोटोबफ़ मैसेज के तरीके
protobuf मैसेज इंटरफ़ेस में कुछ ऐसे तरीके शामिल हैं जो proto-plus इंटरफ़ेस का हिस्सा नहीं हैं. हालांकि, किसी proto-plus मैसेज को protobuf मैसेज में बदलकर, उन्हें आसानी से ऐक्सेस किया जा सकता है:
# 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())
सॉफ़्टवेयर वर्शन ट्रैकर
अगर आपको इन बदलावों के बारे में कोई सवाल पूछना है या लाइब्रेरी के सबसे नए वर्शन पर माइग्रेट करने में कोई समस्या आ रही है, तो हमारे ट्रैकर पर समस्या दर्ज करें.