شروع شدن

این راهنما یک نمای کلی از نحوه شروع به کار با کتابخانه Google Ads API .NET ارائه می دهد.

نصب و راه اندازی

باینری های کتابخانه مشتری با استفاده از 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 کاملاً مستند است، اما می‌توانید برای اطلاعات بیشتر و همچنین استفاده از روش‌های جایگزین برای پیکربندی کتابخانه مشتری، مانند متغیرهای محیط، به راهنمای پیکربندی مراجعه کنید.

یک تماس API برقرار کنید

کاربرد اصلی کتابخانه مشتری به شرح زیر است: 

// 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 است. این به شما امکان می دهد یک کلاس سرویس از پیش پیکربندی شده ایجاد کنید که می تواند برای برقراری تماس های API استفاده شود. 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 ارائه می کنیم که تمام نسخه ها و سرویس های API پشتیبانی شده را برمی شمرد. متد GetService این اشیاء شمارش را به عنوان آرگومان در هنگام ایجاد سرویس می پذیرد. به عنوان مثال، برای ایجاد نمونه ای از CampaignServiceClient برای نسخه V18 API Google Ads، باید روش 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 شما شوند. یک مثال متداول برقراری تماس‌های API از روش مدیریت رویداد یک برنامه 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);
}

رسیدگی به خطا

هر تماس API موفق نخواهد شد. اگر تماس‌های API شما به دلایلی با شکست مواجه شوند، سرور می‌تواند خطا ایجاد کند. مهم است که خطاهای API را ضبط کنید و آنها را به درستی مدیریت کنید.

هنگامی که یک خطای API رخ می دهد، یک نمونه 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}");
}