Local Services Ads (LSA) para asociarse con agregadores a fin de mostrar sus fichas (o proveedores) en Google.com. En esta guía, describimos cómo los agregadores pueden proporcionar datos estructurados de LSA sobre sus proveedores. Específicamente, documentamos el conjunto de extremos de API que los agregadores deben implementar para la integración con las LSA.
Glosario
Agregador (o socio): Estos son socios que agregan proveedores a los que proporcionan servicios y cuyos datos pueden proporcionarse a las LSA.
Proveedor externo (o ficha): Son las empresas individuales individuales (p.ej., la plomería de Juan) que podría tener una relación comercial con 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 los Servicios locales mediante feeds. Cada feed consta de datos sobre varios proveedores. En un feed, los datos sobre un solo proveedor se encapsulan en un elemento del feed. Cada feed también especifica una marca de tiempo del feed que indica su actualidad. Cada feed también especifica un tipo de feed: pueden ser datos sobre el perfil del proveedor o las opiniones sobre este, como se describe a continuación.
Tipos de feed
Para la integración inicial, cada feed puede ser de uno de los siguientes tipos:
Feeds de perfil: proporcionan información sobre los perfiles de proveedores. Cada elemento del feed contiene información de perfil sobre un proveedor en particular. Esto incluye un ID de empresa único, un nombre de empresa, ubicaciones de entrega, servicios ofrecidos, horarios de atención, etc. El elemento del feed también contiene metadatos de entrega para esta empresa (p.ej., importe del presupuesto mensual, estado del anuncio, etcétera).
Feeds de opiniones: Proporcionan información sobre las opiniones de proveedores. Cada elemento del feed contiene una lista de opiniones detalladas de los consumidores sobre un proveedor en particular. Cada opinión de consumidor consiste en el 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.
Obtén más detalles sobre los campos específicos y su semántica en el feed de perfil y el feed de opinión.
Transferencia de feed
Los datos del feed se serializan como JSON. Para enviar datos, las LSA solo admitirán 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 (URL) predefinidos que envían y reciben objetos JSON. Esto es similar a alojar uno o más archivos en un servidor web. LSA emitirá periódicamente solicitudes HTTP GET a estas URL para recuperar datos. Puedes encontrar detalles sobre las URL predefinidas en la siguiente sección sobre extremos de API.
Mecanismo de inserción
En el mecanismo de envío, las LSA proporcionarán un extremo para que los agregadores llamen y proporcionen datos. Semánticamente, esto es lo mismo que una extracción, pero proporciona flexibilidad en los casos en los que los agregadores desean enviar datos específicos a Servicios locales. Toda la semántica, las reglas o las restricciones descritas en el protocolo se aplican a la extracción y la extracción de la misma manera.
Extremos de API
Los agregadores deben ser compatibles con los agregadores: uno para el feed de perfil y otro para el de revisión.
Ruta de acceso de extremos recomendada
Recomendamos que los extremos contengan la siguiente información de la versión: Comenzamos con v1.
| Extremo | Path |
|---|---|
| Feed del perfil | /feeds/{version}/profile |
| Revisar feed | /feeds/{version}/review |
Parámetro de extremo
| Parámetros | Descripción |
|---|---|
maxresults |
Este es el límite de la cantidad de elementos del feed que se pueden solicitar en una página. |
nextpagetoken |
Token de paginación para obtener la siguiente página de resultados |
Autenticación de extremos
La autenticación usa autenticación de acceso básica HTTP: nombre de usuario y contraseña codificados en base64 para la autenticación. A continuación, se muestra un ejemplo.
username"Autorización" (a fines ilustrativos)passwordJ9adfdsafc3RfMjpVU1yif5XMw” (con fines ilustrativos)
Dropbox de SFTP para envío
Ruta de Dropbox: partnerupload.google.com:19321
ADVERTENCIA: Los archivos que se cargan en este buzón de SFTP se borran automáticamente después de 24 horas.
Autenticación de extremos
Par de claves pública/privada (recomendado)
- Usa este instructivo para generar pares de claves.
- Enviar a LSA la clave pública y conservar la clave privada para la autenticación
- LSA usará la clave pública para generar un nombre de usuario y enviarlo al agregador
Autenticación con contraseña
- LSA generará el nombre de usuario y la contraseña, y lo enviará al agregador
Referencia rápida del comando SFTP
Accede. Usa este comando para acceder. (Si no usas una clave privada, deja de lado
). sftp -i <path_to_private_key> -P 19321 <username>@partnerupload.google.comCopiar el archivo. Copia el archivo en el sistema remoto. Puedes usar
lls/lcdparals/cden tu sistema local a fin de encontrar el archivo. Luego, copie el archivo de la siguiente manera:put <path_to_local_file>Verificar. Usa
lspara ver una lista de carpetas y archivos en el directorio SFTP y verificar que el archivo se haya copiado en el sistema remoto.
Categorías de feed
Como se mencionó antes, cada feed es análogo a un archivo y consta de varios elementos del feed. Cada elemento del feed contiene datos sobre un proveedor en particular (ID de la empresa único). Cada feed también tiene una marca de tiempo que indica su actualización. La categoría de feed especifica cómo las LSA interpretan un feed determinado. Hay dos categorías de feeds, como se describe a continuación.
El feed de instantáneas contiene una lista completa de proveedores (debajo de un agregador) en una marca de tiempo en particular. Después de procesar este feed de instantáneas, se aplica 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 (p.ej., creará un proveedor nuevo si se encuentra por primera vez o actualizará los datos del proveedor si el proveedor se procesó en un feed anterior).
Cualquier proveedor del agregador que se encuentra actualmente en la base de datos de LSA, pero que no esté en el feed, se borrará.
Feed de actualización (o incremental) contiene una lista parcial de proveedores (de un agregador) en una marca de tiempo en particular. 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 la primera vez, será una no-op)
En el caso de cualquier proveedor presente en la base de datos de LSA, pero que no se encuentra en el feed, esta es una no-op (es decir, no habrá cambios en este proveedor).
La semántica para el feed del perfil en comparación con el feed de reseñas es ligeramente matizada. Consulta la semántica de feed individual para obtener detalles de procesamiento.
Feeds de perfiles: * Feeds de instantáneas basados en extracciones * Feeds de instantáneas basados en envíos * Feeds de actualizaciones basados en envíos Revisar feeds: * Feeds de instantáneas basados en extracciones * Feeds de instantáneas basados en envíos
Se requieren feeds de perfil independientes para:
Proveedores que se consideran aptos para obtener la insignia de Garantía de Google o Analizada por Google
Proveedores que no son aptos para obtener la insignia
Examples
Feeds de instantáneas
Recuerde que un feed de instantáneas constará de una lista completa de proveedores. Por ejemplo, si un agregador desea que 100 proveedores se transfieran a 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 sencillo que muestra cómo funciona la categoría de instantánea de los feeds de perfil.
- La instantánea 1 tiene Pro 1, Pro 2
- La instantánea 2 tiene Pro 1 y Pro 3
Después de procesar la Instantánea 1, la base de datos de LSA tendrá Pro 1 y Pro 2. Durante el procesamiento de la Snapshot 2, LSA actualizará Pro 1, creará Pro 3 y borrará Pro 2. Es decir, después del procesamiento de la Snapshot 2, la base de datos LSA tendrá Pro 1 y Pro 3.
Actualizar 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ó antes, el feed de actualización solo debe contener el estado más reciente de estos 5 proveedores.
Cómo funciona
A continuación, se muestra un ejemplo sencillo que muestra cómo funciona la categoría de actualización de los "feeds de perfil".
- Actualización 1: Pro 1, Pro 2
- Actualización 2: Pro 1, 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, LSA actualizará Pro 1 y creará Pro 3. Ten en cuenta que Pro 2 no se toca. Es decir, después de procesar la actualización 2, la base de datos de LSA tendrá Pro1, Pro2 y Pro 3.
Implicaciones de la instantánea y la extracción
El mecanismo de feeds de instantáneas + extracción implica las siguientes restricciones:
- Es posible que los socios tarden algunas horas en agregar o borrar proveedores, actualizar la información de perfil, detener anuncios o cambiar presupuestos. El retraso está directamente relacionado 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 push
Abrir el mecanismo de actualización de feeds + envío implica las siguientes mejoras:
- Los socios pueden publicar feeds de instantáneas en envío o extracción. Para los socios que prefieren no mantener el extremo (para extracción), en su lugar, pueden usar el envío a fin de reducir el costo de mantenimiento del extremo. El socio ya admite feeds de instantáneas en la extracción. Puedes seguir entregando instantáneas en la extracción.
- Los socios pueden usar incrementales para actualizar solo un subconjunto de proveedores con cambios de perfil. Esto mejora la actualidad de los datos del perfil.
- En términos de cómo elegir la instantánea frente a los incrementales, el envío y la 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 mediante envíos o extracciones. Esto permite que la LSA maneje emergencias como reversiones y recuperación del sistema en caso de actualizaciones perdidas.
- Con el mecanismo de envío, los socios deben enviar feeds de instantáneas del perfil cada 2 horas y revisar feeds cada 6 horas para garantizar la actualidad de los datos de referencia.
- Con el mecanismo de extracción, LSA extraerá feeds del perfil de instantáneas cada 2 horas y los revisará cada 6 horas para garantizar la actualidad 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 publicar feeds de instantáneas.
De manera opcional, los socios que deseen mejorar la actualidad de los datos pueden enviar feeds de actualización mediante envío. Las LSA no extraerán feeds de actualización.
- Los feeds de actualización se usan para propagar 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 envíos.
- Se recomienda agrupar los elementos del feed de manera razonable en un feed de actualización. Para actualizar 5 proveedores, LSA prefiere que los proveedores envíen 1 feed de actualización con 5 elementos del feed en lugar de enviar 5 feeds de actualización con 1 elemento del feed en cada uno.
- Las LSA admiten feeds incrementales solo para los feeds de perfiles, no para los feeds de opiniones.
Las LSA respetarán el campo feedTimestampMicros en los metadatos para garantizar la coherencia de los datos. Se omitirá un elemento del feed con una marca de tiempo más antigua para evitar que se vuelva obsoleto si se ha transferido un elemento nuevo que actualiza al mismo profesional. Es responsabilidad del socio reflejar correctamente la actualidad de los datos
mediante feedTimestampMicros en los feeds de instantáneas y de actualizaciones.
Los socios deben usar la API de informes para obtener información sobre los clientes potenciales y los cargos por proveedor.