Migrar da API Bid Manager v1.1 para a v2

Em março de 2022, lançamos a versão 2 da API Bid Manager. Com o lançamento dessa nova versão, planejamos anunciar em breve uma data de desativação para a v1.1. Recomendamos que você inicie a migração da v1.1 para a v2 assim que possível.

Migrar o aplicativo

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

Atualizar as chamadas de API da v1.1 para a v2

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

Identificar métodos equivalentes

Para atualizar suas chamadas de API da v1.1 para a v2, primeiro identifique os métodos equivalentes da v1.1 na v2.

Os nomes a seguir de todos os serviços e métodos mudaram um pouco entre v1.1 e v2:

• Os serviços Queries e Reports na v1.1 são conhecidos como queries e queries.reports na v2.
• Os métodos foram renomeados da seguinte forma na v2:

  Nome do método da v1.1	Método equivalente da v2
  Queries.createquery	queries.create
  Queries.deletequery	queries.delete
  Queries.getquery	queries.get
  Queries.listqueries	queries.list
  Queries.runquery	queries.run
  Reports.listreports	queries.reports.list

Atualizar para novos endpoints

Depois de identificar os métodos equivalentes, atualize suas solicitações. Por exemplo, para chamar o método queries.getquery com a v1.1, use o seguinte URL:

https://www.googleapis.com/doubleclickbidmanager/v1.1/query/queryId

Para chamar o método equivalente na v2, conhecido como queries.get, atualize o URL para o seguinte:

GET https://doubleclickbidmanager.googleapis.com/v2/queries/queryId

Se você estiver usando uma biblioteca de cliente para fazer solicitações à API, use a versão mais recente da biblioteca e atualize sua 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 relevantes para seu uso atual da API Bid Manager.

Atualizar chamadas para o serviço queries

• Os seguintes campos no recurso Query, originalmente representados por objetos aninhados gerais, foram alterados para usar os seguintes tipos de objetos:

  Campo v1.1	Tipo de objeto equivalente da v2
  metadata	QueryMetadata
  params	Parameters
  params.options	Options
  params.options.pathQueryOptions	Removido
  params.options.pathQueryOptions.channelGrouping	Removido
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter	Removido
  params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter	Removido
  schedule	QuerySchedule

• Os seguintes campos no recurso Query, originalmente representados por objetos de lista geral, foram alterados para listas dos seguintes novos tipos de objetos:

  Campo de lista v1.1	Tipo de objeto v2
  params.filters[]	FilterPair
  params.options.pathQueryOptions.channelGrouping.rules[]	Removido
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[]	Removido
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[]	Removido
  params.options.pathQueryOptions.pathFilters[]	Removido
  params.options.pathQueryOptions.pathFilters[].eventFilters[]	Removido

• Os seguintes campos no recurso Query, originalmente representados por strings, são representados por tipos de enumeração na v2 e incluem as seguintes mudanças:
  • O equivalente da v2 de metadata.dataRange agora usa a enumeração Range. Ao converter para esse enum, o valor PREVIOUS_HALF_MONTH foi removido, e o valor TYPE_NOT_SUPPORTED foi alterado para RANGE_UNSPECIFIED.
  • O metadata.format agora usa a enumeração Format. Ao converter para esse tipo enumerado, o valor EXCEL_CSV foi removido e o valor FORMAT_UNSPECIFIED foi adicionado.
  • params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter.match e params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter.match agora usam a enumeração Match.
  • params.options.pathQueryOptions.pathFilters[].pathMatchPosition agora usa a enumeração PathMatchPosition. Ao converter para essa enumeração, o valor PATH_MATCH_POSITION_UNSPECIFIED foi adicionado.
  • O schedule.frequency agora usa a enumeração Frequency. Ao converter para essa enumeração, o valor FREQUENCY_UNSPECIFIED foi adicionado.
  • O params.type agora usa a enumeração ReportType. Ao converter para essa enumeração, as seguintes mudanças foram feitas:
  • Os seguintes valores foram descontinuados:
    • TYPE_ACTIVE_GRP
    • TYPE_AUDIENCE_PERFORMANCE
    • TYPE_CLIENT_SAFE
    • TYPE_COMSCORE_VCE
    • TYPE_CROSS_FEE
    • TYPE_CROSS_PARTNER
    • TYPE_CROSS_PARTNER_THIRD_PARTY_DATA_PROVIDER
    • TYPE_ESTIMATED_CONVERSION
    • TYPE_FEE
    • TYPE_KEYWORD
    • TYPE_LINEAR_TV_SEARCH_LIFT
    • TYPE_NIELSEN_AUDIENCE_PROFILE
    • TYPE_NIELSEN_DAILY_REACH_BUILD
    • TYPE_NIELSEN_ONLINE_GLOBAL_MARKET
    • TYPE_PAGE_CATEGORY
    • TYPE_PETRA_NIELSEN_DAILY_REACH_BUILD
    • TYPE_PETRA_NIELSEN_ONLINE_GLOBAL_MARKET
    • TYPE_PIXEL_LOAD
    • TYPE_THIRD_PARTY_DATA_PROVIDER
    • TYPE_TRUEVIEW_IAR
    • TYPE_VERIFICATION
    • TYPE_YOUTUBE_VERTICAL
  • Os valores restantes foram atualizados para refletir melhor os valores equivalentes na interface:

    Valores da v1.1	Valor ReportType equivalente
    TYPE_NOT_SUPPORTED	REPORT_TYPE_UNSPECIFIED
    TYPE_GENERAL	STANDARD
    TYPE_INVENTORY_AVAILABILITY	INVENTORY_AVAILABILITY
    TYPE_AUDIENCE_COMPOSITION	AUDIENCE_COMPOSITION
    TYPE_ORDER_ID	FLOODLIGHT
    TYPE_TRUEVIEW	YOUTUBE
    TYPE_NIELSEN_SITE	GRP
    TYPE_PETRA_NIELSEN_AUDIENCE_PROFILE	YOUTUBE_PROGRAMMATIC_GUARANTEED
    TYPE_REACH_AND_FREQUENCY	REACH
    TYPE_REACH_AUDIENCE	UNIQUE_REACH_AUDIENCE
    TYPE_PATH	FULL_PATH
    TYPE_PATH_ATTRIBUTION	PATH_ATTRIBUTION

• Os campos metadata.dataRange, reportDataStartTimeMs e reportDataEndTimeMs foram substituídos por range, customStartDate e customEndDate. Os novos campos de data usam objetos Date em vez de milissegundos desde a época Unix. Esses campos de substituição foram movidos para o objeto DataRange atribuído ao campo dataRange no objeto QueryMetadata.
• Os campos schedule.startTimeMs e schedule.endTimeMs foram substituídos por startDate e endDate no objeto QuerySchedule. Os novos campos de data usam objetos Date em vez de milissegundos desde a época Unix.
• Os campos metadata.running, metadata.reportCount, metadata.googleCloudStoragePathForLatestReport, metadata.googleDrivePathForLatestReport e metadata.latestReportRunTimeMs foram removidos. Em vez disso, as informações sobre os relatórios gerados mais recentemente de uma consulta devem ser recuperadas usando o método queries.reports.list com o parâmetro de consulta orderBy de "key.reportId desc" para garantir que a solicitação liste os relatórios mais recentes primeiro.
• Os campos kind, timezoneCode, metadata.locale, params.includeInviteData e schedule.nextRunMinuteOfDay foram removidos.
• O queries.create não executa mais consultas automaticamente após a criação, e o parâmetro de consulta asynchronous foi removido. Chame queries.run depois de queries.create para gerar relatórios de novas consultas.
• O método queries.run foi atualizado das seguintes maneiras:
  • O parâmetro de consulta asynchronous foi substituído pelo parâmetro synchronous. O novo parâmetro de consulta opera com lógica inversa e é considerado falso se não for especificado. Por isso, o queries.run gera relatórios de forma assíncrona por padrão na v2, ao contrário da v1.1, em que a geração é síncrona.
  • O corpo da solicitação foi atualizado para remover o campo timezoneCode e substituir os campos dataRange, reportDataStartTimeMs e reportDataEndTimeMs por um objeto DataRange atribuído ao campo dataRange.
  • O método retorna o objeto Report resultante em vez de um corpo de resposta vazio.
• O campo kind no corpo da resposta queries.list foi removido.

Atualizar chamadas para o serviço reports

• Os seguintes campos no recurso Report, originalmente representados por objetos aninhados gerais, foram alterados para usar os seguintes tipos de objeto:

  Campo v1.1	Tipo de objeto equivalente da v2
  key	ReportKey
  metadata	ReportMetadata
  metadata.status	ReportStatus
  params	Parameters
  params.options	Options
  params.options.pathQueryOptions	Removido
  params.options.pathQueryOptions.channelGrouping	Removido
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter	Removido
  params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter	Removido

• Os seguintes campos no recurso Report, originalmente representados por objetos de lista geral, foram alterados para listas dos seguintes novos tipos de objetos:

  Campo de lista v1.1	Tipo de objeto v2
  params.filters[]	FilterPair
  params.options.pathQueryOptions.channelGrouping.rules[]	Removido
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[]	Removido
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[]	Removido
  params.options.pathQueryOptions.pathFilters[]	Removido
  params.options.pathQueryOptions.pathFilters[].eventFilters[]	Removido

• Os campos a seguir no recurso Report originalmente representados por strings mudaram para que os campos equivalentes na v2 sejam representados por novos tipos de enumeração e incluam mudanças nos valores aceitáveis:
  • O metadata.status.format agora usa a enumeração Format. Ao converter para essa enumeração, o valor EXCEL_CSV foi removido e FORMAT_UNSPECIFIED foi adicionado.
  • O metadata.status.state agora usa a enumeração State. Ao converter para esse enum, os valores QUEUED e STATE_UNSPECIFIED foram adicionados.
  • params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter.match e params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter.match agora usam a enumeração Match.
  • params.options.pathQueryOptions.pathFilters[].pathMatchPosition agora usa a enumeração PathMatchPosition. Ao converter para essa enumeração, o valor PATH_MATCH_POSITION_UNSPECIFIED foi adicionado.
  • O params.type agora usa a enumeração ReportType. Ao converter para essa enumeração, várias mudanças foram feitas e estão listadas em detalhe na seção anterior sobre a atualização das chamadas de serviço de consultas.
• Os campos metadata.reportDataStartTimeMs e metadata.reportDataEndTimeMs foram substituídos pelos campos reportDataStartDate e reportDataEndDate no objeto ReportMetadata. Os novos campos usam objetos Date em vez de milissegundos desde a era Unix.
• metadata.status.finishTimeMs foi substituído pelo campo finishTime no objeto ReportStatus. Esse novo campo de hora representa a data e hora como um carimbo de data/hora no formato UTC "Zulu" RFC3339, em vez de milissegundos desde a época Unix.
• Os campos metadata.status.failure e params.includeInviteData foram removidos.
• O campo kind no corpo da resposta reports.list foi removido.

Atualizar a lógica de tratamento de erros

As mensagens de erro em toda a API foram atualizadas na v2. Essas novas mensagens de erro são mais específicas e, em alguns casos, fornecem informações sobre os valores na solicitação de API que estão causando o retorno do erro. Se a lógica de tratamento de erros atual depender de um texto específico de mensagem de erro, generalize o tratamento de erros antes de migrar para a v2.