Annonces Local Services (LSA) à mettre en place avec les agrégateurs pour diffuser leurs fiches (ou fournisseurs) sur Google.com. Dans ce guide, nous décrivons comment les agrégateurs peuvent fournir des données structurées d'annonces produits en magasin concernant leurs fournisseurs. Plus précisément, nous documentons l'ensemble des agrégateurs de points de terminaison de l'API que nous devons mettre en œuvre pour l'intégration aux applications moins sécurisées.
Glossaire
Agrégateur (ou partenaire): il s'agit des partenaires qui regroupent les fournisseurs auxquels ils fournissent des services et dont les données peuvent être fournies aux applications moins sécurisées.
Fournisseur tiers (ou fiche) : il s'agit de petites entreprises individuelles plomberie) qui peut avoir une relation commerciale avec les agrégateurs. Les agrégateurs fournissent des informations sur ces établissements aux Local Services.
Présentation
Les agrégateurs fournissent des données sur leurs fournisseurs aux entreprises à l'aide de flux. Chaque flux contient des données sur plusieurs fournisseurs. Dans un flux, les données d'un seul fournisseur sont encapsulées par un élément de flux. Chaque flux spécifie également un horodatage qui indique la fraîcheur du flux. Chaque flux spécifie également un type de flux: il peut s'agir de données sur le profil du fournisseur ou d'avis sur le fournisseur, comme décrit ci-dessous.
Types de flux
Pour l'intégration initiale, chaque flux peut correspondre à l'un des types suivants:
Flux de profils: ce flux fournit des informations sur les profils des fournisseurs. Chaque élément de flux encapsule les informations de profil d'un fournisseur particulier. Il peut s'agir d'un ID d'entreprise unique, du nom de l'entreprise, des établissements de diffusion, des services proposés, des 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 de l'annonce, etc.).
Flux d'avis: ce flux fournit des informations sur les avis des fournisseurs. Chaque élément de flux encapsule la liste des avis détaillés des consommateurs d'un fournisseur particulier. Chaque avis de consommateurs comprend le nom du consommateur, la note (1 à 5), le texte de l'avis, l'horodatage de l'avis, etc.
Pour en savoir plus sur les champs spécifiques et leur sémantique, consultez les pages 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, les applications moins sécurisées n'acceptent qu'un mécanisme d'extraction. Nous prévoyons d'ajouter un mécanisme push.
Mécanisme d'extraction
Dans le mécanisme pull, les agrégateurs acceptent un ensemble de points de terminaison REST (URL) prédéfinis qui envoient et reçoivent des objets JSON. Cette méthode revient à héberger un ou plusieurs fichiers sur un serveur Web. LSA émet régulièrement des requêtes HTTP GET pour ces URL afin de 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 d'envoi
Dans le mécanisme push, les applications moins sécurisées fourniront un point de terminaison permettant aux agrégateurs d'appeler et de fournir des données. Sur le plan sémantique, cette méthode est semblable à celle d'une extraction, mais elle offre une certaine flexibilité dans les cas où les agrégateurs souhaitent transférer des données spécifiques vers Local Services. L'ensemble de la sémantique, des règles ou des contraintes décrites dans le protocole s'appliquent de la même manière aux modes 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 profils et un pour le flux d'avis.
Chemin des points de terminaison recommandés
Nous vous recommandons d'inclure les informations de version suivantes pour les points de terminaison : Nous commençons par v1.
| Endpoint | Chemin d'accès |
|---|---|
| Flux de profils | /feeds/{version}/profile |
| Examiner le flux | /feeds/{version}/review |
Paramètre du point de terminaison
| Paramètres | Description |
|---|---|
maxresults |
Il s'agit du nombre maximal d'éléments de flux pouvant être demandés sur une page. |
nextpagetoken |
Jeton de pagination pour obtenir la page de résultats suivante |
Authentification des points de terminaison
L'authentification utilise l'authentification de base HTTP: un nom d'utilisateur et un mot de passe encodés en base64. Vous trouverez un exemple ci-dessous.
username"Autorisation" (à titre d'illustration uniquement)passwordJ9adfdsafc3RfMjpVU1yif5XMw" (à titre d'exemple)
Boîte de dépôt SFTP pour le transfert
Chemin d'accès à la boîte de dépôt : 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é)
- Utilisez ce tutoriel pour générer des paires de clés.
- Envoyer la clé publique LSA et conserver la clé privée pour l'authentification
- LSA utilisera la clé publique pour générer un nom d'utilisateur et le renvoyer à l'agrégateur
Authentification par mot de passe
- LSA génère le nom d'utilisateur et le mot de passe, puis les renvoie à l'agrégateur
Guide de référence de la commande SFTP
Connectez-vous. Utilisez cette commande pour vous connecter. (N'utilisez pas de clé privée
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. Ensuite, copiez le fichier via:put <path_to_local_file>Valider Utilisez
lspour afficher la liste des dossiers et des fichiers dans le répertoire SFTP et vérifier que votre fichier a bien été copié sur le système distant
Catégories de flux
Comme indiqué précédemment, chaque flux est semblable à un fichier et comprend plusieurs éléments. Chaque élément de flux encapsule les données sur un fournisseur (ID d'entreprise unique). Chaque flux est également associé à un horodatage qui indique sa fraîcheur. La catégorie de flux indique la façon dont les annonces produits en magasin interprète un flux donné. Il existe deux catégories de flux, comme décrit ci-dessous.
Le flux d'instantané contient la liste complète des fournisseurs (sous un agrégateur) à un horodatage particulier. Après avoir traité ce flux d'instantanés, 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 des applications moins sécurisées (par exemple, vous pouvez créer un fournisseur s'il est détecté pour la première fois ou mettre à jour les données du fournisseur s'il a été traité dans un flux antérieur).
Tous les fournisseurs sous l'agrégateur présents dans la base de données des applications moins sécurisées qui ne figurent pas dans le flux seront supprimés.
Le flux de mise à jour (ou incrémentielle) contient une liste partielle de fournisseurs (sous un agrégateur) à un horodatage spécifique. Après avoir traité un flux incrémentiel, 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 des applications moins sécurisées si celui-ci a été créé dans un flux d'instantanés antérieur. (par exemple, si l'utilisateur rencontre un fournisseur pour la première fois, il s'agit d'une opération sans opération)
Pour tous les fournisseurs présents dans la base de données des applications moins sécurisées, mais manquants dans le flux, il s'agit d'une opération no-op (c'est-à-dire que ce fournisseur ne sera pas modifié).
La sémantique du flux par rapport au flux d'avis est légèrement nuancée. Consultez la sémantique de flux individuelle pour en savoir plus sur le traitement.
Flux de photos instantanées
Des flux de profil distincts sont requis pour:
Fournisseurs considérés comme éligibles au badge Protection Google ou Sélectionné par Google.
Fournisseurs non éligibles à ce badge.
Examples
Flux d'instantanés
Rappelez-vous qu'un flux d'instantanés se compose d'une liste complète de fournisseurs. Par exemple, si un agrégateur souhaite ingérer 100 fournisseurs dans les applications moins sécurisées, le flux d'instantanés doit contenir l'état le plus récent pour les 100 fournisseurs.
Fonctionnement
Vous trouverez ci-dessous un exemple simple montrant comment fonctionne la catégorie d'instantanés des flux de profil.
- L'instantané 1 est associé à Pro 1, Pro 2
- L'instantané 2 est associé à Pro 1, Pro 3
Après le traitement de l'instantané 1, les bases de données LSA sont associées à Pro 1 et Pro 2. Lors du traitement de l'instantané 2, LSA met à jour Pro 1, crée Pro 3 et supprime Pro 2. Autrement dit, après le traitement de l'instantané 2, les bases de données LSA comporteront Pro 1 et Pro 3.
Mettre à jour (flux incrémentiel)
Rappelez-vous qu'un flux de mise à jour contient une liste partielle de fournisseurs d'un agrégateur. Par exemple, si un agrégateur ne souhaite mettre à jour que cinq de ses fournisseurs, le flux de mise à jour ne doit contenir que l'état le plus récent pour ces cinq fournisseurs.
Fonctionnement
Vous trouverez ci-dessous un exemple simple montrant comment fonctionne la catégorie de mise à jour "Flux de profil".
- Update 1: Pro 1, Pro 2
- Update 2: Pro 1, Pro 3
Après le traitement de la mise à jour 1, la base de données des applications moins sécurisées aura les versions 1 et 2. Lors du traitement de la mise à jour 2, LSA met à jour Pro 1 et crée Pro 3. Notez que la version 2 est intacte. Autrement dit, après le traitement de la mise à jour 2, les bases de données LSA auront les versions Pro1, Pro2 et Pro 3.
Implications de la capture et du pull
Le mécanisme flux instantanés + pull implique les restrictions suivantes:
- Un délai de quelques heures peut être nécessaire pour que les partenaires ajoutent ou suppriment des fournisseurs, mettent à jour les informations de profil, mettent en veille les annonces ou modifient les budgets. Le délai est directement lié à la fréquence des requêtes d'extraction.
- Pour les mises à jour urgentes des données, nous pouvons être amenés à accepter manuellement une extraction ponctuelle ou ad hoc.
Conséquences de la prise en charge incrémentielle et push
L'ouverture du flux de mise à jour et du mécanisme de transfert implique les améliorations suivantes:
- Les partenaires peuvent fournir des flux d'instantanés en mode push ou pull. Les partenaires qui préfèrent ne pas gérer le point de terminaison (pour le mode pull) peuvent utiliser le mode push pour réduire les coûts de maintenance du point de terminaison. Les partenaires utilisant déjà les flux d'instantanés Pull peuvent continuer à diffuser des instantanés.
- Les partenaires peuvent utiliser les incréments pour ne mettre à jour qu'un sous-ensemble de fournisseurs avec des modifications de profil. Cela permet d'améliorer la fraîcheur des données de profil.
- Pour découvrir comment choisir un instantané ou un incrément, ou inversement, 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 en mode push ou pull. Cela permet aux applications moins sécurisées de gérer les situations d'urgence 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 profil instantané toutes les deux heures et examiner les flux toutes les six heures pour garantir la fraîcheur des données de référence.
- Avec le mécanisme pull, LSA extraira des flux de profils instantanés toutes les deux heures et examinera les flux toutes les six heures pour garantir la fraîcheur des données de référence.
- Les partenaires n'ont besoin que de l'un des mécanismes (push ou pull), mais pas les deux, pour diffuser des flux d'instantanés.
Les partenaires qui souhaitent améliorer la fraîcheur des données peuvent également envoyer des flux de mise à jour via le mode push. Les annonces produits en magasin ne récupèrent pas les flux de mise à jour.
- Les flux de mise à jour sont utilisés pour propager les éléments modifiés depuis le dernier instantané sans attendre le prochain instantané.
- LSA recommande aux fournisseurs d'utiliser un intervalle de plus de 5 minutes entre deux transferts.
- Nous vous recommandons de regrouper raisonnablement les éléments de flux dans un flux de mise à jour. Pour mettre à jour cinq fournisseurs, les applications moins sécurisées prévoient de transmettre un flux de mise à jour avec cinq éléments au lieu de transférer cinq flux comportant chacun un élément.
- Les annonces produits en magasin ne sont compatibles qu'avec les flux partiels, pas avec les flux d'avis.
LSA respectera le champ feedTimestampMicros dans les métadonnées pour garantir la cohérence des données. Un élément de flux ayant un horodatage plus ancien sera ignoré afin d'éviter l'obsolescence si un élément plus récent qui met à jour le même fournisseur a été ingéré. Il est de la responsabilité du 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.