الخطوات الأولى

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

تثبيت

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

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

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

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

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

  • انسخ عقدة GoogleAdsApi والقسم GoogleAdsApi ضمن node 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 ملفًا شخصيًا لملف تعريف GoogleAdsClient لإنشاء ملف تعريف مستخدم باستخدام الإعدادات المحدّدة في App.config / Web.config في تطبيقك. راجِع دليل الإعداد للاطّلاع على خيارات الإعداد.

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

إنشاء خدمة

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

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

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