Controle de versões

A API Ad Manager tem versões principais nomeadas e versões compatíveis com versões anteriores no lugar da versão principal atual.

Serviços, métodos e campos podem ser marcados como obsoletos a qualquer momento em uma versão principal (por exemplo, v1), mas vão continuar sendo compatíveis até que essa versão principal seja desativada.

Lançamentos de versões principais

Uma versão principal é definida como uma versão com mudanças de API incompatíveis com versões anteriores. Essas versões vão ter nomes e endpoints de API diferentes. As versões principais anteriores são compatíveis por um período de migração.

A API Ad Manager não tem uma cadência de lançamento regular para versões principais. Novas versões principais só serão lançadas quando necessário.

Versões no local

As mudanças compatíveis com versões anteriores, incluindo novos recursos e correções de bugs, são lançadas na versão principal atual da API. Os clientes precisam processar campos desconhecidos em respostas da API.

Compatibilidade com versões anteriores

A compatibilidade com versões anteriores é mantida para mudanças em uma versão principal. A compatibilidade é definida como:

  1. Compatibilidade de origem: o código escrito em uma versão anterior é compilado em uma versão mais recente e executado com êxito com uma versão mais recente da biblioteca de cliente.

  2. Compatibilidade eletrônica: o código escrito em uma versão anterior se comunica corretamente com um servidor mais recente. Em outras palavras, não apenas as entradas e saídas são compatíveis, mas as expectativas de serialização e desserialização continuam correspondendo.

  3. Compatibilidade semântica: o código escrito em uma versão anterior continua recebendo o que a maioria dos desenvolvedores razoáveis esperaria.

As tabelas a seguir enumeram os tipos de mudanças na API e se elas são consideradas compatíveis com versões anteriores.

Serviços

Tipo de mudança Compatível com versões anteriores
Adicionar um novo serviço Sim
Remover um serviço Não

Métodos

Tipo de mudança Compatível com versões anteriores
Adicionar um novo método Sim
Remover um método Não
Mudar o tipo de solicitação ou resposta de um método Não

Objetos

Tipo de mudança Compatível com versões anteriores
Adicionar um campo obrigatório Não
Adicionar um campo opcional Sim
Mover um campo para dentro ou para fora de uma submensagem Não
Mudar um campo de obrigatório para opcional Sim
Mudar um campo de opcional para obrigatório Não
Remover uma restrição imutável Sim
Adicionar uma restrição imutável Não

Enumerações

Tipo de mudança Compatível com versões anteriores
Adicionar um valor de tipo enumerado Sim
Remover um valor de enumeração Não

Comportamento de campo descontinuado

Campos de substituição

Para campos que têm uma substituição, ambos serão preenchidos quando possível. Ao atualizar, qualquer um dos campos pode ser definido. Incluir os dois campos em uma solicitação de atualização resulta em um erro INVALID_ARGUMENT.

Considere o seguinte esquema:

{
  // The cost of this Foo in micros.
  // Deprecated: Use `cost` instead.
  "costMicros": number,

  // The cost of this Foo.
  "cost": {
    object (Money)
  }
}

Uma resposta de leitura preenche os dois campos com valores equivalentes:

{
  "costMicros": 1250000,
  "cost": {
    "currencyCode": "USD",
    "units": "1",
    "nanos": 250000000
  }
}

As solicitações de atualização podem definir qualquer um dos valores. Incluir os dois campos resulta em um erro INVALID_ARGUMENT:

costMicros 

// Update payload
{
  "costMicros": 1500000
}

// Response payload
{
  "costMicros": 1500000,
  "cost": {
    "currencyCode": "USD",
    "units": "1",
    "nanos": 500000000
  }
}

custo 

// Update payload
{
  "cost": {
    "currencyCode": "USD",
    "units": "1",
    "nanos": 500000000
  }
}

// Response payload
{
  "costMicros": 1500000,
  "cost": {
    "currencyCode": "USD",
    "units": "1",
    "nanos": 500000000
  }
}

Ambos 

// Update payload
{
  "costMicros": 1250000,
  "cost": {
    "currencyCode": "USD",
    "units": "1",
    "nanos": 500000000
  }
}

// Response payload
{
  "error": {
    "code": 400,
    "message": "Request contains an invalid argument.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "costMicros",
            "description": "Cannot update both costMicros and cost."
          }
        ]
      }
    ]
  }
}

Recursos descontinuados

Se um recurso de produto for descontinuado, os campos correspondentes serão marcados como descontinuados e poderão retornar um valor padrão semanticamente apropriado. As atualizações podem ser ignoradas.

{
  // The salesperson split amount in micros.
  // Deprecated: The Sales Management feature has been deprecated. This field
  // will always be `0`.
  "salespersonSplitMicros": number,
}