Control de versiones

La API de Ad Manager tiene lanzamientos de versiones principales con nombre y lanzamientos locales retrocompatibles con la versión principal actual.

Los servicios, los métodos y los campos se pueden marcar como obsoletos en cualquier momento dentro de una versión principal (p.ej., v1); sin embargo, seguirán siendo compatibles hasta que se retire esa versión principal.

Lanzamientos de versiones principales

Un lanzamiento de versión principal se define como un lanzamiento con cambios en la API que no son retrocompatibles. Estos lanzamientos tendrán nombres y extremos de API diferentes. Las versiones principales anteriores son compatibles durante un período de migración.

La API de Ad Manager no tiene una cadencia de lanzamiento regular para las versiones principales. Las versiones principales nuevas solo se lanzarán cuando sea necesario.

Lanzamientos locales

Los cambios retrocompatibles, incluidas las funciones nuevas y las correcciones de errores, se lanzan de forma local en la versión principal actual de la API. Los clientes deben controlar los campos desconocidos en las respuestas de la API.

Retrocompatibilidad

Se mantiene la retrocompatibilidad para los cambios dentro de una versión principal. La compatibilidad se define de la siguiente manera:

  1. Compatibilidad de fuente: El código escrito en una versión anterior se compila en una versión más reciente y se ejecuta correctamente con una versión más reciente de la biblioteca cliente.

  2. Compatibilidad de conexión: El código escrito en una versión anterior se comunica correctamente con un servidor más reciente. En otras palabras, no solo son compatibles las entradas y las salidas, sino que las expectativas de serialización y deserialización siguen coincidiendo.

  3. Compatibilidad semántica: El código escrito en una versión anterior sigue recibiendo lo que la mayoría de los desarrolladores razonables esperarían.

En las siguientes tablas, se enumeran los tipos de cambios en la API y si se consideran retrocompatibles.

Servicios

Tipo de cambio Retrocompatibilidad
Agrega un servicio nuevo Sí
Quita un servicio No

Métodos

Tipo de cambio Retrocompatibilidad
Agrega un método nuevo Sí
Quita un método No
Cambia el tipo de solicitud o respuesta de un método No

Objetos

Tipo de cambio Retrocompatibilidad
Agrega un campo obligatorio No
Agrega un campo opcional Sí
Mueve un campo dentro o fuera de un submensaje No
Cambia un campo de obligatorio a opcional Sí
Cambia un campo de opcional a obligatorio No
Quita una restricción inmutable Sí
Agrega una restricción inmutable No

Enumeraciones

Tipo de cambio Retrocompatibilidad
Agrega un valor de enum Sí
Quita un valor de enum No

Comportamiento de los campos obsoletos

Campos de reemplazo

En el caso de los campos que tienen un reemplazo, ambos campos se propagarán cuando sea posible. Cuando se actualiza, se puede configurar cualquiera de los campos. Si se incluyen ambos campos en una solicitud de actualización, se produce un error INVALID_ARGUMENT.

Considera el siguiente esquema:

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

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

Una respuesta de lectura propaga ambos campos con valores equivalentes:

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

Las solicitudes de actualización pueden establecer cualquier valor. Si se incluyen ambos campos, se produce un error INVALID_ARGUMENT:

costMicros 

// Update payload
{
  "costMicros": 1500000
}

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

cost 

// 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."
          }
        ]
      }
    ]
  }
}

Funciones discontinuadas

Si se discontinúa una función del producto, los campos correspondientes se marcarán como obsoletos y podrían mostrar un valor predeterminado semánticamente adecuado. Las actualizaciones se pueden ignorar.

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