Структура кода

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

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

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

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

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

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

Java

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

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

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

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

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

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

// Construct an AdWordsSession.
AdWordsSession session = new AdWordsSession.Builder()
    .fromFile()
    .withOAuth2Credential(oAuth2Credential)
    .build();

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

AdWordsServices adWordsServices = new AdWordsServices();

runExample(adWordsServices, session);

C#

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

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

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

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

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

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

// Create a default AdWordsUser instance. If any configuration
// is available in App.config, those will be used.
AdWordsUser user = new AdWordsUser();

// Override a specific setting at runtime.
AdWordsAppConfig config = (AdWordsAppConfig) user.Config;
user.Config.clientCustomerId = "123-456-7890";

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

// Create a config object with the values in App.config.
AdWordsAppConfig config = new AdWordsAppConfig();

// Override any specific setting you wish to change.
user.Config.clientCustomerId = "123-456-7890";

AdWordsUser user = new AdWordsUser(config);

Python

В интегрированной среде разработки откройте файл 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

В интегрированной среде разработки откройте файл GetCampaigns.php.

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

// Generate a refreshable OAuth2 credential for authentication.
$oAuth2Credential = (new OAuth2TokenBuilder())
    ->fromFile()
    ->build();

Затем при помощи этого токена создается сеанс API, в рамках которого выполняется функция runExample().

// Construct an API session configured from a properties file and the OAuth2
// credentials above.
$session = (new AdWordsSessionBuilder())
    ->fromFile()
    ->withOAuth2Credential($oAuth2Credential)
    ->build();
self::runExample(new AdWordsServices(), $session);

runExample() – основная функция в этом примере, она извлекает названия и идентификаторы кампаний при помощи селектора из CampaignService.

Perl

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

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

# Get AdWords Client, credentials will be read from ~/adwords.properties.
my $client = Google::Ads::AdWords::Client->new({version => "v201710"});

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

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

# Get AdWords Client, credentials will be read from ~/adwords.properties.
my $client = Google::Ads::AdWords::Client->new({version => "v201710"});
$client->set_client_id("123-456-7890");

Ruby

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

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

  # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
  # when called without parameters.
  adwords = AdwordsApi::Api.new

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

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

# Set a new CID value
adwords.config.set("authentication.client_customer_id", "123-456-7890")

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

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

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

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

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

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

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

Java

В интегрированной среде разработки откройте файл DownloadCriteriaReport.java.

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

public static void main(String[] args) throws Exception {
    // Generate a refreshable OAuth2 credential.
    Credential oAuth2Credential = new OfflineCredentials.Builder()
        .forApi(Api.ADWORDS)
        .fromFile()
        .build()
        .generateCredential();

    // Construct an AdWordsSession.
    AdWordsSession session = new AdWordsSession.Builder()
        .fromFile()
        .withOAuth2Credential(oAuth2Credential)
        .build();

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

// Create report definition.
    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.

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

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

reportDefinition.setReportType(ReportDefinitionReportType.CRITERIA_PERFORMANCE_REPORT);

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

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

C#

В интегрированной среде разработки откройте файл 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

В интегрированной среде разработки откройте файл download_criteria_report_with_selector.py.

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

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

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

# Create report definition.
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_with_selector.py.

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

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

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

PHP

В интегрированной среде разработки откройте файл DownloadCriteriaReportWithSelector.php.

Пример содержит стандартный код для аутентификации и создания сеанса AdWords. Он включен в основную функцию runExample(), в которой создается селектор и определяется отчет.

// Create selector.
$selector = new Selector();
$selector->setFields(['CampaignId', 'AdGroupId', 'Id', 'Criteria',
    'CriteriaType', 'Impressions', 'Clicks', 'Cost']);

// Create report definition.
$reportDefinition = new ReportDefinition();
$reportDefinition->setSelector($selector);
$reportDefinition->setReportName(
    'Criteria performance report #' . uniqid());
$reportDefinition->setDateRangeType(
    ReportDefinitionDateRangeType::LAST_7_DAYS);
$reportDefinition->setReportType(
    ReportDefinitionReportType::CRITERIA_PERFORMANCE_REPORT);
$reportDefinition->setDownloadFormat(DownloadFormat::CSV);

Обратите внимание, что в примере задается тип отчета (CRITERIA_PERFORMANCE_REPORT) и указывается, какие поля отчета нужно получить.

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

// Download report.
$reportDownloader = new ReportDownloader($session);
$reportDownloadResult =
    $reportDownloader->downloadReport($reportDefinition);
$reportDownloadResult->saveToFile($filePath);
printf("Report with name '%s' was downloaded to '%s'.\n",
    $reportDefinition->getReportName(), $filePath);

Запустите файл DownloadCriteriaReportWithSelector.php. В консоли появится информация о местонахождении скачанного файла.

Perl

В интегрированной среде разработки откройте файл download_criteria_report_with_selector.pl.

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

# Get AdWords Client, credentials will be read from ~/adwords.properties.
my $client = Google::Ads::AdWords::Client->new({version => "v201710"});

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

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.

# Download the report using the appropriate method on ReportDownloadHandler.
my $result;
if ($output_file) {
  $result = $report_handler->save($output_file);
} else {
  $result = $report_handler->get_as_string();
}

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

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

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

reportType => "CRITERIA_PERFORMANCE_REPORT",

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

# Create selector.
my $selector = Google::Ads::AdWords::Reports::Selector->new({
    fields => [
      "CampaignId", "AdGroupId", "Id",          "CriteriaType",
      "Criteria",   "FinalUrls", "Impressions", "Clicks",
      "Cost"
    ]
});

Ruby

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

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

def download_criteria_report_with_selector(file_name)
  # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
  # when called without parameters.
  adwords = AdwordsApi::Api.new

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

# Define report definition. You can also pass your own XML text as a string.
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',
}

Затем мы передаем его в метод report_utils.download_report_as_file.

# Download report, using "download_report_as_file" utility method.
# To retrieve the report as return value, use "download_report" method.
report_utils.download_report_as_file(report_definition, file_name)
puts "Report was downloaded to '%s'." % file_name
end

Теперь запустите файл download_criteria_report_with_selector.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";

C#

Сравните только что выполненный пример кода и файл 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-кода.

// Create report query to get the data for last 7 days.
$reportQuery = 'SELECT CampaignId, AdGroupId, Id, Criteria, CriteriaType, '
    . 'Impressions, Clicks, Cost FROM CRITERIA_PERFORMANCE_REPORT '
    . 'WHERE Status IN [ENABLED, PAUSED] DURING LAST_7_DAYS';

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.

# Create report query.
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.

# Prepare a date range for the last week. Instead you can use '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

В интегрированной среде разработки откройте файл UpdateAdGroup.java.

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

public static void main(String[] args) throws Exception {
    // Generate a refreshable OAuth2 credential.
    Credential oAuth2Credential = new OfflineCredentials.Builder()
        .forApi(Api.ADWORDS)
        .fromFile()
        .build()
        .generateCredential();

    // Construct an AdWordsSession.
    AdWordsSession session = new AdWordsSession.Builder()
        .fromFile()
        .withOAuth2Credential(oAuth2Credential)
        .build();

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

Как получить идентификатор группы объявлений? Это можно сделать программно при помощи метода get() интерфейса AdGroupService. Также идентификатор извлекается из URL веб-интерфейса AdWords при просмотре группы объявлений.

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

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

// Get the AdGroupService.
AdGroupServiceInterface adGroupService =
    adWordsServices.get(session, AdGroupServiceInterface.class);

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

// Create ad group with updated status.
AdGroup adGroup = new AdGroup();
adGroup.setId(adGroupId);

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

adGroup.setStatus(AdGroupStatus.PAUSED);

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

// Create operations.
AdGroupOperation operation = new AdGroupOperation();
operation.setOperand(adGroup);
operation.setOperator(Operator.SET);

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

// Update ad group.
AdGroupReturnValue result = adGroupService.mutate(operations);

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

C#

В интегрированной среде разработки откройте файл 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.v201710.AdGroupService);
}

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

// Create the ad group.
AdGroup adGroup = new AdGroup();
adGroup.status = AdGroupStatus.PAUSED;
adGroup.id = adGroupId;

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

adGroup.status = AdGroupStatus.PAUSED;

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

// Create the operation.
AdGroupOperation operation = new AdGroupOperation();
operation.@operator = Operator.SET;
operation.operand = adGroup;

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

// Update the ad group.
AdGroupReturnValue retVal = adGroupService.mutate(new AdGroupOperation[] {operation});

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

Python

В интегрированной среде разработки откройте файл 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='v201710')

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

# Construct operations and update an ad group.
  operations = [{
      'operator': 'SET',
      'operand': {
          'id': ad_group_id,
          'status': 'PAUSED'

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

# Construct operations and update an ad group.
  operations = [{
      'operator': 'SET',
      'operand': {
          'id': ad_group_id,
          'status': 'PAUSED'

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

ad_groups = ad_group_service.mutate(operations)

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

PHP

В интегрированной среде разработки откройте файл PauseAd.php.

Нужное объявление определяется при помощи идентификаторов самого объявления и его группы:

const AD_GROUP_ID = 'INSERT_AD_GROUP_ID_HERE';
const AD_ID = 'INSERT_AD_ID_HERE';

Идентификатор группы объявлений можно получить при помощи метода get() из AdGroupService или из URL веб-интерфейса AdWords при просмотре группы объявлений.

Давайте пошагово рассмотрим, что именно делает метод runExample().

  1. Получает ссылку на интерфейс AdGroupService, в котором осуществляется изменение группы объявлений.
    $adGroupAdService =
        $adWordsServices->get($session, AdGroupAdService::class);
    
  2. Создает объект Ad.
    $ad = new Ad();
    $ad->setId($adId);
    
  3. Создает объект AdGroupAd, задает идентификатор группы объявлений и объявление.
    $adGroupAd = new AdGroupAd();
    $adGroupAd->setAdGroupId($adGroupId);
    $adGroupAd->setAd($ad);
    
  4. Присваивает объекту AdGroupAd статус PAUSED.
    $adGroupAd->setStatus(AdGroupAdStatus::PAUSED);
    
  5. Создает операцию и передает ее в AdGroupAdService при помощи метода mutate().
    // Create ad group ad operation and add it to the list.
    $operation = new AdGroupAdOperation();
    $operation->setOperand($adGroupAd);
    $operation->setOperator(Operator::SET);
    $operations[] = $operation;
    
    // Pause the ad on the server.
    $result = $adGroupAdService->mutate($operations);
    

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

Perl

В интегрированной среде разработки откройте файл update_ad_group.pl.

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

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

# Replace with valid values of your account.
my $ad_group_id = "INSERT_AD_GROUP_ID_HERE";

Как получить идентификатор группы объявлений? Это можно сделать программно при помощи метода get() интерфейса AdGroupService. Также идентификатор извлекается из URL веб-интерфейса AdWords при просмотре группы объявлений.

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

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

# Create ad group with updated status.
my $ad_group = Google::Ads::AdWords::v201710::AdGroup->new({
    id     => $ad_group_id,
    status => "PAUSED"
});

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

# Create operation.
my $operation = Google::Ads::AdWords::v201710::AdGroupOperation->new({
    operand  => $ad_group,
    operator => "SET"
});

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

# Update ad group.
my $result = $client->AdGroupService()->mutate({operations => [$operation]});

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

Ruby

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

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

# ID of an ad group to update.
ad_group_id = 'INSERT_AD_GROUP_ID_HERE'.to_i

Как получить идентификатор группы объявлений? Это можно сделать программно при помощи метода get() интерфейса AdGroupService. Также идентификатор извлекается из URL веб-интерфейса AdWords при просмотре группы объявлений.

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

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

ad_group_srv = adwords.service(:AdGroupService, API_VERSION)

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

# Prepare for updating ad group.
operation = {
  :operator => 'SET',
  :operand => {
    :status => 'PAUSED',
    :id => ad_group_id
  }
}

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

# Update ad group.
response = ad_group_srv.mutate([operation])

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

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

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

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

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

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

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

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

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

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

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

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

Java

В интегрированной среде разработки откройте файл AddCampaigns.java.

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

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

C#

В интегрированной среде разработки откройте файл AddCampaigns.cs.

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

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

Python

В интегрированной среде разработки откройте файл add_campaigns.py.

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

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

PHP

В интегрированной среде разработки откройте файл AddCampaigns.php.

Как обычно, основная логическая часть содержится в методе runExample(). Мы задаем бюджет, кампанию, стратегию назначения ставок и дополнительные настройки, например рекламные сети или ограничение частоты показов. Затем мы настраиваем для кампании оператор ADD и передаем операцию в CampaignService при помощи метода mutate().

Perl

В интегрированной среде разработки откройте файл add_campaigns.pl.

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

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

Ruby

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

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

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

Дополнительная информация

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

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

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

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