Diagnostica

Di seguito è riportato il flusso di lavoro consigliato per verificare l'integrità dei caricamenti di eventi e segmenti di pubblico e identificare i problemi relativi ai dati.

  1. Emetti richieste per inviare eventi o inviare o rimuovere membri del pubblico.

  2. Controlla lo stato generale di ogni richiesta. 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 request_id della risposta in modo da poterlo utilizzare per recuperare la diagnostica nel passaggio successivo.

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

    Ripeti periodicamente questo passaggio per ogni request_id finché lo stato della destinazione per ogni destinazione non raggiunge SUCCESS, PARTIAL_SUCCESS o FAILURE. Utilizza un algoritmo di backoff esponenziale per attendere tra una richiesta e l'altra.

  4. Controlla 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.

Invio di richieste

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.

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'account 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 l'importazione dei 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.

Strategia di polling

Invia periodicamente RetrieveRequestStatusRequest utilizzando un algoritmo di backoff esponenziale finché request_status non raggiunge SUCCESS, FAILURE 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 tempo di attesa iniziale e configurazione dei tentativi ragionevoli che bilanciano 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 Per prima cosa, controlla la disponibilità dello stato.
2 01:09 39 min
3 01:59 50,7 min
4 02:59 60,0 min Il ritardo è ora limitato a 1 ora
5 03:59 60 minuti
6 04:59 60 minuti
7 05:59 60,0 min
8 06:59 60,0 min
9 07:59 60,0 min
10 08:59 60 minuti
11 09:59 60,0 min
12 10:59 60 minuti
13 11:59 60,0 min Segno delle 12 ore
14 12:59 60,0 min
15 13:59 60,0 min
16 14:59 60 minuti
17 15:59 60 minuti
18 16:59 60 minuti
19 17:59 60 minuti
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 minuti 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.

Rivedi le risposte

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 conterrà tre voci in request_status_per_destination (una voce per segmento di pubblico).

Controlla lo stato generale della destinazione

Come primo passaggio, controlla il campo request_status per determinare se l'API Data Manager ha terminato l'elaborazione dei dati per destination di RequestStatusPerDestination.

Di seguito sono riportati i valori possibili di request_status:

  • PROCESSING: i dati relativi alla destinazione sono ancora in fase di elaborazione. Gli avvisi e gli errori non vengono compilati per la destinazione in questa fase.

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

  • FAILURE: 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 riusciti. Controlla anche se sono presenti avvisi segnalati durante l'elaborazione.

  • PARTIAL_SUCCESS: alcuni record per la destinazione sono stati caricati correttamente, ma altri non sono stati caricati a causa di errori. Controlla gli errori per determinare perché alcuni record non sono stati caricati. Controlla anche se sono presenti avvisi segnalati durante l'elaborazione.

Controllare 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 dell'oggetto IngestEventStatus per verificare che il numero totale di record ricevuti corrisponda alle tue aspettative. record_count include i record riusciti e 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 dell'IngestCompositeDataStatus per verificare che il numero totale di record ricevuti corrisponda alle tue aspettative. Il record_count include i record riusciti e non riusciti.

Controlla 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 aveva 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 quelli non riusciti.

Controlla il 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 dell'oggetto IngestMobileDataStatus per verificare che il numero totale di record ricevuti corrisponda alle tue aspettative. Il campo record_count include i record riusciti e quelli 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. record_count include sia i record riusciti che 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 che 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 dell'IngestUserDataStatus per verificare che il numero totale di record ricevuti corrisponda alle tue aspettative. record_count include sia i record riusciti che quelli non riusciti.

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

Se la richiesta aveva 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 dell'IngestUserIdDataStatus per verificare che il numero totale di record ricevuti corrisponda alle tue aspettative. record_count include sia i record riusciti che quelli non riusciti.

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

Stato di 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 i dati compositi
google_user_id_data_removal_status
Stato della rimozione per i dati 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 dai partner
ppid_data_removal_status
Stato di rimozione per i dati PPID.
user_data_removal_status
Stato della rimozione dei dati utente.
user_id_data_removal_status
Stato della rimozione per i dati ID utente

Controlla record_count per verificare che il numero totale di record ricevuti corrisponda alle tue aspettative. Il file record_count include record riusciti e 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 il 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, il RetrieveRequestStatusResponse contiene una suddivisione di avvisi ed 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 contenere almeno uno tra ad_identifiers e 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 FAILURE.

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 che presentavano quel tipo di avviso.

Controlla warning_info anche se lo stato della destinazione generale è 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.