Zielgruppenmitglieder senden

In dieser Kurzanleitung erfahren Sie mehr über die Data Manager API. Wählen Sie die gewünschte Version des Schnellstarts aus:

In dieser Kurzanleitung führen Sie die folgenden Schritte aus:

  1. Bereiten Sie ein Destination vor, um Zielgruppendaten zu empfangen.
  2. Zielgruppendaten für den Versand vorbereiten
  3. Erstellen Sie eine IngestionService-Anfrage für Zielgruppenmitglieder.
  4. Senden Sie die Anfrage mit dem Google APIs Explorer.
  5. Erfolgs- und Fehlerantworten verstehen

Ziel vorbereiten

Bevor Sie Daten senden können, müssen Sie das Ziel vorbereiten. Hier ist ein Beispiel für Destination, das Sie verwenden können. Unter Ziele konfigurieren finden Sie Beispiele für Ziele für verschiedene Szenarien.

    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_TYPE",
        "accountId": "LOGIN_ACCOUNT_ID"
      },

      "productDestinationId": "AUDIENCE_ID"
    }
  • Legen Sie operatingAccount auf den Kontotyp und die ID des Kontos fest, das die Zielgruppendaten empfängt.
  • Wenn Ihre OAuth-Anmeldedaten für einen Nutzer mit Zugriff auf ein Google Ads-Verwaltungskonto gelten, das operatingAccount als eines seiner Unterkonten hat, legen Sie loginAccount auf den Kontotyp und die ID des Verwaltungskontos fest.
  • Wenn die OAuth-Anmeldedaten für einen Nutzer mit direktem Zugriff auf die operatingAccount sind, müssen Sie loginAccount nicht festlegen.

Zielgruppendaten vorbereiten

Sehen Sie sich die folgenden Beispieldaten in einer durch Kommas getrennten Datei an. Jede Zeile in der Datei entspricht einem Mitglied der Zielgruppe und jedes Mitglied hat bis zu drei E-Mail-Adressen.

#,email_1,email_2,email_3
1,dana@example.com,DanaM@example.com,
2,ALEXJ@example.com, AlexJ@cymbalgroup.com,alexj@altostrat.com
3,quinn@CYMBALGROUP.com,baklavainthebalkans@gmail.com  ,
4,rosario@example.org,cloudySanFrancisco@GMAIL.com,

Für E-Mail-Adressen gelten die folgenden Formatierungs- und Hashing-Anforderungen:

  1. Entfernen Sie alle voran-, nachgestellten und dazwischenliegenden Leerzeichen.
  2. Wandeln Sie die E-Mail-Adresse in Kleinbuchstaben um.
  3. Hashen Sie die E-Mail-Adresse mit dem SHA-256-Algorithmus.
  4. Codieren Sie die Hash-Bytes mit Hexadezimalzahlen (Hex) oder Base64-Codierung. In den Beispielen in diesem Leitfaden wird die Hexadezimalcodierung verwendet.

So sehen die formatierten Daten aus:

#,email_1,email_2,email_3
1,dana@example.com,danam@example.com,
2,alexj@example.com,alexj@cymbalgroup.com,alexj@altostrat.com
3,quinn@cymbalgroup.com,baklavainthebalkans@gmail.com,
4,rosario@example.org,cloudysanfrancisco@gmail.com,

So sehen die Daten nach dem Hashen und Codieren aus:

#,email_1,email_2,email_3
1,07e2f1394b0ea80e2adca010ea8318df697001a005ba7452720edda4b0ce57b3,1df6b43bc68dd38eca94e6a65b4f466ae537b796c81a526918b40ac4a7b906c7
2,2ef46c4214c3fc1b277a2d976d55194e12b899aa50d721f28da858c7689756e3,54e410b14fa652a4b49b43aff6eaf92ad680d4d1e5e62ed71b86cd3188385a51,e8bd3f8da6f5af73bec1ab3fbf7beb47482c4766dfdfc94e6bd89e359c139478
3,05bb62526f091b45d20e243d194766cca8869137421047dc53fa4876d111a6f0,f1fcde379f31f4d446b76ee8f34860eca2288adc6b6d6c0fdc56d9eee75a2fa5
4,83a834cc5327bc4dee7c5408988040dc5813c7662611cd93b707aff72bf7d33f,223ebda6f6889b1494551ba902d9d381daf2f642bae055888e96343d53e9f9c4

Hier sehen Sie ein Beispiel für AudienceMember für die formatierten, gehashten und codierten E-Mail-Adressen von dana@example.com und danam@example.com aus der ersten Zeile der Eingabedaten:

{
  "userData": {
    "userIdentifiers": [
      {
        "emailAddress": "07e2f1394b0ea80e2adca010ea8318df697001a005ba7452720edda4b0ce57b3"
      },
      {
        "emailAddress": "1df6b43bc68dd38eca94e6a65b4f466ae537b796c81a526918b40ac4a7b906c7"
      }
    ]
  }
}

Anfragetext erstellen

Kombinieren Sie zum Erstellen des Anfragetexts die Felder destinations und audienceMembers, legen Sie das Feld encoding fest und fügen Sie alle anderen gewünschten Anfragefelder wie validateOnly und consent hinzu.

Wenn Sie Zielgruppenmitglieder für den Kundenabgleich senden, legen Sie termsOfService fest, um anzugeben, ob der Nutzer die Nutzungsbedingungen für den Kundenabgleich akzeptiert hat.

In den Beispielen in diesem Leitfaden wird keine Verschlüsselung verwendet. Sie können aber der Anleitung unter Nutzerdaten verschlüsseln folgen, um Ihrem Prozess eine Verschlüsselung hinzuzufügen.

Anfrage senden

  1. Klicken Sie auf Im API Explorer öffnen, um den API Explorer in einem neuen Tab oder Fenster zu öffnen.
  2. Ersetzen Sie im Anfragetext im API Explorer jeden String, der mit REPLACE_WITH beginnt, z. B. REPLACE_WITH_OPERATING_ACCOUNT_TYPE, durch den entsprechenden Wert.
  3. Klicken Sie unten auf der Seite „API Explorer“ auf Ausführen und folgen Sie der Anleitung zur Autorisierung, um die Anfrage zu senden.
  4. Setzen Sie validateOnly auf true, um die Anfrage zu validieren, ohne die Änderungen zu übernehmen. Wenn Sie die Änderungen anwenden möchten, legen Sie validateOnly auf false fest.

Aufnahmeanfrage

Im API Explorer öffnen 
{
    "destinations": [
        {
            "operatingAccount": {
                "accountType": "OPERATING_ACCOUNT_TYPE",
                "accountId": "OPERATING_ACCOUNT_ID"
            },
            "loginAccount": {
                "accountType": "LOGIN_ACCOUNT_TYPE",
                "accountId": "LOGIN_ACCOUNT_ID"
            },
            "productDestinationId": "AUDIENCE_ID"
        }
    ],
    "audienceMembers": [
        {
            "userData": {
                "userIdentifiers": [
                    {
                        "emailAddress": "07e2f1394b0ea80e2adca010ea8318df697001a005ba7452720edda4b0ce57b3"
                    },
                    {
                        "emailAddress": "1df6b43bc68dd38eca94e6a65b4f466ae537b796c81a526918b40ac4a7b906c7"
                    }
                ]
            }
        },
        {
            "userData": {
                "userIdentifiers": [
                    {
                        "emailAddress": "2ef46c4214c3fc1b277a2d976d55194e12b899aa50d721f28da858c7689756e3"
                    },
                    {
                        "emailAddress": "54e410b14fa652a4b49b43aff6eaf92ad680d4d1e5e62ed71b86cd3188385a51"
                    },
                    {
                        "emailAddress": "e8bd3f8da6f5af73bec1ab3fbf7beb47482c4766dfdfc94e6bd89e359c139478"
                    }
                ]
            }
        },
        {
            "userData": {
                "userIdentifiers": [
                    {
                        "emailAddress": "05bb62526f091b45d20e243d194766cca8869137421047dc53fa4876d111a6f0"
                    },
                    {
                        "emailAddress": "f1fcde379f31f4d446b76ee8f34860eca2288adc6b6d6c0fdc56d9eee75a2fa5"
                    }
                ]
            }
        },
        {
            "userData": {
                "userIdentifiers": [
                    {
                        "emailAddress": "83a834cc5327bc4dee7c5408988040dc5813c7662611cd93b707aff72bf7d33f"
                    },
                    {
                        "emailAddress": "223ebda6f6889b1494551ba902d9d381daf2f642bae055888e96343d53e9f9c4"
                    }
                ]
            }
        }
    ],
    "consent": {
        "adUserData": "CONSENT_GRANTED",
        "adPersonalization": "CONSENT_GRANTED"
    },
    "encoding": "HEX",
    "termsOfService": {
        "customerMatchTermsOfServiceStatus": "ACCEPTED"
    },
    "validateOnly": true
}

Erfolgsantworten

Eine erfolgreiche Anfrage gibt eine Antwort mit einem Objekt zurück, das eine requestId enthält.

{
  "requestId": "126365e1-16d0-4c81-9de9-f362711e250a"
}

Erfassen Sie die zurückgegebene requestId, damit Sie Diagnosedaten abrufen können, während die einzelnen Ziele in der Anfrage verarbeitet werden.

Fehlerantworten

Eine fehlgeschlagene Anfrage führt zu einem Fehlerantwort-Statuscode wie 400 Bad Request und einer Antwort mit Fehlerdetails.

Wenn beispielsweise ein emailAddress einen Nur-Text-String anstelle eines hexadezimal codierten Werts enthält, wird die folgende Antwort zurückgegeben:

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "audience_members.audience_members[0].user_data.user_identifiers",
            "description": "Email is not hex encoded.",
            "reason": "INVALID_HEX_ENCODING"
          }
        ]
      }
    ]
  }
}

Eine emailAddress, die nicht gehasht und nur hexadezimal codiert ist, führt zu folgender Antwort:

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "audience_members.audience_members[0]",
            "reason": "INVALID_SHA256_FORMAT"
          }
        ]
      }
    ]
  }
}

Ereignisse für mehrere Ziele senden

Wenn Ihre Daten Zielgruppenmitglieder für verschiedene Ziele enthalten, können Sie sie mit Zielreferenzen im selben Request senden.

Wenn Sie beispielsweise ein Zielgruppenmitglied für die Nutzerlisten-ID 11112222 und ein weiteres Zielgruppenmitglied für die Nutzerlisten-ID 77778888 haben, senden Sie beide Zielgruppenmitglieder in einer einzelnen Anfrage, indem Sie die reference der einzelnen Destination festlegen. Die reference ist nutzerdefiniert. Die einzige Anforderung ist, dass jede Destination eine eindeutige reference hat. Hier ist die geänderte destinations-Liste für die Anfrage:

  "destinations": [
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_TYPE",
        "accountId": "LOGIN_ACCOUNT_ID"
      },

      "productDestinationId": "11112222",
      "reference": "audience_1"
    },
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_2_TYPE",
        "accountId": "OPERATING_ACCOUNT_2_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_2_TYPE",
        "accountId": "LOGIN_ACCOUNT_2_ID"
      },

      "productDestinationId": "77778888",
      "reference": "audience_2"
    }
  ]

Legen Sie den destination_references für jede AudienceMember fest, um sie an ein oder mehrere bestimmte Ziele zu senden. Hier ist beispielsweise ein AudienceMember, das nur für das erste Destination gilt. Die destination_references-Liste enthält also nur die reference des ersten Destination:

{
  "userData": {
    "userIdentifiers": [
      {
        "emailAddress": "07e2f1394b0ea80e2adca010ea8318df697001a005ba7452720edda4b0ce57b3"
      },
      {
        "emailAddress": "1df6b43bc68dd38eca94e6a65b4f466ae537b796c81a526918b40ac4a7b906c7"
      }
    ],
  }
  "destinationReferences": [
    "audience_1"
  ]
}

Das Feld destination_references ist eine Liste. Sie können also mehrere Ziele für ein Zielgruppenmitglied angeben. Wenn Sie die destination_references eines AudienceMember nicht festlegen, sendet die Data Manager API das Zielgruppenmitglied an alle Ziele in der Anfrage.

Nächste Schritte

Zurück
Zielgruppen