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": {
        "product": "OPERATING_ACCOUNT_PRODUCT",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "AUDIENCE_ID"
    }

  • Legen Sie operatingAccount auf das Produkt 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": {
        "product": "OPERATING_ACCOUNT_PRODUCT",
        "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_PRODUCT, 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, folgen Sie der Anleitung zur Autorisierung 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"
}

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"
          }
        ]
      }
    ]
  }
}

Nächste Schritte