البدء

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

تثبيت

يتم توزيع الملفات الثنائية لـ "مكتبة العميل" باستخدام 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 تطبيق تلقائي الدالة الإنشائية التي تُنشئ كائن مستخدم باستخدام الإعدادات المحددة في 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.

يمكن أن تؤدي الطرق المتزامنة إلى توقُّف بعض تطبيقات ‎.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}");
}