תחילת העבודה

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

התקנה

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

הגדרת הרשאה

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

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

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

  • מעתיקים את הצומת 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, צריך להפעיל את השיטה 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);

  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}");
}