शुरू करें

इस गाइड में, Google Ads API की .NET लाइब्रेरी का इस्तेमाल शुरू करने के तरीके की खास जानकारी दी गई है.

इंस्टॉल करना

क्लाइंट लाइब्रेरी बाइनरी को NuGet का इस्तेमाल करके डिस्ट्रिब्यूट किया जाता है. क्लाइंट लाइब्रेरी का इस्तेमाल करने के लिए, अपने प्रोजेक्ट में Google.Ads.GoogleAds package के लिए Nuget रेफ़रंस जोड़ें.

अनुमति देने की सुविधा सेट अप करें

अपने एपीआई कॉल को अनुमति देने के लिए, आपको लाइब्रेरी में अपना क्लाइंट आईडी, क्लाइंट सीक्रेट, रीफ़्रेश टोकन, और डेवलपर टोकन की जानकारी देनी होगी.

अगर आपके पास पहले से क्रेडेंशियल हैं...

• GitHub में App.config फ़ाइल से अपनी App.config / Web.config फ़ाइल में GoogleAdsApi नोड और configSections नोड में मौजूद GoogleAdsApi सेक्शन को कॉपी करें. अगर आपने पैकेज इंस्टॉल करने के लिए NuGet का इस्तेमाल किया है, तो ये नोड आपकी App.config / Web.config फ़ाइल में अपने-आप शामिल हो जाएंगे.
• अपने ऐप्लिकेशन के App.config / Web.config में डेवलपर टोकन, क्लाइंट आईडी, क्लाइंट सीक्रेट, और रीफ़्रेश टोकन शामिल करें. GitHub में शामिल App.config फ़ाइल के बारे में अच्छी तरह से जानकारी मौजूद है. हालांकि, ज़्यादा जानकारी के साथ-साथ कॉन्फ़िगरेशन के लिए वैकल्पिक सेटिंग इस्तेमाल करने के बारे में ज़्यादा जानने के लिए, कॉन्फ़िगरेशन गाइड भी देखा जा सकता है.

अगर आपको क्रेडेंशियल जनरेट करने हैं...

• अगर आपके पास पहले से कोई डेवलपर टोकन नहीं है, तो उसे पाने के लिए डेवलपर टोकन गाइड देखें.
• क्लाइंट आईडी, क्लाइंट सीक्रेट, और रीफ़्रेश टोकन जनरेट करने के लिए, OAuth डेस्कटॉप ऐप्लिकेशन फ़्लो गाइड का पालन करें.
• GitHub में App.config फ़ाइल से अपनी App.config / Web.config फ़ाइल में GoogleAdsApi नोड और configSections नोड में मौजूद GoogleAdsApi सेक्शन को कॉपी करें. अगर आपने पैकेज इंस्टॉल करने के लिए NuGet का इस्तेमाल किया है, तो ये नोड आपकी App.config / Web.config फ़ाइल में अपने-आप शामिल हो जाएंगे.
• अपने ऐप्लिकेशन के App.config / Web.config में डेवलपर टोकन, क्लाइंट आईडी, क्लाइंट सीक्रेट, और रीफ़्रेश टोकन शामिल करें. GitHub में शामिल App.config फ़ाइल के बारे में अच्छी तरह से जानकारी मौजूद है. हालांकि, ज़्यादा जानकारी के साथ-साथ कॉन्फ़िगरेशन के लिए वैकल्पिक सेटिंग इस्तेमाल करने के बारे में ज़्यादा जानने के लिए, कॉन्फ़िगरेशन गाइड भी देखा जा सकता है.

एपीआई कॉल करें

क्लाइंट लाइब्रेरी का बुनियादी इस्तेमाल नीचे दिखाया गया है:

// Create a Google Ads client.
GoogleAdsClient client = new GoogleAdsClient();

// Create the required service.
CampaignServiceClient campaignService =
    client.GetService(Services.V16.CampaignService);

// Make more calls to service class.

GoogleAdsClient इंस्टेंस बनाएं

Google Ads API की .NET लाइब्रेरी में सबसे ज़रूरी क्लास GoogleAdsClient है. इससे पहले से कॉन्फ़िगर की गई सर्विस क्लास बनाई जा सकती है, जिसका इस्तेमाल एपीआई कॉल करने के लिए किया जा सकता है. GoogleAdsClient एक डिफ़ॉल्ट कंस्ट्रक्टर देता है, जो आपके ऐप्लिकेशन के App.config / Web.config में बताई गई सेटिंग का इस्तेमाल करके, उपयोगकर्ता ऑब्जेक्ट बनाता है. कॉन्फ़िगरेशन के अलग-अलग विकल्पों के लिए कॉन्फ़िगरेशन गाइड देखें.

// Create a new GoogleAdsClient with the App.config settings.
GoogleAdsClient user = new GoogleAdsClient();

सेवा बनाएं

GoogleAdsClient में, GetService का तरीका दिया गया है. इसका इस्तेमाल विज्ञापन सेवा बनाने के लिए किया जा सकता है.

CampaignServiceClient campaignService = client.GetService(Services.V16.CampaignService);
// Now make calls to CampaignService.

हम एक Services क्लास उपलब्ध कराते हैं, जिसमें इस्तेमाल किए जा सकने वाले सभी एपीआई वर्शन और सेवाओं की सूची होती है. सेवा बनाते समय, GetService तरीका, गिनती के इन ऑब्जेक्ट को तर्क के तौर पर स्वीकार करता है. उदाहरण के लिए, Google Ads API के V16 वर्शन के लिए CampaignServiceClient का इंस्टेंस बनाने के लिए, आपको ऊपर बताए गए तरीके से, Services.V16.CampaignService के साथ GoogleAdsClient.GetService तरीके को कॉल करना होगा.

थ्रेड की सुरक्षा

एक से ज़्यादा थ्रेड के बीच GoogleAdsClient इंस्टेंस शेयर करना सुरक्षित नहीं है, क्योंकि एक थ्रेड में किसी इंस्टेंस पर कॉन्फ़िगरेशन में किए गए बदलाव, अन्य थ्रेड में बनाई जाने वाली सेवाओं पर असर डाल सकते हैं. किसी GoogleAdsClient इंस्टेंस से नई सेवा इंस्टेंस पाने जैसी कार्रवाइयां, एक साथ कई सेवाओं को कॉल करना वगैरह जैसी कार्रवाइयां, थ्रेड के लिए सुरक्षित होती हैं.

मल्टीथ्रेड ऐप्लिकेशन कुछ ऐसा दिखेगा:

GoogleAdsClient client1 = new GoogleAdsClient();
GoogleAdsClient client2 = new GoogleAdsClient();

Thread userThread1 = new Thread(addAdGroups);
Thread userThread2 = new Thread(addAdGroups);

userThread1.start(client1);
userThread2.start(client2);

userThread1.join();
userThread2.join();

public void addAdGroups(object data) {
  GoogleAdsClient client = (GoogleAdsClient) data;
  // Do more operations here.
  ...
}

.NET फ़्रेमवर्क ऐप्लिकेशन में फ़्रीज़ होने से बचना

सिंक्रोनस तरीकों की वजह से आपके कुछ .NET फ़्रेमवर्क ऐप्लिकेशन फ़्रीज़ हो सकते हैं. इसका एक सामान्य उदाहरण यह है कि किसी WinForm ऐप्लिकेशन के इवेंट हैंडलर तरीके से एपीआई कॉल करना.

इस समस्या को हल करने के दो तरीके हैं:

1. लेगसी Grpc लाइब्रेरी का इस्तेमाल करें.

   डिफ़ॉल्ट Grpc.Net.Client लाइब्रेरी के बजाय, लेगसी Grpc.Core लाइब्रेरी का इस्तेमाल करने के लिए, GoogleAdsConfig की UseGrpcCore प्रॉपर्टी को सेट किया जा सकता है. इस तरीके की जांच, .NET फ़्रेमवर्क ऐप्लिकेशन पर बहुत ज़्यादा नहीं की गई है. इसलिए, हो सकता है कि इससे समस्या हल न हो. सैंपल के तौर पर यहां एक स्निपेट दिया गया है:

   GoogleAdsConfig config = new GoogleAdsConfig();
   config.UseGrpcCore = true;
   GoogleAdsClient client = new GoogleAdsClient(config);
   

2. एसिंक्रोनस तरीकों का इस्तेमाल करें.

   फ़्रीज़ से बचने के लिए, एसिंक्रोनस तरीकों का इस्तेमाल किया जा सकता है. यहां कुछ उदाहरण दिए गए हैं:

   SearchStream

   SearchStream() को कॉल किया जाता है और नतीजों को सूची की तरह दिखाया जाता है.

   private async void button1_Click(object sender, EventArgs e)
   {
   // Get the GoogleAdsService.
   GoogleAdsServiceClient googleAdsService = client.GetService(
       Services.V16.GoogleAdsService);
    
   // Create a query that will retrieve all campaigns.
   string query = @"SELECT
                   campaign.id,
                   campaign.name,
                   campaign.network_settings.target_content_network
               FROM campaign
               ORDER BY campaign.id";
    
   List items = new List();
   Task t =  googleAdsService.SearchStreamAsync(customerId.ToString(), query,
       delegate (SearchGoogleAdsStreamResponse resp)
       {
           foreach (GoogleAdsRow googleAdsRow in resp.Results)
           {
               ListViewItem item = new ListViewItem();
               item.Text = googleAdsRow.Campaign.Id.ToString();
               item.SubItems.Add(googleAdsRow.Campaign.Name);
               items.Add(item);
           }
       }
   );
   await t;
   listView1.Items.AddRange(items.ToArray());
   }
   

   कैंपेन का बजट

   एक CampaignBudget कॉल बनाया जाता है और MessageBox सूचना का इस्तेमाल करके नए बजट के संसाधन का नाम दिखाया जाता है.

   private async void button2_Click(object sender, EventArgs e)
   {
   // Get the BudgetService.
   CampaignBudgetServiceClient budgetService = client.GetService(
       Services.V16.CampaignBudgetService);
    
   // Create the campaign budget.
   CampaignBudget budget = new CampaignBudget()
   {
       Name = "Interplanetary Cruise Budget #" + ExampleUtilities.GetRandomString(),
       DeliveryMethod = BudgetDeliveryMethod.Standard,
       AmountMicros = 500000
   };
    
   // Create the operation.
   CampaignBudgetOperation budgetOperation = new CampaignBudgetOperation()
   {
       Create = budget
   };
    
   // Create the campaign budget.
   Task t = budgetService.MutateCampaignBudgetsAsync(
       customerId.ToString(), new CampaignBudgetOperation[] { budgetOperation });
    
   await t;
   MutateCampaignBudgetsResponse response = t.Result;
   MessageBox.Show(response.Results[0].ResourceName);
   }
   

एक साथ काम नहीं करने वाली प्रोसेस के तरीकों को रद्द करना

एक साथ काम नहीं करने वाली प्रोग्रामिंग के लिए, callSettings पैरामीटर का इस्तेमाल करके, CancellationToken को पास किया जा सकता है:

CancellationTokenSource cancellationTokenSource = new CancellationTokenSource();
cancellationTokenSource.CancelAfter(3000);
CallSettings callSettings = CallSettings.FromCancellationToken(cancellationTokenSource.Token);

string query = "SELECT campaign.name FROM campaign";
var request = new SearchGoogleAdsStreamRequest()
{
    CustomerId = customerId.ToString(),
    Query = query,
};

GoogleAdsServiceClient googleAdsService = client.GetService(
    Services.V16.GoogleAdsService);

googleAdsService.SearchStream(request,
    delegate (SearchGoogleAdsStreamResponse resp)
    {
        foreach (GoogleAdsRow googleAdsRow in resp.Results)
        {
            // Process the row.
        }
    }, callSettings
);

गड़बड़ी ठीक करना

हर एपीआई कॉल पूरा नहीं होगा. अगर किसी वजह से आपका एपीआई कॉल फ़ेल हो जाता है, तो सर्वर गड़बड़ी दिखा सकता है. एपीआई की गड़बड़ियों को कैप्चर करना और उन्हें सही तरीके से मैनेज करना ज़रूरी है.

एपीआई से जुड़ी कोई गड़बड़ी होने पर, GoogleAdsException इंस्टेंस थ्रो होता है. इसमें ऐसी जानकारी दी गई है, जिससे आपको गड़बड़ियों का पता लगाने में मदद मिलेगी:

// Get the CampaignService.
CampaignServiceClient campaignService = client.GetService(Services.V16.CampaignService);

// Create a campaign for update.
Campaign campaignToUpdate = new Campaign()
{
    ResourceName = ResourceNames.Campaign(customerId, campaignId),
    // More fields to update.
    // ...
};

// Create the operation.
CampaignOperation operation = new CampaignOperation()
{
    Update = campaignToUpdate,
    UpdateMask = FieldMasks.AllSetFieldsOf(campaignToUpdate)
};

try
{
    // Update the campaign.
    MutateCampaignsResponse response = campaignService.MutateCampaigns(
        customerId.ToString(), new CampaignOperation[] { operation });

    // Display the results.
    // ...
}
catch (GoogleAdsException e)
{
    Console.WriteLine("Failure:");
    Console.WriteLine($"Message: {e.Message}");

    // Can examine to get more error details.
    Console.WriteLine($"Failure: {e.Failure}");

    // Can be shared with Google for further troubleshooting.
    Console.WriteLine($"Request ID: {e.RequestId}");
}