कॉन्फ़िगरेशन

Google Ads API की क्लाइंट लाइब्रेरी में, कई कॉन्फ़िगरेशन सेटिंग उपलब्ध हैं. इनका इस्तेमाल करके, लाइब्रेरी के काम करने के तरीके को अपनी ज़रूरत के मुताबिक बनाया जा सकता है.

रनटाइम के दौरान लाइब्रेरी को कॉन्फ़िगर करना

क्लाइंट लाइब्रेरी को कॉन्फ़िगर करने का सबसे सही तरीका, रनटाइम के दौरान GoogleAdsConfig ऑब्जेक्ट को शुरू करना है:

using Google.Ads.Gax.Config;
using Google.Ads.GoogleAds.Config;
using Google.Ads.GoogleAds.Lib;

GoogleAdsConfig config = new GoogleAdsConfig()
{
    OAuth2Mode = OAuth2Flow.APPLICATION,
    OAuth2ClientId = "INSERT_CLIENT_ID.apps.googleusercontent.com",
    OAuth2ClientSecret = "INSERT_CLIENT_SECRET",
    OAuth2RefreshToken = "INSERT_REFRESH_TOKEN",
    LoginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"
};

GoogleAdsClient client = new GoogleAdsClient(config);

कॉन्फ़िगरेशन के अन्य विकल्प

लाइब्रेरी में, appsettings.json, कस्टम JSON फ़ाइलों, एनवायरमेंट वैरिएबल या App.config से कॉन्फ़िगरेशन सेटिंग लोड करने के अन्य विकल्प भी मिलते हैं. इन्हें चालू करने के लिए, अपने प्रोजेक्ट में Google.Ads.GoogleAds.Extensions NuGet पैकेज इंस्टॉल करें:

dotnet add package Google.Ads.GoogleAds.Extensions

इनमें से किसी विकल्प का इस्तेमाल करने पर, कॉन्फ़िगरेशन सेटिंग अपने-आप लागू नहीं होती हैं. आपको उन्हें साफ़ तौर पर लोड करना होगा, जैसा कि यहां बताया गया है. बाहरी फ़ाइलों या स्ट्रीम से सेटिंग लोड करते समय, फ़ाइल I/O अपवादों (जैसे, FileNotFoundException या UnauthorizedAccessException) को मैनेज करना न भूलें.

appsettings.json या settings.json का इस्तेमाल करना

.NET 8.0 और ASP.NET Core ऐप्लिकेशन में, अपनी कॉन्फ़िगरेशन कुंजियों को appsettings.json (या settings.json) में GoogleAdsApi सेक्शन के अंदर रखें:

{
  "GoogleAdsApi": {
    "LoginCustomerId": "INSERT_LOGIN_CUSTOMER_ID_HERE",
    "OAuth2Mode": "APPLICATION",
    "OAuth2ClientId": "INSERT_CLIENT_ID.apps.googleusercontent.com",
    "OAuth2ClientSecret": "INSERT_CLIENT_SECRET",
    "OAuth2RefreshToken": "INSERT_REFRESH_TOKEN"
  }
}

इसके बाद, अपने ऐप्लिकेशन के IConfiguration इंस्टेंस से GoogleAdsApi सेक्शन को निकालें. उदाहरण के लिए, ASP.NET Core से इंजेक्ट किया गया या ConfigurationBuilder से बनाया गया. इसके बाद, इसे LoadFromConfigurationSection के साथ लोड करें:

using Google.Ads.GoogleAds.Config;
using Google.Ads.GoogleAds.Extensions.Config;
using Google.Ads.GoogleAds.Lib;
using Microsoft.Extensions.Configuration;

IConfigurationSection section = configuration.GetSection("GoogleAdsApi");
GoogleAdsConfig config = new GoogleAdsConfig();
config.LoadFromConfigurationSection(section);
GoogleAdsClient client = new GoogleAdsClient(config);

इसके अलावा, LoadFromSettingsJson का इस्तेमाल करके, पाथ से सीधे appsettings.json या settings.json फ़ाइल लोड की जा सकती है:

using Google.Ads.GoogleAds.Config;
using Google.Ads.GoogleAds.Extensions.Config;
using Google.Ads.GoogleAds.Lib;

GoogleAdsConfig config = new GoogleAdsConfig();
config.LoadFromSettingsJson("appsettings.json", "GoogleAdsApi");
GoogleAdsClient client = new GoogleAdsClient(config);

config.TryLoadFromEnvironmentFilePath को कॉल करके, GOOGLE_ADS_CONFIGURATION_FILE_PATH एनवायरमेंट वैरिएबल (EnvironmentVariableNames.CONFIG_FILE_PATH) से भी पाथ लोड किया जा सकता है.

कस्टम JSON फ़ाइल का इस्तेमाल करना

IConfigurationRoot इंस्टेंस का इस्तेमाल करके भी, टॉप-लेवल GoogleAdsApi सेक्शन के बिना फ़्लैट JSON फ़ाइल लोड की जा सकती है.

JSON फ़ाइल बनाना

GoogleAdsApi.json नाम की एक JSON फ़ाइल बनाएं, जो रूट लेवल पर कॉन्फ़िगरेशन कुंजियों को तय करती है:

{
  "Timeout": "2000",
  "ProxyServer": "http://localhost:8888",
  "ProxyUser": "",
  "ProxyPassword": "",
  "ProxyDomain": "",
  "LoginCustomerId": "INSERT_LOGIN_CUSTOMER_ID_HERE",
  "OAuth2Mode": "APPLICATION",
  "OAuth2ClientId": "INSERT_CLIENT_ID.apps.googleusercontent.com",
  "OAuth2ClientSecret": "INSERT_CLIENT_SECRET",
  "OAuth2RefreshToken": "INSERT_REFRESH_TOKEN"
}

कॉन्फ़िगरेशन लोड करें

इसके बाद, JSON फ़ाइल को IConfigurationRoot में लोड करें:

using System.IO;
using Google.Ads.GoogleAds.Config;
using Google.Ads.GoogleAds.Extensions.Config;
using Google.Ads.GoogleAds.Lib;
using Microsoft.Extensions.Configuration;

ConfigurationBuilder builder = new ConfigurationBuilder()
    .SetBasePath(Directory.GetCurrentDirectory())
    .AddJsonFile("GoogleAdsApi.json");
IConfigurationRoot configRoot = builder.Build();

GoogleAdsConfig config = new GoogleAdsConfig();
config.LoadFromConfigurationRoot(configRoot);
GoogleAdsClient client = new GoogleAdsClient(config);

एनवायरमेंट वैरिएबल का इस्तेमाल करना

एनवायरमेंट वैरिएबल का इस्तेमाल करके भी GoogleAdsClient को शुरू किया जा सकता है:

using Google.Ads.GoogleAds.Config;
using Google.Ads.GoogleAds.Extensions.Config;
using Google.Ads.GoogleAds.Lib;

GoogleAdsConfig config = new GoogleAdsConfig();
config.LoadFromEnvironmentVariables();
GoogleAdsClient client = new GoogleAdsClient(config);

ध्यान दें: GoogleAdsConfig.OAuth2Mode डिफ़ॉल्ट रूप से APPLICATION पर सेट होता है. इसलिए, GOOGLE_ADS_JSON_KEY_FILE_PATH का इस्तेमाल करके सेवा खाते की पुष्टि करते समय, GOOGLE_ADS_OAUTH2_MODE=SERVICE_ACCOUNT को भी सेट करना न भूलें.

इस्तेमाल किए जा सकने वाले एनवायरमेंट वैरिएबल की पूरी सूची देखें.

App.config का इस्तेमाल करना

.NET Framework ऐप्लिकेशन में, Google Ads API से जुड़ी सभी सेटिंग, App.config फ़ाइल के GoogleAdsApi नोड में सेव होती हैं. आम तौर पर, कॉन्फ़िगरेशन App.config इस तरह होता है:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <configSections>
    <section name="GoogleAdsApi"
             type="System.Configuration.DictionarySectionHandler" />
  </configSections>
  <GoogleAdsApi>
    <!-- Set the service timeout in milliseconds. -->
    <add key="Timeout" value="2000" />

    <!-- Proxy settings for library. -->
    <add key="ProxyServer" value="http://localhost:8888" />
    <add key="ProxyUser" value="" />
    <add key="ProxyPassword" value="" />
    <add key="ProxyDomain" value="" />

    <!-- Google Ads API settings. -->
    <add key="LoginCustomerId" value="INSERT_LOGIN_CUSTOMER_ID_HERE" />

    <!-- OAuth2 settings -->
    <add key="OAuth2Mode" value="APPLICATION" />
    <add key="OAuth2ClientId"
         value="INSERT_CLIENT_ID.apps.googleusercontent.com" />
    <add key="OAuth2ClientSecret" value="INSERT_CLIENT_SECRET" />
    <add key="OAuth2RefreshToken" value="INSERT_REFRESH_TOKEN" />
  </GoogleAdsApi>
  <startup>
    <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.7.2" />
  </startup>
</configuration>

App.config फ़ाइल से कॉन्फ़िगरेशन सेटिंग लोड करने के लिए, GoogleAdsConfig ऑब्जेक्ट पर LoadFromDefaultAppConfigSection तरीके को कॉल करें:

using Google.Ads.GoogleAds.Config;
using Google.Ads.GoogleAds.Extensions.Config;
using Google.Ads.GoogleAds.Lib;

GoogleAdsConfig config = new GoogleAdsConfig();
config.LoadFromDefaultAppConfigSection();
GoogleAdsClient client = new GoogleAdsClient(config);

कोई अलग App.config फ़ाइल तय करना

अगर आपको App.config को व्यवस्थित रखना है, तो लाइब्रेरी के हिसाब से कॉन्फ़िगरेशन को उसकी अपनी कॉन्फ़िगरेशन फ़ाइल में ले जाएं. इसके लिए, configSource प्रॉपर्टी का इस्तेमाल करें:

1. अपने App.config में configSource की जानकारी दें. किसी बाहरी कॉन्फ़िगरेशन फ़ाइल का रेफ़रंस देने के लिए, अपनी App.config में बदलाव करें:

   <?xml version="1.0" encoding="utf-8" ?>
   <configuration>
     <configSections>
       <section name="GoogleAdsApi"
                type="System.Configuration.DictionarySectionHandler" />
     </configSections>
     <GoogleAdsApi configSource="GoogleAdsApi.config" />
   </configuration>
   

2. अपनी कॉन्फ़िगरेशन फ़ाइल का कॉन्टेंट तय करें. configSource (GoogleAdsApi.config) में बताए गए नाम से एक और कॉन्फ़िगरेशन फ़ाइल बनाएं. इसके बाद, GoogleAdsApi कॉन्फ़िगरेशन नोड को App.config से इस फ़ाइल में ले जाएं:

   <?xml version="1.0" encoding="utf-8" ?>
   <GoogleAdsApi>
     <!-- More settings. -->
   </GoogleAdsApi>
   

3. अपने .csproj में बिल्ड के नियमों को अपडेट करें. अपने प्रोजेक्ट में नई कॉन्फ़िगरेशन फ़ाइल शामिल करें. साथ ही, इसकी Copy to Output Directory प्रॉपर्टी को Copy always पर सेट करें. अपने प्रोजेक्ट को फिर से बनाएं और चलाएं, ताकि आपका ऐप्लिकेशन नई कॉन्फ़िगरेशन फ़ाइल से वैल्यू ले सके.

सामान्य स्ट्रीम का इस्तेमाल करना

कॉन्फ़िगरेशन या उसके कुछ हिस्सों को सामान्य स्ट्रीम से भी लोड किया जा सकता है. इसमें एन्क्रिप्ट (सुरक्षित) की गई स्ट्रीम भी शामिल है:

GoogleAdsConfig config = new GoogleAdsConfig()
{
    // Set some configuration properties in code.
    OAuth2Mode = OAuth2Flow.SERVICE_ACCOUNT,
};

// Load your encrypted data from a file and dispose of the streams properly.
using (CryptoStream strm = GetEncryptedCredentialsStream())
using (StreamReader rdr = new StreamReader(strm))
{
    // Configure the OAuth credentials from the encrypted stream.
    config.LoadOAuth2SecretsFromStream(rdr);
}

GoogleAdsClient client = new GoogleAdsClient(config);

कॉन्फ़िगरेशन फ़ील्ड

यहां दिए गए सेक्शन में, Google Ads .NET लाइब्रेरी के साथ काम करने वाली सेटिंग की सूची दी गई है.

कनेक्टिविटी की सेटिंग

• Timeout: इस बटन का इस्तेमाल करके, सेवा के टाइम आउट को मिलीसेकंड में सेट करें. डिफ़ॉल्ट वैल्यू, googleads_grpc_service_config.json में method_config/timeout सेटिंग के आधार पर सेट की जाती है. अगर आपको एपीआई कॉल के लिए ज़्यादा से ज़्यादा समय की सीमा को कम करना है, तो कम वैल्यू सेट करें. टाइम आउट को दो घंटे या उससे ज़्यादा पर सेट किया जा सकता है. हालांकि, एपीआई अब भी बहुत लंबे समय तक चलने वाले अनुरोधों को टाइम आउट कर सकता है और DEADLINE_EXCEEDED गड़बड़ी दिखा सकता है.
• ProxyServer: अगर इंटरनेट से कनेक्ट करने के लिए प्रॉक्सी का इस्तेमाल किया जा रहा है, तो इसे एचटीटीपी प्रॉक्सी सर्वर यूआरएल पर सेट करें.
• ProxyUser: इसे उस उपयोगकर्ता नाम पर सेट करें जिसकी ज़रूरत आपको प्रॉक्सी सर्वर की पुष्टि करने के लिए है. अगर उपयोगकर्ता नाम की ज़रूरत नहीं है, तो इसे खाली छोड़ दें.
• ProxyPassword: अगर आपने ProxyUser के लिए कोई वैल्यू सेट की है, तो इसे ProxyUser के पासवर्ड पर सेट करें.
• ProxyDomain: अगर आपके प्रॉक्सी सर्वर को डोमेन सेट करने की ज़रूरत है, तो इसे ProxyUser के डोमेन पर सेट करें.
• MaxReceiveMessageLengthInBytes: इस सेटिंग का इस्तेमाल करके, एपीआई से मिलने वाली जानकारी के ज़्यादा से ज़्यादा साइज़ को बढ़ाया जा सकता है. यह साइज़, क्लाइंट लाइब्रेरी के हिसाब से तय होता है. इसकी डिफ़ॉल्ट वैल्यू 64 एमबी होती है.
• MaxMetadataSizeInBytes: इस सेटिंग का इस्तेमाल करके, एपीआई से मिलने वाली गड़बड़ी के जवाब का ज़्यादा से ज़्यादा साइज़ बढ़ाया जा सकता है. यह साइज़, क्लाइंट लाइब्रेरी के हिसाब से तय होता है. इसकी डिफ़ॉल्ट वैल्यू 16 एमबी होती है.

ResourceExhausted से जुड़ी कुछ गड़बड़ियों को ठीक करने के लिए, MaxReceiveMessageLengthInBytes और MaxMetadataSizeInBytes सेटिंग में बदलाव करें. इन सेटिंग से, इस तरह की गड़बड़ियों को ठीक किया जा सकता है:

Status(StatusCode="ResourceExhausted",Detail="Received
message larger than max (423184132 versus 67108864)"

इस उदाहरण में, गड़बड़ी की वजह यह है कि मैसेज का साइज़ (423184132 bytes), लाइब्रेरी के लिए तय किए गए साइज़ (67108864 bytes) से ज़्यादा है. इस गड़बड़ी से बचने के लिए, MaxReceiveMessageLengthInBytes को बढ़ाकर 500000000 करें. ध्यान दें कि गड़बड़ी से यह भी पता चलता है कि आपके कोड ने काफ़ी बड़े रिस्पॉन्स ऑब्जेक्ट (जैसे कि बड़ा SearchGoogleAdsResponse) को मैनेज किया है. .NET के लार्ज ऑब्जेक्ट हीप की वजह से, आपके कोड की परफ़ॉर्मेंस पर असर पड़ सकता है. अगर इससे परफ़ॉर्मेंस पर असर पड़ता है, तो आपको एपीआई कॉल को फिर से व्यवस्थित करने या अपने ऐप्लिकेशन के कुछ हिस्सों को फिर से डिज़ाइन करने का तरीका ढूंढना पड़ सकता है.

OAuth2 की सेटिंग

Google Ads API सर्वर के लिए, OAuth 2.0 का इस्तेमाल करके कॉल को अनुमति देते समय, आपको ये कॉन्फ़िगरेशन कुंजियां सेट करनी चाहिए:

• AuthorizationMethod: OAuth2 पर सेट करें.
• OAuth2Mode: इसे APPLICATION या SERVICE_ACCOUNT पर सेट करें.
• OAuth2ClientId: इस वैल्यू को अपने OAuth 2.0 क्लाइंट आईडी पर सेट करें.
• OAuth2ClientSecret: इस वैल्यू को अपने OAuth 2.0 क्लाइंट सीक्रेट पर सेट करें.
• OAuth2Scope: अगर आपको एक से ज़्यादा एपीआई के लिए OAuth 2.0 टोकन को अनुमति देनी है, तो इस वैल्यू को अलग-अलग स्कोप पर सेट करें. इस सेटिंग का इस्तेमाल करना ज़रूरी नहीं है.
• UseApplicationDefaultCredentials: ऐप्लिकेशन के डिफ़ॉल्ट क्रेडेंशियल का इस्तेमाल करके पुष्टि करने के लिए, इस वैल्यू को true पर सेट करें. यह सुविधा, Google.Ads.GoogleAds v24.1.0 और इसके बाद के वर्शन में काम करती है. config.LoadFromEnvironmentVariables(), बिना प्रीफ़िक्स वाले USE_APPLICATION_DEFAULT_CREDENTIALS एनवायरमेंट वैरिएबल को पढ़ता है.
• Credentials: (सिर्फ़ रनटाइम के लिए, v27.0.0 और उसके बाद के वर्शन में काम करता है) रनटाइम के दौरान, पहले से बनाए गए ICredential या GoogleCredential इंस्टेंस को सीधे GoogleAdsConfig पर इंजेक्ट करें.

अगर OAuth2Mode == APPLICATION का इस्तेमाल किया जा रहा है, तो आपको ये अतिरिक्त कॉन्फ़िगरेशन कुंजियां सेट करनी होंगी:

• OAuth2RefreshToken: अगर आपको OAuth 2.0 टोकन का फिर से इस्तेमाल करना है, तो इस वैल्यू को पहले से जनरेट किए गए OAuth 2.0 रीफ़्रेश टोकन पर सेट करें. इस सेटिंग का इस्तेमाल करना ज़रूरी नहीं है.
• OAuth2RedirectUri: इस वैल्यू को OAuth 2.0 रीडायरेक्ट यूआरएल पर सेट करें. इस सेटिंग का इस्तेमाल करना ज़रूरी नहीं है.

ज़्यादा जानकारी के लिए, यहां दी गई गाइड देखें:

• OAuth डेस्कटॉप ऐप्लिकेशन फ़्लो
• OAuth वेब ऐप्लिकेशन फ़्लो

अगर OAuth2Mode == SERVICE_ACCOUNT का इस्तेमाल किया जा रहा है, तो आपको कॉन्फ़िगरेशन की ये अतिरिक्त कुंजियां सेट करनी होंगी:

• OAuth2SecretsJsonPath: इस वैल्यू को OAuth 2.0 JSON कुंजी फ़ाइल के पाथ पर सेट करें.
• OAuth2PrnEmail: इस वैल्यू को उस खाते के ईमेल पते पर सेट करें जिसकी पहचान का इस्तेमाल, Google Workspace के डोमेन-वाइड डेलिगेशन का इस्तेमाल करते समय किया जा रहा है. इस सेटिंग का इस्तेमाल करना ज़रूरी नहीं है.

ज़्यादा जानकारी के लिए, OAuth सेवा खाते के फ़्लो की गाइड देखें.

यात्रा की सेटिंग

• UseGrpcCore: Grpc.Core लाइब्रेरी को ट्रांसपोर्ट लेयर के तौर पर इस्तेमाल करने के लिए, इस सेटिंग को true पर सेट करें. Grpc.Core लाइब्रेरी का इस्तेमाल करना देखें.

Google Ads API की सेटिंग

यहां दी गई सेटिंग, Google Ads API के लिए खास तौर पर उपलब्ध हैं:

• LoginCustomerId: यह उस ग्राहक का आईडी है जिसे अनुरोध में इस्तेमाल करने की अनुमति मिली है. इसमें हाइफ़न (-) नहीं होने चाहिए.
• LinkedCustomerId: यह हेडर सिर्फ़ उन तरीकों के लिए ज़रूरी है जो किसी इकाई के संसाधनों को अपडेट करते हैं. ऐसा तब होता है, जब Google Ads यूज़र इंटरफ़ेस (यूआई) में लिंक किए गए खातों (Google Ads API में AccountLink संसाधन) के ज़रिए अनुमति दी जाती है. इस वैल्यू को डेटा उपलब्ध कराने वाली उस कंपनी के ग्राहक आईडी पर सेट करें जो दिए गए ग्राहक आईडी के संसाधनों को अपडेट करती है. इसे हाइफ़न (-) के बिना सेट किया जाना चाहिए. लिंक किए गए खातों के बारे में ज़्यादा जानें.