[Ultimate]{class="badge positive"}

HTTP-API-Verbindung

Übersicht overview

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

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

Anwendungsbeispiele use-cases

Mit dem HTTP-API-Ziel können Sie XDM-Profildaten und -Zielgruppen in allgemeine HTTP-Endpunkte 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 Zielgruppentypen Sie an dieses Ziel exportieren können.

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:

mTLS-Protokollunterstützung und -Zertifikat mtls-protocol-support

Sie können Mutual Transport Layer Security (mTLS) verwenden, um eine höhere Sicherheit bei ausgehenden Verbindungen zu Ihren HTTP-API-Zielverbindungen sicherzustellen.

mTLS ist eine durchgängige Sicherheitsmethode für die gegenseitige Authentifizierung, mit der sichergestellt wird, dass beide Parteien, die Informationen teilen, die sind, die sie angeblich sind, bevor Daten freigegeben werden. mTLS enthält einen zusätzlichen Schritt im Vergleich zu TLS, bei dem der Server auch nach dem Zertifikat des Clients fragt und es an dessen Ende überprüft.

Wenn Sie mTLS mit HTTP API -Zielen verwenden möchten, muss für die Serveradresse, die Sie auf der Seite Zieldetails eingegeben haben, TLS Protokolle deaktiviert und nur mTLS aktiviert sein. Wenn das Protokoll TLS 1.2 noch am -Endpunkt aktiviert ist, wird kein Zertifikat für die Client-Authentifizierung gesendet. Damit Sie mTLS mit Ihrem HTTP API-Ziel verwenden können, muss Ihr "Empfangs"-Server-Endpunkt ein nur mTLS aktivierter Verbindungsendpunkt sein.

Zertifikat herunterladen certificate

Wenn Sie die Werte Common Name (CN) und Subject Alternative Names (SAN) überprüfen möchten, um eine zusätzliche Validierung von Drittanbietern durchzuführen, können Sie das folgende Zertifikat herunterladen:

Sie können auch öffentliche Zertifikate sicher abrufen, indem Sie eine GET-Anfrage an den MTLS-Endpunkt senden. Weitere Informationen finden Sie in der Dokumentation 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. Eine vollständige Liste der IP-Zulassungslisten für Streaming-Ziele finden Sie in der IP-Adressen-Zulassungsliste für Streaming-Ziele .

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 zu Ihrem HTTP-Endpunkt wählen, füllen Sie die Felder unten aus und wählen Sie Mit Ziel verbinden:

Keine Authentifizierung no-authentication

Wenn Sie keinen Authentifizierungstyp zum Herstellen einer Verbindung mit Ihrem HTTP-Endpunkt auswählen:

Wenn Sie diese offene Authentifizierung auswählen, brauchen Sie nur auf Mit Ziel verbinden zu klicken, und die Verbindung zu Ihrem Endpunkt wird hergestellt.

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

Wenn Sie für die Verbindung zu Ihrem HTTP-Endpunkt den Authentifizierungstyp OAuth 2 mit Passwort wählen, füllen Sie die unten stehenden Felder aus und klicken Sie auf Mit Ziel verbinden:

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

Wenn Sie den Authentifizierungstyp Client-Anmeldeinformationen für OAuth 2 wählen, um sich mit Ihrem HTTP-Endpunkt zu verbinden, füllen Sie die unten stehenden Felder aus und klicken Sie auf Mit Ziel verbinden:

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 alle Details für Ihre Zielverbindung eingegeben haben, klicken Sie auf Weiter.

Aktivieren von Zielgruppen für dieses Ziel activate

Anweisungen zum Aktivieren von Zielgruppen für dieses Ziel finden Sie unter Aktivieren von Zielgruppendaten für Streaming-Profilexport-Ziele .

Zielattribute attributes

Im Schritt Attribute auswählen empfiehlt Adobe, eine eindeutige Kennung aus Ihrem Vereinigungsschema auszuwählen. 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 des Profilexports an Ihr HTTP-API-Ziel, sodass nur Daten an Ihren API-Endpunkt exportiert werden, wenn nach der Zielgruppenqualifizierung oder anderen wichtigen Ereignissen relevante Aktualisierungen an einem Profil stattgefunden haben. 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 Zielgruppe, die dem Zielfluss zugeordnet ist, aus hundert Mitgliedern besteht und fünf neue Profile sich für das Segment qualifizieren, ist der Export in Ihr Ziel inkrementell und umfasst nur die fünf neuen Profile.

Beachten Sie, dass alle zugeordneten Attribute unabhängig von der Art der Änderungen für ein Profil exportiert werden. Daher werden im obigen Beispiel alle zugeordneten Attribute für diese fünf neuen Profile exportiert, selbst wenn sich die Attribute selbst nicht geändert haben.

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 kann durch ein Profil bestimmt werden, das sich für eines der drei zugeordneten Segmente qualifiziert. Im Datenexport werden jedoch im Objekt segmentMembership (siehe Abschnitt Exportierte Daten unten) möglicherweise weitere nicht zugeordnete Zielgruppen angezeigt, wenn das betreffende Profil Mitglied dieser Zielgruppe ist und diese dieselbe Zusammenführungsrichtlinie wie die Zielgruppe nutzen, die den Export ausgelöst hat. Wenn ein Profil für das Segment Kunde mit DeLorean Cars qualifiziert ist, aber auch Mitglied der Segmente Überwachter "Back to the Future" und Science Fiction Fans ist, sind diese beiden anderen Zielgruppen auch im Objekt segmentMembership des Datenexports vorhanden, auch wenn sie nicht im Datenfluss zugeordnet sind, sofern sie dieselbe Zusammenführungsrichtlinie nutzen mit dem Segment Kunde mit DeLorean Cars .

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 ihm Zielgruppen zuordnen, exportiert Experience Platform historische Zielgruppenqualifizierungsdaten an das Ziel. Profile, die sich für die Zielgruppe vor qualifiziert haben, die zum Ziel hinzugefügt wurde, 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. Beispielsweise enthält der folgende Export ein Profil, das sich für ein bestimmtes Segment qualifiziert hat, Mitglied zweier weiterer Segmente ist und ein weiteres Segment 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 Segmentnamen einschließen und Zeitstempel für Segmente einschließen 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"
          }
        }
      }

"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

Experience Platform versucht, in 95 Prozent der Fälle 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 zu bieten.

Bei fehlgeschlagenen Anfragen an Ihr HTTP-API-Ziel speichert Experience Platform die fehlgeschlagenen Anfragen und versucht es zweimal erneut, die Anfragen an Ihren Endpunkt zu senden.