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

Поле 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() для извлечения ключа Campaign.enhanced из поля forwardCompatibilityMap. Этот пример взят из клиентской библиотеки Java.

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

 // Create selector.
 Selector selector = new Selector();
 // Set the selector fields.
 // Notice there is no need to explicitly request the
 // forwardCompatibilityMap, indeed adding to the list of fields
 // will throw an error.
 selector.setFields(new String[] {"Id", "Name"});

 CampaignPage page = campaignService.get(selector);

 // Display campaigns.
 if (page.getEntries() != null) {
   for (Campaign campaign : page.getEntries()) {
     Map forwardCompatibilityMap =
         Maps.toMap(campaign.getForwardCompatibilityMap());
     System.out.println(String.format(
         "Campaign ID %d has enhanced value of '%s'",
         campaign.getId(),
         forwardCompatibilityMap.get("Campaign.enhanced")));
   }
 } else {
   System.out.println("No campaigns were found.");
 }

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

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

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

Пример

Ниже показано, как перейти на расширенную кампанию путем отправки ключа Campaign.enhanced со значением true в поле forwardCompatibilityMap. Пример взят из клиентской библиотеки Java.

// This is an example on how to enhance 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 "Campaign.enhanced" as "true" to update the campaign.
campaign.setForwardCompatibilityMap(new String_StringMapEntry[] {
    new String_StringMapEntry("Campaign.enhanced",
        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);

Исправление ошибок

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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