Los Anuncios de Servicios Locales (ASL) se asocian con agregadores para mostrar sus fichas (o proveedores) en Google.com. En esta guía, se describe cómo los agregadores pueden proporcionar datos estructurados de los ASL sobre sus proveedores. Específicamente, documentamos el conjunto de extremos de API que los agregadores deben implementar para integrarse con las LSA.
Glosario
Agregador (o socio): Son los socios que agregan proveedores a los que les brindan servicios y cuyos datos se pueden proporcionar a la LSA.
Proveedor externo (o ficha): Son las pequeñas empresas individuales (p.ej., Joe’s Plumbing), que puede tener una relación comercial con los agregadores. Los agregadores proporcionan a los Servicios Locales información sobre estas empresas.
Descripción general
Los agregadores proporcionarán datos sobre sus proveedores (empresas) a Servicios Locales a través de feeds. Cada feed contiene datos sobre varios proveedores. Dentro de un feed, un elemento del feed encapsula los datos sobre un solo proveedor. Cada feed también especifica una marca de tiempo que indica cuándo se actualizó el feed por última vez. Cada feed también especifica un tipo de feed: puede ser datos sobre el perfil del proveedor o las opiniones sobre el proveedor, como se describe a continuación.
Tipos de feed
Para la integración inicial, cada feed puede ser uno de los siguientes tipos:
Feeds de perfil: Este feed proporciona información sobre los perfiles de los proveedores. Cada elemento del feed encapsula la información del perfil de un proveedor en particular. Esto incluye un ID de la empresa único, el nombre de la empresa, las ubicaciones de publicación, los servicios ofrecidos, el horario de atención, etcétera. El elemento del feed también contiene metadatos de publicación para esta empresa (p.ej., el importe del presupuesto mensual, el estado del anuncio, etcétera).
Feeds de opiniones: Este feed proporciona información sobre las opiniones de los proveedores. Cada elemento del feed incluye una lista de opiniones detalladas de los consumidores sobre un proveedor en particular. Cada opinión del consumidor consta del nombre del consumidor, la calificación (1 a 5), el texto de la opinión, la marca de tiempo de la opinión, etcétera.
Más detalles sobre los campos específicos y su semántica en el feed de perfil y el feed de opiniones
Transferencia del feed
Los datos del feed se serializan como JSON. Para enviar datos, LSA solo admitirá un mecanismo de extracción. Existen planes futuros para admitir un mecanismo de envío.
Mecanismo de extracción
En el mecanismo de extracción, los agregadores admiten un conjunto de extremos de REST predefinidos (URLs) que envían y reciben objetos JSON. Esto es análogo a alojar uno o más archivos en un servidor web. La LSA emitirá periódicamente solicitudes HTTP GET a estas URLs para recuperar datos. Puedes encontrar detalles sobre las URLs predefinidas en la siguiente sección sobre extremos de la API.
Mecanismo de envío
En el mecanismo de envío, la LSA proporcionará un extremo para que los agregadores llamen y proporcionen datos. Semánticamente, es lo mismo que una extracción, pero proporciona flexibilidad en los casos en que los agregadores desean enviar datos específicos a Servicios Locales. Todas las semánticas, reglas o restricciones que se describen en el protocolo se aplican tanto a la transferencia como a la extracción de la misma manera.
extremos de API
Los agregadores deben admitir los siguientes extremos: uno para el feed de perfil y otro para el feed de opiniones.
Ruta de extremos recomendada
Recomendamos que los extremos contengan información de la versión, como se muestra a continuación. Comenzamos con v1.
| Extremo | Ruta |
|---|---|
| Feed del perfil | /feeds/{version}/profile |
| Revisar feed | /feeds/{version}/review |
Parámetro del extremo
| Params | Descripción |
|---|---|
maxresults |
Es el límite de la cantidad de elementos del feed que se pueden solicitar en una página. |
nextpagetoken |
Es un token de paginación para obtener la siguiente página de resultados. |
Autenticación de extremos
La autenticación usa la autenticación de acceso básico HTTP: nombre de usuario y contraseña codificados en base64 para la autenticación. Aquí tienen un ejemplo.
username"Autorización" (con fines ilustrativos)passwordJ9adfdsafc3RfMjpVU1yif5XMw” (con fines ilustrativos)
Buzón SFTP para Push
Ruta de acceso de Dropbox: partnerupload.google.com:19321
ADVERTENCIA: Los archivos que se suben a este buzón de SFTP se borran automáticamente después de 24 horas.
Autenticación de extremos
Par de claves públicas y privadas (opción recomendada)
- Usa el instructivo aquí para generar pares de claves.
- Envía a la LSA la clave pública y conserva la clave privada para la autenticación
- La LSA usará la clave pública para generar un nombre de usuario y enviarlo de vuelta al agregador.
Autenticación con contraseña
- La LSA generará el nombre de usuario y la contraseña, y los enviará de vuelta al agregador.
Referencia rápida de comandos de SFTP
Accede. Usa este comando para acceder. (Omite -i
si no usas una clave privada). sftp -i <path_to_private_key> -P 19321 <username>@partnerupload.google.comCopia el archivo. Copia el archivo en el sistema remoto. Puedes usar
lls/lcdparals/cden tu sistema local y encontrar el archivo. Luego, copia el archivo con el siguiente comando:put <path_to_local_file>Verificar. Usa
lspara ver una lista de carpetas y archivos en el directorio SFTP y verifica que tu archivo se haya copiado en el sistema remoto.
Categorías de feeds
Como se señaló anteriormente, cada feed es análogo a un archivo y consta de varios elementos del feed. Cada elemento del feed encapsula datos sobre un proveedor en particular (ID de empresa único). Cada feed también tiene una marca de tiempo que indica su actualidad. Categoría del feed especifica cómo interpreta LSA un feed determinado. Existen dos categorías de feeds, como se describe a continuación.
El feed de instantáneas contiene una lista completa de proveedores (en un agregador) en una marca de tiempo específica. Después de procesar este feed de instantáneas, se aplican las siguientes semánticas:
Para cualquier proveedor presente en el feed, el sistema actualizará los datos de este proveedor en la base de datos de LSA (p.ej., creará un proveedor nuevo si se encuentra por primera vez o actualizará los datos del proveedor si se procesó en un feed anterior).
Se borrará cualquier proveedor del agregador que esté presente en la base de datos de LSA, pero que falte en el feed.
El feed de actualización (o incremental) contiene una lista parcial de proveedores (en un agregador) en una marca de tiempo determinada. Después de procesar un feed incremental, se aplicará la siguiente semántica:
Para cualquier proveedor presente en el feed, el sistema actualizará los datos de este proveedor en la base de datos de LSA si el proveedor se creó en un feed de instantáneas anterior. (p.ej., si se encuentra un proveedor por primera vez, no se realizará ninguna operación)
Para cualquier proveedor que esté presente actualmente en la base de datos de LSA, pero que falte en el feed, esta es una operación nula (es decir, no habrá ningún cambio en este proveedor).
La semántica del feed de opiniones y del feed de perfil es ligeramente diferente. Consulta la semántica de cada feed para obtener detalles sobre el procesamiento.
Feeds de perfil: * Feeds de instantáneas basados en extracción * Feeds de instantáneas basados en envío * Feeds de actualización basados en envío Feeds de opiniones: * Feeds de instantáneas basados en extracción * Feeds de instantáneas basados en envío
Se requieren feeds de perfil separados para los siguientes casos:
Proveedores que se consideran aptos para la insignia de Con garantía de Google o Analizado por Google
Proveedores que no cumplen con los requisitos para obtener la insignia
Ejemplos
Feeds de instantáneas
Recuerda que un feed de instantáneas contendrá una lista completa de proveedores. Por ejemplo, si un agregador desea que se ingieran 100 proveedores en la LSA, el feed de instantáneas debe contener el estado más reciente de los 100 proveedores.
Cómo funciona
A continuación, se muestra un ejemplo simple que demuestra cómo funciona la categoría de instantáneas de los feeds de perfil.
- La instantánea 1 tiene Pro 1 y Pro 2.
- La instantánea 2 tiene Pro 1 y Pro 3
Después de procesar la instantánea 1, la base de datos del LSA tendrá Pro 1 y Pro 2. Durante el procesamiento de la instantánea 2, la LSA actualizará el Pro 1, creará el Pro 3 y borrará el Pro 2. Es decir, después del procesamiento de la instantánea 2, la base de datos de LSA tendrá Pro 1 y Pro 3.
Actualiza feeds (incrementales)
Recuerda que un feed de actualización contiene una lista parcial de proveedores en un agregador. Por ejemplo, si un agregador solo desea actualizar 5 de los 100 proveedores que proporcionó anteriormente, el feed de actualización solo debe contener el estado más reciente de esos 5 proveedores.
Cómo funciona
A continuación, se muestra un ejemplo simple que ilustra cómo funciona la categoría de actualización de los "feeds de perfil".
- Actualización 1: Pro 1 y Pro 2
- Actualización 2: Pro 1 y Pro 3
Después de procesar la actualización 1, la base de datos de LSA tendrá Pro 1 y Pro 2. Durante el procesamiento de la actualización 2, la LSA actualizará Pro 1 y creará Pro 3. Ten en cuenta que Pro 2 no se modificó. Es decir, después del procesamiento de la actualización 2, la base de datos de la LSA tendrá Pro1, Pro2 y Pro3.
Implicaciones de Snapshot y Pull
El mecanismo de feeds de instantáneas y extracción implica las siguientes restricciones:
- Es posible que los socios tarden algunas horas en agregar o borrar proveedores, actualizar la información del perfil, detener anuncios o cambiar presupuestos. La demora se relaciona directamente con la frecuencia de las solicitudes de extracción.
- Para las actualizaciones de datos urgentes, es posible que debamos admitir manualmente una extracción única o ad hoc.
Implicaciones de la asistencia incremental y de envío
El mecanismo de apertura de actualización de feeds y envío implica las siguientes mejoras:
- Los socios pueden entregar el feed de instantáneas con el método de envío o extracción. Los socios que prefieran no mantener el extremo (para la extracción) pueden usar la inserción para reducir el costo de mantenimiento del extremo. Los socios que ya admiten feeds de instantáneas en la extracción pueden seguir enviando instantáneas en la extracción.
- Los socios pueden usar los incrementales para actualizar solo un subconjunto de proveedores con cambios en el perfil. Esto mejora la actualización de los datos del perfil.
- En cuanto a cómo elegir entre instantáneas y datos incrementales, o entre envío y extracción, consulta esta sección para conocer el enfoque de integración recomendado.
Enfoque de integración recomendado
Los socios deben tener feeds de instantáneas periódicos, ya sea a través de la inserción o la extracción. Esto permite que LSA controle emergencias, como reversiones y recuperación del sistema, en caso de que se omitan actualizaciones.
- Con el mecanismo de envío, los socios deben enviar feeds de perfiles de instantáneas cada 2 horas y feeds de opiniones cada 6 horas para garantizar la actualización de los datos básicos.
- Con el mecanismo de extracción, la LSA extraerá feeds de perfiles de instantáneas cada 2 horas y feeds de opiniones cada 6 horas para garantizar la actualización de los datos de referencia.
- Los socios solo necesitan uno de los mecanismos (ya sea de envío o extracción), pero no ambos, para entregar feeds de instantáneas.
De manera opcional, los socios que deseen mejorar la actualización de los datos pueden enviar feeds de actualización a través de la función push. La LSA no extraerá feeds de actualización.
- Los feeds de actualización se usan para propagar los elementos modificados desde la última instantánea sin esperar a la siguiente.
- Las LSA recomiendan que los proveedores tengan un intervalo de más de 5 minutos entre dos notificaciones push.
- Se recomienda agrupar los elementos del feed de forma razonable en un feed de actualización. Para actualizar 5 proveedores, la LSA prefiere que los proveedores envíen 1 feed de actualización con 5 feeditems en lugar de enviar 5 feeds de actualización con 1 feeditem en cada uno.
- Las LSA solo admiten feeds incrementales para los feeds de perfil, no para los feeds de opiniones.
La LSA respetará el campo feedTimestampMicros en los metadatos para garantizar la coherencia de los datos. Se omitirá un elemento del feed con una marca de tiempo anterior para evitar que se introduzca obsolescencia si se ingirió un elemento más reciente que actualiza el mismo pro. Es responsabilidad del socio reflejar la actualización de los datos correctamente con feedTimestampMicros en los feeds de instantáneas y de actualizaciones.
Los socios deben usar la API de Reporting para obtener información sobre los clientes potenciales y los cargos por proveedor.