Migrar para uma nova versão

Novas versões da API DCM/DFA Reporting and Trafficking são lançadas regularmente. À medida que novas versões são lançadas, as mais antigas são suspensas e, depois de um tempo, desativadas. Quando uma versão é desativada, todas as solicitações dessa versão começam a retornar erros.

Se uma versão da API que você estiver usando for suspensa, será necessário migrar para uma versão mais recente antes da data programada para a desativação. Este guia fornece detalhes sobre como determinar se a versão da API usada está suspensa e apresenta as etapas de migração recomendadas.

Etapa 1: determinar qual versão você está usando

Se você tiver um aplicativo e suspeitar que ele esteja usando uma versão suspensa da API DCM/DFA Reporting and Trafficking, primeiro verifique qual versão específica está sendo usada. Na maioria dos casos, a API é acessada por meio de uma das nossas bibliotecas de cliente específicas para cada linguagem ou por uma integração oficial. As instruções para encontrar a versão da API em uso por essas bibliotecas de cliente e integrações podem ser encontradas abaixo:

Apps Script

As informações de versão do Apps Script são exibidas na caixa de diálogo de serviços avançados:

  1. No editor do Google Apps Script, acesse Recursos > Serviços avançados do Google.
  2. Localize a API DCM/DFA Reporting and Trafficking na lista de serviços disponíveis.
  3. O valor selecionado na lista suspensa é a versão da API DCM/DFA Reporting and Trafficking em uso.

C#

As informações de versão da biblioteca de cliente da Google API para .NET estão expostas nos seguintes locais:

  1. Incluídas no nome do pacote nuget e no namespace de serviço
    Google.Apis.Dfareporting.v3_2
  2. Expostas por uma propriedade pública de DfareportingService
    Console.WriteLine(DfareportingService.Version);

Java

As informações de versão da Biblioteca de Cliente da Google API para Java estão expostas nos seguintes locais:

  1. Especificadas no maven artifactId.
    <dependency>
      <groupId>com.google.apis</groupId>
      <artifactId>google-api-services-dfareporting</artifactId>
      <version>v3.3-rev1-1.21.0</version>
    </dependency>
  2. Incluídas no nome de arquivo JAR
    google-api-services-dfareporting-v3.3-rev1-1.21.0.jar
  3. Expostas por uma propriedade pública de Dfareporting
    System.out.println(Dfareporting.DEFAULT_SERVICE_PATH);

PHP

As informações de versão da biblioteca de cliente da API do Google para PHP estão expostas por uma propriedade pública de Google_Client_Dfareporting:

$service = new Google_Client_Dfareporting($client)
print $service->version;

Python

A biblioteca de cliente da Google API para Python não recebe uma versão. A versão da API a ser usada é especificada como um argumento para o gerador de descobertas:

discovery.build('dfareporting', 'v3.3', http=http)

Ruby

A biblioteca de cliente da Google API versões Ruby < 0.9 não recebe versões. A versão da API a ser usada é especificada como um argumento para o gerador de serviços:

service = Google::APIClient::Service.new("dfareporting", "v3.3",
    {
      :application_name => "My application",
      :application_version => '1.0.0',
      :authorization => authorization
    }
)

No caso da biblioteca de cliente da Google API para versões Ruby >= 0.9, a versão é exposta no namespace de serviço:

Google.Apis.DfareportingV3_2

Anote a versão que você está usando, porque essa informação será necessária mais tarde.

Etapa 2: determinar o status da sua versão

A Programação de suspensão lista o status de todas as versões atualmente compatíveis. Encontre sua versão nessa lista e determine o status dela da seguinte maneira:

  1. Se não houver datas listadas nas colunas Data de suspensão e Data de desativação, significa que você está usando uma versão totalmente compatível.
  2. Se as datas estiverem listadas, significa que a versão usada está atualmente suspensa e será desativada na data especificada.
  3. Se sua versão não estiver listada, significa que ela já foi desativada e não é mais compatível.

Se o seu caso for o 2 ou 3 acima, será necessário migrar para uma versão mais recente a fim de evitar uma interrupção no serviço. É recomendável que você migre para a versão mais recente, que está listada na parte superior da tabela da programação de suspensão (excluindo versões Beta). Isso possibilitará a você o máximo de tempo entre upgrades.

Etapa 3: upgrade de versões

Após determinar a necessidade de fazer a migração, a próxima etapa é atualizar sua integração ou conseguir uma compilação atualizada da biblioteca de cliente que você prefere. Algumas bibliotecas de cliente fornecem somente uma versão que funciona com qualquer versão da API. No entanto, outras têm versões separadas para cada versão. A lista abaixo fornece informações gerais de upgrade para as bibliotecas de cliente e integrações mais usadas.

Apps Script

O Google Apps Script é compatível com todas as versões da API DCM/DFA Reporting and Trafficking e permite selecionar a versão usada em cada script. Para alterar a versão usada por um script específico:

  1. No editor do Google Apps Script, acesse Recursos > Serviços avançados do Google.
  2. Localize a API DCM/DFA Reporting and Trafficking na lista de serviços disponíveis.
  3. Altere a versão da API DCM/DFA Reporting and Trafficking em uso no menu suspenso de versões.
  4. Clique em OK para salvar as alterações.

C#

A biblioteca de cliente da API do Google para .NET fornece versões separadas para cada versão da API DCM/DFA Reporting and Trafficking, distribuída por meio do Nuget.

Para receber instruções de instalação detalhadas ou opções alternativas de download, consulte a documentação da biblioteca de cliente.

Java

A biblioteca de cliente da API do Google para Java fornece versões separadas para cada versão da API DCM/DFA Reporting and Trafficking, distribuída pelo Maven.

Para receber instruções de instalação detalhadas ou opções alternativas de download, consulte a documentação da biblioteca de cliente.

PHP

A biblioteca de cliente da API do Google para PHP fornece versões separadas para cada versão da API DCM/DFA Reporting and Trafficking, distribuída por meio do Packagist.

Para receber instruções de instalação detalhadas ou opções alternativas de download, consulte a documentação da biblioteca de cliente.

Python

Cada versão da biblioteca de cliente da Google API para Python é compatível com todas as versões da API de relatórios e tráfego do DCM/DFA. Basta atualizar a string da versão sendo enviada como um argumento para o criador de descobertas:

discovery.build('dfareporting', 'v3.3', http=http)
Para receber instruções de instalação detalhadas ou opções alternativas de download, consulte a documentação da biblioteca de cliente.

Ruby

A biblioteca de cliente da Google API para Ruby v0.8 e inferiores é compatível com todas as versões da API de relatórios e tráfego do DCM/DFA. Basta atualizar a string da versão sendo enviada como um argumento para o criador de serviços:

service = Google::APIClient::Service.new("dfareporting", "v3.3",
    {
      :application_name => "My application",
      :application_version => '1.0.0',
      :authorization => authorization
    }
)
A biblioteca de cliente da API do Google para Ruby v0.9+ fornece versões separadas para cada versão da API DCM/DFA Reporting and Trafficking, distribuídas por meio do RubyGems. Para receber instruções de instalação detalhadas ou opções alternativas de download, consulte a documentação da biblioteca de cliente.

Etapa 4: resolver diferenças de versão

Nós nos esforçamos para tornar nossos lançamentos compatíveis com versões anteriores, o que significa que a migração entre versões de API não exigirá alterações no seu código. Quando isso não for possível, anunciaremos as mudanças que exigem alguma ação dos desenvolvedores (também conhecidas como alterações interruptivas) nas notas da versão.

Nesse ponto, você deve revisar nossas notas da versão, começando com a versão posterior àquela pela qual você iniciou (que você anotou em uma seção anterior) e continuando até a versão para a qual você está atualizando. As seções das notas da versão devem ser interpretadas da seguinte maneira:

  • Novos recursos: são funcionalidades adicionadas recentemente.
  • Desativações – funcionalidades removidas da API. Quando disponível, a funcionalidade de substituição será abordada nessa seção.
  • Problemas conhecidos: são alterações que não são adições nem remoções. Por exemplo, essa seção pode abordar campos ou métodos que foram renomeados ou lógica de validação que foi alterada.

As funcionalidades em Novos recursos não exigem alterações de código e podem ser ignoradas por enquanto. Volte a essa seção mais tarde se quiser testar algo que adicionamos.

Porém, se você encontrar alterações nas seções Desativações ou Problemas conhecidos, talvez seja necessário realizar alguma ação. Pesquise seu código para determinar se alguma das funcionalidades removidas ou modificadas é usada pelo seu aplicativo. Se for esse o caso, será necessário atualizar seu código para solucionar essas alterações.

Mantenha-se informado

Como mencionado anteriormente, os lançamentos e as desativações da API de relatórios e tráfego do DCM/DFA ocorrem regularmente. Atualizações sobre novas versões, suspensões e desativações são lançadas nos seguintes canais:

Recomendamos que você se inscreva em um ou mais desses canais para receber as últimas notícias sobre as APIs.