Карты прямой совместимости

Поле forwardCompatibilityMap позволяет использовать самые новые функции API до момента их официального выхода. Оно включается в несколько основных объектов API (например, в объект Campaign).

Поле forwardCompatibilityMap – это разновидность поля String_StringMapEntry. Оно используется для получения и настройки простых свойств объектов API, которые ещё не доступны в качестве формальных атрибутов объекта или его потомков. Эти свойства отображаются в поле forwardCompatibilityMap в виде ключей. К объектам, которые содержат поле forwardCompatibilityMap, относятся Campaign, AdGroup и AdGroupAd.

Расшифровка карты

Поле forwardCompatibilityMap не нужно обозначать как часть массива Selector.fields. Если используется по крайней мере один ключ, отображаемый в текущей версии API и сервисе, с которым вы работаете, то поле forwardCompatibilityMap всегда будет присутствовать в ответе.

Для каждого типа объектов карта может содержать свой набор ключей, которые будут отображаться как расширение формальных атрибутов объекта или одного из его потомков. Ключ в поле forwardCompatibilityMap может обозначать атрибут потомка объекта, а не самого объекта. Например, в карте для AdGroupAd может отображаться ключ Ad.devicePreferred, который в действительности будет принадлежать объекту Ad – одному из потомков AdGroupAd.

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

Пример

Ниже показано, как вызвать метод get() в CampaignService для извлечения ключа forwardCompatibilityMap из всех кампаний.

Java

// Get the CampaignService.
CampaignServiceInterface campaignService =
    adWordsServices.get(session, CampaignServiceInterface.class);

// Create selector.
// Notice there is no need to explicitly request the
// forwardCompatibilityMap, indeed adding to the list of fields
// will throw an error.
SelectorBuilder selectorBuilder =
    new SelectorBuilder().fields(CampaignField.Id).limit(PAGE_SIZE);

int offset = 0;

CampaignPage page;
Map<Long, Boolean> campaignMap = new HashMap<>();
do {
  page = campaignService.get(selectorBuilder.build());

  // Collect the campaigns from the page.
  for (Campaign campaign : page.getEntries()) {
    Map<String, String> forwardCompatibilityMap =
        Maps.toMap(campaign.getForwardCompatibilityMap());
    String value = forwardCompatibilityMap.get(compatibilityMapKey);
    System.out.printf(
        "Campaign ID %d has forward compatibility map value of '%s' for key '%s'.%n",
        campaign.getId(), value, compatibilityMapKey);
    // This demonstrates how to handle a forward compatibility map key where
    // the value is a boolean. Check the forward compatibility map documentation
    // for the data type for each supported key:
    // https://developers.google.com/adwords/api/docs/guides/forward-compatibility-maps
    campaignMap.put(campaign.getId(), value == null ? null : Boolean.valueOf(value));
  }
  offset += PAGE_SIZE;
  selectorBuilder.increaseOffsetBy(PAGE_SIZE);
} while (offset < page.getTotalNumEntries());
return campaignMap;

C#

// Get the CampaignService.
CampaignService campaignService = (CampaignService)user.GetService(
    AdWordsService.v201802.CampaignService);

// Create selector. There is no need to explicitly request the forwardCompatibilityMap field.
// Requesting this field through selectors will throw an error.
Selector selector = new Selector() {
  fields = new string[] { Campaign.Fields.Id },
  paging = Paging.Default
};

CampaignPage page = new CampaignPage();
Dictionary<long, bool> campaignMap = new Dictionary<long, bool>();

try {
  do {
    // Get the campaigns.
    page = campaignService.get(selector);

    // Display the results.
    if (page != null && page.entries != null) {
      foreach (Campaign campaign in page.entries) {
        Dictionary<String, String> forwardCompatibilityMap =
            campaign.forwardCompatibilityMap.ToDict();

        String value = CollectionUtilities.TryGetValue(
            forwardCompatibilityMap, compatibilityMapKey);

        if (value != null) {
          Console.WriteLine("Campaign ID {0} has forward compatibility map value of " +
              "'{1}' for key '{2}'.", campaign.id, compatibilityMapKey);
          // This demonstrates how to handle a forward compatibility map key where
          // the value is a boolean. Check the forward compatibility map documentation
          // for the data type for each supported key:
          // https://developers.google.com/adwords/api/docs/guides/forward-compatibility-maps
          campaignMap[campaign.id] = Convert.ToBoolean(value);
        } else {
          campaignMap[campaign.id] = false;
        }
      }
    }
    selector.paging.IncreaseOffset();
  } while (selector.paging.startIndex < page.totalNumEntries);
  Console.WriteLine("Number of campaigns found: {0}", page.totalNumEntries);
} catch (Exception e) {
  throw new System.ApplicationException("Failed to retrieve forward compatibility map for " +
      "campaigns", e);
}
return campaignMap;

PHP

// Get the CampaignService.
$campaignService =
    $adWordsServices->get($session, CampaignService::class);

// Create selector.
// Notice there is no need to explicitly request the
// forwardCompatibilityMap, indeed adding to the list of fields
// will throw an error.
$selector = new Selector();
$selector->setFields(['Id']);
$selector->setPaging(new Paging(0, self::PAGE_LIMIT));

$campaignMap = [];
$foundResults = false;
do {
    // Retrieve campaigns one page at a time, continuing to request pages
    // until all campaigns have been retrieved.
    $page = $campaignService->get($selector);

    // Print out some information for each campaign.
    if ($page->getEntries() !== null) {
        $totalNumEntries = $page->getTotalNumEntries();
        foreach ($page->getEntries() as $campaign) {
            if (is_null($campaign->getForwardCompatibilityMap())) {
                continue;
            }
            $forwardCompatibilityMap = MapEntries::toAssociativeArray(
                $campaign->getForwardCompatibilityMap()
            );
            // This demonstrates how to handle a forward compatibility map key
            // where the value is a boolean. Check the forward compatibility map
            // documentation for the data type for each supported key:
            // https://developers.google.com/adwords/api/docs/guides/forward-compatibility-maps
            $value =
                boolval($forwardCompatibilityMap[$compatibilityMapKey]);
            $foundResults = true;
            printf(
                "Campaign ID %d has forward compatibility map value of '%s' for "
                . "key '%s'.\n",
                $campaign->getId(),
                $value,
                $compatibilityMapKey
            );
            // Cast the ID to string to prevent 32-bit PHP to convert this to
            // negative number.
            $campaignId = strval($campaign->getId());
            $campaignMap[$campaignId] = $value;
        }
    }
    $selector->getPaging()->setStartIndex(
        $selector->getPaging()->getStartIndex() + self::PAGE_LIMIT
    );
} while ($selector->getPaging()->getStartIndex() < $totalNumEntries);
if (!$foundResults) {
    print "No forward compatibility maps are found.\n";
}

return $campaignMap;

Python

# Get the CampaignService.
campaign_service = client.GetService('CampaignService', version='v201802')

# Create selector.
# Notice there is no need to explicitly request the forwardCompatibilityMap;
# adding to the list of fields will throw an error.
offset = 0
selector = {
    'fields': ['Id'],
    'paging': {
        'startIndex': offset,
        'numberResults': PAGE_SIZE
    }
}

campaign_map = {}
more_pages = True

while more_pages:
  page = campaign_service.get(selector)

  if 'entries' in page:
    for campaign in page['entries']:
      raw_fcm = getattr(
          campaign, 'forwardCompatibilityMap', {})
      forward_compatibility_map = {
          string_map_entry['key']: string_map_entry['value']
          for string_map_entry in raw_fcm
      }

      campaign_id = campaign['id']
      value = forward_compatibility_map.get(bool(compatibility_map_key),
                                            False)
      campaign_map[campaign_id] = value

      # This demonstrates how to handle a forward compatibility map key where
      # the value is a boolean. Check the forward compatibility map
      # documentation for the data type for each supported key:
      # https://developers.google.com/adwords/api/docs/guides/forward-compatibility-maps
      print ('Campaign with id "%s" has forward compatibility map value of '
             '"%s" for key "%s".' % (campaign_id, value,
                                     compatibility_map_key))
  offset += PAGE_SIZE
  selector['paging']['startIndex'] = offset
  more_pages = offset < int(page['totalNumEntries'])

return campaign_map

Perl

# Create selector.
# Notice there is no need to explicitly request the forwardCompatibilityMap,
# indeed adding to the list of fields will throw an error.
my $paging = Google::Ads::AdWords::v201802::Paging->new({
  startIndex    => 0,
  numberResults => PAGE_SIZE
});
my $selector = Google::Ads::AdWords::v201802::Selector->new({
  fields     => ["Id"],
  paging     => $paging
});

my $campaign_map = {};
# Retrieve campaigns one page at a time, continuing to request pages until
# all campaigns have been retrieved.
Google::Ads::AdWords::Utilities::PageProcessor->new({
    client   => $client,
    service  => $client->CampaignService(),
    selector => $selector
  }
  )->process_entries(
  sub {
    # Print out some information for each campaign.
    my ($campaign) = @_;

    my $forward_compatibility_map =
        Google::Ads::Common::MapUtils::get_map(
          $campaign->get_forwardCompatibilityMap());
    if (defined $forward_compatibility_map) {
      # This demonstrates how to handle a forward compatibility map key
      # where the value is a boolean. Check the forward compatibility map
      # documentation for the data type for each supported key:
      # https://developers.google.com/adwords/api/docs/guides/forward-compatibility-maps
      my $value = $forward_compatibility_map->{$compatibility_map_key};
      if (defined $value) {
        printf "Campaign ID %d has forward compatibility map value of '%s'" .
          " for key '%s'.\n", $campaign->get_id(), $value,
          $compatibility_map_key;
        $campaign_map->{$campaign->get_id()} = $value;
      }
    }
  });

if (!keys %{$campaign_map}) {
  print "No forward compatibility maps were found.\n";
}

return $campaign_map;

Ruby

# Create selector.
# Notice there is no need to explicitly request the forwardCompatibilityMap,
# indeed adding it to the list of fields will throw an error.
selector = {
  :fields => ['Id'],
  :paging => {
    :start_index => 0,
    :number_results => PAGE_SIZE
  }
}

campaign_map = {}

# Iterate over all pages.
offset, page = 0, {}
begin
  page = campaign_srv.get(selector)
  if page[:entries]
    page[:entries].each do |campaign|
      unless campaign[:forward_compatibility_map].nil?
        value = campaign[:forward_compatibility_map][fcm_key]
        unless value.nil?
          puts ("Campaign ID %d has forward compatibility map value of '%s'" +
             " for key '%s'") % [campaign[:id], fcm_key, value]
          # This demonstrates how to handle a forward compatibility map key
          # where the value is a boolean. Check the forward compatibility map
          # documentation for the data type for each supported key:
          # https://developers.google.com/adwords/api/docs/guides/forward-compatibility-maps
          campaign_map[campaign[:id]] = (value.casecmp('true') >= 0)
        end
      end
    end
    # Increment values to request the next page.
    offset += PAGE_SIZE
    selector[:paging][:start_index] = offset
  end
end while page[:total_num_entries] > offset

return campaign_map

Изменение свойств с помощью карты

Изменение ключей с помощью поля mutate() (в частности ключа forwardCompatibilityMap из предыдущего примера) выполняется точно так же, как и для любого другого атрибута. Для этого необходимо создать регулярный вызов и проверить, заполняется ли поле forwardCompatibilityMap нужными ключами и значениями. Данные из полей forwardCompatibilityMap могут использоваться в регулярных операциях mutate ADD и SET, однако при этом может потребоваться соблюдение определенных условий.

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

Пример

Ниже показано, как изменить кампанию, отправив ключ со значением из поля forwardCompatibilityMap.

Java

// This is an example on how to update a campaign using the
// CampaignService and the forwardCompatibilityMap field.

// Get the CampaignService.
CampaignServiceInterface campaignService =
    adWordsServices.get(session, CampaignServiceInterface.class);

// Create campaign with updated status.
Campaign campaign = new Campaign();
campaign.setId(campaignId);
// Set the forward compatibility map entry to "true" to update the campaign.
// This demonstrates how to handle a forward compatibility map key where
// the value is a boolean. Check the forward compatibility map documentation
// for the data type for each supported key:
// https://developers.google.com/adwords/api/docs/guides/forward-compatibility-maps
campaign.setForwardCompatibilityMap(
    new String_StringMapEntry[] {
      new String_StringMapEntry(compatibilityMapKey, Boolean.TRUE.toString())
    });

// Create operations.
CampaignOperation operation = new CampaignOperation();
operation.setOperand(campaign);
operation.setOperator(Operator.SET);

CampaignOperation[] operations = new CampaignOperation[] {operation};

// Update campaign.
CampaignReturnValue result = campaignService.mutate(operations);
System.out.printf(
    "Updated forward compatibility map of campaign ID %d.%n", result.getValue(0).getId());

C#

// This is an example on how to update a campaign using the
// CampaignService and the forwardCompatibilityMap field.

// Get the CampaignService.
CampaignService campaignService = (CampaignService)user.GetService(
    AdWordsService.v201802.CampaignService);

// Create campaign with updated status.
Campaign campaign = new Campaign();
campaign.id = campaignId;
// Set the forward compatibility map entry to "true" to update the campaign.
// This demonstrates how to handle a forward compatibility map key where
// the value is a boolean. Check the forward compatibility map documentation
// for the data type for each supported key:
// https://developers.google.com/adwords/api/docs/guides/forward-compatibility-maps
campaign.forwardCompatibilityMap = new String_StringMapEntry[] {
  new String_StringMapEntry() {
    key = compatibilityMapKey,
    value = Boolean.TrueString
  }
};

// Create operations.
CampaignOperation operation = new CampaignOperation();
operation.operand = campaign;
operation.@operator = Operator.SET;

try {
  CampaignOperation[] operations = new CampaignOperation[] { operation };

  // Update campaign.
  CampaignReturnValue result = campaignService.mutate(operations);
  Console.WriteLine("Updated forward compatibility map of campaign ID {0}.",
      result.value[0].id);
} catch (Exception e) {
  throw new System.ApplicationException("Failed to update forward compatibility map for " +
      "campaigns", e);
}

PHP

// This is an example on how to update a campaign using the
// CampaignService and the forwardCompatibilityMap field.

// Get the CampaignService.
$campaignService =
    $adWordsServices->get($session, CampaignService::class);

// Create campaign with updated status.
$campaign = new Campaign();
$campaign->setId($campaignId);
// Set the forward compatibility map entry to "true" to update the campaign.
// This demonstrates how to handle a forward compatibility map key
// where the value is a boolean. Check the forward compatibility map
// documentation for the data type for each supported key:
// https://developers.google.com/adwords/api/docs/guides/forward-compatibility-maps
$campaign->setForwardCompatibilityMap(
    [
        new String_StringMapEntry($compatibilityMapKey, 'true')
    ]
);

// Create operations.
$operation = new CampaignOperation();
$operation->setOperand($campaign);
$operation->setOperator(Operator::SET);

// Update campaign on the server.
$result = $campaignService->mutate([$operation]);
printf(
    "Updated forward compatibility map of campaign ID %d.\n",
    $result->getValue()[0]->getId()
);

Python

# This is an example on how to update a campaign using the CampaignService and
# the forwardCompatibilityMap field.

# Get the CampaignService.
campaign_service = client.GetService('CampaignService', version='v201802')

# Create campaign with updated status.
campaign = {
    'id': campaign_id,
    # This demonstrates how to handle a forward compatibility map key where
    # the value is a boolean. Check the forward compatibility map
    # documentation for the data type for each supported key:
    # https://developers.google.com/adwords/api/docs/guides/forward-compatibility-maps
    'forwardCompatibilityMap': [{
        'key': compatibility_map_key,
        'value': str(True)
    }]
}

# Create operations.
operations = [{
    'operand': campaign,
    'operator': 'SET'
}]

# Update campaign.
updated_campaign = campaign_service.mutate(operations)['value'][0]
print 'Updated forward compatibility map of campaign ID "%d".' % (
    updated_campaign['id'])

Perl

# This is an example on how to update a campaign using the
# CampaignService and the forwardCompatibilityMap field.

# Create campaign with updated status.
my $campaign = Google::Ads::AdWords::v201802::Campaign->new({
  id => $campaign_id,
  # Set the forward compatibility map entry to "1" to update the campaign.
  # This demonstrates how to handle a forward compatibility map key
  # where the value is a boolean. Check the forward compatibility map
  # documentation for the data type for each supported key:
  # https://developers.google.com/adwords/api/docs/guides/forward-compatibility-maps
  forwardCompatibilityMap =>
    [Google::Ads::AdWords::v201802::String_StringMapEntry->new({
      key   => $compatibility_map_key,
      value => 1})]
});

my $operation = Google::Ads::AdWords::v201802::CampaignOperation->new({
  operand  => $campaign,
  operator => "SET"
});

# Update campaign on the server.
my $result = $client->CampaignService()->mutate({
  operations => [$operation]});

printf("Updated forward compatibility map of campaign ID %d.\n",
      $result->get_value()->[0]->get_id());

Ruby

# Prepare for updating campaign.
operation = {
  :operator => 'SET',
  :operand => {
    :id => campaign_id,
    # Set the forward compatibility map entry to "true" as an example.
    :forward_compatibility_map => [
      {:key => fcm_key, :value => true}
    ]
  }
}

# Update campaign.
response = campaign_srv.mutate([operation])
if response and response[:value]
  campaign = response[:value].first
  puts "Campaign ID %d was successfully updated." % campaign[:id]
else
  puts 'No campaigns were updated.'
end

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

В результате некоторых операций, например ввода недопустимого значения ключа в поле forwardCompatibilityMap, вызывается исключение ApiException и возвращается ошибка ApiError. Она будет включать параметр fieldPath, указывающий на forwardCompatibilityMap, и параметр trigger с неверным значением.

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

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

Часто задаваемые вопросы

Как запросить заполнение поля forwardCompatibilityMap в ответе? Я не могу найти соответствующее имя поля в документации.

Заполнение не нужно запрашивать в составе массива Selector.fields: оно будет выполнено, если объект, который должен быть возвращен в карте, содержит данные.

Почему поле forwardCompatibilityMap не заполняется?

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

Произойдет ли ошибка, если передать неверный ключ?

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

В объекте поддерживается новое поле или ключ, но я не вижу в нем поля forwardCompatibilityMap.

Поле forwardCompatibilityMap отображается только в объектах API верхнего уровня, таких как Campaign, AdGroup и AdGroupAd. Но некоторые ключи влияют на объекты нижних уровней.

Что произойдет, если передать в карте неверное значение?

Если вы используете правильный ключ, но неподдерживаемое значение, появится ApiException.

Ключи можно использовать во всех версиях API?

Нет, только в тех версиях, в которых ещё не реализованы соответствующие функции.

Доступные ключи ForwardCompatibilityMap

Ключи ForwardCompatibilityMap
Сервис
AdGroupAdService
Объект
AdGroupAd
Название ключа
Ad.type
Поле селектора
AdType
Тип
Enum
Поддерживаемые версии
201710, 201802
Только для чтения

Если развернутое текстовое объявление ExpandedTextAd является вариантом объявления, должен быть выбран вариант AD_VARIATION. Этого ключа не будет в карте прямой совместимости для остальных типов объявлений, а также для развернутых текстовых объявлений ExpandedTextAd, которые не являются вариантами исходного объявления.

Возможность определять варианты объявлений доступна в версии v201802 и выше. Используйте это поле для обнаружения вариантов объявлений в предыдущих версиях API.

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

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