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:

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

      "productDestinationId": "AUDIENCE_ID"
    }

  • Legen Sie operatingAccount auf den Kontotyp und die ID des Kontos fest, das die Zielgruppendaten empfängt.

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-, nach- und zwischengestellten 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 Destination und userData für den Anfragetext:

{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_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
}
  1. Aktualisieren Sie die Platzhalter im Text, z. B. OPERATING_ACCOUNT_TYPE, OPERATING_ACCOUNT_ID und AUDIENCE_ID, mit den Werten für Ihr Konto und Ziel.
  2. Setzen Sie validateOnly auf true, um die Anfrage zu validieren, ohne die Änderungen anzuwenden. Wenn Sie die Änderungen anwenden möchten, setzen Sie validateOnly auf false.
  3. Legen Sie termsOfService fest, um anzugeben, dass der Nutzer die Nutzungsbedingungen für den Kundenabgleich akzeptiert hat.
  4. Diese Anfrage weist darauf hin, dass consent gewährt wird und keine Verschlüsselung verwendet wird.

Anfrage senden

  1. Kopieren Sie den Anfragetext mit der Schaltfläche zum Kopieren oben rechts im Beispiel.
  2. Klicken Sie in der Symbolleiste auf die Schaltfläche API.
  3. Fügen Sie den kopierten Anfragetext in das Feld Request body (Anfragetext) ein.
  4. Klicken Sie auf die Schaltfläche Ausführen, füllen Sie die Autorisierungsaufforderungen aus und prüfen Sie die Antwort.

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, wenn 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 email_address 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 email_address, 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 Liste destinations für die Anfrage:

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

      "productDestinationId": "11112222",
      "reference": "audience_1"
    },
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_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 einer AudienceMember nicht festlegen, wird das Zielgruppenmitglied über die Data Manager API an alle Ziele in der Anfrage gesendet.

Nächste Schritte

Zurück
Zielgruppen