Mapas de compatibilidade com versões futuras

O campo forwardCompatibilityMap permite que você explore as mais novas funcionalidades antes que elas sejam disponibilizadas formalmente na API. Algumas das principais entidades da API incluem esse campo (por exemplo, Campaign).

O campo forwardCompatibilityMap é do tipo String_StringMapEntry, que representa um mapeamento string por string. O mapeamento é usado para recuperar e definir as propriedades nas entidades da API, ou seja, as propriedades que ainda não estão disponíveis como atributos formais do objeto ou dos descendentes dele. Essas propriedades são expostas por meio das chaves de forwardCompatibilityMap. Entre os objetos que têm o campo forwardCompatibilityMap, estão Campaign, AdGroup e AdGroupAd.

Leitura do mapa

Não é necessário referenciar o campo forwardCompatibilityMap como parte da sua matriz de Selector.fields. Se houver pelo menos uma chave exposta na versão e no serviço da API usada, o campo forwardCompatibilityMap estará presente na resposta.

Um mapa pode conter um conjunto de chaves, uma para cada tipo de objeto. Essas chaves são expostas como uma extensão dos atributos formais do objeto ou um dos seus descendentes. Uma chave em um forwardCompatibilityMap de um objeto pode fazer referência a um atributo do descendente do objeto em vez de ao próprio objeto. Por exemplo, você pode ver a chave Ad.devicePreferred no mapa do AdGroupAd, mas na verdade essa chave pertence ao objeto Ad (que é um descendente do AdGroupAd).

Os valores do mapa são do tipo string. No entanto, dependendo da chave associada e ao atributo que ela representa, esses valores podem ser representações de strings de outros tipos de dados básicos, como "integers" ou "booleans". Talvez seja necessário converter o tipo antes de usá-lo.

Exemplo de get

Veja um exemplo da chamada de um método get() no CampaignService para recuperar o valor para uma chave específica a partir do forwardCompatibilityMap de cada campanha.

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

Como alterar as propriedades a partir do mapa

A modificação de chaves por meio de forwardCompatibilityMap é semelhante à utilizada em qualquer outro atributo: basta chamar o método mutate(), certificando-se de que o forwardCompatibilityMap esteja preenchido com as chaves e valores que você quer alterar. As operações normais de modificação ADD e SET aceitam dados forwardCompatibilityMap, mas podem requerer algumas disposições.

Passe valores válidos para as chaves para evitar erros como ApiException. Além disso, verifique se o nome da chave está correto, já que os nomes incorretos ou indefinidos são ignorados pela API sem acionar alertas e podem causar erros de diagnóstico difícil.

Exemplo de mutate

O exemplo a seguir demonstra como alterar uma campanha enviando a chave e o valor no 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

Tratamento de erros

Algumas operações, como passar um valor inválido de uma chave no forwardCompatibilityMap, resultam em um ApiException que contém um ApiError. Esse erro contém o fieldPath que aponta para o forwardCompatibilityMap e o trigger preenchido com o valor que ocasionou o problema.

A passagem de um nome de chave inválido pode resultar em erros de difícil diagnóstico, pois a API permitirá que isso ocorra sem acionar alertas.

Também é interessante notar que as chaves são vinculadas às versões da API. Uma chave que é válida para uma versão deixa de ser aceita em uma versão futura quando a funcionalidade dela é formalmente implementada na API. Se uma chave é passada em uma versão da API que não a aceita mais, uma ApiException é retornada.

Perguntas frequentes

Como faço para solicitar o forwardCompatibilityMap a ser preenchido na resposta? Não consigo encontrar um nome de campo para ele na documentação.

Não é necessário solicitá-lo como parte dos valores Selector.fields. Ele será preenchido se houver dados vinculados ao objeto a ser retornado no mapa.

Por que o forwardCompatibilityMap não está sendo preenchido?

Geralmente porque o objeto não tem dados vinculados à chave que você espera ver no mapa.

Vou receber um erro se eu enviar a chave errada no mapa?

Não, mas você precisa ter cuidado ao especificar o nome da chave, pois a API ignora as chaves não reconhecidas sem acionar alertas.

Sei que há um novo campo/chave compatível em um objeto, mas não consigo ver o objeto com um forwardCompatibilityMap.

Apenas as entidades de nível superior da API, como Campaign, AdGroup e AdGroupAd, expõem o forwardCompatibilityMap. Mas algumas chaves afetam objetos subjacentes.

O que acontece se eu enviar o valor errado no mapa?

Se você definir a chave certa, mas usar um valor não suportado, a API retornará uma ApiException.

As chaves são expostas em todas as versões da API?

Não, as chaves são expostas e aceitas somente nas versões da API que não têm a funcionalidade já exposta.

Chaves ForwardCompatibilityMap atuais

Chaves ForwardCompatibilityMap disponíveis
Serviço
AdGroupAdService
Entidade
AdGroupAd
Nome da chave
Ad.type
Campo do seletor
AdType
Tipo
Enum
Versão aceita
v201710, v201802
Somente leitura

Define como AD_VARIATION se um ExpandedTextAd é uma variação de anúncio. Para todos os outros tipos de anúncio e para ExpandedTextAds que não são variações de anúncios, essa chave não estará presente no mapa de compatibilidade com versões futuras.

A capacidade de detectar variações de anúncios foi introduzida na v201802. Use este campo para detectar variações de anúncios em versões anteriores da API.

Enviar comentários sobre…

Precisa de ajuda? Acesse nossa página de suporte.