Diagnose

Hier finden Sie den empfohlenen Workflow, um den Status Ihrer Event- und Zielgruppen-Uploads zu prüfen und Probleme mit Ihren Daten zu ermitteln.

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

  2. Prüfen Sie den Gesamtstatus der einzelnen Anfragen. 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 Abrufen von Diagnosedaten verwenden können.

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

    Wiederholen Sie diesen Schritt regelmäßig für jede request_id, bis der Zielstatus für jedes Ziel SUCCESS, PARTIAL_SUCCESS oder FAILURE erreicht. Verwenden Sie einen exponentiellen Backoff-Algorithmus, 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.

Anfragen senden

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

Autorisierung

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 auf jedem 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 Erfassungsanfrage für ein Google Ads-Konto operating_account ein übergeordnetes Verwaltungskonto als login_account angegeben wurde, müssen die Anmeldedaten auch über dasselbe Verwaltungskonto Zugriff auf das operating_account haben. Auch 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 für dieses Konto kein Zugriff über das während der Aufnahme angegebene login_account-Verwaltungskonto besteht.

  • 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 dem Google-Konto beispielsweise die Zugriffsebene Administrator oder Standard zugewiesen sein. Eine Anfrage mit Anmeldedaten für ein Konto mit der Zugriffsebene Nur lesen schlägt mit dem Fehler PERMISSION_DENIED fehl.

Abfragestrategie

Senden Sie die RetrieveRequestStatusRequest regelmäßig mit einem exponentiellen Backoff-Algorithmus, bis der request_status für jedes Ziel in der ursprünglichen Anfrage SUCCESS, FAILURE oder PARTIAL_SUCCESS erreicht. Das kann bis zu 24 Stunden dauern. Bei einigen Anfragen kann die Verarbeitung über die Data Manager API jedoch auch schon nach 30 Minuten abgeschlossen sein.

Hier 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 sehen Sie eine Abfolge von Anfragen und die verstrichene Zeit bei dieser Konfiguration:

Grafik

Polling-Strategie

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 ausführen.

Antworten überprü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 enthält, um Daten an drei verschiedene Zielgruppen zu senden, enthält die Statusantwort drei Einträge in request_status_per_destination (ein Eintrag pro Zielgruppe).

Gesamtstatus des Ziels prüfen

Prüfen Sie zuerst das Feld request_status, um festzustellen, ob die Data Manager API die Verarbeitung der Daten für die destination der RequestStatusPerDestination 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.

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

  • FAILURE: 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 angezeigt wurden.

  • PARTIAL_SUCCESS: Einige der Datensätze für das Ziel wurden erfolgreich verarbeitet, 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.

Ereignis- oder Zielgruppenstatus nach Zielvorhaben 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 den record_count des 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 Zielgruppendatentyp geprüft werden muss. Nur eines dieser Felder ist 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 auf der data_type_counts, ob die Anzahl der Kennzeichnungen 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 die record_count von 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 google_user_id_count, um zu bestätigen, dass 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 in der mobile_id_count, 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 in der pair_id_count, ob die Anzahl der erhaltenen PAIR-IDs Ihren Erwartungen entspricht.

partner_provided_id_data_ingestion_status

Prüfen Sie das Feld record_count des 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 anhand der partner_provided_id_count, ob die Anzahl der 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 der 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 die record_count der 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 eine RemoveAudienceMembersRequest war. Hier ist das Feld RemoveAudienceMembersStatus, das für jeden Typ von Zielgruppendaten geprüft werden muss. Nur eines dieser Felder ist 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 Datensätze.

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 RetrieveRequestStatusResponse eine Aufschlüsselung der Warnungen und Fehler für die Anfrage.

  • Ein Fehler bedeutet, dass der Datensatz von der API vollständig abgelehnt wurde.
  • Eine Warnung gibt an, dass die API den Datensatz nicht abgelehnt hat, aber Teile der Daten des Datensatzes 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 den 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 FAILURE erreicht.

warning_info

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

Prüfen Sie warning_info auch dann, 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.