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

Les requêtes d'envoi d'événements ou de membres d'audience sont traitées de manière asynchrone. Une réponse d'ingestion réussie renvoie un request_id et indique que la requête répondait à toutes les exigences et a été acceptée pour traitement. Toutefois, il n'indique pas si les enregistrements de la requête ont été traités avec succès.

Utilisez l'élément request_id renvoyé avec RetrieveRequestStatus pour vérifier l'état de votre importation et examiner les diagnostics.

Voici le workflow recommandé pour vérifier l'état de vos demandes et l'état de vos importations d'événements et d'audiences :

  1. Émettez des requêtes pour envoyer des événements, ou pour envoyer ou supprimer des membres de l'audience.

  2. Vérifiez l'état général de chaque demande d'ingestion. Une requête réussie comporte un Status avec code égal à 0 (valeur d'énumération OK, réponse HTTP 200 OK) et renvoie un IngestEventsResponse, un IngestAudienceMembersResponse ou un RemoveAudienceMembersResponse.

    Si une requête échoue, modifiez-la pour corriger l'erreur, puis renvoyez-la.

    Si une requête aboutit, capturez l'élément request_id de la réponse afin de pouvoir l'utiliser pour vérifier l'état du traitement à l'étape suivante.

  3. Attendez 30 minutes, puis envoyez une requête RetrieveRequestStatus pour chaque request_id réussi.

    Un RetrieveRequestStatusRequest nécessite une seule valeur request_id. Envoyez une demande d'état distincte pour chaque ID de requête que vous avez capturé à partir d'une requête d'ingestion réussie.

    Répétez régulièrement cette étape pour chaque request_id jusqu'à ce que l'état de la destination pour chaque destination atteigne SUCCESS, PARTIAL_SUCCESS ou FAILURE. Suivez la stratégie d'interrogation recommandée pour attendre entre chaque requête.

  4. Examinez chaque RetrieveRequestStatusResponse pour vérifier que vos importations fonctionnent correctement et identifier les problèmes liés à vos données.

  5. Corrigez les problèmes liés aux données.

  6. Revenez à l'étape 1 et répétez l'opération jusqu'à ce que vous ayez résolu tous les problèmes liés à vos importations.

Vérifier l'état général de la destination

Le champ request_status_per_destination d'un RetrieveRequestStatusResponse contient une entrée distincte pour chaque destination de la requête d'ingestion correspondante.

Par exemple, si votre IngestAudienceMembersRequest contenait trois entrées dans la liste destinations pour envoyer des données à trois audiences différentes, la réponse d'état contient trois entrées dans request_status_per_destination (une entrée par audience).

Vérifiez le champ request_status sur chaque RequestStatusPerDestination pour déterminer si l'API Data Manager a fini de traiter les données pour cette destination.

Voici les valeurs possibles de request_status :

  • PROCESSING : les données de la destination sont toujours en cours de traitement. Les avertissements et erreurs ne sont pas renseignés pour la destination à ce stade. Continuez l'interrogation jusqu'à ce que l'état atteigne un état final.

  • SUCCESS : le traitement de la requête pour la destination s'est terminé sans erreur. Vérifiez les avertissements signalés lors du traitement.

  • FAILURE : tous les enregistrements de la destination ont échoué en raison d'erreurs. Recherchez les avertissements et les erreurs pour déterminer pourquoi tous les enregistrements ont échoué. Vérifiez également si des avertissements ont été signalés lors du traitement.

  • PARTIAL_SUCCESS : certains enregistrements de la destination ont réussi, mais d'autres ont échoué en raison d'erreurs. Recherchez les erreurs pour déterminer pourquoi certains enregistrements ont échoué. Vérifiez également les avertissements signalés lors du traitement.

Examiner les diagnostics

Une fois que le request_status d'une destination atteint SUCCESS, FAILURE ou PARTIAL_SUCCESS, examinez les diagnostics détaillés dans la réponse pour vérifier les nombres et résoudre les problèmes.

Vérifier l'état des événements ou des audiences par destination

Inspectez le champ d'état correspondant au type de requête d'ingestion. Un seul des champs suivants est défini sur chaque RequestStatusPerDestination :

État de l'ingestion des événements

Le champ events_ingestion_status est renseigné si la requête était un IngestEventsRequest.

Vérifiez le champ record_count de IngestEventStatus pour confirmer que le nombre total d'enregistrements reçus correspond à vos attentes. record_count inclut les enregistrements réussis et échoués.

État d'ingestion des membres de l'audience

Le champ audience_members_ingestion_status est renseigné si la requête était un IngestAudienceMembersRequest. Voici le champ IngestAudienceMembersStatus à vérifier pour chaque type de données d'audience. Un seul de ces champs est défini.

composite_data_ingestion_status

Vérifiez la valeur record_count de IngestCompositeDataStatus pour confirmer que le nombre total d'enregistrements reçus correspond à vos attentes. Le record_count inclut les enregistrements réussis et ceux ayant échoué.

Vérifiez le data_type_counts pour confirmer que le nombre d'identifiants correspond à vos attentes. Cette liste fournit une répartition de tous les identifiants reçus (comme l'adresse e-mail, le numéro de téléphone, l'adresse physique et l'adresse IP) par DataType.

Si la requête contenait un nombre suffisant d'enregistrements, upload_match_rate_range contient la plage de taux de correspondance pour les enregistrements de la requête.

google_user_id_data_ingestion_status

Vérifiez le champ record_count de IngestGoogleUserIdDataStatus pour confirmer que le nombre total d'enregistrements reçus correspond à vos attentes. record_count inclut les enregistrements réussis et ceux ayant échoué.

Vérifiez le google_user_id_count pour confirmer que le nombre d'ID utilisateur Google reçus correspond à vos attentes.

mobile_data_ingestion_status

Vérifiez la valeur record_count de IngestMobileDataStatus pour confirmer que le nombre total d'enregistrements reçus correspond à vos attentes. record_count inclut les enregistrements réussis et ceux ayant échoué.

Vérifiez le mobile_id_count pour confirmer que le nombre de Mobile ID reçus correspond à vos attentes.

pair_data_ingestion_status

Vérifiez le champ record_count de IngestPairDataStatus pour confirmer que le nombre total d'enregistrements reçus correspond à vos attentes. record_count inclut les enregistrements réussis et ceux ayant échoué.

Vérifiez le pair_id_count pour confirmer que le nombre d'ID PAIR reçus correspond à vos attentes.

partner_provided_id_data_ingestion_status

Vérifiez le champ record_count de IngestPartnerProvidedIdDataStatus pour confirmer que le nombre total d'enregistrements reçus correspond à vos attentes. Le record_count inclut les enregistrements réussis et ceux ayant échoué.

Vérifiez la partner_provided_id_count pour confirmer que le nombre d'ID fournis par le partenaire correspond à vos attentes.

ppid_data_ingestion_status

Vérifiez le champ record_count de IngestPpidDataStatus pour confirmer que le nombre total d'enregistrements reçus correspond à vos attentes. record_count inclut les enregistrements réussis et ceux ayant échoué.

Consultez le ppid_count pour vérifier que le nombre de PPID reçus correspond à vos attentes.

user_data_ingestion_status

Vérifiez le champ record_count de IngestUserDataStatus pour confirmer que le nombre total d'enregistrements reçus correspond à vos attentes. record_count inclut les enregistrements réussis et ceux ayant échoué.

Vérifiez le user_identifier_count pour confirmer que le nombre d'identifiants utilisateur reçus correspond à vos attentes.

Si la requête contenait un nombre suffisant d'enregistrements, upload_match_rate_range contient la plage de taux de correspondance pour les enregistrements de la requête.

user_id_data_ingestion_status

Vérifiez le champ record_count de IngestUserIdDataStatus pour confirmer que le nombre total d'enregistrements reçus correspond à vos attentes. record_count inclut les enregistrements réussis et ceux ayant échoué.

Vérifiez le user_id_count pour confirmer que le nombre d'ID utilisateur reçus correspond à vos attentes.

État de la suppression des membres de l'audience

Le champ audience_members_removal_status est renseigné si la requête était un RemoveAudienceMembersRequest. Voici le champ RemoveAudienceMembersStatus à vérifier pour chaque type de données d'audience. Un seul de ces champs est défini.

composite_data_removal_status
État de la suppression pour Données composites
google_user_id_data_removal_status
État de la suppression des données d'ID utilisateur Google
mobile_data_removal_status
État de la suppression pour les données mobiles.
pair_data_removal_status
État de la suppression des données PAIR.
partner_provided_id_data_removal_status
État de la suppression pour Données d'ID fournies par le partenaire
ppid_data_removal_status
État de la suppression des données PPID.
user_data_removal_status
État de la suppression des données utilisateur.
user_id_data_removal_status
État de la suppression des données d'ID utilisateur

Vérifiez record_count pour confirmer que le nombre total d'enregistrements reçus correspond à vos attentes. record_count inclut les enregistrements réussis et échoués.

Vérifiez également user_identifier_count, mobile_id_count, pair_id_count, ppid_count, user_id_count, google_user_id_count ou partner_provided_id_count pour confirmer le nombre total d'identifiants reçus.

Pour les données composites, vérifiez le data_type_counts pour confirmer que le nombre d'identifiants correspond à vos attentes. Cette liste fournit une répartition de tous les identifiants reçus (comme l'adresse e-mail, le numéro de téléphone, l'adresse physique et l'adresse IP) par DataType.

Vérifier les avertissements et les erreurs

En plus des champs d'état pour la destination et le type de requête, RetrieveRequestStatusResponse contient une répartition des avertissements et des erreurs pour la requête.

  • Une erreur indique que l'API a complètement rejeté l'enregistrement.

  • Un avertissement indique que l'API n'a pas rejeté l'enregistrement, mais qu'elle a dû ignorer certaines parties des données de l'enregistrement.

Par exemple, si un Event contient des données UserIdentifier chiffrées et des AdIdentifiers telles que gclid, et que les données UserIdentifier ne peuvent pas être déchiffrées, l'API Data Manager traite toujours l'enregistrement à l'aide de AdIdentifiers, mais renvoie l'avertissement PROCESSING_WARNING_REASON_USER_IDENTIFIER_DECRYPTION_ERROR.

Toutefois, si Event ne contient pas AdIdentifiers et que les données UserIdentifier ne peuvent pas être déchiffrées, l'API Data Manager rejette l'intégralité de l'enregistrement et signale l'erreur PROCESSING_ERROR_REASON_USER_IDENTIFIER_DECRYPTION_ERROR, car un Event valide doit comporter au moins l'un des éléments ad_identifiers ou user_data.

Voici les champs de réponse qui contiennent des informations sur les avertissements et les erreurs. Ces champs sont renseignés lorsque l'état global de la destination atteint SUCCESS, PARTIAL_SUCCESS ou FAILURE.

warning_info

Un objet WarningInfo. Son champ warning_counts contient une liste d'objets WarningCount. Chaque WarningCount contient un reason avec le type d'avertissement et un record_count indiquant le nombre d'enregistrements ayant ce type d'avertissement.

Vérifiez l'warning_info même si l'état global de la destination est SUCCESS.

error_info

Un objet ErrorInfo. Son champ error_counts contient une liste d'objets ErrorCount. Chaque ErrorCount contient un reason avec le type d'erreur et un record_count indiquant le nombre d'enregistrements ayant échoué en raison de ce type d'erreur.

Stratégie d'interrogation

Envoyez régulièrement la requête RetrieveRequestStatusRequest à l'aide d'un algorithme d'intervalle exponentiel entre les tentatives jusqu'à ce que request_status atteigne SUCCESS, FAILURE ou PARTIAL_SUCCESS pour chaque destination de la requête d'origine. Cette opération peut prendre jusqu'à 24 heures, bien que l'API Data Manager puisse terminer le traitement de certaines requêtes en seulement 30 minutes.

Voici un exemple de configuration raisonnable du temps d'attente initial et des nouvelles tentatives, qui équilibre l'activité et l'utilisation des quotas :

Paramètre Valeur
Temps d'attente avant la première demande de diagnostic (minutes) 30
Multiplicateur d'intervalle entre les tentatives 1.3
Intervalle maximal entre les tentatives (minutes) 60 (1 heure)
Durée totale maximale (minutes) 1440 (24 heures)

Voici une séquence de requêtes et le temps écoulé avec cette configuration :

Graphique

Stratégie d'interrogation

Données

Tentative Temps écoulé depuis la demande d'ingestion (hh:mm) Délai avant tentative Remarques
1 00:30 30,0 min Vérifier d'abord la disponibilité de l'état
2 01:09 39 min
3 01:59 50,7 min
4 02:59 60 min Le délai est désormais limité à une heure
5 03:59 60 min
6 04:59 60 min
7 05:59 60 min
8 06:59 60 min
9 07:59 60 min
10 08:59 60 min
11 09:59 60 min
12 10:59 60 min
13 11:59 60 min 12 heures
14 12:59 60 min
15 13:59 60 min
16 14:59 60 min
17 15:59 60 min
18 16:59 60 min
19 17:59 60 min
20 18:59 60 min
21 19:59 60 min
22 20:59 60 min
23 21:59 60 min
24 22:59 60 min
25 23:59 60 min Dernière requête avant la durée totale maximale de 24 heures

Ajoutez une petite quantité aléatoire de gigue aux délais d'intervalle exponentiel entre les tentatives pour éviter le problème de "troupeau tonitruant" où de nombreux clients effectuent une nouvelle tentative simultanément.

Exigences concernant les autorisations

Un RetrieveRequestStatusRequest n'accepte pas les comptes de destination ni les en-têtes de requête. À la place, l'API Data Manager identifie les destinations à partir de la requête d'ingestion d'origine associée à l'request_id et vérifie que l'appelant a accès au operating_account sur chaque Destination.

Pour vérifier l'état d'une requête, les identifiants utilisés dans un RetrieveRequestStatusRequest doivent répondre aux exigences suivantes pour le operating_account de chaque destination de la requête d'ingestion d'origine :

  • Chemin d'accès identique : les identifiants doivent avoir accès à chaque operating_account en utilisant le chemin d'accès exact spécifié dans la requête d'ingestion d'origine.

    Par exemple, si une requête d'ingestion pour un operating_account Google Ads spécifie un compte administrateur parent comme login_account, les identifiants doivent également avoir accès au operating_account via ce même compte administrateur. Même si le compte Google associé aux identifiants dispose d'un accès direct au compte enfant operating_account, la requête échoue avec une erreur PERMISSION_DENIED si ce compte n'a pas d'accès via le compte administrateur login_account spécifié lors de l'ingestion.

  • Niveau d'accès suffisant : le compte Google associé aux identifiants doit disposer d'un niveau d'accès ou d'un rôle avec l'autorisation d'ingérer des données dans operating_account.

    Par exemple, dans Google Ads, le compte Google doit disposer du niveau d'accès Administrateur ou Standard. Une requête avec les identifiants d'un compte disposant du niveau d'accès Lecture seule échoue avec une erreur PERMISSION_DENIED.

Précédent
Chiffrer les données utilisateur
Suivant
Comprendre les erreurs d'API