Anfragestatus und Diagnoseinformationen prüfen

Anfragen zum Senden von Ereignissen oder Zielgruppenmitgliedern werden asynchron verarbeitet. Eine erfolgreiche Aufnahmeantwort gibt einen request_id zurück und gibt an, dass die Anfrage alle Anforderungen erfüllt hat und zur Verarbeitung akzeptiert wurde. Es wird jedoch nicht angegeben, ob die Datensätze in der Anfrage erfolgreich verarbeitet wurden.

Verwenden Sie die zurückgegebene request_id mit RetrieveRequestStatus, um den Status des Uploads zu prüfen und die Diagnosedaten zu überprüfen.

Hier ist der empfohlene Workflow, um den Status Ihrer Anfragen zu prüfen und den Zustand Ihrer Ereignis- und Zielgruppenuploads zu überprüfen:

  1. Anfragen zum Senden von Ereignissen oder zum Senden oder Entfernen von Zielgruppenmitgliedern stellen.

  2. Prüfen Sie den Gesamtstatus jeder Aufnahme-Anfrage. Eine erfolgreiche Anfrage hat einen Status mit code gleich 0 (Enum-Wert OK, HTTP-Antwort 200 OK) und gibt einen IngestEventsResponse, IngestAudienceMembersResponse oder RemoveAudienceMembersResponse zurück.

    Wenn eine Anfrage nicht erfolgreich ist, ändern Sie sie, um den Fehler zu beheben, und senden Sie sie noch einmal.

    Wenn eine Anfrage erfolgreich ist, erfassen Sie die request_id der Antwort, damit Sie sie im nächsten Schritt zum Prüfen des Verarbeitungsstatus verwenden können.

  3. Warten Sie 30 Minuten und senden Sie dann für jede erfolgreiche request_id eine RetrieveRequestStatus-Anfrage.

    Für ein RetrieveRequestStatusRequest ist ein einzelner request_id-Wert erforderlich. Senden Sie für jede Anfrage-ID, die Sie aus einer erfolgreichen Aufnahme-Anfrage erfasst haben, eine separate Statusanfrage.

    Wiederholen Sie diesen Schritt regelmäßig für jeden request_id, bis der Zielstatus für jedes Ziel SUCCESS, PARTIAL_SUCCESS oder FAILED erreicht. Folgen Sie der empfohlenen Abfragestrategie, um zwischen den einzelnen Anfragen zu warten.

  4. Prüfen Sie jede RetrieveRequestStatusResponse, um sicherzustellen, dass Ihre Uploads ordnungsgemäß funktionieren, und um Probleme mit Ihren Daten zu identifizieren.

  5. Datenprobleme beheben

  6. Gehen Sie zurück zu Schritt 1 und wiederholen Sie den Vorgang, bis Sie alle Probleme mit Ihren Uploads behoben haben.

Gesamtstatus des Ziels prüfen

request_status_per_destination in einem RetrieveRequestStatusResponse enthält einen separaten Eintrag für jedes Ziel in der entsprechenden Aufnahme-Anfrage.

Wenn Ihre IngestAudienceMembersRequest beispielsweise drei Einträge in der Liste destinations enthielt, um Daten an drei verschiedene Zielgruppen zu senden, enthält die Statusantwort drei Einträge in request_status_per_destination (ein Eintrag pro Zielgruppe).

Prüfen Sie das Feld request_status für jede RequestStatusPerDestination, um festzustellen, ob die Data Manager API die Verarbeitung der Daten für dieses Ziel abgeschlossen hat.

Folgende Werte sind für request_status möglich:

  • PROCESSING: Die Daten für das Ziel werden noch verarbeitet. Die Warnungen und Fehler werden für das Ziel in dieser Phase nicht ausgefüllt. Führen Sie die Abfrage so lange aus, bis der Status einen Endzustand erreicht.

  • SUCCESS: Die Anfrageverarbeitung für das Ziel wurde ohne Fehler abgeschlossen. Prüfe, ob während der Verarbeitung Warnungen angezeigt wurden.

  • FAILED: Alle Datensätze für das Ziel sind aufgrund von Fehlern fehlgeschlagen. Prüfen Sie, ob Warnungen und Fehler vorliegen, um festzustellen, warum alle Einträge fehlgeschlagen sind. Prüfen Sie auch, ob während der Verarbeitung Warnungen ausgegeben wurden.

  • PARTIAL_SUCCESS: Einige der Datensätze für das Ziel waren erfolgreich, andere sind jedoch aufgrund von Fehlern fehlgeschlagen. Prüfen Sie, ob Fehler vorliegen, um herauszufinden, warum einige Einträge fehlgeschlagen sind. Prüfen Sie auch, ob während der Verarbeitung Warnungen angezeigt wurden.

Diagnose ansehen

Sobald der request_status für ein Ziel SUCCESS, FAILED oder PARTIAL_SUCCESS erreicht, sehen Sie sich die detaillierte Diagnose in der Antwort an, um die Anzahl zu überprüfen und Probleme zu beheben.

Ereignis- oder Zielgruppenstatus pro Ziel prüfen

Prüfen Sie das Statusfeld, das dem Typ der Aufnahme-Anfrage entspricht. In jedem RequestStatusPerDestination ist nur eines der folgenden Felder festgelegt:

Status der Ereignisaufnahme

Das Feld events_ingestion_status wird ausgefüllt, wenn die Anfrage ein IngestEventsRequest war.

Prüfen Sie das Feld record_count von IngestEventStatus, um zu bestätigen, dass die Gesamtzahl der empfangenen Datensätze Ihren Erwartungen entspricht. Die record_count enthält sowohl erfolgreiche als auch fehlgeschlagene Einträge.

Status der Aufnahme von Zielgruppenmitgliedern

Das Feld audience_members_ingestion_status wird ausgefüllt, wenn die Anfrage ein IngestAudienceMembersRequest war. Hier ist das Feld IngestAudienceMembersStatus, das für jeden Typ von Zielgruppendaten geprüft werden muss. Es ist nur eines dieser Felder festgelegt.

composite_data_ingestion_status

Prüfen Sie im IngestCompositeDataStatus das Feld record_count, um zu bestätigen, dass die Gesamtzahl der empfangenen Datensätze Ihren Erwartungen entspricht. Die record_count enthält sowohl erfolgreiche als auch fehlgeschlagene Datensätze.

Prüfen Sie die data_type_counts, um zu bestätigen, dass die Anzahl der Kennungen Ihren Erwartungen entspricht. Diese Liste enthält eine Aufschlüsselung aller von DataType empfangenen Kennungen (z. B. E‑Mail-Adresse, Telefonnummer, Postanschrift und IP-Adresse).

Wenn die Anfrage eine ausreichende Anzahl von Datensätzen enthielt, enthält die upload_match_rate_range den Bereich der Abgleichsrate für Datensätze in der Anfrage.

google_user_id_data_ingestion_status

Prüfen Sie das Feld record_count des IngestGoogleUserIdDataStatus, um zu bestätigen, dass die Gesamtzahl der empfangenen Datensätze Ihren Erwartungen entspricht. Die record_count enthält sowohl erfolgreiche als auch fehlgeschlagene Datensätze.

Prüfen Sie in der google_user_id_count, ob die Anzahl der empfangenen Google-Nutzer-IDs Ihren Erwartungen entspricht.

mobile_data_ingestion_status

Prüfen Sie im IngestMobileDataStatus das Feld record_count, um zu bestätigen, dass die Gesamtzahl der empfangenen Datensätze Ihren Erwartungen entspricht. Die record_count enthält sowohl erfolgreiche als auch fehlgeschlagene Datensätze.

Prüfen Sie die mobile_id_count, um festzustellen, ob die Anzahl der empfangenen mobilen IDs Ihren Erwartungen entspricht.

pair_data_ingestion_status

Prüfen Sie das Feld record_count des IngestPairDataStatus, um zu bestätigen, dass die Gesamtzahl der empfangenen Datensätze Ihren Erwartungen entspricht. Die record_count enthält sowohl erfolgreiche als auch fehlgeschlagene Einträge.

Prüfen Sie die pair_id_count, um festzustellen, ob die Anzahl der erhaltenen PAIR-IDs Ihren Erwartungen entspricht.

partner_provided_id_data_ingestion_status

Prüfen Sie das Feld record_count der IngestPartnerProvidedIdDataStatus, um zu bestätigen, dass die Gesamtzahl der empfangenen Datensätze Ihren Erwartungen entspricht. Die record_count enthält sowohl erfolgreiche als auch fehlgeschlagene Einträge.

Prüfen Sie im partner_provided_id_count, ob die Anzahl der erhaltenen vom Partner bereitgestellten IDs Ihren Erwartungen entspricht.

ppid_data_ingestion_status

Prüfen Sie das Feld record_count des IngestPpidDataStatus, um zu bestätigen, dass die Gesamtzahl der empfangenen Datensätze Ihren Erwartungen entspricht. Die record_count enthält sowohl erfolgreiche als auch fehlgeschlagene Einträge.

Prüfen Sie in der ppid_count, ob die Anzahl der empfangenen PPIDs Ihren Erwartungen entspricht.

user_data_ingestion_status

Prüfen Sie das Feld record_count des IngestUserDataStatus, um zu bestätigen, dass die Gesamtzahl der empfangenen Datensätze Ihren Erwartungen entspricht. Die record_count enthält sowohl erfolgreiche als auch fehlgeschlagene Einträge.

Prüfen Sie in user_identifier_count, ob die Anzahl der empfangenen Nutzer-IDs Ihren Erwartungen entspricht.

Wenn die Anfrage eine ausreichende Anzahl von Datensätzen enthielt, enthält die upload_match_rate_range den Bereich der Abgleichsrate für Datensätze in der Anfrage.

user_id_data_ingestion_status

Prüfen Sie das Feld record_count des IngestUserIdDataStatus, um zu bestätigen, dass die Gesamtzahl der empfangenen Datensätze Ihren Erwartungen entspricht. Die record_count enthält sowohl erfolgreiche als auch fehlgeschlagene Einträge.

Prüfen Sie in user_id_count, ob die Anzahl der empfangenen Nutzer-IDs Ihren Erwartungen entspricht.

Status der Entfernung von Zielgruppenmitgliedern

Das Feld audience_members_removal_status wird ausgefüllt, wenn die Anfrage ein RemoveAudienceMembersRequest war. Hier ist das Feld RemoveAudienceMembersStatus, das für jeden Typ von Zielgruppendaten geprüft werden muss. Es ist nur eines dieser Felder festgelegt.

composite_data_removal_status
Entfernungsstatus für Zusammengesetzte Daten
google_user_id_data_removal_status
Entfernungsstatus für Google-Nutzer-ID-Daten
mobile_data_removal_status
Entfernungsstatus für mobile Daten.
pair_data_removal_status
Entfernungsstatus für PAIR-Daten.
partner_provided_id_data_removal_status
Entfernungsstatus für vom Partner bereitgestellte ID-Daten
ppid_data_removal_status
Entfernungsstatus für PPID-Daten.
user_data_removal_status
Entfernungsstatus für Nutzerdaten.
user_id_data_removal_status
Entfernungsstatus für Nutzer-ID-Daten

Prüfen Sie record_count, um zu bestätigen, dass die Gesamtzahl der empfangenen Datensätze Ihren Erwartungen entspricht. Die record_count enthält sowohl erfolgreiche als auch fehlgeschlagene Einträge.

Prüfen Sie außerdem die user_identifier_count, mobile_id_count, pair_id_count, ppid_count, user_id_count, google_user_id_count oder partner_provided_id_count, um die Gesamtzahl der empfangenen Kennungen zu bestätigen.

Prüfen Sie bei zusammengesetzten Daten die data_type_counts, um zu bestätigen, dass die Anzahl der Kennungen Ihren Erwartungen entspricht. Diese Liste enthält eine Aufschlüsselung aller von DataType empfangenen Kennungen (z. B. E‑Mail-Adresse, Telefonnummer, Postanschrift und IP-Adresse).

Warnungen und Fehler prüfen

Zusätzlich zu den Statusfeldern für das Ziel und den Anfragetyp enthält die RetrieveRequestStatusResponse eine Aufschlüsselung der Warnungen und Fehler für die Anfrage.

  • Ein Fehler weist darauf hin, dass die API den Eintrag vollständig abgelehnt hat.

  • Eine Warnung gibt an, dass die API den Eintrag nicht abgelehnt hat, aber Teile der Daten des Eintrags ignorieren musste.

Wenn ein Event beispielsweise verschlüsselte UserIdentifier-Daten und AdIdentifiers wie gclid enthält und die UserIdentifier-Daten nicht entschlüsselt werden können, verarbeitet die Data Manager API den Datensatz trotzdem mit dem AdIdentifiers, gibt aber die Warnung PROCESSING_WARNING_REASON_USER_IDENTIFIER_DECRYPTION_ERROR zurück.

Wenn die Event jedoch keine AdIdentifiers enthält und die UserIdentifier-Daten nicht entschlüsselt werden können, lehnt die Data Manager API den gesamten Eintrag ab und meldet den Fehler PROCESSING_ERROR_REASON_USER_IDENTIFIER_DECRYPTION_ERROR, da eine gültige Event mindestens eine ad_identifiers oder user_data enthalten muss.

Hier sind die Antwortfelder, die Warn- und Fehlerinformationen enthalten. Diese Felder werden ausgefüllt, wenn der Gesamtstatus des Ziels SUCCESS, PARTIAL_SUCCESS oder FAILED erreicht.

warning_info

Ein WarningInfo-Objekt. Das Feld warning_counts enthält eine Liste von WarningCount-Objekten. Jeder WarningCount enthält einen reason mit dem Typ der Warnung und einen record_count, der die Anzahl der Datensätze mit diesem Typ von Warnung angibt.

Prüfen Sie den warning_info, auch wenn der Gesamtstatus des Ziels SUCCESS lautet.

error_info

Ein ErrorInfo-Objekt. Das Feld error_counts enthält eine Liste von ErrorCount-Objekten. Jeder ErrorCount enthält einen reason mit dem Fehlertyp und einen record_count, der die Anzahl der Datensätze angibt, die aufgrund dieses Fehlertyps fehlgeschlagen sind.

Abfragestrategie

Senden Sie die RetrieveRequestStatusRequest regelmäßig mit einem exponentiellen Backoff-Algorithmus, bis die request_status für jedes Ziel in der ursprünglichen Anfrage SUCCESS, FAILED oder PARTIAL_SUCCESS erreicht. Dies kann bis zu 24 Stunden dauern, obwohl die Data Manager API einige Anfragen in nur 30 Minuten verarbeiten kann.

Hier ist ein Beispiel für eine angemessene anfängliche Wartezeit und Wiederholungskonfiguration, die Aktivität und Kontingentnutzung in Einklang bringt:

Einstellung Wert
Wartezeit vor der ersten Diagnoseanfrage (Minuten) 30
Backoff-Multiplikator 1.3
Maximaler Backoff (Minuten) 60 (1 Stunde)
Maximale Gesamtzeit (Minuten) 1440 (24 Stunden)

Hier ist eine Abfolge von Anfragen und die verstrichene Zeit mit dieser Konfiguration:

Grafik

Abfragestrategie

Daten

Versuch Zeit seit der Aufnahme-Anfrage (hh:mm) Verzögerung vor Versuch Hinweise
1 00:30 30,0 Min. Zuerst die Verfügbarkeit des Status prüfen
2 01:09 39,0 Min.
3 01:59 50,7 Min.
4 02:59 60,0 Min. Die Verzögerung ist jetzt auf 1 Stunde begrenzt
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-Stunden-Marke
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. Letzte Anfrage vor der maximalen Gesamtzeit von 24 Stunden

Fügen Sie den Backoff-Verzögerungen einen kleinen zufälligen Jitter hinzu, um das „Thundering-Herd-Problem“ zu vermeiden, bei dem viele Clients gleichzeitig Wiederholungsversuche starten.

Autorisierungsanforderungen

Ein RetrieveRequestStatusRequest akzeptiert keine Zielkonten oder Anfrageheader. Stattdessen identifiziert die Data Manager API die Ziele aus der ursprünglichen Aufnahme-Anfrage, die mit der request_id verknüpft ist, und prüft, ob der Aufrufer Zugriff auf die operating_account für jede Destination hat.

Wenn Sie den Status einer Anfrage prüfen möchten, müssen die in einer RetrieveRequestStatusRequest verwendeten Anmeldedaten die folgenden Anforderungen für die operating_account jedes Ziels aus der ursprünglichen Aufnahme-Anfrage erfüllen:

  • Identischer Zugriffspfad: Die Anmeldedaten müssen Zugriff auf jede operating_account über den genau gleichen Zugriffspfad haben, der in der ursprünglichen Aufnahme-Anfrage angegeben wurde.

    Wenn beispielsweise in einer Aufnahme-Anfrage für ein Google Ads-operating_account ein übergeordnetes Verwaltungskonto als login_account angegeben wurde, müssen die Anmeldedaten auch über dasselbe Verwaltungskonto Zugriff auf das operating_account haben. Selbst wenn das mit den Anmeldedaten verknüpfte Google-Konto direkten Zugriff auf das untergeordnete operating_account hat, schlägt die Anfrage mit einem PERMISSION_DENIED-Fehler fehl, wenn dieses Konto keinen Zugriff über das während der Aufnahme angegebene login_account-Verwaltungskonto hat.

  • Ausreichende Zugriffsebene: Das mit den Anmeldedaten verknüpfte Google-Konto muss eine Zugriffsebene oder Rolle mit der Berechtigung zum Aufnehmen von Daten in operating_account haben.

    In Google Ads muss das Google-Konto beispielsweise die Zugriffsebene Administrator oder Standard haben. Eine Anfrage mit Anmeldedaten für ein Konto mit der Zugriffsebene Lesezugriff schlägt mit dem Fehler PERMISSION_DENIED fehl.

Zurück
Nutzerdaten verschlüsseln
Weiter
API-Fehler verstehen