Controlla lo stato della richiesta e la diagnostica

Le richieste di invio di eventi o membri del segmento di pubblico vengono elaborate in modo asincrono. Una risposta di importazione riuscita restituisce un request_id e indica che la richiesta ha soddisfatto tutti i requisiti ed è stata accettata per l'elaborazione. Tuttavia, non indica se i record nella richiesta sono stati elaborati correttamente.

Utilizza l'elemento request_id restituito con RetrieveRequestStatus per controllare lo stato del caricamento ed esaminare la diagnostica.

Ecco il flusso di lavoro consigliato per controllare lo stato delle tue richieste e verificare l'integrità dei caricamenti di eventi e segmenti di pubblico:

  1. Invia richieste per inviare eventi o inviare o rimuovere membri del segmento di pubblico.

  2. Controlla lo stato generale di ogni richiesta di importazione. Una richiesta riuscita ha un Status con code uguale a 0 (valore enum OK, risposta HTTP 200 OK) e restituisce un IngestEventsResponse, IngestAudienceMembersResponse o RemoveAudienceMembersResponse.

    Se una richiesta non va a buon fine, modificala per risolvere l'errore e inviala di nuovo.

    Se una richiesta ha esito positivo, acquisisci il valore request_id della risposta in modo da poterlo utilizzare per controllare lo stato di elaborazione nel passaggio successivo.

  3. Attendi 30 minuti, quindi invia una richiesta RetrieveRequestStatus per ogni request_id riuscito.

    Un RetrieveRequestStatusRequest richiede un singolo valore request_id. Invia una richiesta di stato separata per ogni ID richiesta acquisito da una richiesta di importazione riuscita.

    Ripeti periodicamente questo passaggio per ogni request_id finché lo stato della destinazione per ogni destinazione non raggiunge SUCCESS, PARTIAL_SUCCESS o FAILED. Segui la strategia di polling consigliata per attendere tra una richiesta e l'altra.

  4. Esamina ogni RetrieveRequestStatusResponse per verificare che i caricamenti funzionino correttamente e identificare eventuali problemi con i dati.

  5. Correggi i problemi relativi ai dati.

  6. Torna al passaggio 1 e ripeti la procedura fino a quando non avrai risolto tutti i problemi relativi ai caricamenti.

Controlla lo stato generale della destinazione

request_status_per_destination in un RetrieveRequestStatusResponse contiene una voce separata per ogni destinazione nella richiesta di importazione corrispondente.

Ad esempio, se IngestAudienceMembersRequest conteneva tre voci nell'elenco destinations per inviare dati a tre segmenti di pubblico diversi, la risposta di stato contiene tre voci in request_status_per_destination (una voce per segmento di pubblico).

Controlla il campo request_status in ogni RequestStatusPerDestination per determinare se l'API Data Manager ha terminato l'elaborazione dei dati per la destinazione.

Di seguito sono riportati i valori possibili di request_status:

  • PROCESSING: i dati relativi alla destinazione sono ancora in fase di elaborazione. In questa fase, gli avvisi e gli errori non vengono compilati per la destinazione. Continua il polling finché lo stato non raggiunge uno stato finale.

  • SUCCESS: l'elaborazione della richiesta per la destinazione è stata completata senza errori. Controlla se sono presenti avvisi segnalati durante l'elaborazione.

  • FAILED: tutti i record per la destinazione non sono riusciti a causa di errori. Controlla la presenza di avvisi ed errori per determinare il motivo per cui tutti i record non sono stati caricati. Controlla anche se sono presenti avvisi segnalati durante l'elaborazione.

  • PARTIAL_SUCCESS: alcuni record per la destinazione sono stati elaborati correttamente, ma altri non sono riusciti a causa di errori. Controlla la presenza di errori per determinare il motivo per cui alcuni record non sono stati importati. Controlla anche se sono presenti avvisi segnalati durante l'elaborazione.

Rivedi la diagnostica

Quando il request_status per una destinazione raggiunge SUCCESS, FAILED o PARTIAL_SUCCESS, esamina la diagnostica dettagliata nella risposta per verificare i conteggi e risolvere i problemi.

Controlla lo stato dell'evento o del segmento di pubblico per destinazione

Esamina il campo dello stato corrispondente al tipo di richiesta di importazione. Solo uno dei seguenti campi è impostato su ogni RequestStatusPerDestination:

Stato di importazione degli eventi

Il campo events_ingestion_status viene compilato se la richiesta era un IngestEventsRequest.

Controlla il campo record_count di IngestEventStatus per verificare che il numero totale di record ricevuti corrisponda alle tue aspettative. record_count include sia i record riusciti sia quelli non riusciti.

Stato di importazione dei membri del segmento di pubblico

Il campo audience_members_ingestion_status viene compilato se la richiesta era un IngestAudienceMembersRequest. Ecco il campo IngestAudienceMembersStatus da controllare per ogni tipo di dati sul pubblico. Viene impostato solo uno di questi campi.

composite_data_ingestion_status

Controlla il campo record_count di IngestCompositeDataStatus per verificare che il numero totale di record ricevuti corrisponda alle tue aspettative. Il campo record_count include i record riusciti e non riusciti.

Controlla la data_type_counts per verificare che il numero di identificatori corrisponda alle tue aspettative. Questo elenco fornisce una suddivisione di tutti gli identificatori ricevuti (ad esempio indirizzo email, numero di telefono, indirizzo fisico e indirizzo IP) da DataType.

Se la richiesta conteneva un numero sufficiente di record, upload_match_rate_range contiene l'intervallo del tasso di corrispondenza per i record nella richiesta.

google_user_id_data_ingestion_status

Controlla il campo record_count di IngestGoogleUserIdDataStatus per verificare che il numero totale di record ricevuti corrisponda alle tue aspettative. Il campo record_count include i record riusciti e non riusciti.

Controlla il campo google_user_id_count per verificare che il numero di ID utente Google ricevuti corrisponda alle tue aspettative.

mobile_data_ingestion_status

Controlla il campo record_count di IngestMobileDataStatus per verificare che il numero totale di record ricevuti corrisponda alle tue aspettative. Il campo record_count include i record riusciti e non riusciti.

Controlla la mobile_id_count per verificare che il numero di identità digitali ricevute corrisponda alle tue aspettative.

pair_data_ingestion_status

Controlla il campo record_count di IngestPairDataStatus per verificare che il numero totale di record ricevuti corrisponda alle tue aspettative. Il record_count include sia i record riusciti sia quelli non riusciti.

Controlla il pair_id_count per verificare che il numero di ID PAIR ricevuti corrisponda alle tue aspettative.

partner_provided_id_data_ingestion_status

Controlla il campo record_count di IngestPartnerProvidedIdDataStatus per verificare che il numero totale di record ricevuti corrisponda alle tue aspettative. Il record_count include sia i record riusciti sia quelli non riusciti.

Controlla la partner_provided_id_count per verificare che il numero di ID forniti dai partner ricevuti corrisponda alle tue aspettative.

ppid_data_ingestion_status

Controlla il campo record_count di IngestPpidDataStatus per verificare che il numero totale di record ricevuti corrisponda alle tue aspettative. Il record_count include sia i record riusciti sia quelli non riusciti.

Controlla la ppid_count per verificare che il numero di PPID ricevuti corrisponda alle tue aspettative.

user_data_ingestion_status

Controlla il campo record_count di IngestUserDataStatus per verificare che il numero totale di record ricevuti corrisponda alle tue aspettative. Il record_count include sia i record riusciti sia quelli non riusciti.

Controlla user_identifier_count per verificare che il numero di identificatori dell'utente ricevuti corrisponda alle tue aspettative.

Se la richiesta conteneva un numero sufficiente di record, upload_match_rate_range contiene l'intervallo del tasso di corrispondenza per i record nella richiesta.

user_id_data_ingestion_status

Controlla il campo record_count di IngestUserIdDataStatus per verificare che il numero totale di record ricevuti corrisponda alle tue aspettative. Il record_count include sia i record riusciti sia quelli non riusciti.

Controlla il user_id_count per verificare che il numero di ID utente ricevuti corrisponda alle tue aspettative.

Stato della rimozione dei membri del segmento di pubblico

Il campo audience_members_removal_status viene compilato se la richiesta era un RemoveAudienceMembersRequest. Ecco il campo RemoveAudienceMembersStatus da controllare per ogni tipo di dati sul pubblico. Viene impostato solo uno di questi campi.

composite_data_removal_status
Stato della rimozione per Dati compositi
google_user_id_data_removal_status
Stato della rimozione per i dati dell'ID utente Google
mobile_data_removal_status
Stato della rimozione per i dati mobili.
pair_data_removal_status
Stato della rimozione per i dati PAIR.
partner_provided_id_data_removal_status
Stato della rimozione per i dati ID forniti dal partner
ppid_data_removal_status
Stato della rimozione dei dati PPID.
user_data_removal_status
Stato della rimozione dei dati utente.
user_id_data_removal_status
Stato della rimozione per i dati degli ID utente

Controlla record_count per verificare che il numero totale di record ricevuti corrisponda alle tue aspettative. record_count include i record riusciti e quelli non riusciti.

Inoltre, controlla user_identifier_count, mobile_id_count, pair_id_count, ppid_count, user_id_count, google_user_id_count o partner_provided_id_count per confermare il numero totale di identificatori ricevuti.

Per i dati compositi, controlla la data_type_counts per verificare che il numero di identificatori corrisponda alle tue aspettative. Questo elenco fornisce una suddivisione di tutti gli identificatori ricevuti (ad esempio indirizzo email, numero di telefono, indirizzo fisico e indirizzo IP) da DataType.

Controlla gli avvisi e gli errori

Oltre ai campi di stato per la destinazione e il tipo di richiesta, RetrieveRequestStatusResponse contiene una suddivisione degli avvisi e degli errori per la richiesta.

  • Un errore indica che l'API ha rifiutato completamente il record.

  • Un avviso indica che l'API non ha rifiutato il record, ma ha dovuto ignorare parti dei dati del record.

Ad esempio, se un Event contiene dati UserIdentifier criptati e AdIdentifiers come gclid e i dati UserIdentifier non possono essere decriptati, l'API Data Manager elabora comunque il record utilizzando AdIdentifiers, ma restituisce l'avviso PROCESSING_WARNING_REASON_USER_IDENTIFIER_DECRYPTION_ERROR.

Tuttavia, se Event non contiene AdIdentifiers e i dati UserIdentifier non possono essere decriptati, l'API Data Manager rifiuta l'intero record e segnala l'errore PROCESSING_ERROR_REASON_USER_IDENTIFIER_DECRYPTION_ERROR perché un Event valido deve avere almeno ad_identifiers o user_data.

Di seguito sono riportati i campi della risposta che contengono informazioni su avvisi ed errori. Questi campi vengono compilati quando lo stato complessivo della destinazione raggiunge SUCCESS, PARTIAL_SUCCESS o FAILED.

warning_info

Un oggetto WarningInfo. Il campo warning_counts contiene un elenco di oggetti WarningCount. Ogni WarningCount contiene un reason con il tipo di avviso e un record_count che indica il numero di record con quel tipo di avviso.

Controlla l'warning_info anche se lo stato generale della destinazione è SUCCESS.

error_info

Un oggetto ErrorInfo. Il campo error_counts contiene un elenco di oggetti ErrorCount. Ogni ErrorCount contiene un reason con il tipo di errore e un record_count che indica il numero di record che non sono stati elaborati a causa di quel tipo di errore.

Strategia di polling

Invia periodicamente RetrieveRequestStatusRequest utilizzando un algoritmo di backoff esponenziale finché request_status non raggiunge SUCCESS, FAILED o PARTIAL_SUCCESS per ogni destinazione nella richiesta originale. L'operazione potrebbe richiedere fino a 24 ore, anche se l'API Data Manager potrebbe completare l'elaborazione di alcune richieste in soli 30 minuti.

Ecco un esempio di configurazione ragionevole del tempo di attesa iniziale e dei nuovi tentativi che bilancia l'attività e l'utilizzo della quota:

Impostazione Valore
Tempo di attesa prima della prima richiesta di diagnostica (minuti) 30
Moltiplicatore di backoff 1.3
Backoff massimo (minuti) 60 (1 ora)
Tempo totale massimo (minuti) 1440 (24 ore)

Ecco una sequenza di richieste e il tempo trascorso con questa configurazione:

Grafico

Strategia di polling

Dati

Tentativo Tempo trascorso dalla richiesta di importazione (hh:mm) Ritardo prima del tentativo Note
1 00:30 30,0 min Verifica innanzitutto la disponibilità dello stato
2 01:09 39,0 min
3 01:59 50,7 min
4 02:59 60,0 min Il ritardo è ora limitato a 1 ora
5 03:59 60,0 min
6 04:59 60,0 min
7 05:59 60,0 min
8 06:59 60,0 min
9 07:59 60,0 min
10 08:59 60,0 min
11 09:59 60,0 min
12 10:59 60,0 min
13 11:59 60,0 min 12 ore
14 12:59 60,0 min
15 13:59 60,0 min
16 14:59 60,0 min
17 15:59 60,0 min
18 16:59 60,0 min
19 17:59 60,0 min
20 18:59 60,0 min
21 19:59 60,0 min
22 20:59 60,0 min
23 21:59 60,0 min
24 22:59 60,0 min
25 23:59 60,0 min Ultima richiesta prima del tempo totale massimo di 24 ore

Aggiungi una piccola quantità casuale di jitter ai ritardi di backoff per evitare il problema del "thundering herd", in cui molti client riprovano contemporaneamente.

Requisiti di autorizzazione

Un RetrieveRequestStatusRequest non accetta account di destinazione o intestazioni della richiesta. Invece, l'API Data Manager identifica le destinazioni dalla richiesta di importazione originale associata a request_id e verifica che il chiamante abbia accesso a operating_account su ogni Destination.

Per controllare lo stato di una richiesta, le credenziali utilizzate in un RetrieveRequestStatusRequest devono soddisfare i seguenti requisiti per il operating_account di ogni destinazione della richiesta di importazione originale:

  • Percorso di accesso identico: le credenziali devono avere accesso a ogni operating_account utilizzando l'esatto percorso di accesso specificato nella richiesta di importazione originale.

    Ad esempio, se una richiesta di importazione per un operating_account Google Ads ha specificato un account amministratore principale come login_account, le credenziali devono avere accesso anche al operating_account tramite lo stesso account amministratore. Anche se l'Account Google associato alle credenziali ha accesso diretto all'operating_account secondario, la richiesta non va a buon fine e viene restituito un errore PERMISSION_DENIED se l'account non ha accesso tramite l'account amministratore login_account specificato durante l'importazione.

  • Livello di accesso sufficiente: l'Account Google associato alle credenziali deve avere un livello di accesso o un ruolo con l'autorizzazione per importare i dati in operating_account.

    Ad esempio, in Google Ads, l'Account Google deve avere il livello di accesso Amministratore o Standard. Una richiesta con credenziali per un account con il livello di accesso Sola lettura non va a buon fine e genera un errore PERMISSION_DENIED.

Indietro
Cripta i dati utente
Avanti
Informazioni sugli errori API