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, incluido el estado y los problemas del producto. 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 Content API for Shopping. Si deseas obtener una guía detallada para usar las funciones nuevas, 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 datos de entrada y procesados: La API de Merchant divide la administración de productos en dos recursos. Puedes usar el ProductInput recurso para insertar, actualizar y borrar los datos de tus 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 (sección 5 de RFC 4648) 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 URL, 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 quitó el servicio productstatuses. Los problemas de validación de productos y los estados de destino ahora se incluyen directamente en el Product recurso dentro del productStatus campo, lo que simplifica la recuperación de datos.

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

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

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

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

Sugerencia: Mejora la capacidad de procesamiento con grupos de canales: Configura un grupo de canales para maximizar la capacidad de procesamiento de las operaciones masivas. Esto omite el límite típico de 100 transmisiones de un solo canal de gRPC mediante la administración de varias conexiones subyacentes. Para obtener más información, consulta Refactoriza el código para solicitudes simultáneas: Mejora la capacidad de procesamiento con grupos de canales

Lineamientos para la fuente de datos durante la migración

Término clave: El "robo de ofertas" se produce cuando un producto identificado por su clave única (language, feedlabel, offerID) se inserta en una fuente de datos principal diferente de la que pertenece. Esto borra el producto de la fuente anterior y lo mueve a la nueva, donde se pueden aplicar diferentes reglas de fuente de datos y parámetros de configuración de propiedad. Si bien el robo se puede usar de forma intencional para reorganizar los productos, puede ocurrir de forma accidental si se proporciona un dataSource incorrecto durante la inserción.

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

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

• Realiza una carga inicial de tu base de datos: En lugar de llamar a dataSources.list antes de cada operación de producto, te recomendamos que realices una carga inicial única 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 y lenguaje: La API de Merchant permite crear una fuente de datos sin especificar la etiqueta y el lenguaje, y, por lo tanto, permite insertar productos con cualquier etiqueta y lenguaje de fuente de datos. Considera usar una sola fuente de datos para cualquier etiqueta y lenguaje.

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

Nota: Asegúrate de usar el mismo offerId para el mismo producto cuando llames a la API de Merchant como lo hiciste con Content API for Shopping para evitar perder el historial de tus productos. Consulta también la sección Identificadores en esta página.

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	POST https://shoppingcontent.googleapis.com/content/v2.1/products/custombatch	Usa solicitudes asíncronas o lotes HTTP

Identificadores

El formato de los identificadores de productos cambió en la API de Merchant a un nombre de recurso 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	Una cadena name de recursos REST. 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 ID de productos que contienen caracteres que usa la API de Merchant o caracteres reservados para URL.

Nota: El campo channel ya no está presente en la API de Merchant. Los productos con el canal LOCAL en Content API for Shopping deben establecer el campo legacy_local en verdadero.

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. 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. Requiere un dataSource.
products.custombatch	No disponible	Usa solicitudes asíncronas o lotes HTTP.
productstatuses.get	products.get	Se quitó el servicio productstatuses. La información de estado ahora forma parte del recurso Product.
productstatuses.list	products.list	Se quitó el servicio productstatuses. La información de estado ahora forma parte del recurso Product.
productstatuses.custombatch	No disponible	Usa solicitudes asíncronas o lotes HTTP.

Cambios detallados en 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 name de recursos REST. Se recomienda la codificación base64url sin relleno y es obligatoria en el caso de los nombres de productos que contienen caracteres que usa la API de Merchant o caracteres reservados para URL.
Atributos de especificación de datos de productos de nivel superior (p.ej., title, price, link)	Objeto productAttributes	Los atributos de productos 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 clara y organizada.
targetCountry	feedLabel	El nombre del recurso ahora usa feedLabel en lugar de targetCountry para alinearse con la funcionalidad de Merchant Center.
feedId	dataSource (parámetro de consulta)	Un nombre dataSource ahora es un parámetro de consulta obligatorio para todos los métodos de escritura de productInputs (insert, update, delete).
channel	No disponible. Usa legacy_local solo para productos locales.	El campo channel ya no está presente en la API de Merchant. Los productos con el canal LOCAL en Content API for Shopping deben establecer el campo legacy_local en verdadero.
No disponible	versionNumber	Un nuevo campo opcional en ProductInput que se puede usar para evitar inserciones desordenadas en 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 productos con un conjunto de valores definido (por ejemplo, excluded_destinations, availability) ahora son de tipo enum.