HTTP-API-Verbindung

Übersicht

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

Mit dem HTTP-API-Ziel können Sie XDM-Profildaten und Zielgruppensegmente in generische 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.

Exporttyp und -häufigkeit

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

Voraussetzungen

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

• Sie müssen über einen HTTP-Endpunkt verfügen, der die REST-API unterstützt.
• Ihr HTTP-Endpunkt muss das Profilschema von Experience Platform unterstützen. Im HTTP-API-Ziel wird keine Umwandlung in ein Payload-Schema von Drittanbietern unterstützt. Im Abschnitt exportierte Daten finden Sie ein Beispiel für das Ausgabeschema von Experience Platform.
• Ihr HTTP-Endpunkt muss Kopfzeilen unterstützen.

Zulassungsliste von IP-Adressen

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 Zulassungsliste von IP-Adressen für Streaming-Ziele, um die vollständige Liste der IP-Adressen in der Zulassungsliste einzusehen.

Unterstützte Authentifizierungstypen

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

• HTTP-Endpunkt ohne Authentifizierung;
• Authentifizierung mit Bearer-Token;
• Authentifizierung über Client-Anmeldeinformationen für OAuth 2.0 mit dem Textkörper-Formular, mit client ID, client secret und grant type im Textkörper der HTTP-Anfrage, wie im folgenden Beispiel gezeigt.

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>'

• Anmeldeinformationen für OAuth 2.0 mit einfacher Autorisierung, mit einer Autorisierungskopfzeile, die URL-codierte client ID und client secret enthält.

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'

• Passwortgewährung für OAuth 2.0.

Herstellen einer Verbindung mit dem Ziel

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

Authentifizierung über Bearer-Token

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:

• Bearer-Token: Fügen Sie das Bearer-Token ein, um sich bei Ihrer HTTP-Adresse zu authentifizieren.

Keine Authentifizierung

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

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:

• Zugriffstoken-URL: Die URL auf Ihrer Seite, die Zugriffstoken ausgibt und Token optional aktualisiert.
• Client-ID: Die client ID, die Ihr System Adobe Experience Platform zuweist.
• Client-Geheimnis: Das client secret, das Ihr System Adobe Experience Platform zuweist.
• Benutzername: Der Benutzername für den Zugriff auf Ihren HTTP-Endpunkt.
• Passwort: Das Passwort für den Zugriff auf Ihren HTTP-Endpunkt.

Authenifizierung mit Client-Anmeldeinformationen für OAuth 2

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:

• Zugriffstoken-URL: Die URL auf Ihrer Seite, die Zugriffstoken ausgibt und Token optional aktualisiert.
• Client-ID: Die client ID, die Ihr System Adobe Experience Platform zuweist.
• Client-Geheimwort: Das client secret, das Ihr System Adobe Experience Platform zuweist.
• Typ der Client-Anmeldeinformationen: Wählen Sie den Typ der von Ihrem Endpunkt unterstützten Client-Anmeldeinformationen für OAuth2 aus:
  • Im Textkörper codiert: In diesem Fall sind client ID und client secret im Textkörper der Anfrage enthalten, die an Ihr Ziel gesendet wird… Ein Beispiel finden Sie im Abschnitt unterstützte Authentifizierungstypen.
  • Einfache Autorisierung: In diesem Fall werden client ID und client secret, nachdem sie mit Base64 codiert wurden, in eine Authorization-Kopfzeile aufgenommen und an Ihr Ziel gesendet. Ein Beispiel finden Sie im Abschnitt Unterstützte Authentifizierungstypen.

Ausfüllen der Zieldetails

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.

• Name: Geben Sie einen Namen ein, um dieses Ziel in Zukunft zu erkennen.
• Beschreibung: Geben Sie eine Beschreibung ein, die Ihnen hilft, dieses Ziel in Zukunft zu identifizieren.
• Kopfzeilen: Geben Sie alle benutzerdefinierten Kopfzeilen ein, die in die Ziel-Aufrufe aufgenommen werden sollen. Verwenden Sie dazu folgendes Format: header1:value1,header2:value2,...headerN:valueN.
• HTTP-Endpunkt: Die URL des HTTP-Endpunkts, an den Sie die Profildaten senden möchten.
• Abfrageparameter: Optional können Sie Abfrageparameter zur HTTP-Endpunkt-URL hinzufügen. Formatieren Sie die verwendeten Abfrageparameter wie folgt: parameter1=value&parameter2=value.
• Segmentnamen einschließen: Schalten Sie diese Option ein, wenn der Datenexport die Namen der zu exportierenden Segmente enthalten soll. Ein Beispiel für einen Datenexport, bei dem diese Option aktiviert ist, finden Sie im Abschnitt Exportierte Daten weiter unten.
• Zeitstempel für Segmente einschließen: Schalten Sie diese Option ein, wenn der Datenexport den UNIX-Zeitstempel enthalten soll, an dem die Segmente erstellt und aktualisiert wurden, sowie den UNIX-Zeitstempel, an dem die Segmente dem Ziel für die Aktivierung zugeordnet wurden. Ein Beispiel für einen Datenexport, bei dem diese Option aktiviert ist, finden Sie im Abschnitt exportierte Daten weiter unten.

Aktivieren von Warnhinweisen

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, klicken Sie auf Weiter.

Aktivieren von Segmenten für dieses Ziel

Anweisungen zum Aktivieren von Zielgruppensegmenten für dieses Ziel finden Sie unter Aktivieren von Zielgruppendaten für Streaming-Profil-Exportziele.

Zielattribute

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

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

• Die Aktualisierung des Profils wurde durch eine Änderung der Segmentzugehörigkeit für mindestens eines der dem Ziel zugeordneten Segmente bestimmt. Beispielsweise hat sich das Profil für eines der Segmente qualifiziert, die dem Ziel zugeordnet sind, oder es hat eines der dem Ziel zugeordneten Segmente verlassen.
• Die Aktualisierung des Profils wurde durch eine Änderung der Identitätszuordnung bestimmt. Beispielsweise wurde einem Profil, das sich bereits für eines der dem Ziel zugeordneten Segmente qualifiziert hatte, eine neue Identität im Identitätszuordnungsattribut hinzugefügt.
• Die Aktualisierung des Profils wurde durch eine Änderung der Attribute für mindestens eines der dem Ziel zugeordneten Attribute bestimmt. Beispielsweise wird eines der Attribute, die dem Ziel im Zuordnungsschritt zugeordnet sind, einem Profil hinzugefügt.

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

Beachten Sie, dass alle zugeordneten Attribute unabhängig vom Speicherort 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?

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 drei Segmente im Datenfluss 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 jedoch wird im segmentMembership -Objekt (siehe Exportierte Daten weiter unten), können weitere nicht zugeordnete Segmente angezeigt werden, wenn dieses bestimmte Profil Mitglied dieses Profils ist und diese dieselbe Zusammenführungsrichtlinie wie das Segment nutzen, das den Export ausgelöst hat. Wenn ein Profil für die Kunde mit DeLorean Cars -Segment, ist aber auch Mitglied der "Zurück in die Zukunft" Film und Fans von Science-Fiction Segmente, dann sind auch diese beiden anderen Segmente im segmentMembership -Objekt des Datenexports, auch wenn diese nicht im Datenfluss zugeordnet sind, wenn diese dieselbe Zusammenführungsrichtlinie mit der Kunde mit DeLorean Cars Segment.

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

Wenn Sie ein neues Segment zu einem vorhandenen Ziel hinzufügen oder wenn Sie ein neues Ziel erstellen und ihm Segmente zuordnen, exportiert Experience Platform historische Segmentqualifikationsdaten an das Ziel. Profile, die sich für das Segment qualifiziert haben, bevor das Segment zum Ziel hinzugefügt wurde, werden innerhalb von etwa einer Stunde an das Ziel exportiert.

Exportierte Daten

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":"existing"
      },
      "947c1c46-008d-40b0-92ec-3af86eaf41c1":{
         "lastQualificationTime":"2021-08-25T23:37:33Z",
         "status":"existing"
      },
      "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": "existing",
            "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": "existing",
            "createdAt": 1648553325000,
            "updatedAt": 1648553330000,
            "mappingCreatedAt": 1649856570000,
            "mappingUpdatedAt": 1649856570000,
          }
        }
      }

Beschränkungen und Wiederholungsrichtlinien

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.

Ressourcen für Business.Adobe.com