תחילת העבודה

במדריך הזה נספק סקירה כללית קצרה על תחילת העבודה עם ספריית 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.

יצירת מופע של Google AdsClient

הכיתה החשובה ביותר בספריית 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 שבעזרתו אפשר ליצור שירות מודעות.

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 משיטת טיפול באירועים. של אפליקציה ב-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}");
}