Примеры кода и варианты использования

Мы уже рассмотрели, как осуществить первый вызов API, и обсудили элементы конфигурации, необходимые для выполнения таких вызовов.

В этом руководстве мы разберем структуру типичного примера кода для AdWords API.

Затем мы рассмотрим несколько распространенных вариантов использования, которые демонстрируют, как с помощью примеров кода можно добавить в приложение практически любую функцию API.

Структура примера кода для API

Представленные примеры кода с клиентскими библиотеками охватывают все основные функции API. Они автоматически выполняют большинство внутренних задач и значительно упрощают разработку приложений на основе AdWords API.

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

Java

В среде IDE откройте файл GetCampaigns.java из предыдущего руководства.

Обратите внимание на шаблонный код в методе main. Он выполняет следующие функции:

  • создание учетных данных;
  • создание сеанса AdWords;
  • создание экземпляров служб AdWords.

Чтобы лучше понять, как все работает, изучите примеры кода в клиентской библиотеке.

В примере GetCampaigns есть ещё одна строка, которая вам может понадобиться. Обратите внимание, что в предыдущем руководстве идентификатор клиента был задан в файле ads.properties.

Но что, если вы управляете несколькими аккаунтами одного клиента? В этом случае можно убрать идентификатор клиента из файла ads.properties и задать его программным образом через объект AdWordsSession. Созданный объект динамически назначается с помощью метода setClientCustomerID.

// Создание объекта AdWordsSession.
    AdWordsSession session = new AdWordsSession.Builder()
        .fromFile()
        .withOAuth2Credential(oAuth2Credential)
        .build();

    session.setClientCustomerID("123-456-7890");

    AdWordsServices adWordsServices = new AdWordsServices();

    runExample(adWordsServices, session);
  }

.NET

В среде IDE откройте файл GetCampaigns.cs из предыдущего руководства.

Обратите внимание на шаблонный код в методе main, ссылающийся на AdWordsUser.
public static void Main(string[] args) {
      GetCampaigns codeExample = new GetCampaigns();
      Console.WriteLine(codeExample.Description);
      try {
        codeExample.Run(new AdWordsUser());

Самыми важными в библиотеке .NET являются классы AdsUser. Они обычно инкапсулируют один аккаунт Ads (в данном случае – аккаунт AdWords).

Класс AdWordsUser позволяет создать предварительно настроенный класс службы, который можно использовать для осуществления вызовов API с применением настроек, заданных в файле app.config вашего приложения.

// Создание экземпляра класса AdWordsUser с использованием настроек из файла App.config.
AdWordsUser user = new AdWordsUser();

Но что, если вы управляете несколькими аккаунтами одного клиента? В этом случае можно программным образом задать идентификатор клиента во время выполнения, используя свойство Config объекта AdsUser.

// Создание экземпляра AdWordsUser по умолчанию. Если конфигурация
// задана в файле App.config, она будет использоваться.
AdWordsUser user = new AdWordsUser();

// Переопределение параметра во время выполнения.
AdWordsAppConfig config = (AdWordsAppConfig) user.Config;
user.Config.clientCustomerId = "123-456-7890";

Другой способ состоит в том, чтобы использовать конструктор, принимающий экземпляр AdWordsAppConfig.

// Создание объекта конфигурации с использованием значений из файла App.config.
AdWordsAppConfig config = new AdWordsAppConfig();

// Переопределение любого параметра, который нужно изменить.
user.Config.clientCustomerId = "123-456-7890";

AdWordsUser user = new AdWordsUser(config);

Python

В среде IDE откройте файл get_campaigns.py из предыдущего руководства.

В приведенном ниже примере кода комментарии указывают, что метод LoadFromStorage получает учетные данные и свойства из файла googleads.yaml. Обратите внимание, что в предыдущем руководстве идентификатор клиента был задан в файле googleads.yaml. По умолчанию метод LoadFromStorage ищет файл с таким названием в главном каталоге, хотя вы можете указать путь к нужному YAML-файлу. Чтобы использовать главный каталог:

adwords_client = adwords.AdWordsClient.LoadFromStorage()
Чтобы указать местонахождение файла:
adwords_client = adwords.AdWordsClient.LoadFromStorage('C:\My\Directory\googleads.yaml')

Но что, если вы управляете несколькими аккаунтами одного клиента? В этом случае можно программным образом задать идентификатор клиента во время выполнения, используя следующий код:

adwords_client = AdWordsClient.LoadFromStorage()
adwords_client.SetClientCustomerId('123-456-7890')

PHP

В среде IDE откройте файл GetCampaigns.php из предыдущего руководства.

Обратите внимание на код, который получает информацию об учетных данных из файла конфигурации auth.ini.

try {
  // Получение AdWordsUser из учетных данных в "../auth.ini"
  // относительно каталога файла AdWordsUser.php.
  $user = new AdWordsUser();

В примере GetCampaigns есть ещё одна строка, которая вам может понадобиться. Обратите внимание, что в предыдущем руководстве идентификатор клиента был задан в файле auth.ini.

Но что, если вы управляете несколькими аккаунтами одного клиента? В этом случае можно убрать идентификатор клиента из файла auth.ini и задать его программным образом, вызвав метод SetClientCustomerId() объекта AdWordsUser с параметром.

// Создание экземпляра AdWordsUser с использованием конструктора по умолчанию,
// который загружает информацию из файла auth.ini.
$user = new AdWordsUser();
$user->SetClientCustomerId('123-456-7890');

Perl

В среде IDE откройте файл get_campaigns.pl из предыдущего руководства.

Обратите внимание на код, который получает информацию об учетных данных из файла конфигурации adwords.properties.

# Получение клиента AdWords, учетные данные считываются из файла ~/adwords.properties.
my $client = Google::Ads::AdWords::Client->new({version => "v201702"});

Обратите внимание, что в предыдущем руководстве идентификатор клиента был задан в файле adwords.properties.

Но что, если вы управляете несколькими аккаунтами одного клиента? В этом случае можно убрать идентификатор клиента из файла adwords.properties и задать его программным образом, вызвав метод set_client_id.

# Получение клиента AdWords, учетные данные считываются из файла ~/adwords.properties.
my $client = Google::Ads::AdWords::Client->new({version => "v201702"});
$client->set_client_id("123-456-7890");

Ruby

Откройте файл get_campaigns.rb из предыдущего руководства.

Обратите внимание на шаблонный код в методе main, который обрабатывает получение информации об учетных данных из файла конфигурации adwords_api.yml.

  # AdwordsApi::Api считывает файл конфигурации из ENV['HOME']/adwords_api.yml
  # при вызове без параметров.
  adwords = AdwordsApi::Api.new

В примере есть ещё одна строка, которая вам может понадобиться. Обратите внимание, что в предыдущем руководстве идентификатор клиента был задан в файле конфигурации adwords_api.yml.

Но что, если вы управляете несколькими аккаунтами одного клиента? В этом случае можно убрать идентификатор клиента из файла adwords_api.yml и задать его программным образом через объект AdWordsSession. Созданный объект динамически назначается с помощью метода adwords.config.set.

# Новое значение CID
adwords.config.set("authentication.client_customer_id", "123-456-7890")

Доступ к примерам кода

Вы можете просмотреть все примеры кода для AdWords API в разделе Клиентские библиотеки и примеры кода. Примеры кода охватывают все основные функции API, включая следующие:

  • управление аккаунтом;
  • управление кампаниями;
  • обработка ошибок;
  • оптимизация;
  • отчеты;
  • таргетинг.

Итак, мы рассмотрели структуру типичного примера кода для AdWords API. Теперь обсудим некоторые варианты использования примеров кода.

К основным функциям API относятся создание отчетов и автоматизация. Начнем с создания отчетов.

Использование примеров кода для создания отчетов

Сначала мы рассмотрим пример кода для скачивания отчета по эффективности критериев.

Java

В среде IDE откройте файл DownloadCriteriaReport.java.

Мы рассмотрим тот же шаблонный код в методе main, что и выше.

public static void main(String[] args) throws Exception {
    // Создание обновляемых учетных данных OAuth2.
    Credential oAuth2Credential = new OfflineCredentials.Builder()
        .forApi(Api.ADWORDS)
        .fromFile()
        .build()
        .generateCredential();

    // Создание сеанса AdWords.
    AdWordsSession session = new AdWordsSession.Builder()
        .fromFile()
        .withOAuth2Credential(oAuth2Credential)
        .build();

В этом классе нас интересует метод RunExample, где создается иерархия объектов, которая определяет нужный отчет.

// Создание определения отчета.
    ReportDefinition reportDefinition = new ReportDefinition();
    reportDefinition.setReportName("Criteria performance report #" + System.currentTimeMillis());
    reportDefinition.setDateRangeType(ReportDefinitionDateRangeType.YESTERDAY);
    reportDefinition.setReportType(ReportDefinitionReportType.CRITERIA_PERFORMANCE_REPORT);
    reportDefinition.setDownloadFormat(DownloadFormat.CSV);

Затем мы передаем его в экземпляр ReportDownloader.

 ReportDownloadResponse response =
          new ReportDownloader(session).downloadReport(reportDefinition);
      response.saveToFile(reportFile);

Теперь запустите файл DownloadCriteriaReport.java.

В консоли среды IDE появится местонахождение загруженного файла.

Обратите внимание, что в примере кода указан тип отчета. В данном случае это отчет по эффективности критериев.

reportDefinition.setReportType(ReportDefinitionReportType.CRITERIA_PERFORMANCE_REPORT);

В примере также указывается, какие поля отчета нужно получить.

Selector selector = new Selector();
    selector.getFields().addAll(Lists.newArrayList("CampaignId",
        "AdGroupId",
        "Id",
        "CriteriaType",
        "Criteria",
        "FinalUrls",
        "Impressions",
        "Clicks",
        "Cost"));

.NET

В среде IDE откройте файл DownloadCriteriaReport.cs.

Мы рассмотрим тот же шаблонный код, выполняющий аутентификацию путем получения значений из файла app.config.

public static void Main(string[] args) {
      GetCampaigns codeExample = new GetCampaigns();
      Console.WriteLine(codeExample.Description);
      try {
        codeExample.Run(new AdWordsUser());

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

public void Run(AdWordsUser user, string fileName) {
      ReportDefinition definition = new ReportDefinition() {
        reportName = "Last 7 days CRITERIA_PERFORMANCE_REPORT",
        reportType = ReportDefinitionReportType.CRITERIA_PERFORMANCE_REPORT,
        downloadFormat = DownloadFormat.GZIPPED_CSV,
        dateRangeType = ReportDefinitionDateRangeType.LAST_7_DAYS,

Теперь запустите файл DownloadCriteriaReport.cs.

В консоли появится местонахождение загруженного файла.

Обратите внимание, что в примере кода указан тип отчета. В данном случае это отчет по эффективности критериев.

reportType = ReportDefinitionReportType.CRITERIA_PERFORMANCE_REPORT,

В примере также указывается, какие поля отчета нужно получить.

selector = new Selector() {
          fields = new string[] {"CampaignId", "AdGroupId", "Id", "CriteriaType", "Criteria",
              "FinalUrls", "Clicks", "Impressions", "Cost"},
          predicates = new Predicate[] {
            Predicate.In("Status", new string[] {"ENABLED", "PAUSED"})

Python

В среде IDE откройте файл download_criteria_report.py.

Мы рассмотрим тот же шаблонный код, выполняющий аутентификацию путем получения значений из файла конфигурации googleads.yaml.

adwords_client = adwords.AdWordsClient.LoadFromStorage()
  main(adwords_client)

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

 # Создание определения отчета.
  report = {
      'reportName': 'Last 7 days CRITERIA_PERFORMANCE_REPORT',
      'dateRangeType': 'LAST_7_DAYS',
      'reportType': 'CRITERIA_PERFORMANCE_REPORT',
      'downloadFormat': 'CSV',
      'selector': {
          'fields': ['CampaignId', 'AdGroupId', 'Id', 'CriteriaType',
                     'Criteria', 'FinalUrls', 'Impressions', 'Clicks', 'Cost']

Затем мы передаем его в экземпляр ReportDownloader.

 report_downloader.DownloadReport(
      report, sys.stdout, skip_report_header=False, skip_column_header=False,
      skip_report_summary=False)

Теперь запустите файл download_criteria_report.py.

В консоли появится местонахождение загруженного файла.

Обратите внимание, что в примере кода указан тип отчета. В данном случае это отчет по эффективности критериев.

В разделе selector данного примера также указывается, какие поля отчета нужно получить, например CampaignId, AdGroupId и т. д.

PHP

В среде IDE откройте файл DownloadCriteriaReport.php.

Мы рассмотрим тот же шаблонный код, выполняющий аутентификацию путем получения значений из файла конфигурации auth.ini.

  // Получение AdWordsUser из учетных данных в "../auth.ini"
  // относительно каталога файла AdWordsUser.php.
  $user = new AdWordsUser();

В этом примере нас интересует код создания селектора, который определяет нужный отчет.

  // Создание определения отчета.
  $reportDefinition = new ReportDefinition();
  $reportDefinition->selector = $selector;
  $reportDefinition->reportName = 'Criteria performance report #' . uniqid();
  $reportDefinition->dateRangeType = 'LAST_7_DAYS';
  $reportDefinition->reportType = 'CRITERIA_PERFORMANCE_REPORT';
  $reportDefinition->downloadFormat = 'CSV';

Затем мы передаем его в средство скачивания отчетов.

  // Скачивание отчета.
  ReportUtils::DownloadReport($reportDefinition, $filePath, $user, $options);
  printf("Report with name '%s' was downloaded to '%s'.\n",
      $reportDefinition->reportName, $filePath);

Теперь запустите файл DownloadCriteriaReport.php.

В консоли появится местонахождение загруженного файла.

Обратите внимание, что в примере кода указан тип отчета. В данном случае это отчет по эффективности критериев.

$reportDefinition->reportType = 'CRITERIA_PERFORMANCE_REPORT';

В примере также указывается, какие поля отчета нужно получить.

$selector->fields = array('CampaignId', 'AdGroupId', 'Id', 'Criteria',
      'CriteriaType', 'Impressions', 'Clicks', 'Cost');

Perl

В среде IDE откройте файл download_criteria_report.pl.

Мы рассмотрим тот же шаблонный код, выполняющий аутентификацию путем получения значений из файла конфигурации adwords.properties.

# Получение клиента AdWords, учетные данные считываются из файла ~/adwords.properties.
my $client = Google::Ads::AdWords::Client->new({version => "v201702"});

В этом примере нас интересует код создания селектора и определения отчета.

my $report_definition = Google::Ads::AdWords::Reports::ReportDefinition->new({
      reportName     => "Last 7 days CRITERIA_PERFORMANCE_REPORT #" . $today,
      dateRangeType  => "LAST_7_DAYS",
      reportType     => "CRITERIA_PERFORMANCE_REPORT",
      downloadFormat => "CSV",
      selector       => $selector
  });

Затем мы передаем его в экземпляр ReportDownloader.

 # Скачивание отчета с использованием соответствующего метода ReportDownloadHandler.
  my $result;
  if ($output_file) {
    $result = $report_handler->save($output_file);
  } else {
    $result = $report_handler->get_as_string();
  }

Теперь запустите файл download_criteria_report.pl.

В консоли появится местонахождение загруженного файла.

Обратите внимание, что в примере кода указан тип отчета. В данном случае это отчет по эффективности критериев.

reportType     => "CRITERIA_PERFORMANCE_REPORT",

В примере также указывается, какие поля отчета нужно получить.

# Создание селектора.
  my $selector = Google::Ads::AdWords::Reports::Selector->new({
      fields => [
        "CampaignId", "AdGroupId", "Id",          "CriteriaType",
        "Criteria",   "FinalUrls", "Impressions", "Clicks",
        "Cost"
      ]});

Ruby

Откройте файл download_criteria_report.rb.

Мы рассмотрим тот же шаблонный код, выполняющий аутентификацию путем получения значений из файла конфигурации adwords_api.yml.

def download_criteria_report(file_name)
  # AdwordsApi::Api считывает файл конфигурации из ENV['HOME']/adwords_api.yml
  # при вызове без параметров.
  adwords = AdwordsApi::Api.new

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

  # Создание определения отчета. Можно также передать строку в формате XML.
  report_definition = {
    :selector => {
      :fields => ['CampaignId', 'AdGroupId', 'Id', 'Criteria', 'CriteriaType',
          'FinalUrls', 'Impressions', 'Clicks', 'Cost'],
    },
...

    :report_name => 'Last 7 days CRITERIA_PERFORMANCE_REPORT',
    :report_type => 'CRITERIA_PERFORMANCE_REPORT',
    :download_format => 'CSV',
    :date_range_type => 'LAST_7_DAYS',

Затем мы передаем его в экземпляр download_report.

 # Скачивание отчета с помощью метода download_report_as_file.
 # Чтобы получить отчет как возвращаемое значение, следует использовать метод download_report.
  report_utils.download_report_as_file(report_definition, file_name)
  puts "Report was downloaded to '%s'." % file_name
end

Теперь запустите файл download_criteria_report.rb.

В консоли появится местонахождение загруженного файла.

Обратите внимание, что в примере кода указан тип отчета. В данном случае это отчет по эффективности критериев.

:report_type => 'CRITERIA_PERFORMANCE_REPORT',

В примере также указывается, какие поля отчета нужно получить.

:fields => ['CampaignId', 'AdGroupId', 'Id', 'Criteria', 'CriteriaType',
          'FinalUrls', 'Impressions', 'Clicks', 'Cost'],

Полный список типов отчетов и полей приведен на странице Типы отчетов.

Вы можете использовать этот пример кода наряду с информацией на странице Типы отчетов, чтобы определять, создавать и скачивать любые нужные вам отчеты.

AdWords Query Language (AWQL)

Помимо определения отчетов с помощью иерархии объектов, можно также использовать AdWords Query Language (AWQL). Это SQL-подобный язык, позволяющий создавать отчеты более лаконичным способом, чем через объекты.

Java

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

String query = "SELECT CampaignId, AdGroupId, Id, Criteria, CriteriaType, "
        + "Impressions, Clicks, Cost FROM CRITERIA_PERFORMANCE_REPORT "
        + "WHERE Status IN [ENABLED, PAUSED] "
        + "DURING YESTERDAY";

.NET

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

string query = "SELECT CampaignId, AdGroupId, Id, Criteria, CriteriaType, Impressions, " +
          "Clicks, Cost FROM CRITERIA_PERFORMANCE_REPORT WHERE Status IN [ENABLED, PAUSED] " +
          "DURING LAST_7_DAYS";

Python

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

report_query = ('SELECT CampaignId, AdGroupId, Id, Criteria, CriteriaType, '
                  'FinalUrls, Impressions, Clicks, Cost '
                  'FROM CRITERIA_PERFORMANCE_REPORT '
                  'WHERE Status IN [ENABLED, PAUSED] '
                  'DURING LAST_7_DAYS')

PHP

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

$reportQuery = 'SELECT CampaignId, AdGroupId, Id, Criteria, CriteriaType, '
      . 'Impressions, Clicks, Cost FROM CRITERIA_PERFORMANCE_REPORT '
      . 'WHERE Status IN [ENABLED, PAUSED] DURING ' . $dateRange;

В этом случае диапазон дат определяется в коде непосредственно перед фрагментом AWQL.

  // Подготовка диапазона данных за последнюю неделю. Вместо этого можно использовать LAST_7_DAYS.
  $dateRange = sprintf('%d,%d',
      date('Ymd', strtotime('-7 day')), date('Ymd', strtotime('-1 day')));

Perl

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

my $report_query =
    "SELECT CampaignId, AdGroupId, Id, Criteria, CriteriaType, " .
    "Impressions, Clicks, Cost FROM CRITERIA_PERFORMANCE_REPORT " .
    ""WHERE Status IN [ENABLED, PAUSED] " . "DURING $last_4_days, $yesterday";";

В этом случае диапазон дат для отчета определяется в коде непосредственно перед фрагментом AWQL.

  # Создание запроса отчета.
  my (undef, undef, undef, $mday, $mon, $year) = localtime(time - 60 * 60 * 24);
  my $yesterday = sprintf("%d%02d%02d", ($year + 1900), ($mon + 1), $mday);
  (undef, undef, undef, $mday, $mon, $year) =
    localtime(time - 60 * 60 * 24 * 4);
  my $last_4_days = sprintf("%d%02d%02d", ($year + 1900), ($mon + 1), $mday);

Ruby

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

report_query = 'SELECT CampaignId, AdGroupId, Id, Criteria, CriteriaType, ' +
      'Impressions, Clicks, Cost FROM CRITERIA_PERFORMANCE_REPORT ' +
      'WHERE Status IN [ENABLED, PAUSED] ' +
      'DURING %s' % date_range

В этом случае диапазон дат определяется в коде непосредственно перед фрагментом AWQL.

  # Подготовка диапазона данных за последнюю неделю. Вместо этого можно использовать LAST_7_DAYS.
  date_range = '%s,%s' % [
      DateTime.parse((Date.today - 7).to_s).strftime('%Y%m%d'),
      DateTime.parse((Date.today - 1).to_s).strftime('%Y%m%d')
  ]

Итак, мы рассмотрели основы создания отчетов. Теперь вы можете реализовать эти функции в своем приложении.

Использование примеров кода для автоматизации

Теперь давайте рассмотрим, как с помощью примеров кода можно вносить изменения в аккаунты AdWords, а также разберем несколько популярных вариантов использования этих примеров для различных способов автоматизации.

Приостановка и возобновление групп объявлений

Одним из основных вариантов использования API является приостановка и возобновление групп объявлений. Например, вы можете приостановить объявление, если закончился товар на складе, чтобы рациональнее использовать рекламный бюджет.

Этот вариант использования демонстрирует эффективность интеграции ваших собственных систем, например системы отслеживания запасов, с AdWords API.

Мы будем использовать примеры кода для приостановки и возобновления группы объявлений.

Java

В среде IDE откройте файл UpdateAdGroup.java.

Мы снова рассмотрим шаблонный код в методе main. Обратите внимание, что в нижней части метода main есть метка-заполнитель для идентификатора группы объявлений.

public static void main(String[] args) throws Exception {
    // Создание обновляемых учетных данных OAuth2.
    Credential oAuth2Credential = new OfflineCredentials.Builder()
        .forApi(Api.ADWORDS)
        .fromFile()
        .build()
        .generateCredential();

    // Создание сеанса AdWords.
    AdWordsSession session = new AdWordsSession.Builder()
        .fromFile()
        .withOAuth2Credential(oAuth2Credential)
        .build();

    Long adGroupId = Long.parseLong("INSERT_AD_GROUP_ID_HERE");

Где взять идентификатор группы объявлений? Это можно сделать программным образом с помощью метода GET интерфейса AdGroupService. Например, идентификатор можно извлечь из URL веб-интерфейса AdWords при просмотре группы объявлений.

Мы снова обратимся к коду метода runExample. Давайте пошагово рассмотрим, что именно он делает.

Во-первых, он получает ссылку на интерфейс AdGroupService, который осуществляет изменение группы объявлений. Чтобы изменить другие объекты, необходимо использовать соответствующие службы. Полный список служб доступен в руководстве Объекты, методы и службы.

// Получение AdGroupService.
    AdGroupServiceInterface adGroupService =
        adWordsServices.get(session, AdGroupServiceInterface.class);

После этого создается новый объект группы объявлений, в котором указывается идентификатор нужной группы объявлений.

// Создание группы объявлений с измененным статусом.
    AdGroup adGroup = new AdGroup();
    adGroup.setId(adGroupId);

Затем ей присваивается статус PAUSED.

adGroup.setStatus(AdGroupStatus.PAUSED);

Затем создается объект AdGroupOperation на основе только что созданного объекта группы объявлений и применяется оператор SET.

// Создание операций.
    AdGroupOperation operation = new AdGroupOperation();
    operation.setOperand(adGroup);
    operation.setOperator(Operator.SET);

Наконец, осуществляется вызов метода mutate интерфейса AdGroupService с передачей объекта операции для группы объявлений.

// Изменение группы объявлений.
    AdGroupReturnValue result = adGroupService.mutate(operations);

Замените метку-заполнитель идентификатором группы объявлений из тестового клиентского аккаунта и попробуйте запустить код. После запуска войдите в тестовый аккаунт через веб-интерфейс AdWords и убедитесь, что статус изменен.

.NET

В среде IDE откройте файл UpdateAdGroup.cs.

Мы снова рассмотрим шаблонный код в методе Main. Обратите внимание, что в нижней части метода Main есть метка-заполнитель для идентификатора группы объявлений.

public static void Main(string[] args) {
      UpdateAdGroup codeExample = new UpdateAdGroup();
      Console.WriteLine(codeExample.Description);
      try {
        long adGroupId = long.Parse("INSERT_ADGROUP_ID_HERE");
        codeExample.Run(new AdWordsUser(), adGroupId);

Где взять идентификатор группы объявлений? Это можно сделать программным образом с помощью метода GET интерфейса AdGroupService. Например, идентификатор можно извлечь из URL веб-интерфейса AdWords при просмотре группы объявлений.

Мы снова обратимся к коду метода runExample. Давайте пошагово рассмотрим, что именно он делает.

Во-первых, он получает ссылку на интерфейс AdGroupService, который осуществляет изменение группы объявлений. Чтобы изменить другие объекты, необходимо использовать соответствующие службы. Полный список служб доступен в руководстве Объекты, методы и службы.

public void Run(AdWordsUser user, long adGroupId) {
      // Get the AdGroupService.
      AdGroupService adGroupService =
          (AdGroupService) user.GetService(AdWordsService.v201702.AdGroupService);

После этого создается новый объект AdGroup, в котором указывается идентификатор нужной группы объявлений.

// Создание группы объявлений.
      AdGroup adGroup = new AdGroup();
      adGroup.status = AdGroupStatus.PAUSED;
      adGroup.id = adGroupId;

Затем ей присваивается статус PAUSED.

adGroup.status = AdGroupStatus.PAUSED;

Затем создается объект AdGroupOperation на основе только что созданного объекта adGroup и применяется оператор SET.

// Создание операции.
      AdGroupOperation operation = new AdGroupOperation();
      operation.@operator = Operator.SET;
      operation.operand = adGroup;

Наконец, осуществляется вызов метода mutate интерфейса AdGroupService с передачей объекта AdGroupOperation.

// Изменение группы объявлений.
        AdGroupReturnValue retVal = adGroupService.mutate(new AdGroupOperation[] {operation});

Замените метку-заполнитель идентификатором группы объявлений из тестового клиентского аккаунта и попробуйте запустить код. После запуска войдите в тестовый аккаунт через веб-интерфейс AdWords и убедитесь, что статус изменен.

Python

В среде IDE откройте файл update_ad_group.py.

Мы снова рассмотрим шаблонный код, в котором метод LoadFromStorage получает учетные данные и свойства из файла конфигурации googleads.yaml. Обратите внимание на метку-заполнитель для идентификатора группы объявлений.

AD_GROUP_ID = 'INSERT_AD_GROUP_ID_HERE'

Где взять идентификатор группы объявлений? Это можно сделать программным образом с помощью метода GET интерфейса AdGroupService. Например, идентификатор можно извлечь из URL веб-интерфейса AdWords при просмотре группы объявлений.

Затем идет интересующий нас фрагмент кода. Давайте пошагово рассмотрим, что именно он делает.

Во-первых, он получает ссылку на интерфейс AdGroupService, который осуществляет изменение группы объявлений. Чтобы изменить другие объекты, необходимо использовать соответствующие службы. Полный список служб доступен в руководстве Объекты, методы и службы.

def main(client, ad_group_id):
  # Initialize appropriate service.
  ad_group_service = client.GetService('AdGroupService', version='v201702')

После этого он задает идентификатор группы объявлений, которую нужно изменить, и присваивает статус PAUSED.

# Создание операций и изменение группы объявлений.
  operations = [{
      'operator': 'SET',
      'operand': {
          'id': ad_group_id,
          'status': 'PAUSED'

Затем создается операция группы объявлений на основе только что созданного объекта группы объявлений, применяется оператор SET и задается статус PAUSED.

# Создание операций и изменение группы объявлений.
  operations = [{
      'operator': 'SET',
      'operand': {
          'id': ad_group_id,
          'status': 'PAUSED'

Наконец, осуществляется вызов метода mutate интерфейса службы группы объявлений с передачей объекта операции для группы объявлений.

ad_groups = ad_group_service.mutate(operations)

Замените метку-заполнитель идентификатором группы объявлений из тестового клиентского аккаунта и попробуйте запустить код. После запуска войдите в тестовый аккаунт через веб-интерфейс AdWords и убедитесь, что статус изменен.

PHP

В среде IDE откройте файл PauseAd.php.

Мы снова рассмотрим шаблонный код, получающий данные аутентификации из файла конфигурации auth.ini.

Обратите внимание на метки-заполнители для идентификатора группы объявлений и идентификатора объявления.

// Укажите требуемые параметры.
$adGroupId = 'INSERT_AD_GROUP_ID_HERE';
$adId = 'INSERT_AD_ID_HERE';

Где взять идентификатор группы объявлений? Это можно сделать программным образом с помощью метода GET интерфейса AdGroupService. Например, идентификатор можно извлечь из URL веб-интерфейса AdWords при просмотре группы объявлений.

Нас интересует код, выполняемый при запуске примера. Давайте пошагово рассмотрим, что именно он делает.

Во-первых, он получает ссылку на интерфейс AdGroupService, который осуществляет изменение группы объявлений. Чтобы изменить другие объекты, необходимо использовать соответствующие службы. Полный список служб доступен в руководстве Объекты, методы и службы.

  // Получение службы, загружающей требуемые классы.
  $adGroupAdService = $user->GetService('AdGroupAdService', ADWORDS_VERSION);

Затем создается объявление с использованием существующего идентификатора.

  // Создание объявления с существующим идентификатором. Чтобы избежать
  // назначения полей объявления используется базовый класс Ad вместо TextAd.
  $ad = new Ad();
  $ad->id = $adId;

После этого создается новый объект группы объявлений, в котором указывается идентификатор нужной группы объявлений.

  // Создание объявления в группе объявлений.
  $adGroupAd = new AdGroupAd();
  $adGroupAd->adGroupId = $adGroupId;
  $adGroupAd->ad = $ad;

Затем ей присваивается статус PAUSED.

  // Изменение статуса.
  $adGroupAd->status = 'PAUSED';

Потом создается объект AdGroupOperation на основе только что созданного объекта группы объявлений и применяется оператор SET.

  // Создание операции.
  $operation = new AdGroupAdOperation();
  $operation->operand = $adGroupAd;
  $operation->operator = 'SET';
  $operations = array($operation);

Наконец, осуществляется вызов метода mutate интерфейса службы группы объявлений с передачей объекта операции для группы объявлений.

  // Создание запроса на изменение.
  $result = $adGroupAdService->mutate($operations);

Замените метку-заполнитель идентификатором группы объявлений из тестового клиентского аккаунта и попробуйте запустить код. После запуска войдите в тестовый аккаунт через веб-интерфейс AdWords и убедитесь, что статус изменен.

Perl

В среде IDE откройте файл update_ad_group.pl.

Мы снова рассмотрим шаблонный код, который получает учетные данные из файла конфигурации adwords.properties.

Обратите внимание на метку-заполнитель для идентификатора группы объявлений, которую нужно приостановить.

# Укажите значения из вашего аккаунта.
my $ad_group_id = "INSERT_AD_GROUP_ID_HERE";

Где взять идентификатор группы объявлений? Это можно сделать программным образом с помощью метода GET интерфейса AdGroupService. Например, идентификатор можно извлечь из URL веб-интерфейса AdWords при просмотре группы объявлений.

Нас интересует код, выполняемый при запуске примера. Давайте пошагово рассмотрим, что именно он делает.

Во-первых, создается группа объявлений с использованием adGroupID. Чтобы изменить другие объекты, необходимо использовать соответствующие службы. Полный список служб доступен в руководстве Объекты, методы и службы. После этого задается статус PAUSED.

 # Создание группы объявлений с измененным статусом.
  my $ad_group = Google::Ads::AdWords::v201702::AdGroup->new({
      id     => $ad_group_id,
      status => "PAUSED"
  });

Затем создается операция группы объявлений на основе только что созданного объекта группы объявлений и применяется оператор SET.

# Создание операции.
  my $operation = Google::Ads::AdWords::v201702::AdGroupOperation->new({
      operand  => $ad_group,
      operator => "SET"
  });

Наконец, осуществляется вызов метода mutate интерфейса AdGroupService с передачей объекта операции для группы объявлений.

# Изменение группы объявлений.
  my $result = $client->AdGroupService()->mutate({operations => [$operation]});

Замените метку-заполнитель идентификатором группы объявлений из тестового клиентского аккаунта и попробуйте запустить код. После запуска войдите в тестовый аккаунт через веб-интерфейс AdWords и убедитесь, что статус изменен.

Ruby

Откройте файл update_ad_group.rb.

Мы снова рассмотрим шаблонный код, который получает учетные данные из файла конфигурации adwords_api.yml. Обратите внимание на метку-заполнитель для идентификатора группы объявлений.

    # Идентификатор изменяемой группы объявлений.
    ad_group_id = 'INSERT_AD_GROUP_ID_HERE'.to_i

Где взять идентификатор группы объявлений? Это можно сделать программным образом с помощью метода GET интерфейса AdGroupService. Например, идентификатор можно извлечь из URL веб-интерфейса AdWords при просмотре группы объявлений.

Нас интересует код, выполняемый при запуске примера. Давайте пошагово рассмотрим, что именно он делает.

Во-первых, он получает ссылку на интерфейс AdGroupService, который осуществляет изменение группы объявлений. Чтобы изменить другие объекты, необходимо использовать соответствующие службы. Полный список служб доступен в руководстве Объекты, методы и службы.

ad_group_srv = adwords.service(:AdGroupService, API_VERSION)

После этого создается новый объект группы объявлений, в котором указывается идентификатор нужной группы объявлений и задается статус PAUSED с использованием оператора SET.

# Подготовка к изменению группы объявлений.
  operation = {
    :operator => 'SET',
    :operand => {
      :status => 'PAUSED',
      :id => ad_group_id
    }
  }

Наконец, осуществляется вызов метода mutate интерфейса AdGroupService с передачей объекта операции группы объявлений.

# Изменение группы объявлений.
  response = ad_group_srv.mutate([operation])

Замените метку-заполнитель идентификатором группы объявлений из тестового клиентского аккаунта и попробуйте запустить код. После запуска войдите в тестовый аккаунт через веб-интерфейс AdWords и убедитесь, что статус изменен.

Анализ шаблона

Тот же процесс, который мы использовали для приостановки и возобновления группы объявлений, применяется и для большинства изменений, вносимых через API. Он состоит из следующих шагов:

  1. Создание нового объекта.
  2. Назначение идентификатора объекта, который нужно изменить.
  3. Назначение нового значения свойству этого объекта.
  4. Создание объекта операции с помощью оператора SET и использование нового объекта в качестве операнда.
  5. Передача объекта операции в метод MUTATE соответствующей службы.

Поскольку речь шла об изменении, мы использовали оператор SET. При добавлении и удалении следует использовать операторы ADD и REMOVE.

Чтобы лучше понять принцип работы этого шаблона, рассмотрите другие примеры кода.

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

Изменение ставок на уровне группы объявлений

Ещё одним популярным вариантом использования кода является программное изменение ставки. В качестве канонического примера можно привести повышение ставки для рекламы зонтов во время дождя. Ваше приложение может быть связано со службой погоды и использовать AdWords API для повышения ставки на уровне группы объявлений.

Для этого можно использовать тот же самый пример обновления группы объявлений, однако вместо AdGroupStatus нужно менять стратегию назначения ставок. Подробнее читайте в руководстве по ставкам.

Создание кампании

Рассмотрим ещё один вариант использования.

Java

В среде IDE откройте файл AddCampaigns.java.

Он содержит много кода, но соответствует тому же шаблону. В этом случае после создания иерархии объектов мы используем оператор ADD для добавления нового бюджета через BudgetService и новых кампаний через CampaignService.

Нам не нужно задавать идентификаторы, поскольку эти новые объекты пока не имеют идентификаторов.

.NET

В среде IDE откройте файл AddCampaigns.cs.

Он содержит много кода, но соответствует тому же шаблону. В этом случае после создания иерархии объектов мы используем оператор ADD для добавления нового бюджета через BudgetService и новых кампаний через CampaignService.

Нам не нужно задавать идентификаторы, поскольку эти новые объекты пока не имеют идентификаторов.

Python

В среде IDE откройте файл add_campaigns.py.

Он содержит много кода, но соответствует тому же шаблону. В этом случае после создания иерархии объектов мы используем оператор ADD для добавления нового бюджета через BudgetService и новых кампаний через CampaignService.

Нам не нужно задавать идентификаторы, поскольку эти новые объекты пока не имеют идентификаторов.

PHP

В среде IDE откройте файл AddCampaigns.php.

Он содержит много кода, но соответствует тому же шаблону. В этом случае после создания иерархии объектов мы используем оператор ADD для добавления нового бюджета через BudgetService и новых кампаний через CampaignService.

Нам не нужно задавать идентификаторы, поскольку эти новые объекты пока не имеют идентификаторов.

Perl

В среде IDE откройте файл add_campaigns.pl.

Он содержит много кода, но соответствует тому же шаблону. В этом случае после создания иерархии объектов мы используем оператор ADD для добавления нового бюджета через BudgetService и новых кампаний через CampaignService.

Нам не нужно задавать идентификаторы, поскольку эти новые объекты пока не имеют идентификаторов.

Ruby

Откройте файл add_campaigns.rb.

Он содержит много кода, но соответствует тому же шаблону. В этом случае после создания иерархии объектов мы используем оператор ADD для добавления нового бюджета через BudgetService и новых кампаний через CampaignService.

Нам не нужно задавать идентификаторы, поскольку эти новые объекты пока не имеют идентификаторов.

Дальнейшие действия

Итак, мы рассмотрели основные сведения. Советуем перейти к руководству Объекты, методы и службы и другим руководствам в разделе Архитектура и понятия, чтобы больше узнать об архитектуре API, предлагаемых службах и интеграции функций API в приложение.

После этого вы будете готовы начать создание собственного приложения с использованием преимуществ автоматизации и создания отчетов, доступных благодаря AdWords API.

Оставить отзыв о...

Текущей странице
Нужна помощь? Обратитесь в службу поддержки.