البدء

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

تثبيت

يتم توزيع الملفات الثنائية لـ "مكتبة العميل" باستخدام 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.V18.CampaignService);

// Make more calls to service class.

إنشاء مثيل GoogleAdsClient

أهمّ الفئات في مكتبة Google Ads API .NET هي فئة 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.V18.CampaignService);
// Now make calls to CampaignService.

نوفّر فئة Services تذكر جميع إصدارات واجهة برمجة التطبيقات و الخدمات المتوافقة. تقبل طريقة 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. ومن الأمثلة الشائعة على ذلك إجراء طلبات بيانات من واجهة برمجة التطبيقات من طريقة معالِج حدث لتطبيق 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);
}

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

لن تنجح كل طلبات البيانات من واجهة برمجة التطبيقات. يمكن أن يُرسِل الخادم أخطاء إذا تعذّرت معالجة طلبات البيانات من واجهة برمجة التطبيقات لسبب ما. من المهم تسجيل أخطاء واجهة برمجة التطبيقات والتعامل معها بشكل مناسب.

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

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