Bonnes pratiques

Gardez à l'esprit les bonnes pratiques suivantes lorsque vous utilisez l'API Data Manager.

Envoyer tous les identifiants utilisateur

Que vous envoyiez des membres de l'audience ou des événements avec UserData, incluez autant de user_identifiers que possible, y compris en envoyant plusieurs identifiants du même type.

Par exemple, si vous disposez de plusieurs adresses e-mail pour un utilisateur, incluez un UserIdentifier distinct pour chaque adresse e-mail. De même, si vous disposez d'identifiants de différents types pour un utilisateur, tels que des adresses e-mail, des numéros de téléphone et des adresses, ajoutez un UserIdentifier distinct pour chaque identifiant, jusqu'au nombre maximal d'identifiants.

Optimiser les requêtes

Pour réduire le risque de dépasser les limites de requêtes quotidiennes, regroupez autant d'éléments que possible dans chaque requête, dans la limite des limites par requête.

Par exemple, si vous souhaitez ajouter 10 000 membres à une audience, ajoutez-les tous à la liste audience_members dans un seul IngestAudienceMembersRequest. Le traitement par lot des 10 000 membres dans une seule requête est plus efficace que l'envoi d'une requête distincte pour ajouter chaque membre de l'audience.

Envoyer des requêtes simultanées

Pour réduire le temps total nécessaire à l'ingestion des données, envoyez des requêtes simultanées à IngestionService. Nous vous recommandons d'envoyer jusqu'à 10 requêtes simultanément pour réduire le risque de dépassement de la limite de requêtes par minute.

Vous pouvez envoyer des requêtes simultanées même si elles ont le même destinations.

Valider les données côté client

L'API Data Manager utilise un modèle d'échec rapide. Si un enregistrement d'une requête échoue à la validation synchrone, l'intégralité de la requête échoue et aucun des enregistrements n'est traité. De plus, l'API valide les requêtes dans des couches séquentielles. Par conséquent, la correction d'une erreur peut révéler une erreur provenant d'une couche de validation ultérieure.

Pour éviter les allers-retours répétés et les requêtes refusées, validez et nettoyez vos données avant de les envoyer :

• Supprimez les valeurs vides avant le hachage : vérifiez les champs tels que email_address et phone_number pour détecter les chaînes vides ou ne contenant que des espaces avant de calculer les hachages SHA-256. Le hachage d'une chaîne vide produit un hachage valide qui passe les contrôles de syntaxe, mais nuit aux taux de correspondance.

• Supprimer les objets composites incomplets : assurez-vous que les objets composites comportent tous les champs obligatoires avant de les ajouter à un enregistrement. Par exemple, s'il manque l'un des quatre champs obligatoires (given_name, family_name, region_code ou postal_code) dans un objet AddressInfo, supprimez l'intégralité de l'identifiant address pour éviter les erreurs REQUIRED_FIELD_MISSING.

• Validez les champs d'encodage et de texte brut : vérifiez que les champs hachés correspondent au encoding déclaré plutôt que d'envoyer du texte brut, et assurez-vous que les champs qui doivent rester en texte brut (comme mobile_ids) ne sont pas hachés.

• Filtrer les codes temporels hors limites : assurez-vous que les codes temporels ne sont pas dans le futur ni plus anciens que la période d'analyse des conversions de la destination.

  Si vous envoyez des requêtes au format JSON, assurez-vous que les chaînes de code temporel utilisent le format RFC 3339 avec un décalage de fuseau horaire.

• Nettoyez les numéros de téléphone : vérifiez que les numéros de téléphone incluent un indicatif de pays et utilisent le format E.164 avant le hachage.

• Élaguer les enregistrements vides ou trop volumineux : limitez user_identifiers à la limite par enregistrement (10 identifiants), supprimez les paramètres personnalisés vides et omettez tout enregistrement ne contenant aucun identifiant valide.

• Vérifiez les exigences liées au cas d'utilisation : assurez-vous que chaque événement inclut tous les champs obligatoires pour sa destination et son cas d'utilisation (par exemple, transaction_id pour les conversions en ligne Google Ads). Pour obtenir la liste complète des champs obligatoires par cas d'utilisation, consultez le guide d'envoi d'événements pour votre destination dans la présentation des événements.

• Utilisez validateOnly pour tester les requêtes : envoyez des requêtes avec validateOnly défini sur true pour intercepter les erreurs d'échec rapide sans ingérer ni supprimer de données. Une requête de validation seule réussie ne garantit pas qu'il n'y aura pas d'erreurs lors du traitement asynchrone. Continuez donc à vérifier l'état de la requête et les diagnostics après l'envoi d'une requête standard.

Pour connaître les règles de normalisation et de hachage détaillées, consultez Formater les données utilisateur.

Vérifier l'état de la demande et les diagnostics

Capturez et collectez l'élément request_id de chaque IngestAudienceMembersResponse ou IngestEventsResponse, puis utilisez les ID de requête pour vérifier l'état et les diagnostics de la requête.

Surveiller les quotas et envoyer des alertes

Pour éviter les rejets de requêtes inattendus, configurez des alertes de quota et une surveillance dans la console Google Cloud. La surveillance de l'utilisation des quotas vous aide à suivre les modèles de consommation et à optimiser le traitement par lot des requêtes avant que votre application n'atteigne les limites quotidiennes ou par minute.

Déployer en production

Lorsque vous passez des tests locaux aux charges de travail de production, utilisez les identifiants par défaut de l'application avec un compte de service associé ou la fédération d'identité de charge de travail pour vous authentifier de manière non interactive et sécurisée.

Pour en savoir plus sur la configuration de l'authentification pour différents environnements de production, consultez Déployer en production.