Migrar da v1 para a v2

Última atualização: 06/12/2022

Migrar seu aplicativo

A migração da v1 para a v2 requer a atualização dos URLs de endpoint para chamar a v2 e atualização do aplicativo para considerar as mudanças importantes.

Atualizar as chamadas de API da v1 para a v2

Para usar a v2 em vez da v1, atualize suas solicitações para usar os novos endpoints v2.

Por exemplo, para chamar o método advertisers.get com v1, use este URL:

GET https://displayvideo.googleapis.com/v1/advertisers/advertiserId

Para a v2, atualize o URL para o seguinte:

GET https://displayvideo.googleapis.com/v2/advertisers/advertiserId

Se você estiver usando uma biblioteca de cliente para fazer solicitações à API, use a versão mais recente da biblioteca de cliente e atualize a configuração para usar a v2.

Faça as alterações necessárias

Estamos introduzindo várias mudanças interruptivas na v2. Leia as instruções a seguir e faça as mudanças necessárias para o uso atual da API Display & Video 360.

Atualizar chamadas para métodos de segmentação

• Alguns tipos de segmentação agora são atribuídos usando valores de tipo enumerado em vez de IDs de opção de segmentação. Por exemplo, os dispositivos tablet agora são segmentados diretamente com o enum DEVICE_TYPE_TABLET DeviceType, em vez do ID da opção de segmentação do serviço targetingTypes.targetingOptions. As versões de string desses enums são representadas no novo campo assignedTargetingOptionIdAlias nesses recursos AssignedTargetingOption e podem ser usadas ao recuperar ou excluir a segmentação atual. O valor assignedTargetingOptionId desses recursos AssignedTargetingOption não mudou.

  Atualize as chamadas que gerenciam os seguintes tipos de segmentação para usar valores de tipo enumerado:

  • TARGETING_TYPE_AGE_RANGE
  • TARGETING_TYPE_CONTENT_INSTREAM_POSITION
  • TARGETING_TYPE_CONTENT_OUTSTREAM_POSITION
  • TARGETING_TYPE_DEVICE_TYPE
  • TARGETING_TYPE_DIGITAL_CONTENT_LABEL_EXCLUSION
  • TARGETING_TYPE_ENVIRONMENT
  • TARGETING_TYPE_EXCHANGE
  • TARGETING_TYPE_GENDER
  • TARGETING_TYPE_HOUSEHOLD_INCOME
  • TARGETING_TYPE_NATIVE_CONTENT_POSITION
  • TARGETING_TYPE_OMID
  • TARGETING_TYPE_PARENTAL_STATUS
  • TARGETING_TYPE_SENSITIVE_CATEGORY_EXCLUSION
  • TARGETING_TYPE_VIDEO_PLAYER_SIZE
  • TARGETING_TYPE_VIEWABILITY

• O método advertisers.lineItems.bulkEditLineItemAssignedTargetingOptions foi substituído pelo método advertisers.lineItems.bulkEditAssignedTargetingOptions.

• O método advertisers.lineItems.bulkListLineItemAssignedTargetingOptions foi substituído pelo método advertisers.lineItems.bulkListAssignedTargetingOptions.

• As chamadas que gerenciam TARGETING_TYPE_PROXIMITY_LOCATION_LIST foram atualizadas para usar um tamanho de raio e uma unidade de distância definidos em vez de um valor de tipo enumerado ProximityRadiusRange.

• Os métodos de segmentação que recuperam ou editam opções de segmentação em vários tipos de segmentação em um único recurso pai foram renomeados.

  Atualize as chamadas para os seguintes métodos para usar os novos nomes:

  • advertisers.bulkEditAdvertiserAssignedTargetingOptions para advertisers.editAssignedTargetingOptions
  • advertisers.bulkListAdvertiserAssignedTargetingOptions para advertisers.listAssignedTargetingOptions
  • advertisers.campaigns.bulkListCampaignAssignedTargetingOptions para advertisers.campaigns.listAssignedTargetingOptions
  • advertisers.insertionOrders.bulkListInsertionOrderAssignedTargetingOptions para advertisers.insertionOrders.listAssignedTargetingOptions
  • partners.bulkEditPartnerAssignedTargetingOptions para partners.editAssignedTargetingOptions

Atualizar chamadas para o serviço advertisers.lineItems

• O campo inventorySourceIds foi removido. Gerencie a atribuição da origem do inventário usando recursos AssignedTargetingOption de TARGETING_TYPE_INVENTORY_SOURCE.

• Os seguintes valores de enumeração LineItemWarningMessage foram descontinuados na v2 e não serão mais exibidos em LineItem.warningMessages:

  • NO_POSITIVE_AUDIENCE_LIST_TARGETED
  • APP_INSTALL_NO_CONVERSION_PIXEL
  • TARGETING_REVOKED_OR_CLOSED_USER_LIST
  • APP_INSTALL_NO_OPTIMAL_BIDDING_STRATEGY
  • CREATIVE_SIZE_NOT_IN_USE_FOR_TARGETED_DEALS
  • NO_CREATIVE_FOR_TARGETED_DEALS
  • TARGETING_DEPRECATED_GEO_TARGET

• O campo triggerId foi removido do objeto LineItemFlight, e o valor LINE_ITEM_FLIGHT_DATE_TYPE_TRIGGER foi removido do tipo de enumeração LineItemFlightDateType. A v2 não oferece suporte para definir itens de linha a serem gastos com base na ativação de gatilhos manuais.

Atualizar chamadas para o serviço customBiddingAlgorithms

Os campos customBiddingAlgorithmState e modelReadiness foram substituídos pelo campo modelDetails , que fornece os estados de preparação e suspensão do modelo de algoritmo para cada anunciante que tem acesso por uma lista de objetos CustomBiddingModelDetails.

Alterações adicionais

Além das mudanças interruptivas listadas acima, a v2 também apresenta novos recursos.

Os recursos adicionados à v2 após o lançamento inicial podem ser encontrados nas notas da versão.

Acesso somente leitura a itens de linha do YouTube

Na v2, os itens de linha do YouTube e as configurações de segmentação deles podem ser recuperados usando os serviços advertisers.lineItems e advertisers.lineItems.targetingTypes.assignedTargetingOptions, respectivamente. A API oferece acesso somente leitura, o que significa que qualquer tentativa de gravação feita nesses itens de linha vai retornar um erro. Os itens de linha do YouTube serão de um dos seguintes valores de LineItemType:

• LINE_ITEM_TYPE_YOUTUBE_AND_PARTNERS_ACTION
• LINE_ITEM_TYPE_YOUTUBE_AND_PARTNERS_AUDIO
• LINE_ITEM_TYPE_YOUTUBE_AND_PARTNERS_NON_SKIPPABLE
• LINE_ITEM_TYPE_YOUTUBE_AND_PARTNERS_NON_SKIPPABLE_OVER_THE_TOP
• LINE_ITEM_TYPE_YOUTUBE_AND_PARTNERS_REACH
• LINE_ITEM_TYPE_YOUTUBE_AND_PARTNERS_REACH_OVER_THE_TOP
• LINE_ITEM_TYPE_YOUTUBE_AND_PARTNERS_SIMPLE
• LINE_ITEM_TYPE_YOUTUBE_AND_PARTNERS_SIMPLE_OVER_THE_TOP
• LINE_ITEM_TYPE_YOUTUBE_AND_PARTNERS_VIDEO_SEQUENCE

Novos métodos que permitem um melhor desempenho

Na v2, o serviço advertisers.lineItems oferece novos métodos para usar em vez de solicitações em lote para melhorar o desempenho e reduzir o consumo de cota:

• Use advertisers.lineItems.bulkUpdate para definir os mesmos valores de campo para vários itens de linha. No momento, só é possível atualizar o campo entityStatus.
• Use advertisers.lineItems.bulkEditAssignedTargetingOptions para adicionar ou remover as mesmas opções de segmentação atribuídas em vários itens de linha.
• Use advertisers.lineItems.bulkListAssignedTargetingOptions para listar as opções de segmentação atribuídas em vários itens de linha.
• Use advertisers.lineItems.duplicate para criar uma cópia de um item de linha existente no mesmo pedido de inserção, copiando todas as configurações e definições de segmentação.

Acesso de gravação parcial para segmentação de pedidos de inserção

Na v2, é possível editar as configurações de segmentação de subconjuntos para recursos InsertionOrder usando os novos métodos create e delete no serviço advertisers.insertionOrders.targetingTypes.assignedTargetingOptions. Os seguintes tipos de segmentação podem ser totalmente gerenciados no nível da ordem de inserção:

• TARGETING_TYPE_AGE_RANGE
• TARGETING_TYPE_BROWSER
• TARGETING_TYPE_CATEGORY
• TARGETING_TYPE_CHANNEL
• TARGETING_TYPE_DEVICE_MAKE_MODEL
• TARGETING_TYPE_DIGITAL_CONTENT_LABEL_EXCLUSION
• TARGETING_TYPE_ENVIRONMENT
• TARGETING_TYPE_GENDER
• TARGETING_TYPE_KEYWORD
• TARGETING_TYPE_LANGUAGE
• TARGETING_TYPE_NEGATIVE_KEYWORD_LIST
• TARGETING_TYPE_OPERATING_SYSTEM
• TARGETING_TYPE_PARENTAL_STATUS
• TARGETING_TYPE_SENSITIVE_CATEGORY_EXCLUSION
• TARGETING_TYPE_VIEWABILITY