תחילת העבודה

במדריך הזה נספק סקירה כללית קצרה על תחילת העבודה עם ספריית Google Ads API ל-‎.NET.

התקנה

הקבצים הבינאריים של ספריית הלקוח מופצים באמצעות 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.V18.CampaignService);

// Make more calls to service class.

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

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

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

יצירת שירות

GoogleAdsClient מספק method GetService שבעזרתו אפשר ליצור שירות Google Ads.

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

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

בטיחות בשרשור

לא בטוח לשתף מכונה של 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 מ-method של הגורם המטפל באירועים של אפליקציית WinForm.

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

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

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

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

   בדף התמיכה של gRPC יש פרטים נוספים על ההבדלים בין ספריית Grpc.Core הקודמת לבין ספריית Grpc.Net.Client שמוגדרת כברירת מחדל.

2. שימוש בשיטות אסינכרוניות

   כדי למנוע קיפאון, אפשר להשתמש בשיטות אסינכרוניות. הנה כמה דוגמאות:

   SearchStream

   מתבצעת קריאה ל-SearchStream() והתוצאות מאוכלסות בתצוגת רשימה.

   private async void button1_Click(object sender, EventArgs e)
   {
   // Get the GoogleAdsService.
   GoogleAdsServiceClient googleAdsService = client.GetService(
       Services.V18.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.V18.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 ולטפל בהן בצורה מתאימה.

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

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