استفاده پایه

استفاده پایه از کتابخانه کلاینت .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 را ارائه می‌دهد که می‌توان از آن برای ایجاد کارخواه سرویس میانای برنامه‌سازی کاربردی استفاده کرد.

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

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

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

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

وقتی خطای 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;
    }
}
      

ایمنی 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}");
    }
}