Google Ads क्वेरी लैंग्वेज

सलाह: अपनी GAQL क्वेरी बनाने और उनकी पुष्टि करने के लिए, इंटरैक्टिव क्वेरी बिल्डर का इस्तेमाल करें.

मुख्य शब्दावली

संसाधन

Google Ads में मौजूद कोई इकाई, जैसे कि campaign या ad_group.

सेगमेंट

डेटा को ग्रुप करने के लिए इस्तेमाल किया जाने वाला डाइमेंशन, जैसे कि segments.date या segments.device. जब सेगमेंट को मेट्रिक के साथ SELECT क्लॉज़ में शामिल किया जाता है, तो मेट्रिक को सेगमेंट के हिसाब से बांटा जाता है.

मेट्रिक

परफ़ॉर्मेंस का आकलन, जैसे कि metrics.impressions या metrics.clicks.

एट्रिब्यूट किया गया संसाधन

ऐसा संसाधन जो FROM क्लॉज़ में मुख्य संसाधन से सीधे तौर पर जुड़ा होता है. इससे आपको मुख्य संसाधन के एट्रिब्यूट के साथ-साथ, उसके एट्रिब्यूट चुनने की सुविधा मिलती है.

संसाधन या मेटाडेटा की जानकारी के लिए क्वेरी

Google Ads Query Language, Google Ads API से इस तरह की जानकारी के लिए क्वेरी कर सकती है:

• GoogleAdsService Search या SearchStream का इस्तेमाल करके, संसाधन और उनसे जुड़े एट्रिब्यूट, सेगमेंट, और मेट्रिक: GoogleAdsService क्वेरी का नतीजा, GoogleAdsRow इंस्टेंस की सूची होती है. इसमें हर GoogleAdsRow एक संसाधन को दिखाता है.

  अगर किसी एट्रिब्यूट या मेट्रिक का अनुरोध किया जाता है, तो पंक्ति में वे फ़ील्ड भी शामिल होते हैं. अगर किसी सेगमेंट के लिए अनुरोध किया जाता है, तो जवाब में हर सेगमेंट-रिसॉर्स ट्यूपल के लिए एक अतिरिक्त लाइन भी दिखती है.

• GoogleAdsFieldService में उपलब्ध फ़ील्ड और संसाधनों का मेटाडेटा: यह सेवा, क्वेरी किए जा सकने वाले फ़ील्ड का कैटलॉग उपलब्ध कराती है. इसमें, फ़ील्ड के टाइप और उनके साथ काम करने वाले फ़ील्ड की जानकारी होती है.

  GoogleAdsFieldService क्वेरी का नतीजा, GoogleAdsField इंस्टेंस की सूची होती है. इसमें हर GoogleAdsField में, अनुरोध किए गए फ़ील्ड की जानकारी होती है.

क्वेरी के स्ट्रक्चर के बारे में ज़्यादा जानने के लिए, क्वेरी का स्ट्रक्चर और Google Ads क्वेरी लैंग्वेज का व्याकरण देखें.

संसाधन के एट्रिब्यूट के लिए क्वेरी करना

यहां कैंपेन रिसॉर्स के एट्रिब्यूट के लिए, एक बुनियादी क्वेरी का उदाहरण दिया गया है. इससे पता चलता है कि कैंपेन आईडी, नाम, और स्टेटस कैसे दिखाया जाता है:

SELECT
  campaign.id,
  campaign.name,
  campaign.status
FROM campaign
ORDER BY campaign.id

यह क्वेरी, कैंपेन आईडी के हिसाब से क्रम में लगाई जाती है. हर नतीजे के तौर पर मिलने वाला GoogleAdsRow, चुने गए फ़ील्ड से भरा हुआ campaign ऑब्जेक्ट दिखाता है. इसमें कैंपेन का resource_name भी शामिल है.

कैंपेन क्वेरी के लिए कौनसे अन्य फ़ील्ड उपलब्ध हैं, यह जानने के लिए Campaign रेफ़रंस दस्तावेज़ देखें.

मेट्रिक के लिए क्वेरी

किसी संसाधन के लिए चुने गए एट्रिब्यूट के साथ-साथ, उससे जुड़ी मेट्रिक के लिए भी क्वेरी की जा सकती है:

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  metrics.impressions
FROM campaign
WHERE campaign.status = 'PAUSED'
  AND metrics.impressions > 1000
ORDER BY campaign.id

यह क्वेरी सिर्फ़ उन कैंपेन को फ़िल्टर करती है जिनका स्टेटस PAUSED है और जिन्हें 1,000 से ज़्यादा इंप्रेशन मिले हैं. साथ ही, यह कैंपेन आईडी के हिसाब से क्रम में लगाए गए हैं. नतीजे के तौर पर मिलने वाले हर GoogleAdsRow में, चुनी गई मेट्रिक के साथ metrics फ़ील्ड भरा होगा.

क्वेरी की जा सकने वाली मेट्रिक की सूची के लिए, Metrics दस्तावेज़ देखें.

सेगमेंट के लिए क्वेरी

किसी संसाधन के लिए चुने गए एट्रिब्यूट के साथ-साथ, उससे जुड़े सेगमेंट के लिए भी क्वेरी की जा सकती है:

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  metrics.impressions,
  segments.date
FROM campaign
WHERE campaign.status = 'PAUSED'
  AND metrics.impressions > 1000
  AND segments.date DURING LAST_30_DAYS
ORDER BY campaign.id

मेट्रिक के लिए क्वेरी करने की तरह ही, यह क्वेरी सिर्फ़ उन कैंपेन को फ़िल्टर करती है जिनका स्टेटस PAUSED है और जिन्हें 1,000 से ज़्यादा इंप्रेशन मिले हैं. हालांकि, यह क्वेरी डेटा को तारीख के हिसाब से सेगमेंट करती है. इससे हर नतीजे में, GoogleAdsRow कैंपेन और तारीख के सेगमेंट का एक ट्यूपल दिखाता है. सेगमेंट करने से, चुनी गई मेट्रिक को अलग-अलग सेगमेंट में बांटा जाता है. इसके लिए, SELECT क्लॉज़ में हर सेगमेंट के हिसाब से ग्रुप बनाया जाता है.

क्वेरी किए जा सकने वाले सेगमेंट की सूची के लिए, Segments दस्तावेज़ देखें.

किसी मिलते-जुलते संसाधन के एट्रिब्यूट के लिए क्वेरी

किसी संसाधन के लिए क्वेरी में, आपके पास अन्य मिलते-जुलते संसाधनों को शामिल करने का विकल्प होता है. हालांकि, इसके लिए ज़रूरी है कि वे संसाधन उपलब्ध हों. इनसे जुड़े संसाधनों को "एट्रिब्यूट किए गए संसाधन" कहा जाता है. अपनी क्वेरी में एट्रिब्यूट चुनकर, एट्रिब्यूट किए गए संसाधनों के साथ इंप्लिसिट तरीके से शामिल हुआ जा सकता है.

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  bidding_strategy.name
FROM campaign
ORDER BY campaign.id

यह क्वेरी, कैंपेन के एट्रिब्यूट चुनने के साथ-साथ, चुने गए हर कैंपेन से जुड़े एट्रिब्यूट भी फ़ेच करती है. नतीजे के तौर पर मिलने वाला हर GoogleAdsRow, चुने गए कैंपेन एट्रिब्यूट के साथ-साथ बिडिंग की रणनीति के चुने गए एट्रिब्यूट bidding_strategy.name से भरे हुए campaign ऑब्जेक्ट को दिखाता है.

कैंपेन क्वेरी के लिए कौनसे एट्रिब्यूट किए गए संसाधन उपलब्ध हैं, यह जानने के लिए Campaign रेफ़रंस दस्तावेज़ देखें.

सबसे सही तरीके

• सिर्फ़ वे फ़ील्ड चुनें जिनकी आपको ज़रूरत है. इससे, जवाब मिलने में ज़्यादा समय लगने और टाइम आउट होने की समस्या से बचा जा सकता है.
• डेवलपमेंट और टेस्टिंग के दौरान LIMIT का इस्तेमाल करें, ताकि बड़े रिज़ल्ट सेट को प्रोसेस करने से बचा जा सके.
• डेटा ट्रांसफ़र और रिस्पॉन्स के साइज़ को कम करने के लिए, WHERE क्लॉज़ में फ़िल्टर लागू करें.
• जटिल क्वेरी बनाने से पहले, फ़ील्ड के साथ काम करने की सुविधा और डेटा टाइप की जांच करने के लिए, GoogleAdsFieldService का इस्तेमाल करें.
• ध्यान रखें कि कुछ फ़ील्ड, खास तौर पर ज़्यादा डेटा या मुश्किल कैलकुलेशन वाले फ़ील्ड, क्वेरी की लागत बढ़ा सकते हैं.

क्वेरी के नतीजों के आधार पर म्यूटेट करना

किसी संसाधन के लिए क्वेरी करते समय, आपको मिले नतीजों को ऑब्जेक्ट के तौर पर तुरंत इस्तेमाल किया जा सकता है. साथ ही, उनमें बदलाव करके, उन्हें उस संसाधन की सेवा में मौजूद, म्यूटेट तरीके पर वापस भेजा जा सकता है. यहां एक सैंपल वर्कफ़्लो दिया गया है:

1. उन सभी PAUSED कैंपेन के लिए क्वेरी चलाएं जिनमें 1,000 से ज़्यादा इंप्रेशन हैं.
2. जवाब में मौजूद हर GoogleAdsRow के campaign फ़ील्ड से Campaign ऑब्जेक्ट पाएं.
3. हर कैंपेन का स्टेटस PAUSED से बदलकर ENABLED करें.
4. बदले गए कैंपेन और उन्हें अपडेट करने के लिए, उनसे जुड़े FieldMask के साथ CampaignService.MutateCampaigns को कॉल करें.

ध्यान दें: क्वेरी से मिले संसाधनों को अपडेट करते समय, FieldMask की जानकारी दें (या क्लाइंट लाइब्रेरी की पहले से मौजूद फ़ील्ड मास्क सुविधा का इस्तेमाल करें), ताकि सिर्फ़ बदले गए फ़ील्ड अपडेट हों. इससे READ_ONLY_FIELD या IMMUTABLE_FIELD गड़बड़ियों से बचा जा सकता है या अनजाने में अन्य एट्रिब्यूट को ओवरराइट होने से रोका जा सकता है.

फ़ील्ड मेटाडेटा

GoogleAdsFieldService को भेजी गई क्वेरी, फ़ील्ड मेटाडेटा को वापस पाने के लिए होती हैं. इस जानकारी का इस्तेमाल करके यह समझा जा सकता है कि किसी क्वेरी में फ़ील्ड को एक साथ कैसे इस्तेमाल किया जा सकता है. एपीआई से डेटा उपलब्ध होता है और यह क्वेरी की पुष्टि करने या उसे बनाने के लिए ज़रूरी मेटाडेटा उपलब्ध कराता है. इससे डेवलपर, प्रोग्राम के हिसाब से ऐसा कर सकते हैं. मेटाडेटा के लिए एक सामान्य क्वेरी यहां दी गई है:

SELECT
  name,
  category,
  selectable,
  filterable,
  sortable,
  selectable_with,
  data_type,
  is_repeated
WHERE name = "<INSERT_RESOURCE_OR_FIELD>"

इस क्वेरी में <INSERT_RESOURCE_OR_FIELD> को किसी संसाधन (जैसे, customer या campaign) या फ़ील्ड (जैसे, campaign.id, metrics.impressions या ad_group.id) से बदला जा सकता है.

अहम जानकारी: ध्यान दें कि इस क्वेरी में कोई FROM क्लॉज़ नहीं है.

क्वेरी किए जा सकने वाले फ़ील्ड की सूची के लिए, GoogleAdsField दस्तावेज़ देखें.

वर्शन के हिसाब से अंतर

Google Ads Query Language के सिंटैक्स, क्लॉज़, और ऑपरेटर, Google Ads API के सभी वर्शन (v23, v24, v25, और v26) में एक जैसे होते हैं. हालांकि, क्वेरी किए जा सकने वाले संसाधनों, सेगमेंट, मेट्रिक, और रिपोर्टिंग के व्यवहार का कैटलॉग, मेजर वर्शन के हिसाब से अलग-अलग होता है. टारगेट एपीआई वर्शन एंडपॉइंट पर GoogleAdsFieldService को क्वेरी करें, ताकि उस वर्शन के फ़ील्ड और साथ काम करने के नियमों की जांच की जा सके:

• फ़ाइनल यूआरएल एक्सपैंशन की ऐसेट का व्यू:
  • शॉपिंग कैंपेन के लिए सहायता (v26 और इसके बाद के वर्शन): final_url_expansion_asset_view परफ़ॉर्मेंस मैक्स और सर्च कैंपेन के अलावा, शॉपिंग कैंपेन (campaign.advertising_channel_type = 'SHOPPING') के लिए भी सहायता उपलब्ध है. शॉपिंग कैंपेन के लिए, ad_group फ़ील्ड को चुना और फ़िल्टर किया जा सकता है. हालांकि, asset_group फ़ील्ड को नहीं चुना जा सकता.
  • चुनी जा सकने वाली मेट्रिक (v25 और इसके बाद के वर्शन): final_url_expansion_asset_view को क्वेरी करने पर, व्यू के लिए चुनी जा सकने वाली सभी मेट्रिक दिखती हैं. v24 और इससे पहले के वर्शन में, जवाबों में परफ़ॉर्मेंस मैक्स कैंपेन के लिए सिर्फ़ metrics.conversions और metrics.conversions_value शामिल होते हैं. साथ ही, सर्च कैंपेन के लिए metrics.impressions शामिल होता है.
• लाइफ़साइकल के लक्ष्य से जुड़े संसाधन: v25 और इसके बाद के वर्शन में, लाइफ़साइकल के सभी लक्ष्यों (नए ग्राहक हासिल करना, ग्राहक को जोड़े रखना, और लॉयल्टी प्रोग्राम के तहत ग्राहक को जोड़े रखना) के लिए, यूनिफ़ाइड goal और campaign_goal_config संसाधनों से क्वेरी की जाती है. ये संसाधन, customer_lifecycle_goal और campaign_lifecycle_goal की जगह इस्तेमाल किए जाते हैं. v24 और इससे पहले के वर्शन में, नए ग्राहक हासिल करने के लक्ष्यों के लिए और का इस्तेमाल किया जाता था. साथ ही, ग्राहक को जोड़े रखने के लक्ष्यों के लिए, goal और campaign_goal_config का इस्तेमाल किया जाता था.
• ऐप्लिकेशन कैंपेन के लिए शॉपिंग प्रॉडक्ट रिपोर्टिंग: v24 और इसके बाद के वर्शन में, shopping_product रिसॉर्स, शॉपिंग, परफ़ॉर्मेंस मैक्स, मांग बढ़ाने में मदद करने वाले कैंपेन, और वीडियो कैंपेन के साथ-साथ ऐप्लिकेशन कैंपेन के लिए भी प्रॉडक्ट की लाइनें दिखाता है. v23 में, ऐप्लिकेशन कैंपेन को shopping_product के नतीजों से बाहर रखा गया है.
• वर्शन के हिसाब से संसाधन, सेगमेंट, और मेट्रिक:
  • v26 और इसके बाद के वर्शन: इसमें search_lift_keyword_bundle संसाधन, campaign.lift_measurement_config, local_services_lead.campaign, segments.search_lift_keyword_bundle, segments.search_property, और खोज में बढ़त की मेट्रिक (जैसे, metrics.relative_search_lift, metrics.normalized_incremental_searches, metrics.search_lift_cost_micros, और metrics.search_lift_impressions) शामिल हैं.
  • v25 और इसके बाद के वर्शन: इसमें लिफ़्ट मेज़रमेंट के संसाधन (जैसे, lift_measurement_config), segments.ad_sub_format_type और segments.loyalty_membership जैसे सेगमेंट, और YouTube यूज़र ऐक्टिविटी मेट्रिक (metrics.youtube_likes, metrics.youtube_comments, और metrics.youtube_shares) शामिल हैं. local_services_lead.contact_details.email को हटाता है (इसे v24 और इससे पहले के वर्शन में चुना जा सकता है).
  • v24 और इसके बाद के वर्शन: इसमें cart_data_sales_view रिसॉर्स शामिल है. इसे shopping_performance_view को segments.conversion_attribution_event_type और performance_max_placement_view को segments.mobile_device_platform और segments.ad_network_type पर रिलीज़ किया गया. campaign.video_brand_safety_suitability को हटाता है (इसकी जगह customer.video_brand_safety_suitability का इस्तेमाल किया जाता है), segments.ad_sub_network_type को campaign_budget पर, और segments.click_type को ad_group_asset, campaign_asset, और customer_asset पर (इन्हें सिर्फ़ v23 में चुना जा सकता है).
• तारीख के हिसाब से ज़्यादा जानकारी वाले डेटा के लिए लुकबैक विंडो से जुड़ी गड़बड़ी का कोड: segments.date, segments.week या segments.hour के हिसाब से सेगमेंट की गई क्वेरी (या महीने से कम की तारीख की सीमा पर फ़िल्टर की गई क्वेरी) के लिए, 37 महीने की लुकबैक विंडो से ज़्यादा का डेटा नहीं मिलता. इसके बाद, v24 और उसके बाद के वर्शन में DateRangeError.REQUESTED_DATE_GRANULARITY_NOT_SUPPORTED (या v23 में DateRangeError.UNKNOWN) गड़बड़ी का कोड दिखता है. ज़्यादा जानकारी के लिए, तारीख की सीमाएं देखें.

कोड के उदाहरण

क्लाइंट लाइब्रेरी में, GoogleAdsService में Google Ads क्वेरी लैंग्वेज का इस्तेमाल करने के उदाहरण दिए गए हैं. बेसिक ऑपरेशन फ़ोल्डर में, GetCampaigns, GetKeywords, और SearchForGoogleAdsFields जैसे उदाहरण मौजूद हैं.