Control de versiones

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

Los servicios, métodos y campos podrían marcarse como obsoletos en cualquier momento dentro de un la versión principal (por ejemplo, v1); sin embargo, seguirán siendo compatibles hasta esa versión principal está retirada.

Lanzamientos de las 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 REST de Ad Manager no tiene una cadencia de lanzamiento regular para las versiones. Las nuevas versiones principales solo se lanzarán cuando sea necesario.

Versiones locales

Lanzamiento de cambios retrocompatibles, incluidas nuevas funciones y correcciones de errores. a la versión actual de la API principal. Los clientes deben procesar 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 con fuentes: código escrito en compilaciones de versiones anteriores con una versión más reciente y se ejecuta correctamente con una versión más reciente del biblioteca cliente.

  2. Compatibilidad con cables: código escrito en función de una versión anterior se comunica correctamente con un servidor más nuevo. En otras palabras, las entradas y salidas compatibles, pero las expectativas de serialización y deserialización seguirán coincidiendo.

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

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

Servicios

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

Métodos

Tipo de cambio Retrocompatibilidad
Agregar un método nuevo Sí
Quita un método No
Cambia la solicitud o el tipo de 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
Cómo cambiar un campo de obligatorio a opcional Sí
Cómo cambiar 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 enumeración Sí
Quita un valor de enumeración No

Comportamiento de campo obsoleto

Campos de reemplazo

En el caso de los campos que tienen un reemplazo, ambos se propagarán cuando sea posible. Durante la actualización, se puede configurar cualquier campo. Incluye ambos campos en una actualización solicitud da como resultado 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. Incluir ambos campos da como resultado 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 una función de producto está descontinuada, los campos correspondientes se marcarán como obsoleto y puede mostrar un valor predeterminado adecuado a nivel semántico. 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,
}