Основное использование

Основное использование клиентской библиотеки .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 Google Ads сначала настройте и создайте экземпляр 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 , используют перечисление основной версии, Services.V25 ) и сервисы. Метод GetService принимает эти объекты перечисления в качестве аргумента при создании сервиса. Например, чтобы создать экземпляр CampaignServiceClient для версии V25 API Google Ads, вызовите метод GoogleAdsClient.GetService с аргументом Services.V25.CampaignService , как показано в предыдущем примере.

Обработка ошибок

Не каждый вызов API завершается успешно. Сервер может вернуть ошибки, если ваши вызовы API по какой-либо причине не удаются. Важно перехватывать ошибки API и обрабатывать их соответствующим образом.

При возникновении ошибки API генерируется исключение GoogleAdsException . Оно содержит подробную информацию, которая поможет вам выяснить, что пошло не так: 

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 в нескольких потоках не является потокобезопасным, поскольку изменения конфигурации, внесенные в одном потоке, могут повлиять на службы, созданные в других потоках. Однако операции только для чтения, такие как получение новых экземпляров служб из неизменяемого экземпляра 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.
}

Обеспечьте адаптивность вашего приложения.

Вызовы методов 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);

Используйте асинхронные методы

Для обеспечения быстродействия приложения можно использовать асинхронные методы. Вот несколько примеров.

Получите список кампаний и заполните им 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}");
    }
}