البدء

يقدّم هذا الدليل نظرة عامة مختصرة حول كيفية بدء استخدام Google Ads API. .NET.

تثبيت

ويتم توزيع البرامج الثنائية لمكتبة العملاء باستخدام NuGet. إضافة مرجع NuGet إلى Google.Ads.GoogleAds حزمة في مشروعك لاستخدامها ومكتبة العملاء.

إعداد التفويض

لاعتماد طلبات البيانات من واجهة برمجة التطبيقات، يجب تحديد معرِّف العميل وسر العميل والرمز المميز للتحديث والرمز المميز للمطوِّر إلى المكتبة.

في حال كنت بحاجة إلى إنشاء بيانات اعتماد

إذا كانت لديك بيانات اعتماد

  • انسخ العقدة GoogleAdsApi والقسم GoogleAdsApi ضمن العقدة configSections من الملف App.config في GitHub في ملف App.config / Web.config. إذا استخدمت NuGet لتثبيت فسيتم إدراج هذه العُقد تلقائيًا في الملف App.config من إجمالي Web.config
  • تضمين الرمز المميز للمطوِّر ومعرِّف العميل وسر العميل والرمز المميز لإعادة التحميل في App.config / Web.config لتطبيقك

App.config المدرج في GitHub موثق جيدًا، ولكن يمكنك أيضًا الرجوع إلى دليل الإعداد لمعرفة المزيد بالإضافة إلى استخدام طرق بديلة لتكوين مكتبة البرامج، مثل متغيرات البيئة.

إجراء طلب بيانات من واجهة برمجة التطبيقات

في ما يلي الاستخدام الأساسي لمكتبة البرامج:

// 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.

إنشاء مثيل GoogleAdsClient

أهم الفئات في مكتبة .NET ضمن واجهة Google Ads API هي صف واحد (GoogleAdsClient). يتيح لك إنشاء فئة خدمة مُعدّة مسبقًا التي يمكن استخدامها لإجراء طلبات البيانات من واجهة برمجة التطبيقات. GoogleAdsClient تطبيق تلقائي الدالة الإنشائية التي تُنشئ كائن مستخدم باستخدام الإعدادات المحددة في App.config / Web.config للتطبيق يُرجى الرجوع إلى الإعدادات دليل للإعدادات الخيارات.

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

إنشاء خدمة

توفّر GoogleAdsClient طريقة GetService التي يمكن استخدامها لإنشاء خدمة الإعلانات.

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

نوفّر فئة Services التي تتضمّن جميع إصدارات واجهة برمجة التطبيقات المتوافقة تقبل طريقة GetService كائنات التعداد هذه كوسيطة. عند إنشاء الخدمة. على سبيل المثال، لإنشاء مثيل CampaignServiceClient للإصدار V17 من Google Ads API عليك استدعاء طريقة 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.

يمكن أن تتسبب الطرق المتزامنة في حدوث أخطاء في بعض تطبيقات NET. تجميد. من الأمثلة الشائعة إجراء طلبات البيانات من واجهة برمجة التطبيقات من طريقة معالج الأحداث لتطبيق WinForm.

هناك طريقتان لحلّ هذه المشكلة:

  1. استخدام مكتبة Grpc القديمة.

    يمكنك ضبط السمة UseGrpcCore في GoogleAdsConfig لاستخدام مكتبة Grpc.Core القديمة بدلاً من مكتبة Grpc.Net.Client التلقائية. لم يتم اختبار هذه الطريقة بشكل مكثف على تطبيقات NET. لذلك قد لا يحل المشكلة. في ما يلي نموذج للمقتطف:

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

خطأ أثناء المعالجة

لن تنجح كل طلبات بيانات من واجهة برمجة التطبيقات. يمكن أن يعرض الخادم أخطاءً في حال استدعاء واجهة برمجة التطبيقات تفشل لسبب ما. من المهم رصد أخطاء واجهة برمجة التطبيقات ومعالجتها بشكل مناسب.

يتم طرح نسخة افتراضية من GoogleAdsException عند حدوث خطأ في واجهة برمجة التطبيقات. تحتوي على تفاصيل لمساعدتك في اكتشاف الخطأ الذي حدث:

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