Controle de versões

A API Ad Manager tem versões principais nomeadas e versões in-place compatíveis com versões anteriores para a versão principal atual.

Serviços, métodos e campos podem ser marcados como descontinuados a qualquer momento em uma A versão principal (por exemplo, v1), porém, permanecerá aceita até que a principal é 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 serão nomeadas e terão endpoints de API diferentes. As versões principais anteriores têm suporte por um período de migração.

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

Lançamentos 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 de API.

Compatibilidade com versões anteriores

A compatibilidade com versões anteriores é mantida para as mudanças feitas nas versões principais. A compatibilidade é definida da seguinte maneira:

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

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

  3. Compatibilidade semântica: o código escrito com base em uma versão anterior continua para receber o que os desenvolvedores mais razoáveis esperam.

As tabelas a seguir enumeram os tipos de alterações de 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 alteração Compatível com versões anteriores
Adicionar um novo método Sim
Remover um método Não
Alterar a solicitação ou o tipo de resposta de um método Não

Objetos

Tipo de alteração 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 alteração Compatível com versões anteriores
Adicionar um valor de tipo enumerado Sim
Remover um valor de tipo enumerado Não

Comportamento de campo descontinuado

Campos de substituição

Para campos que têm uma substituição, ambos os campos serão preenchidos quando possível. Ao atualizar, é possível definir qualquer um dos campos. Como incluir ambos os campos em uma atualização vai resultar em um erro INVALID_ARGUMENT.

Considere o esquema a seguir:

{
  // 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 valor. A inclusão de ambos os campos resulta em um erro INVALID_ARGUMENT:

Micros de custo 

// 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 do 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,
}