استفاده اساسی

کاربرد اساسی کتابخانه کلاینت .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.V25.CampaignService);

// Make calls to the service client.

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

برای تعامل با 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.V25.CampaignService);
// Now make calls to CampaignService.

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

مدیریت خطا

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

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

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

ایمنی نخ

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

برای جداسازی تغییرات پیکربندی به ازای هر رشته، به ازای هر وظیفه یا رشته‌ی کاری، یک 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.
}

اپلیکیشن خود را واکنش‌گرا نگه دارید

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

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

اگر در حال توسعه برنامه‌ای هستید که چارچوب دات‌نت را هدف قرار می‌دهد و از یک فناوری رابط کاربری قدیمی مانند 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.V25.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.V25.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}");
    }
}