Migra productos

La API de Merchant presenta una forma más sólida e intuitiva de administrar tus datos de productos. El cambio principal es la separación de los datos de productos en dos recursos distintos: ProductInput para enviar tus datos y Product para ver la versión final procesada, incluidos el estado y los problemas de los productos. Esta nueva estructura proporciona una experiencia más predecible y transparente.

En esta guía, se explican las diferencias clave para ayudarte a migrar tu integración desde la Content API for Shopping. Para obtener una guía detallada sobre cómo usar las nuevas funciones, consulta Administra tus productos.

Diferencias clave

Estos son los cambios más significativos en la forma en que administras los productos en la API de Merchant en comparación con Content API for Shopping:

• Recursos dedicados para los datos de entrada y procesados: La API de Merchant divide la administración de productos en dos recursos. Puedes usar el recurso ProductInput para insertar, actualizar y borrar tus datos de productos. Puedes usar el recurso Product de solo lectura para ver el producto final después de que Google procese tus entradas, aplique reglas y combine datos de fuentes complementarias.

• Codificación para nombres de productos: Puedes usar la codificación base64url sin relleno (RFC 4648, sección 5) para los campos ProductInput.name y Product.name. En caso de que los nombres de los productos contengan caracteres que usa la API de Merchant o caracteres reservados para URLs, la codificación es obligatoria. Por ejemplo, debes codificar los nombres de los productos si contienen alguno de los siguientes caracteres:

  % . + / : ~ , ( * ! ) & ? = @ # $
  

• Estado del producto integrado: Se quita el servicio de productstatuses. Los problemas de validación de productos y los estados de destino ahora se incluyen directamente en el recurso Product dentro del campo productStatus, lo que simplifica la recuperación de datos.

• Actualizaciones de productos predecibles: El nuevo método productInputs.patch modifica directamente una entrada de producto específica. Esta es una mejora significativa con respecto a la Content API for Shopping, en la que las actualizaciones se podían reemplazar de forma inesperada por otras cargas de feeds. En la API de Merchant, una actualización permanece hasta que se vuelve a actualizar o se borra esa entrada de producto específica. Las actualizaciones de productos se aplican al recurso ProductInput en lugar del recurso Product procesado.

• Elige tu fuente de datos para una administración de datos más limpia: Todas las operaciones de escritura de productInputs ahora requieren un parámetro de consulta dataSource, lo que hace explícito qué fuente de datos estás modificando. Esto es especialmente útil si tienes varias fuentes que proporcionan datos.

• Nuevos identificadores de recursos: Ahora los productos se identifican con un recurso RESTful name en lugar del campo id. El formato es accounts/{account}/products/{product}.

• No hay lotes personalizados: El método custombatch ya no está disponible. Puedes usar solicitudes asíncronas o el procesamiento por lotes HTTP para enviar varias solicitudes en una sola llamada HTTP.

Lineamientos para las fuentes de datos durante la migración

Antes de migrar tus fuentes de datos, te recomendamos que elijas tu estrategia de fuentes de datos.

Para garantizar una migración sin problemas y evitar problemas como el robo de ofertas, sigue estas recomendaciones:

• Rellena tu base de datos: En lugar de llamar a dataSources.list antes de cada operación de producto, te recomendamos que realices un reabastecimiento único de tu base de datos local. Agrega un campo de nombre dataSource a cada registro de producto para que puedas proporcionar el identificador correcto directamente en tus solicitudes.

• Consolida y usa fuentes de datos para cualquier etiqueta de fuente de datos y lenguaje: La API de Merchant permite crear una fuente de datos sin especificar la etiqueta de fuente de datos ni el lenguaje y, por lo tanto, permite insertar productos con cualquier etiqueta de fuente de datos y lenguaje de fuente de datos. Considera usar una sola fuente de datos para cualquier etiqueta e idioma.

• Protege tus productos: Si usas reglas de fuentes de datos, llama a products.get para encontrar el dataSource exacto asociado con un producto antes de actualizarlo o borrarlo. Esto garantiza que modifiques la fuente prevista y evita el robo accidental de ofertas.

Solicitudes

En esta sección, se comparan los formatos de solicitud de Content API for Shopping y la API de Merchant.

Descripción de la solicitud	Content API for Shopping	API de Merchant
Obtén un producto	GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}	GET https://merchantapi.googleapis.com/products/v1/accounts/{account}/products/{product}
Enumera productos	GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products	GET https://merchantapi.googleapis.com/products/v1/accounts/{account}/products
Insertar un producto	POST https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products	POST https://merchantapi.googleapis.com/products/v1/accounts/{account}/productInputs:insert
Actualiza un producto	PATCH https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}	PATCH https://merchantapi.googleapis.com/products/v1/accounts/{account}/productInputs/{productinput}
Borrar un producto	DELETE https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}	DELETE https://merchantapi.googleapis.com/products/v1/accounts/{account}/productInputs/{productinput}
Obtén el estado del producto	GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/productstatuses/{productId}	GET https://merchantapi.googleapis.com/products/v1/accounts/{account}/products/{product}
Enumera los estados de los productos	GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/productstatuses	GET https://merchantapi.googleapis.com/products/v1/accounts/{account}/products
Agrupa varias solicitudes por lotes	POST https://shoppingcontent.googleapis.com/content/v2.1/products/custombatch	Usa solicitudes asíncronas o procesamiento por lotes HTTP

Identificadores

El formato de los identificadores de productos cambió en la API de Merchant a un nombre de recurso de REST estándar.

Descripción del identificador	Content API for Shopping	API de Merchant
ID del producto	Es una cadena compuesta por segmentos separados por dos puntos (:). Formato: channel:contentLanguage:targetCountry:offerId o channel:contentLanguage:feedLabel:offerId. Ejemplo: online:en:US:sku123	Es una cadena de recursos de REST name. Formato: accounts/{account}/products/{product}, donde {product} es contentLanguage~feedLabel~offerId. Ejemplo: accounts/12345/products/en~US~sku123. Codificación: Se recomienda la codificación base64url sin relleno y es obligatoria en el caso de los IDs de productos que contienen caracteres que usa la API de Merchant o caracteres reservados para URLs.

Métodos

En esta tabla, se muestran los métodos de Content API for Shopping y sus equivalentes en la API de Merchant.

Método de Content API for Shopping	Método de la API de Merchant	Disponibilidad y notas
products.get	products.get	Recupera el producto final procesado.
products.list	products.list	Enumera los productos finales procesados.
products.insert	productInputs.insert	Inserta una entrada de producto. Se requiere un dataSource.
products.update	productInputs.patch	El comportamiento es significativamente diferente. Actualiza una entrada de producto específica y es persistente.
products.delete	productInputs.delete	Borra una entrada de producto específica. Se requiere un dataSource.
products.custombatch	No disponible	Usa solicitudes asíncronas o procesamiento por lotes HTTP.
productstatuses.get	products.get	Se quita el servicio productstatuses. La información de estado ahora forma parte del recurso Product.
productstatuses.list	products.list	Se quita el servicio productstatuses. La información de estado ahora forma parte del recurso Product.
productstatuses.custombatch	No disponible	Usa solicitudes asíncronas o el procesamiento por lotes HTTP.

Cambios detallados de los campos

En esta tabla, se destacan los campos importantes que se cambiaron, agregaron o quitaron en la API de Merchant.

Content API for Shopping	API de Merchant	Descripción
id	name	El identificador principal de un producto ahora es el recurso de REST name. Se recomienda la codificación base64url sin relleno, que es obligatoria en el caso de los nombres de productos que contienen caracteres que usa la API de Merchant o caracteres reservados para URLs.
Atributos de especificaciones de datos de productos de nivel superior (p.ej., title, price, link)	Objeto productAttributes	Los atributos de producto, como title, price y link, ya no son campos de nivel superior. Ahora se agrupan dentro del objeto productAttributes en los recursos Product y ProductInput. Esto proporciona una estructura de recursos más limpia y organizada.
targetCountry	feedLabel	Ahora, el nombre del recurso usa feedLabel en lugar de targetCountry para alinearse con la funcionalidad de Merchant Center.
feedId	dataSource (parámetro de consulta)	Ahora, el nombre de dataSource es un parámetro de consulta obligatorio para todos los métodos de escritura de productInputs (insert, update y delete).
channel	No disponible. Usa legacy_local para los productos solo locales.	El campo channel ya no está presente en la API de Merchant. En el caso de los productos con el canal LOCAL en Content API for Shopping, se debe establecer el campo legacy_local como verdadero.
No disponible	versionNumber	Es un nuevo campo opcional en ProductInput que se puede usar para evitar inserciones desordenadas en las fuentes de datos principales.
Campos de tipo string con un conjunto de valores definido	Campos de tipo enum con un conjunto de valores definido	Los campos dentro de los atributos de producto con un conjunto definido de valores (por ejemplo, excluded_destinations, availability) ahora son del tipo enum.