Controle de versões

A API REST do Ad Manager tem os nomes "Versões de versão principais" e lançamentos locais 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

Um lançamento de versão principal é definido como um lançamento incompatível com versões anteriores Mudanças na API. Essas versões serão nomeadas e terão endpoints de API diferentes. As versões principais anteriores são compatíveis durante um período de migração.

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

Lançamentos no local

Foram lançadas mudanças compatíveis com versões anteriores, incluindo novos recursos e correções de bugs. em vigor para a versão atual da API principal. Os clientes precisam lidar com campos desconhecidos nas respostas da 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: código criado com base em 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 mudanças de API e se são consideradas compatível com versões anteriores.

Serviços

Tipo de alteração 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
Como mover um campo para dentro ou para fora de uma submensagem Não
Alterar um campo de obrigatório para opcional Sim
Alterar 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 enumeração Não

Comportamento de campo descontinuado

Campos de substituição

No caso dos campos substitutos, ambos serão preenchidos quando possível. Durante a atualização, qualquer um dos campos pode ser definido. Como incluir ambos os campos em uma atualização vai resultar 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 valor. Incluir os dois campos resulta em uma INVALID_ARGUMENT erro:

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 desativados

Se um recurso do produto for descontinuado, os campos correspondentes serão marcados como descontinuada e pode retornar um valor padrão semanticamente adequado. 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,
}