Migrar da v1 para a v2

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

Migrar seu aplicativo

Migrar da v1 para a v2 exige a atualização dos URLs do endpoint para chamar a v2 e a atualização do aplicativo para considerar as alterações interruptivas.

Atualizar as chamadas de API da v1 para a v2

Para usar a v2 em vez da v1, é preciso atualizar as solicitações para que usem os novos endpoints da v2.

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

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

Para 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 sua configuração para usar a v2.

Faça as alterações necessárias

Lançamos várias alterações interruptivas na v2. Leia as instruções a seguir e faça as alterações necessárias relevantes ao seu 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, tablets agora são segmentados diretamente com a enumeração 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 tipos enumerados são representadas no novo campo assignedTargetingOptionIdAlias nesses recursos AssignedTargetingOption e podem ser usadas ao recuperar ou excluir uma segmentação existente. O valor assignedTargetingOptionId desses recursos AssignedTargetingOption não mudou.

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

  • 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.

• Atualize as chamadas que gerenciam TARGETING_TYPE_PROXIMITY_LOCATION_LIST 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 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 de inventário usando recursos AssignedTargetingOption de TARGETING_TYPE_INVENTORY_SOURCE.

• Os seguintes valores de tipo enumerado 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 permite a definição de itens de linha para gastar o orçamento com base na ativação de acionadores manuais.

Atualizar chamadas para o serviço customBiddingAlgorithms

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

Alterações adicionais

Além das alterações interruptivas listadas acima, a v2 também introduz novos recursos.

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

Acesso somente leitura aos 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 fornece acesso somente leitura, o que significa que todas as tentativas de gravação feitas nesses itens de linha retornarão um erro. Os itens de linha do YouTube terão um destes 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 melhoram a performance

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

• É possível usar advertisers.lineItems.bulkUpdate para definir os mesmos valores de campo para vários itens de linha. No momento, há suporte apenas para atualizações no campo entityStatus.
• É possível usar advertisers.lineItems.bulkEditAssignedTargetingOptions para adicionar ou remover as mesmas opções de segmentação atribuídas em vários itens de linha.
• É possível usar advertisers.lineItems.bulkListAssignedTargetingOptions para listar as opções de segmentação atribuídas em vários itens de linha.
• É possível usar 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 parcial de gravação à segmentação do pedido de inserção

Na v2, é possível editar as configurações de segmentação de um subconjunto 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 do pedido 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