شروع شدن

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

اگر نیاز به تولید اعتبار دارید ...

  • راهنمای توکن توسعه دهنده را دنبال کنید تا توکن توسعه دهنده خود را دریافت کنید، اگر قبلاً یکی از آن را ندارید.
  • راهنمای جریان برنامه دسکتاپ OAuth را دنبال کنید تا شناسه مشتری، رمز سرویس گیرنده و نشانه تازه سازی ایجاد کنید.
  • گره 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.V16.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.V16.CampaignService);
// Now make calls to CampaignService.

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

لغو روش های ناهمگام

برای برنامه نویسی غیر همگام، می توانید از پارامتر callSettings برای ارسال CancellationToken استفاده کنید:

CancellationTokenSource cancellationTokenSource = new CancellationTokenSource();
cancellationTokenSource.CancelAfter(3000);
CallSettings callSettings = CallSettings.FromCancellationToken(cancellationTokenSource.Token);

string query = "SELECT campaign.name FROM campaign";
var request = new SearchGoogleAdsStreamRequest()
{
    CustomerId = customerId.ToString(),
    Query = query,
};

GoogleAdsServiceClient googleAdsService = client.GetService(
    Services.V16.GoogleAdsService);

googleAdsService.SearchStream(request,
    delegate (SearchGoogleAdsStreamResponse resp)
    {
        foreach (GoogleAdsRow googleAdsRow in resp.Results)
        {
            // Process the row.
        }
    }, callSettings
);

رسیدگی به خطا

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

هنگامی که یک خطای API رخ می دهد، یک نمونه GoogleAdsException پرتاب می شود. دارای جزئیاتی است که به شما کمک می کند بفهمید چه مشکلی رخ داده است:

// Get the CampaignService.
CampaignServiceClient campaignService = client.GetService(Services.V16.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}");
}