Начало работы

В этом руководстве дается краткий обзор того, как начать работу с библиотекой Google Ads API .NET.

Установка

Бинарные файлы клиентской библиотеки распространяются с помощью NuGet. Добавьте ссылку NuGet на пакет Google.Ads.GoogleAds в вашем проекте, чтобы использовать клиентскую библиотеку.

Настроить авторизацию

Для авторизации вызовов API вам необходимо указать в библиотеке свой идентификатор клиента, секретный код клиента, токен обновления и токен разработчика.

Если вам необходимо сгенерировать учетные данные

Если у вас уже есть учетные данные

  • Скопируйте узел GoogleAdsApi и раздел GoogleAdsApi в узле configSections из файла App.config в GitHub в ваш файл App.config / Web.config . Если вы использовали NuGet для установки пакета, эти узлы будут автоматически вставлены в ваш файл App.config / Web.config .
  • Включите токен разработчика, идентификатор клиента, секретный код клиента и токен обновления в App.config / Web.config вашего приложения.

Файл App.config , включенный в GitHub, хорошо документирован, но вы также можете обратиться к руководству по настройке , чтобы узнать больше, а также использовать альтернативные способы настройки клиентской библиотеки, такие как переменные среды.

Сделать вызов API

Основное использование клиентской библиотеки выглядит следующим образом:

// Create a Google Ads client.
GoogleAdsClient client = new GoogleAdsClient();

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

// Make more calls to service class.

Создайте экземпляр GoogleAdsClient

Наиболее важными классами в библиотеке Google Ads API .NET являются классы GoogleAdsClient . Они позволяют создавать предварительно настроенный класс службы, который можно использовать для выполнения вызовов API. GoogleAdsClient предоставляет конструктор по умолчанию, который создает объект пользователя с использованием настроек, указанных в App.config / Web.config вашего приложения. Параметры конфигурации см. в руководстве по настройке.

// Create a new GoogleAdsClient with the App.config settings.
GoogleAdsClient user = new GoogleAdsClient();

Создать услугу

GoogleAdsClient предоставляет метод GetService , который можно использовать для создания рекламной службы.

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

Мы предоставляем класс Services , который перечисляет все поддерживаемые версии API и службы. Метод GetService принимает эти объекты перечисления в качестве аргумента при создании службы. Например, чтобы создать экземпляр CampaignServiceClient для версии V20 API Google Ads, вам необходимо вызвать метод GoogleAdsClient.GetService с Services.V20.CampaignService в качестве аргумента, как показано в предыдущем примере.

Безопасность потока

Небезопасно совместно использовать экземпляр 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.
  ...
}

Избегайте зависаний в приложениях .NET Framework

Синхронные методы могут привести к зависанию некоторых приложений .NET Framework. Типичным примером является выполнение вызовов API из метода обработчика событий приложения WinForm.

Есть два способа решения этой проблемы:

  1. Используйте устаревшую библиотеку Grpc.

    Вы можете задать свойство UseGrpcCore для GoogleAdsConfig для использования устаревшей библиотеки Grpc.Core вместо библиотеки Grpc.Net.Client по умолчанию. Этот метод не был тщательно протестирован на приложениях .NET Framework, поэтому он может не решить проблему. Вот пример фрагмента:

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

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

    Чтобы избежать зависаний, можно использовать асинхронные методы. Вот несколько примеров:

    ПоискStream

    Выполняется вызов SearchStream() , и результаты отображаются в виде списка.

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

    Бюджет кампании

    Создается вызов CampaignBudget, и имя ресурса нового бюджета отображается с помощью оповещения MessageBox .

    private async void button2_Click(object sender, EventArgs e)
{
// Get the BudgetService.
CampaignBudgetServiceClient budgetService = client.GetService(
    Services.V20.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 t = budgetService.MutateCampaignBudgetsAsync(
    customerId.ToString(), new CampaignBudgetOperation[] { budgetOperation });
 
await t;
MutateCampaignBudgetsResponse response = t.Result;
MessageBox.Show(response.Results[0].ResourceName);
}

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

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

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

// Get the CampaignService.
CampaignServiceClient campaignService = client.GetService(Services.V20.CampaignService);

// Create a campaign for update.
Campaign campaignToUpdate = new Campaign()
{
    ResourceName = ResourceNames.Campaign(customerId, campaignId),
    // More fields to update.
    // ...
};

// Create the operation.
CampaignOperation operation = new CampaignOperation()
{
    Update = campaignToUpdate,
    UpdateMask = FieldMasks.AllSetFieldsOf(campaignToUpdate)
};

try
{
    // Update the campaign.
    MutateCampaignsResponse response = campaignService.MutateCampaigns(
        customerId.ToString(), new CampaignOperation[] { operation });

    // Display the results.
    // ...
}
catch (GoogleAdsException e)
{
    Console.WriteLine("Failure:");
    Console.WriteLine($"Message: {e.Message}");

    // Can examine to get more error details.
    Console.WriteLine($"Failure: {e.Failure}");

    // Can be shared with Google for further troubleshooting.
    Console.WriteLine($"Request ID: {e.RequestId}");
}