תחילת העבודה

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

התקנה

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

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

  • אם עדיין אין לכם קוד מפתח, פועלים לפי ההוראות במדריך לקוד מפתח כדי לקבל את קוד המפתח.
  • פועלים לפי ההוראות במדריך תהליך 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.V17.CampaignService);

// Make more calls to service class.

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

המחלקות החשובות ביותר בספריית .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 מספק method GetService שבעזרתו אפשר ליצור שירות Google Ads.

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

יש לנו מחלקה Services שמפרטת את כל הגרסאות והשירותים הנתמכים של API. כשיוצרים את השירות, ה-method GetService מקבלת את אובייקטי הספירה האלה כארגומנט. לדוגמה, כדי ליצור מכונה של CampaignServiceClient לגרסה V17 של Google Ads API, צריך לקרוא ל-method GoogleAdsClient.GetService עם Services.V17.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. משתמשים בספריית Grapc בגרסה הקודמת.

    אפשר להגדיר את המאפיין 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.V17.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.V17.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.V17.GoogleAdsService);

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

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

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

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

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