Les annonces Local Services (ALS) permettent aux agrégateurs de diffuser leurs fiches (ou celles de leurs fournisseurs) sur Google.com. Ce guide explique comment les agrégateurs peuvent fournir des données structurées ALS sur leurs fournisseurs. Plus précisément, nous documentons l'ensemble des points de terminaison d'API que les agrégateurs doivent implémenter pour s'intégrer aux annonces Local Services.
Glossaire
Agrégateur (ou partenaire) : il s'agit de partenaires qui regroupent des fournisseurs auxquels ils proposent des services et dont les données peuvent être fournies à LSA.
Fournisseur (ou fiche) tiers : il s'agit de petites entreprises individuelles (par exemple, Joe's plumbing) qui peuvent avoir une relation commerciale avec des agrégateurs. Les agrégateurs fournissent à Local Services des informations sur ces entreprises.
Présentation
Les agrégateurs fourniront des données sur leurs fournisseurs (entreprises) à Local Services à l'aide de flux. Chaque flux contient des données sur plusieurs fournisseurs. Dans un flux, les données concernant un seul fournisseur sont encapsulées par un élément de flux. Chaque flux spécifie également un code temporel qui indique sa fraîcheur. Chaque flux spécifie également un type de flux. Il peut s'agir de données sur le profil du fournisseur ou sur les avis le concernant, comme décrit ci-dessous.
Types de flux
Pour l'intégration initiale, chaque flux peut être l'un des types suivants :
Flux de profils : ce flux fournit des informations sur les profils des fournisseurs. Chaque élément du flux contient des informations sur un fournisseur spécifique. Cela inclut un ID d'établissement unique, le nom de l'établissement, les zones de diffusion, les services proposés, les horaires d'ouverture, etc. L'élément de flux contient également des métadonnées de diffusion pour cet établissement (par exemple, le montant du budget mensuel, l'état des annonces, etc.).
Flux d'avis : ce flux fournit des informations sur les avis des fournisseurs. Chaque élément de flux contient une liste d'avis détaillés de consommateurs sur un fournisseur spécifique. Chaque avis de consommateur se compose du nom du consommateur, de la note (de 1 à 5), du texte de l'avis, de l'horodatage de l'avis, etc.
Pour en savoir plus sur les champs spécifiques et leur sémantique, consultez Flux de profils et Flux d'avis.
Ingestion de flux
Les données du flux sont sérialisées au format JSON. Pour envoyer des données, LSA n'acceptera qu'un mécanisme d'extraction. Nous prévoyons de prendre en charge un mécanisme push à l'avenir.
Mécanisme d'extraction
Dans le mécanisme d'extraction, les agrégateurs sont compatibles avec un ensemble de points de terminaison REST prédéfinis (URL) qui envoient et reçoivent des objets JSON. Cela revient à héberger un ou plusieurs fichiers sur un serveur Web. LSA enverra régulièrement des requêtes HTTP GET à ces URL pour récupérer les données. Pour en savoir plus sur les URL prédéfinies, consultez la section suivante sur les points de terminaison de l'API.
Mécanisme push
Dans le mécanisme push, LSA fournira un point de terminaison que les agrégateurs pourront appeler et fournir des données. Sémantiquement, cela revient à une extraction, mais offre de la flexibilité dans les cas où les agrégateurs souhaitent envoyer des données spécifiques aux services locaux. Toutes les sémantiques, règles ou contraintes décrites dans le protocole s'appliquent de la même manière aux opérations push et pull.
points de terminaison de l'API
Les agrégateurs doivent prendre en charge les points de terminaison suivants : un pour le flux de profil et un pour le flux d'avis.
Chemin d'accès aux points de terminaison recommandés
Nous vous recommandons d'inclure des informations sur la version dans les points de terminaison, comme ci-dessous. Commençons par v1.
| Point de terminaison | Chemin |
|---|---|
| Flux de profil | /feeds/{version}/profile |
| Examiner le flux | /feeds/{version}/review |
Paramètre de point de terminaison
| Paramètres | Description |
|---|---|
maxresults |
Il s'agit de la limite du nombre d'éléments de flux pouvant être demandés sur une page. |
nextpagetoken |
Jeton de pagination permettant d'obtenir la page de résultats suivante. |
Authentification des points de terminaison
L'authentification utilise l'authentification HTTP de base pour l'accès : nom d'utilisateur et mot de passe encodés en base64 pour l'authentification. Vous trouverez un exemple ci-dessous.
username"Autorisation" (à titre d'exemple)passwordJ9adfdsafc3RfMjpVU1yif5XMw” (à titre d'exemple)
Boîte de dépôt SFTP pour Push
Chemin Dropbox : partnerupload.google.com:19321
AVERTISSEMENT : Les fichiers chargés dans cette boîte de dépôt SFTP sont automatiquement supprimés au bout de 24 heures.
Authentification des points de terminaison
Paire de clés publique/privée (recommandée)
- Utilisez ce tutoriel pour générer des paires de clés.
- Envoyez la clé publique à LSA et conservez la clé privée pour l'authentification.
- LSA utilisera la clé publique pour générer un nom d'utilisateur et l'envoyer à l'agrégateur.
Authentification par mot de passe
- LSA générera le nom d'utilisateur et le mot de passe, puis les renverra à l'agrégateur.
Documentation de référence rapide sur les commandes SFTP
Connectez-vous. Utilisez cette commande pour vous connecter. (Omettez -i
si vous n'utilisez pas de clé privée). sftp -i <path_to_private_key> -P 19321 <username>@partnerupload.google.comCopier le fichier Copiez le fichier dans le système distant. Vous pouvez utiliser
lls/lcdpourls/cddans votre système local afin de trouver le fichier. Copiez ensuite le fichier via :put <path_to_local_file>Valider. Utilisez
lspour afficher la liste des dossiers et des fichiers du répertoire SFTP, et vérifiez que votre fichier a été copié sur le système distant.
Catégories de flux
Comme indiqué précédemment, chaque flux est analogue à un fichier et se compose de plusieurs éléments de flux. Chaque élément de flux contient des données sur un fournisseur spécifique (ID d'établissement unique). Chaque flux comporte également un code temporel qui indique sa fraîcheur. La catégorie de flux indique comment LSA interprète un flux donné. Il existe deux catégories de flux, comme décrit ci-dessous.
Le flux d'instantanés contient la liste complète des fournisseurs (sous un agrégateur) à un instant donné. Après le traitement de ce flux d'instantanés, les sémantiques suivantes s'appliquent :
Pour tout fournisseur présent dans le flux, le système met à jour les données de ce fournisseur dans la base de données LSA (par exemple, en créant un fournisseur s'il est rencontré pour la première fois ou en mettant à jour les données du fournisseur s'il a été traité dans un flux précédent).
Tout fournisseur de l'agrégateur actuellement présent dans la base de données LSA, mais manquant dans le flux, sera supprimé.
Le flux de mise à jour (ou incrémentiel) contient une liste partielle de fournisseurs (sous un agrégateur) à un moment donné. Une fois un flux incrémentiel traité, la sémantique suivante s'applique :
Pour tout fournisseur présent dans le flux, le système met à jour les données de ce fournisseur dans la base de données LSA s'il a été créé dans un flux d'instantané précédent. (par exemple, si un fournisseur est rencontré pour la première fois, il s'agira d'une opération sans effet)
Pour tout fournisseur actuellement présent dans la base de données LSA, mais manquant dans le flux, il s'agit d'une opération sans effet (c'est-à-dire qu'il n'y aura aucun changement pour ce fournisseur).
La sémantique du flux de fiche par rapport à celle du flux d'avis est légèrement nuancée. Pour en savoir plus sur le traitement, consultez la sémantique de chaque flux.
Flux de profil : * Flux instantanés basés sur l'extraction * Flux instantanés basés sur l'envoi * Flux de mise à jour basés sur l'envoi Flux d'avis : * Flux instantanés basés sur l'extraction * Flux instantanés basés sur l'envoi
Des flux de profil distincts sont requis pour :
Les fournisseurs qui sont jugés éligibles au badge Protection Google ou Sélectionné par Google.
Prestataires qui ne sont pas éligibles au badge
Exemples
Flux d'instantanés
N'oubliez pas qu'un flux instantané se compose d'une liste complète de fournisseurs. Par exemple, si un agrégateur souhaite que 100 fournisseurs soient ingérés dans LSA, le flux d'instantanés doit contenir le dernier état pour les 100 fournisseurs.
Fonctionnement
Vous trouverez ci-dessous un exemple simple illustrant le fonctionnement de la catégorie d'instantanés des flux de profil.
- L'instantané 1 contient Pro 1 et Pro 2.
- Snapshot 2 dispose de Pro 1 et Pro 3
Après le traitement de l'instantané 1, la base de données LSA contiendra Pro 1 et Pro 2. Lors du traitement du Snapshot 2, LSA mettra à jour Pro 1, créera Pro 3 et supprimera Pro 2. Autrement dit, après le traitement de l'instantané 2, la base de données LSA contiendra Pro 1 et Pro 3.
Mettre à jour des flux (incrémentiels)
Rappelons qu'un flux de mise à jour contient une liste partielle de fournisseurs sous un agrégateur. Par exemple, si un agrégateur ne souhaite mettre à jour que 5 des 100 fournisseurs qu'il a fournis précédemment, le flux de mise à jour ne doit contenir que le dernier état de ces 5 fournisseurs.
Fonctionnement
Vous trouverez ci-dessous un exemple simple illustrant le fonctionnement de la catégorie de mise à jour "Flux de profil".
- Mise à jour 1 : Pro 1, Pro 2
- Mise à jour 2 : Pro 1, Pro 3
Après le traitement de la mise à jour 1, la base de données LSA contiendra les niveaux Pro 1 et Pro 2. Lors du traitement de la mise à jour 2, LSA mettra à jour Pro 1 et créera Pro 3. Notez que Pro 2 n'est pas concerné. Autrement dit, après le traitement de la mise à jour 2, la base de données LSA contiendra Pro1, Pro2 et Pro3.
Implications de l'instantané et de l'extraction
Le mécanisme Flux d'instantanés + extraction implique les restrictions suivantes :
- Il peut s'écouler quelques heures avant que les partenaires puissent ajouter ou supprimer des fournisseurs, mettre à jour les informations de leur profil, mettre en veille des annonces ou modifier des budgets. Le délai est directement lié à la fréquence des demandes d'extraction.
- Pour les mises à jour urgentes des données, nous devrons peut-être effectuer manuellement une extraction ponctuelle/ad hoc.
Implications de la prise en charge incrémentielle et push
L'ouverture du mécanisme Mettre à jour les flux et les notifications push implique les améliorations suivantes :
- Les partenaires peuvent fournir le flux d'instantanés en mode push ou pull. Les partenaires qui préfèrent ne pas gérer le point de terminaison (pour l'extraction) peuvent utiliser le mode Push à la place pour réduire les coûts de maintenance du point de terminaison. Si vous êtes un partenaire qui prend déjà en charge les flux d'instantanés dans l'extraction, vous pouvez continuer à les fournir dans l'extraction.
- Les partenaires peuvent utiliser les incrémentaux pour mettre à jour uniquement un sous-ensemble de fournisseurs avec des modifications de profil. Cela améliore la fraîcheur des données du profil.
- Pour savoir comment choisir entre les instantanés et les incréments, ou entre le mode push et le mode pull, consultez cette section pour connaître l'approche d'intégration recommandée.
Approche d'intégration recommandée
Les partenaires doivent disposer de flux d'instantanés périodiques, que ce soit par envoi ou par extraction. Cela permet à LSA de gérer les urgences telles que les rollbacks et la récupération du système en cas de mises à jour manquées.
- Avec le mécanisme push, les partenaires doivent envoyer des flux de profils instantanés toutes les deux heures et des flux d'avis toutes les six heures pour garantir la fraîcheur des données de base.
- Avec le mécanisme d'extraction, LSA extrait les flux de profils instantanés toutes les deux heures et examine les flux toutes les six heures pour garantir la fraîcheur des données de référence.
- Les partenaires n'ont besoin que d'un seul mécanisme (push ou pull) pour fournir des flux d'instantanés.
Si vous le souhaitez, vous pouvez envoyer des flux de mise à jour en mode Push pour améliorer la fraîcheur des données. LSA ne récupérera pas les flux de mise à jour.
- Les flux de mise à jour permettent de propager les éléments modifiés depuis le dernier instantané sans attendre le prochain.
- LSA recommande aux fournisseurs de prévoir un intervalle de plus de cinq minutes entre deux notifications push.
- Il est recommandé de regrouper raisonnablement les éléments de flux dans un flux de mise à jour. Pour mettre à jour cinq fournisseurs, LSA préfère que les fournisseurs envoient un flux de mise à jour avec cinq éléments de flux plutôt que cinq flux de mise à jour avec un élément de flux chacun.
- LSA n'accepte les flux partiels que pour les flux de fiches, et non pour les flux d'avis.
LSA respectera le champ feedTimestampMicros des métadonnées pour garantir la cohérence des données. Un élément de flux avec un ancien code temporel sera ignoré pour éviter d'introduire une obsolescence si un élément plus récent qui met à jour le même professionnel a été ingéré. Il incombe au partenaire de refléter correctement la fraîcheur des données à l'aide de feedTimestampMicros dans les flux d'instantanés et de mises à jour.
Les partenaires doivent utiliser l'API Reporting pour obtenir des informations sur les prospects et les frais par fournisseur.