תחילת העבודה

במדריך הזה מוסבר בקצרה איך להתחיל להשתמש בספריית ‎.NET של Google Ads API.

התקנה

קובצי ההפעלה של ספריית הלקוח מופצים באמצעות NuGet. כדי להשתמש בספריית הלקוח, מוסיפים הפניה ל-NuGet אל Google.Ads.GoogleAds החבילה בפרויקט.

הגדרת הרשאה

כדי לאשר את קריאות ה-API, צריך לציין בספרייה את מזהה הלקוח, הסוד של הלקוח, טוקן הרענון וקוד המפתח.

אם צריך ליצור פרטי כניסה

• אם אין לכם קוד מפתח, אתם יכולים לקבל אותו בעזרת המדריך לקוד מפתח.
• פועלים לפי ההוראות במדריך בנושא תהליך OAuth באפליקציות למחשב כדי ליצור מזהה לקוח, סוד לקוח ואסימון לרענון.

אם כבר יש לכם פרטי כניסה

• מעתיקים את הצומת GoogleAdsApi ואת הקטע GoogleAdsApi מתחת לצומת configSections מהקובץ App.config ב-GitHub לקובץ App.config / Web.config. אם השתמשתם ב-NuGet כדי להתקין את החבילה, הצמתים האלה יתווספו אוטומטית לקובץ App.config / Web.config.
• צריך לכלול באפליקציה את טוקן המפתח, מזהה הלקוח, סוד הלקוח וטוקן הרענון ב-App.config / Web.config של האפליקציה.

קובץ App.config שכלול ב-GitHub מתועד היטב, אבל אפשר גם לעיין במדריך ההגדרה כדי לקבל מידע נוסף, וגם להשתמש בדרכים חלופיות להגדרת ספריית הלקוח, כמו משתני סביבה.

ביצוע קריאה ל-API

השימוש הבסיסי בספריית הלקוח הוא כדלקמן:

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

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

// Make more calls to service class.

יצירת מופע של GoogleAdsClient

המחלקות הכי חשובות בספריית ‎ .NET של Google Ads API הן המחלקות GoogleAdsClient. הוא מאפשר ליצור מחלקת שירות שהוגדרה מראש, שאפשר להשתמש בה כדי לבצע קריאות ל-API. ‫GoogleAdsClient מספק בנאי ברירת מחדל שיוצר אובייקט משתמש באמצעות ההגדרות שצוינו ב-App.config / Web.config של האפליקציה. אפשרויות ההגדרה מפורטות במדריך ההגדרה.

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

יצירת שירות

‫GoogleAdsClient מספק שיטה GetService שאפשר להשתמש בה כדי ליצור שירות של Google Ads.

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

אנחנו מספקים מחלקה Services שמפרטת את כל גרסאות ה-API והשירותים הנתמכים. השיטה GetService מקבלת את אובייקטי ה-enumeration האלה כארגומנט כשיוצרים את השירות. לדוגמה, כדי ליצור מופע של CampaignServiceClient לגרסה V20 של Google Ads API, צריך להפעיל את השיטה GoogleAdsClient.GetService עם Services.V20.CampaignService כארגומנט, כמו שמוצג בדוגמה הקודמת.

Thread safety

לא מומלץ לשתף מופע 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 Framework

שימוש בשיטות סינכרוניות עלול לגרום להקפאה של חלק מהאפליקציות שלכם ב-‎ .NET Framework. דוגמה נפוצה היא ביצוע קריאות ל-API משיטת handler של אירוע באפליקציית WinForm.

יש שתי דרכים לפתור את הבעיה:

1. שימוש בספריית Grpc מדור קודם.

   אפשר להגדיר את המאפיין UseGrpcCore של GoogleAdsConfig כך שישתמש בספריית Grpc.Core מדור קודם במקום בספריית Grpc.Net.Client שמוגדרת כברירת מחדל. השיטה הזו לא נבדקה באופן נרחב באפליקציות של ‎ .NET Framework, לכן יכול להיות שהיא לא תפתור את הבעיה. דוגמה לקטע קוד:

   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.V20.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.V20.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);
   }

טיפול בשגיאות

לא כל קריאה ל-API תצליח. השרת יכול להחזיר שגיאות אם הקריאות ל-API נכשלות מסיבה כלשהי. חשוב לתעד שגיאות ב-API ולטפל בהן בצורה מתאימה.

מופעל כשמתרחשת שגיאת API.GoogleAdsException הוא כולל פרטים שיעזרו לכם להבין מה השתבש:

// Get the CampaignService.
CampaignServiceClient campaignService = client.GetService(Services.V20.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}");
}