استفاده پایه

استفاده پایه از کتابخانه کلاینت .NET به‌صورت زیر است:

// Initialize a GoogleAdsConfig instance.
GoogleAdsConfig config = new GoogleAdsConfig()
{
    OAuth2Mode = OAuth2Flow.SERVICE_ACCOUNT,
    OAuth2SecretsJsonPath = "PATH_TO_CREDENTIALS_JSON",
    LoginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"
};

// Initialize a GoogleAdsClient instance.
GoogleAdsClient client = new GoogleAdsClient(config);

// Create the required service.
CampaignServiceClient campaignService =
    client.GetService(Services.V26.CampaignService);

// Make calls to the service client.

مقداردهی اولیه کارخواه و سرویس‌ها

برای تعامل با Google Ads API، ابتدا یک GoogleAdsClient را پیکربندی و نمونه‌سازی کنید، و سپس از آن برای ایجاد کارخواه‌های سرویس API خاصی که نیاز دارید استفاده کنید.

ایجاد نمونه GoogleAdsClient

مهم‌ترین کلاس در کتابخانه Google Ads API .NET کلاس GoogleAdsClient است. این روش به شما امکان می‌دهد یک کارخواه سرویس ازپیش پیکربندی‌شده ایجاد کنید که می‌تواند برای برقراری تماس‌های API استفاده شود. برای پیکربندی شیء GoogleAdsClient، شیء GoogleAdsConfig ایجاد کنید و ویژگی‌های لازم را تنظیم کنید. برای اطلاعات بیشتر، به راهنمای پیکربندی مراجعه کنید.

// Initialize a GoogleAdsConfig instance.
GoogleAdsConfig config = new GoogleAdsConfig()
{
    OAuth2Mode = OAuth2Flow.SERVICE_ACCOUNT,
    OAuth2SecretsJsonPath = "PATH_TO_CREDENTIALS_JSON",
    LoginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"
};

// Initialize a GoogleAdsClient instance.
GoogleAdsClient client = new GoogleAdsClient(config);

// Modify the GoogleAdsClient configuration afterwards if needed.
client.Config.LoginCustomerId = "INSERT_UPDATED_LOGIN_CUSTOMER_ID_HERE";

ایجاد سرویس

‫GoogleAdsClient روش GetService را ارائه می‌دهد که می‌توان از آن برای ایجاد کارخواه سرویس API استفاده کرد.

CampaignServiceClient campaignService = client.GetService(
    Services.V26.CampaignService);
// Now make calls to CampaignService.

این کتابخانه کلاس Services را ارائه می‌دهد که همه نسخه‌های API پشتیبانی‌شده را فهرست می‌کند (در جایی که نسخه‌های فرعی مثل v25.1 از شمارشگر نسخه اصلی خود استفاده می‌کنند، Services.V25) و سرویس‌ها. روش GetService این اشیای شمارشی را به‌عنوان آرگومان هنگام ایجاد سرویس می‌پذیرد. برای مثال، برای ایجاد نمونه‌ای از CampaignServiceClient برای نسخه V26 از «میانای برنامه‌سازی کاربردی Google Ads»، روش GoogleAdsClient.GetService را با Services.V26.CampaignService به‌عنوان آرگومان فراخوانی کنید، همان‌طور که در مثال قبلی نشان داده شده است.

مدیریت کردن خطا

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

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

public void Run(GoogleAdsClient client, long customerId)
{
    // Get the GoogleAdsService.
    GoogleAdsServiceClient googleAdsService = client.GetService(
        Services.V26.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";

    try
    {
        // Issue a search request.
        googleAdsService.SearchStream(customerId.ToString(), query,
            delegate (SearchGoogleAdsStreamResponse resp)
            {
                foreach (GoogleAdsRow googleAdsRow in resp.Results)
                {
                    Console.WriteLine("Campaign with ID {0} and name '{1}' was found.",
                        googleAdsRow.Campaign.Id, googleAdsRow.Campaign.Name);
                }
            }
        );
    }
    catch (GoogleAdsException e)
    {
        Console.WriteLine("Failure:");
        Console.WriteLine($"Message: {e.Message}");
        Console.WriteLine($"Failure: {e.Failure}");
        Console.WriteLine($"Request ID: {e.RequestId}");
        throw;
    }
}
GetCampaigns.cs
      

ایمنی Thread

اصلاح وضعیت پیکربندی نمونه GoogleAdsClient مشترک در چندین رشته، رشته‌ای ایمن نیست، زیرا تغییرات پیکربندی که در یک نمونه در یک رشته ایجاد می‌کنید می‌تواند بر سرویس‌هایی که در رشته‌های دیگر ایجاد می‌کنید تأثیر بگذارد. بااین‌حال، عملیات فقط خواندنی مانند دریافت نمونه‌های سرویس جدید از یک نمونه GoogleAdsClient بدون تغییر و برقراری تماس با چندین سرویس به‌طور موازی، ایمن از رشته هستند.

برای جداسازی تغییرات پیکربندی هر رشته، یک GoogleAdsClient جداگانه برای هر تکلیف یا رشته کارگر نمونه‌سازی کنید:

GoogleAdsClient client1 = new GoogleAdsClient();
GoogleAdsClient client2 = new GoogleAdsClient();

Task task1 = Task.Run(() => AddAdGroups(client1));
Task task2 = Task.Run(() => AddAdGroups(client2));

await Task.WhenAll(task1, task2);

public void AddAdGroups(GoogleAdsClient client)
{
    // Perform operations with client.
}

برنامه‌تان را واکنش‌گرا نگه دارید

تکمیل فراخوانی‌های روش Google Ads API ممکن است مدتی طول بکشد، بسته به اینکه درخواست‌ها چقدر بزرگ باشند. برای اینکه برنامه‌تان پاسخگو بماند، این مراحل را دنبال کنید:

برای چارچوب‌های واسط کاربر قدیمی از کتابخانه Grpc.Core استفاده کنید

اگر درحال توسعه برنامه‌ای هستید که .NET Framework را هدف قرار می‌دهد و از فناوری قدیمی واسط کاربر مانند ASP.NET Web Forms یا WinForms استفاده می‌کند، می‌توانید کتابخانه انتقال قدیمی Grpc.Core را به‌صورت زیر فعال کنید:

GoogleAdsConfig config = new GoogleAdsConfig();
config.UseGrpcCore = true;
GoogleAdsClient client = new GoogleAdsClient(config);

استفاده از روش‌های ناهمزمان

می‌توانید از روش‌های ناهم‌زمان برای حفظ پاسخ‌دهی برنامه‌تان استفاده کنید. در اینجا چند نمونه آورده شده است.

فهرست پویش‌ها را بازیابی کنید و ListView را پر کنید

private async void OnRetrieveCampaignsButtonClick(object sender, EventArgs e)
{
    try
    {
        // Get the GoogleAdsService.
        GoogleAdsServiceClient googleAdsService = client.GetService(
            Services.V26.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<ListViewItem> items = new List<ListViewItem>();
        await googleAdsService.SearchStreamAsync(
            customerId.ToString(),
            query,
            (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);
                }
            }
        );
        listView1.Items.AddRange(items.ToArray());
    }
    catch (GoogleAdsException ex)
    {
        MessageBox.Show($"API Error: {ex.Message}");
    }
}

به‌روزرسانی بودجه پویش و نمایش هشدار چارگوش پیام

private async void OnUpdateBudgetButtonClick(object sender, EventArgs e)
{
    try
    {
        // Get the CampaignBudgetService.
        CampaignBudgetServiceClient budgetService = client.GetService(
            Services.V26.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 asynchronously.
        MutateCampaignBudgetsResponse response =
            await budgetService.MutateCampaignBudgetsAsync(
                customerId.ToString(),
                new CampaignBudgetOperation[] { budgetOperation });

        MessageBox.Show(response.Results[0].ResourceName);
    }
    catch (GoogleAdsException ex)
    {
        MessageBox.Show($"API Error: {ex.Message}");
    }
}