[Ultimate]{class="badge positive"}

HTTP-API-Verbindung

Überblick overview

Das HTTP-API-Ziel ist ein Experience Platform-Streaming-Ziel, mit dem Sie Profildaten an HTTP-Endpunkte von Drittanbietern senden können.

Um Profildaten an HTTP-Endpunkte zu senden, müssen Sie in Experience Platform zunächst eine Verbindung zum ​ herstellen).

Anwendungsfälle use-cases

Verwenden Sie das HTTP-API-Ziel, um XDM-Profildaten und -Zielgruppen in generische HTTP-Endpunkte zu exportieren. Dort können Sie Ihre eigenen Analysen oder beliebige andere Vorgänge ausführen, die Sie für aus Experience Platform exportierte Profildaten benötigen.

HTTP-Endpunkte können entweder eigene Systeme von Kunden oder Lösungen von Drittanbietern sein.

Unterstützte Zielgruppen supported-audiences

In diesem Abschnitt wird beschrieben, welche Arten von Zielgruppen Sie an dieses Ziel exportieren können.

Unterstützte Zielgruppen nach Zielgruppen-Datentyp:

Exporttyp und -häufigkeit export-type-frequency

Beziehen Sie sich auf die folgende Tabelle, um Informationen zu Typ und Häufigkeit des Zielexports zu erhalten.

Voraussetzungen prerequisites

Um Daten aus Experience Platform mithilfe des HTTP-API-Ziels zu exportieren, müssen folgende Voraussetzungen erfüllt sein:

Unterstützung und Zertifikat des mTLS-Protokolls mtls-protocol-support

Sie können Mutual Transport Layer Security (mTLS) verwenden, um erweiterte Sicherheit bei ausgehenden Verbindungen zu Ihren HTTP-API-Zielverbindungen zu gewährleisten.

mTLS ist ein gegenseitiges Authentifizierungsprotokoll, das sicherstellt, dass beide Parteien, die Informationen austauschen, vor der Datenfreigabe diejenigen sind, die sie zu sein behaupten. mTLS enthält einen zusätzlichen Schritt im Vergleich zu Standard-TLS, bei dem der Server auch das Zertifikat des Clients anfordert und überprüft, während der Client das Zertifikat des Servers überprüft.

Überlegungen zu mTLS mtls-considerations

Die mTLS-Unterstützung für HTTP-API Ziele gilt nur für den Datenempfangsendpunkt an den Profilexporte gesendet werden (das HTTP Endpoint Feld in Zieldetails).

Konfigurieren von TLS für den Datenexport configuring-mtls

Um mTLS mit HTTP-API-Zielen verwenden zu können, müssen für den HTTP Endpoint (Datenempfangsendpunkt), den Sie auf der Seite Zieldetails konfigurieren, TLS-Protokolle deaktiviert und nur mTLS aktiviert sein. Wenn das TLS 1.2-Protokoll weiterhin auf dem Endpunkt aktiviert ist, wird kein Zertifikat für die Client-Authentifizierung gesendet. Das bedeutet, dass Ihr Datenempfangsserver-Endpunkt ein nur für mTLS aktivierter Verbindungsendpunkt sein muss, um mTLS mit Ihrem HTTP-API-Ziel verwenden zu können.

Abrufen und Überprüfen von Zertifikatdetails certificate

Wenn Sie Zertifikatdetails wie Common Name (CN) und Subject Alternative Names (SAN) auf zusätzliche Validierungen durch Drittanbieter überprüfen möchten, verwenden Sie die -API, um das Zertifikat abzurufen und diese Felder aus der Antwort zu extrahieren.

Weitere Informationen finden ​ in der ​ zum öffentlichen Zertifikatendpunkt .

Zulassungsliste von IP-Adressen ip-address-allowlist

Um die Sicherheits- und Compliance-Anforderungen von Kunden zu erfüllen, stellt Experience Platform eine Liste mit statischen IPs bereit, die Sie für das HTTP-API-Ziel auf die Zulassungsliste setzen können. Siehe IP-Adresse für Streaming-Ziele für die vollständige Liste der zu auf die Zulassungsliste setzend IPs.

Unterstützte Authentifizierungstypen supported-authentication-types

Das HTTP-API-Ziel unterstützt mehrere Authentifizierungstypen für Ihren HTTP-Endpunkt:

curl --location --request POST '<YOUR_API_ENDPOINT>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<CLIENT_ID>' \
--data-urlencode 'client_secret=<CLIENT_SECRET>'

curl --location --request POST 'https://some-api.com/token' \
--header 'Authorization: Basic base64(clientId:clientSecret)' \
--header 'Content-type: application/x-www-form-urlencoded; charset=UTF-8' \
--data-urlencode 'grant_type=client_credentials'

Herstellen einer Verbindung mit dem Ziel connect-destination

Um eine Verbindung mit diesem Ziel herzustellen, gehen Sie wie im Tutorial zur Zielkonfiguration beschrieben vor. Beim Herstellen einer Verbindung zu diesem Ziel müssen Sie die folgenden Informationen angeben:

Authentifizierungsinformationen authentication-information

Authentifizierung über Bearer-Token bearer-token-authentication

Wenn Sie den Authentifizierungstyp Bearer token für die Verbindung mit Ihrem HTTP-Endpunkt wählen, geben Sie die folgenden Informationen ein und wählen Sie Connect to destination:

Keine Authentifizierung no-authentication

Wenn Sie den Authentifizierungstyp None für die Verbindung mit Ihrem HTTP-Endpunkt auswählen:

Wenn Sie diese Authentifizierungsoption auswählen, brauchen Sie nur Connect to destination auszuwählen, und die Verbindung zu Ihrem Endpunkt wird hergestellt.

Passwort-Authentifizierung für OAuth 2 oauth-2-password-authentication

Wenn Sie den Authentifizierungstyp OAuth 2 Password für die Verbindung mit Ihrem HTTP-Endpunkt wählen, geben Sie die folgenden Informationen ein und wählen Sie Connect to destination:

Authentifizierung mit Client-Anmeldedaten für OAuth 2 oauth-2-client-credentials-authentication

Wenn Sie den Authentifizierungstyp OAuth 2 Client Credentials für die Verbindung mit Ihrem HTTP-Endpunkt wählen, geben Sie die folgenden Informationen ein und wählen Sie Connect to destination:

Ausfüllen der Zieldetails destination-details

Füllen Sie die folgenden erforderlichen und optionalen Felder aus, um Details für das Ziel zu konfigurieren. Ein Sternchen neben einem Feld in der Benutzeroberfläche zeigt an, dass das Feld erforderlich ist.

Aktivieren von Warnhinweisen enable-alerts

Sie können Warnhinweise aktivieren, um Benachrichtigungen zum Status des Datenflusses zu Ihrem Ziel zu erhalten. Wählen Sie einen Warnhinweis aus der zu abonnierenden Liste aus, um Benachrichtigungen über den Status Ihres Datenflusses zu erhalten. Weitere Informationen zu Warnhinweisen finden Sie im Handbuch zum Abonnieren von Zielwarnhinweisen über die Benutzeroberfläche.

Wenn Sie mit dem Eingeben der Details für Ihre Zielverbindung fertig sind, wählen Sie Next aus.

Aktivieren von Zielgruppen für dieses Ziel activate

Anweisungen ​ Aktivieren von Zielgruppen für dieses Ziel finden Sie ​ „Aktivieren von Zielgruppendaten für Streaming Profilexportziele“.

Zielattribute attributes

Im Select attributes Schritt empfiehlt Adobe die Auswahl einer eindeutigen Kennung aus Ihrem Vereinigungsschema. Wählen Sie die eindeutige Kennung und alle anderen XDM-Felder aus, die Sie an das Ziel exportieren möchten.

Profilexportverhalten profile-export-behavior

Experience Platform optimiert das Verhalten beim Profilexport für Ihr HTTP-API-Ziel, sodass nur Daten an Ihren API-Endpunkt exportiert werden, wenn relevante Profilaktualisierungen nach der Zielgruppen-Qualifizierung oder anderen wichtigen Ereignissen durchgeführt wurden. Profile werden in den folgenden Situationen an Ihr Ziel exportiert:

In allen oben beschriebenen Fällen werden nur die Profile exportiert, in denen relevante Aktualisierungen vorgenommen wurden. Wenn beispielsweise eine dem Zielfluss zugeordnete Zielgruppe aus hundert Mitgliedern besteht und fünf neue Profile für die Zielgruppe qualifiziert sind, ist der Export in Ihr Ziel inkrementell und umfasst nur die fünf neuen Profile.

Was bestimmt einen Datenexport und was ist im Export enthalten? what-determines-export-what-is-included

Was die Daten betrifft, die für ein bestimmtes Profil exportiert werden, ist es wichtig, die beiden verschiedenen Konzepte zu verstehen, nämlich was den Datenexport an Ihr HTTP-API-Ziel bestimmt und welche Daten im Export enthalten sind.

Betrachten Sie beispielsweise den folgenden Datenfluss an ein HTTP-Ziel, bei dem im Datenfluss drei Zielgruppen ausgewählt und dem Ziel vier Attribute zugeordnet sind.

Ein Profilexport an das Ziel wird ausgelöst, wenn ein Profil sich für eine der (zugeordneten Zielgruppen) qualifiziert oder. Im Datenexport kann das segmentMembership-Objekt (siehe Exportierte Daten unten) auch nicht zugeordnete Zielgruppen enthalten, wenn dieses Profil zu ihnen gehört und diese Zielgruppen dieselbe Zusammenführungsrichtlinie wie die Zielgruppe verwenden, die den Export ausgelöst hat. Wenn sich beispielsweise ein Profil für die Zielgruppe Kunde mit DeLorean-) qualifiziert, aber auch Mitglied der Zielgruppen Hat „Zurück in die Zukunft“ und Science-Fiction-" ist, werden diese beiden Zielgruppen ebenfalls im segmentMembership-Objekt angezeigt, sofern sie dieselbe Zusammenführungsrichtlinie für die Zielgruppe Kunde mit DeLorean-Autos verwenden.

Aus Sicht der Profilattribute bestimmen alle Änderungen an den vier oben zugeordneten Attributen einen Zielexport, und eines der vier im Profil vorhandenen zugeordneten Attribute wird im Datenexport vorhanden sein.

Aufstockung historischer Daten historical-data-backfill

Wenn Sie eine neue Zielgruppe zu einem vorhandenen Ziel hinzufügen oder wenn Sie ein neues Ziel erstellen und diesem Zielgruppen zuordnen, exportiert Experience Platform historische Zielgruppen-Qualifizierungsdaten an das Ziel. Profile, die sich für die Zielgruppe qualifiziert haben zuvor wurde die Zielgruppe zum Ziel hinzugefügt, werden innerhalb von etwa einer Stunde an das Ziel exportiert.

Exportierte Daten exported-data

Ihre exportierten Experience Platform-Daten landen in Ihrem HTTP-Ziel im JSON-Format. Der folgende Export enthält beispielsweise ein Profil, das sich für eine bestimmte Zielgruppe qualifiziert hat, Mitglied zweier weiterer Zielgruppen ist und eine andere Zielgruppe verlassen hat. Der Export umfasst außerdem Vorname, Nachname, Geburtsdatum und persönliche E-Mail-Adresse des Profilattributs. Die Identitäten für dieses Profil sind ECID und E-Mail.

{
  "person": {
    "birthDate": "YYYY-MM-DD",
    "name": {
      "firstName": "John",
      "lastName": "Doe"
    }
  },
  "personalEmail": {
    "address": "john.doe@acme.com"
  },
  "segmentMembership": {
   "ups":{
      "7841ba61-23c1-4bb3-a495-00d3g5fe1e93":{
         "lastQualificationTime":"2022-01-11T21:24:39Z",
         "status":"exited"
      },
      "59bd2fkd-3c48-4b18-bf56-4f5c5e6967ae":{
         "lastQualificationTime":"2022-01-02T23:37:33Z",
         "status":"realized"
      },
      "947c1c46-008d-40b0-92ec-3af86eaf41c1":{
         "lastQualificationTime":"2021-08-25T23:37:33Z",
         "status":"realized"
      },
      "5114d758-ce71-43ba-b53e-e2a91d67b67f":{
         "lastQualificationTime":"2022-01-11T23:37:33Z",
         "status":"realized"
      }
   }
},
  "identityMap": {
    "ecid": [
      {
        "id": "14575006536349286404619648085736425115"
      },
      {
        "id": "66478888669296734530114754794777368480"
      }
    ],
    "email_lc_sha256": [
      {
        "id": "655332b5fa2aea4498bf7a290cff017cb4"
      },
      {
        "id": "66baf76ef9de8b42df8903f00e0e3dc0b7"
      }
    ]
  }
}

Im Folgenden finden Sie weitere Beispiele für exportierte Daten, abhängig von den Benutzeroberflächeneinstellungen, die Sie im Fluss „Ziel verbinden“ für die Optionen Include Segment Names und Include Segment Timestamps auswählen:

"segmentMembership": {
        "ups": {
          "5b998cb9-9488-4ec3-8d95-fa8338ced490": {
            "lastQualificationTime": "2019-04-15T02:41:50+0000",
            "status": "realized",
            "createdAt": 1648553325000,
            "updatedAt": 1648553330000,
            "mappingCreatedAt": 1649856570000,
            "mappingUpdatedAt": 1649856570000,
            "name": "First name equals John"
          },
          "354e086f-2e11-49a2-9e39-e5d9a76be683": {
            "lastQualificationTime": "2020-04-15T02:41:50+0000",
            "status": "realized"
          }
        }
      }

"segmentMembership": {
        "ups": {
          "5b998cb9-9488-4ec3-8d95-fa8338ced490": {
            "lastQualificationTime": "2019-04-15T02:41:50+0000",
            "status": "realized",
            "createdAt": 1648553325000,
            "updatedAt": 1648553330000,
            "mappingCreatedAt": 1649856570000,
            "mappingUpdatedAt": 1649856570000
          }
        }
      }

Beschränkungen und Wiederholungsrichtlinien limits-retry-policy

In 95 Prozent der Fälle versucht Experience Platform, eine Durchsatzlatenz von weniger als 10 Minuten für erfolgreich gesendete Nachrichten mit einer Rate von weniger als 10.000 Anfragen pro Sekunde für jeden Datenfluss an ein HTTP-Ziel anzubieten.

Wenn Anfragen an Ihr HTTP-API-Ziel fehlschlagen, speichert Experience Platform sie und versucht es zweimal.

Fehlerbehebung troubleshooting

Um eine zuverlässige Datenbereitstellung zu gewährleisten und Zeitüberschreitungsprobleme zu vermeiden, stellen Sie sicher, dass Ihr HTTP-Endpunkt innerhalb von 2 Sekunden auf Experience Platform-Anfragen reagiert, wie im Abschnitt Voraussetzungen angegeben. Antworten, die länger dauern, führen zu Zeitüberschreitungsfehlern.