Mapas de compatibilidade com versões futuras

O campo forwardCompatibilityMap permite que você explore funcionalidades de última geração 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.

Receber um exemplo

Veja um exemplo da chamada de um método get() no CampaignService para recuperar a chave Campaign.enhanced do forwardCompatibilityMap. Este exemplo é derivado da nossa biblioteca cliente 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.");
 }

Alteração das propriedades a partir do mapa

A modificação de chaves (como a Campaign.enhanced) por meio do forwardCompatibilityMap não é diferente do que com qualquer outro atributo: basta chamar o método mutate(), verificando se o forwardCompatibilityMap foi preenchido com as chaves e os valores que você deseja 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, pois os nomes incorretos ou indefinidos são ignorados pela API sem acionar alertas e podem causar erros de diagnóstico difícil.

Exemplo de modificação

O exemplo a seguir demonstra como alterar uma campanha para uma campanha avançada enviando a chave Campaign.enhanced com um valor true no forwardCompatibilityMap. Este exemplo é derivado da biblioteca cliente 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);

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.

Enviar comentários sobre…

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