Best Practices

Beachten Sie bei der Verwendung der Data Manager API die folgenden Best Practices.

Alle Nutzer-IDs senden

Unabhängig davon, ob Sie Zielgruppenmitglieder oder Ereignisse mit UserData senden, sollten Sie so viele user_identifiers wie möglich einbeziehen, einschließlich mehrerer Kennungen desselben Typs.

Wenn Sie beispielsweise mehrere E-Mail-Adressen für einen Nutzer haben, fügen Sie für jede E-Mail-Adresse ein separates UserIdentifier ein. Wenn Sie verschiedene Arten von Kennungen für einen Nutzer haben, z. B. E-Mail-Adressen, Telefonnummern und Adressen, fügen Sie für jede Kennung ein separates UserIdentifier-Element hinzu, bis die maximale Anzahl von Kennungen erreicht ist.

Anfragen optimieren

Um die Wahrscheinlichkeit zu verringern, dass die täglichen Limits für Anfragen überschritten werden, sollten Sie so viele Elemente wie möglich in jeder Anfrage zusammenfassen, bis die Limits pro Anfrage erreicht sind.

Wenn Sie beispielsweise 10.000 Zielgruppenmitglieder zu einer Zielgruppe hinzufügen möchten, fügen Sie alle 10.000 Mitglieder in der Liste audience_members in einem IngestAudienceMembersRequest hinzu. Es ist effizienter, alle 10.000 Mitglieder in einer einzigen Anfrage zusammenzufassen, als für jedes Zielgruppenmitglied eine separate Anfrage zu senden.

Gleichzeitige Anfragen senden

Wenn Sie die Gesamtzeit für die Datenaufnahme reduzieren möchten, senden Sie gleichzeitige Anfragen an die IngestionService. Wir empfehlen, bis zu 10 Anfragen gleichzeitig zu senden, um die Wahrscheinlichkeit zu verringern, dass das Limit für Anfragen pro Minute überschritten wird.

Sie können gleichzeitige Anfragen senden, auch wenn die Anfragen dieselbe destinations haben.

Daten auf der Clientseite validieren

Die Data Manager API verwendet ein Fast-Fail-Modell. Wenn ein Eintrag in einer Anfrage die synchrone Validierung nicht besteht, schlägt die gesamte Anfrage fehl und keiner der Einträge wird verarbeitet. Außerdem werden Anfragen von der API in sequenziellen Ebenen validiert. Wenn Sie also einen Fehler beheben, kann ein Fehler aus einer nachfolgenden Validierungsebene auftreten.

Um wiederholte Roundtrips und abgelehnte Anfragen zu vermeiden, sollten Sie Ihre Daten vor dem Senden validieren und bereinigen:

• Leere Werte vor dem Hashen entfernen: Prüfen Sie Felder wie email_address und phone_number auf leere Strings oder Strings, die nur Leerzeichen enthalten, bevor Sie SHA-256-Hashes berechnen. Das Hashen eines leeren Strings führt zu einem gültigen Hash, der die Syntaxprüfungen besteht, aber die Abgleichsraten beeinträchtigt.

• Unvollständige zusammengesetzte Objekte verwerfen: Achten Sie darauf, dass zusammengesetzte Objekte alle erforderlichen Felder enthalten, bevor Sie sie einem Eintrag hinzufügen. Wenn beispielsweise in einem AddressInfo-Objekt eines der vier erforderlichen Felder (given_name, family_name, region_code oder postal_code) fehlt, verwerfen Sie die gesamte address-ID, um REQUIRED_FIELD_MISSING-Fehler zu vermeiden.

• Codierungs- und Klartextfelder validieren: Prüfen Sie, ob gehashte Felder mit dem deklarierten encoding übereinstimmen, anstatt Rohklartext zu senden. Achten Sie darauf, dass Felder, die im Klartext bleiben müssen (z. B. mobile_ids), nicht gehasht werden.

• Zeitstempel außerhalb des zulässigen Bereichs herausfiltern: Achten Sie darauf, dass Zeitstempel nicht in der Zukunft liegen oder älter als das Lookback-Window für Conversions des Ziels sind.

  Wenn Sie Anfragen im JSON-Format senden, müssen Zeitstempelstrings das RFC 3339-Format mit einem Zeitzonen-Offset verwenden.

• Telefonnummern bereinigen: Prüfen Sie, ob Telefonnummern eine Landesvorwahl enthalten und vor dem Hashen das E.164-Format verwendet wird.

• Leere oder zu große Datensätze entfernen: Begrenzen Sie user_identifiers auf das Limit pro Datensatz (10 IDs), löschen Sie leere benutzerdefinierte Parameter und lassen Sie alle Datensätze weg, die keine gültigen IDs enthalten.

• Anforderungen für Anwendungsfälle prüfen: Jedes Ereignis muss alle Pflichtfelder für das Ziel und den Anwendungsfall enthalten (z. B. transaction_id für Google Ads-Online-Conversions). Eine vollständige Liste der erforderlichen Felder nach Anwendungsfall finden Sie in der Anleitung zum Senden von Ereignissen für Ihr Ziel in der Ereignisübersicht.

• Anfragen mit validateOnly testen: Senden Sie Anfragen, bei denen validateOnly auf true gesetzt ist, um Fast-Fail-Fehler zu erkennen, ohne Daten aufzunehmen oder zu entfernen. Eine erfolgreiche Anfrage nur zur Validierung ist keine Garantie dafür, dass bei der asynchronen Verarbeitung keine Fehler auftreten. Sie sollten daher nach dem Senden einer regulären Anfrage weiterhin den Anfragestatus und die Diagnosedaten prüfen.

Detaillierte Regeln zur Normalisierung und zum Hashing finden Sie unter Nutzerdaten formatieren.

Anfragestatus und Diagnoseinformationen prüfen

Erfassen und sammeln Sie die request_id aus jedem IngestAudienceMembersResponse oder IngestEventsResponse und verwenden Sie die Anfrage-IDs, um den Anfragestatus und die Diagnosedaten zu prüfen.

Kontingente überwachen und Benachrichtigungen ausgeben

Um unerwartete Ablehnungen von Anfragen zu vermeiden, richten Sie in der Google Cloud Console Kontingentbenachrichtigungen und Monitoring ein. Wenn Sie die Kontingentnutzung im Blick behalten, können Sie Nutzungsmuster nachvollziehen und die Batchverarbeitung von Anfragen optimieren, bevor Ihre Anwendung die Tages- oder Minutenlimits erreicht.

Für die Produktion bereitstellen

Wenn Sie von lokalen Tests zu Produktionsarbeitslasten wechseln, verwenden Sie Standardanmeldedaten für Anwendungen mit einem angehängten Dienstkonto oder Workload Identity-Föderation, um sich nicht interaktiv und sicher zu authentifizieren.

Weitere Informationen zum Konfigurieren der Authentifizierung für verschiedene Produktionsumgebungen finden Sie unter In Produktion bereitstellen.