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

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

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

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

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

// Make more calls to service class.

یک نمونه GoogleAdsClient ایجاد کنید

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

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

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

// Modify the GoogleAdsClient afterwards.

client.Config.LoginCustomerId = ******;

یک سرویس ایجاد کنید

GoogleAdsClient یک روش GetService ارائه می دهد که می تواند برای ایجاد یک سرویس تبلیغاتی استفاده شود.

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

ما یک کلاس Services ارائه می کنیم که تمام نسخه ها و سرویس های API پشتیبانی شده را برمی شمرد. متد GetService این اشیاء شمارش را به عنوان آرگومان در هنگام ایجاد سرویس می پذیرد. برای مثال، برای ایجاد نمونه ای از CampaignServiceClient برای نسخه V21 API Google Ads، باید روش GoogleAdsClient.GetService را با آرگومان Services.V21.CampaignService فراخوانی کنید، همانطور که در مثال قبلی نشان داده شده است.

رسیدگی به خطا

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

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

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

ایمنی نخ

اشتراک‌گذاری یک نمونه 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.
  ...
}

برنامه خود را پاسخگو نگه دارید

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

از کتابخانه Grpc.Core استفاده کنید

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

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

### Use the asynchronous methods {: #asynchronous}

You can use asynchronous methods to keep your application responsive. Here are a
couple of examples.

#### Retrieve the list of campaigns, and populate a `ListView`

```c#
private async void button1_Click(object sender, EventArgs e)
{
    // Get the GoogleAdsService.
    GoogleAdsServiceClient googleAdsService = client.GetService(
        Services.V21.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>();
    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());
}
```

#### Update a campaign budget and display a Message box alert

```c#
private async void button2_Click(object sender, EventArgs e)
{
    // Get the BudgetService.
    CampaignBudgetServiceClient budgetService = client.GetService(
        Services.V21.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<MutateCampaignBudgetsResponse> t = budgetService.MutateCampaignBudgetsAsync(
        customerId.ToString(), new CampaignBudgetOperation[] { budgetOperation });

    await t;
    MutateCampaignBudgetsResponse response = t.Result;
    MessageBox.Show(response.Results[0].ResourceName);
}
```