Control de versiones

La API de Ad Manager tiene lanzamientos de versiones principales con nombre versiones locales retrocompatibles a 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

Una versión principal se define como una versión con incompatibilidad con versiones anteriores Cambios en la API Estas versiones tendrán un nombre y tendrán diferentes extremos de la API. Las versiones principales anteriores son compatibles con un período de migración.

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

Lanzamientos in situ

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

Retrocompatibilidad

La retrocompatibilidad se mantiene 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 para 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 con cables: código escrito en función de una versión anterior se comunique correctamente con un servidor más nuevo. En otras palabras, no solo las entradas y las salidas son compatibles, 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 de 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 Retrocompatible
Agregar un método nuevo Sí
Cómo quitar 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í
Mover un campo hacia o fuera de un submensaje No
Cambia un campo de obligatorio a opcional Sí
Cambia un campo de opcional a obligatorio No
Cómo quitar una restricción inmutable Sí
Cómo agregar una restricción inmutable No

Enumeraciones

Tipo de cambio Retrocompatibilidad
Agrega un valor de enumeración Sí
Cómo quitar un valor de enumeración No

Comportamiento de los campos obsoletos

Campos de reemplazo

En el caso de los campos que tienen un reemplazo, se propagarán ambos campos cuando sea posible. Durante la actualización, se puede configurar cualquier campo. Si incluyes ambos campos en una solicitud de actualización, se genera 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 cualquiera de los valores. Si incluyes ambos campos, se genera un error INVALID_ARGUMENT:

costMicros 

// Update payload
{
  "costMicros": 1500000
}

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

costo 

// 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 descontinuadas

Si se descontinua una función de un producto, los campos correspondientes se marcarán como obsoletos y pueden mostrar un valor predeterminado semánticamente adecuado. Se pueden ignorar las actualizaciones.

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