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

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

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

  • Следуйте руководству по токену разработчика , чтобы получить токен разработчика, если у вас его еще нет.
  • Следуйте руководству по работе с классическим приложением OAuth , чтобы создать идентификатор клиента, секрет клиента и токен обновления.
  • Скопируйте узел 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.V16.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.V16.CampaignService);
// Now make calls to CampaignService.

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

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

    Поисковый поток

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

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

Отмена асинхронных методов

Для асинхронного программирования вы можете использовать параметр callSettings для передачи CancellationToken :

CancellationTokenSource cancellationTokenSource = new CancellationTokenSource();
cancellationTokenSource.CancelAfter(3000);
CallSettings callSettings = CallSettings.FromCancellationToken(cancellationTokenSource.Token);

string query = "SELECT campaign.name FROM campaign";
var request = new SearchGoogleAdsStreamRequest()
{
    CustomerId = customerId.ToString(),
    Query = query,
};

GoogleAdsServiceClient googleAdsService = client.GetService(
    Services.V16.GoogleAdsService);

googleAdsService.SearchStream(request,
    delegate (SearchGoogleAdsStreamResponse resp)
    {
        foreach (GoogleAdsRow googleAdsRow in resp.Results)
        {
            // Process the row.
        }
    }, callSettings
);

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

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

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

// Get the CampaignService.
CampaignServiceClient campaignService = client.GetService(Services.V16.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}");
}