Mehrere Nachrichten in einer einzelnen HTTP-Anfrage senden
Beim Streaming von Daten an Adobe Experience Platform kann das Ausführen zahlreicher HTTP-Aufrufe teuer werden. Anstatt beispielsweise 200 HTTP-Anfragen mit Payloads von 1 KB zu erstellen, ist es viel effizienter, 1 HTTP-Anfrage mit 200 Nachrichten mit jeweils 1 KB und einer Payload von 200 KB zu erstellen. Bei korrekter Verwendung ist die Gruppierung mehrerer Nachrichten in einer einzigen Anfrage eine hervorragende Möglichkeit, die an Experience Platform gesendeten Daten zu optimieren.
Dieses Dokument enthält ein Tutorial zum Senden mehrerer Nachrichten an Experience Platform innerhalb einer einzelnen HTTP-Anfrage mithilfe der Streaming-Erfassung.
Erste Schritte
Dieses Tutorial setzt ein Verständnis von Adobe Experience Platform Data Ingestion voraus. Bevor Sie mit dem Tutorial beginnen, lesen Sie die folgenden Dokumente:
- Datenerfassung - Übersicht: Behandelt die Kernkonzepte von Experience Platform Data Ingestion, einschließlich Erfassungsmethoden und Data Connectors.
- Streaming-Erfassung - Übersicht: Der Workflow und die Bausteine der Streaming-Erfassung, z. B. Streaming-Verbindungen, Datensätze, XDM Individual Profile und XDM ExperienceEvent.
Für dieses Tutorial müssen Sie außerdem das Tutorial Authentifizierung für Adobe Experience Platform abgeschlossen haben, damit Sie erfolgreich Aufrufe an Platform -APIs durchführen können. Durch Abschließen des Authentifizierungs-Tutorials erhalten Sie den Wert für die Autorisierungs-Kopfzeile, der für alle API-Aufrufe in diesem Tutorial erforderlich ist. Die Kopfzeile wird in Beispielaufrufen wie folgt angezeigt:
- Authorization: Bearer
{ACCESS_TOKEN}
Für alle POST-Anfragen ist eine zusätzliche Kopfzeile erforderlich:
- Content-Type: application/json
Aufbauen einer Streaming-Verbindung
Sie müssen zunächst eine Streaming-Verbindung erstellen, bevor Sie mit dem Streaming von Daten an Experience Platform beginnen können. Lesen Sie die Anleitung zum Aufbauen einer Streaming-Verbindung, um zu erfahren, wie Sie eine Streaming-Verbindung aufbauen.
Nach der Registrierung einer Streaming-Verbindung haben Sie als Datenproduzent eine eindeutige URL, die zum Streamen von Daten an Platform verwendet werden kann.
Streamen in einen Datensatz
Das folgende Beispiel zeigt, wie mehrere Nachrichten an einen bestimmten Datensatz innerhalb einer einzelnen HTTP-Anfrage gesendet werden. Fügen Sie die Datensatz-ID in die Kopfzeile der Nachricht ein, damit die Nachricht direkt darin aufgenommen wird.
Sie können die ID für einen vorhandenen Datensatz über die Benutzeroberfläche von Platform oder mithilfe eines Auflistungsvorgangs in der API abrufen. Die Datensatz-ID kann auf Experience Platform gefunden werden, indem Sie auf die Registerkarte Datensätze gehen, auf den Datensatz klicken, für den die ID verwendet werden soll, und die Zeichenfolge aus dem Feld für die Datensatz-ID auf der Registerkarte Info kopieren. Informationen zum Abrufen von Datensätzen mithilfe der API finden Sie unter Katalogdienst – Überblick.
Anstatt einen vorhandenen Datensatz zu verwenden, können Sie einen neuen Datensatz erstellen. Weitere Informationen zum Erstellen eines Datensatzes mithilfe von APIs finden Sie im Tutorial Erstellen eines Datensatzes mithilfe von APIs.
API-Format
POST /collection/batch/{CONNECTION_ID}
{CONNECTION_ID}Anfrage
curl -X POST https://dcs.adobedc.net/collection/batch/{CONNECTION_ID} \
-H 'Content-Type: application/json' \
-d '{
"messages": [
{
"header": {
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
"contentType": "application/vnd.adobe.xed-full+json;{SCHEMA_VERSION}"
},
"imsOrgId": "{ORG_ID}",
"datasetId": "{DATASET_ID}",
"createdAt": 1526283801869
},
"body": {
"xdmMeta": {
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
"contentType": "application/vnd.adobe.xed-full+json;{SCHEMA_VERSION}"
}
},
"xdmEntity": {
"_id": "9af5adcc-db9c-4692-b826-65d3abe68c22",
"timestamp": "2019-02-23T22:07:01Z",
"environment": {
"browserDetails": {
"userAgent": "Mozilla/5.0 (Windows NT 5.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/29.0.1547.57 Safari/537.36 OPR/16.0.1196.62",
"acceptLanguage": "en-US",
"cookiesEnabled": true,
"javaScriptVersion": "1.6",
"javaEnabled": true
},
"colorDepth": 32,
"viewportHeight": 799,
"viewportWidth": 414
},
"productListItems": [
{
"SKU": "CC",
"name": "Fernie Snow",
"quantity": 30,
"priceTotal": 7.8
}
],
"commerce": {
"productViews": {
"value": 1
}
},
"_experience": {
"campaign": {
"message": {
"profileSnapshot": {
"workEmail": {
"address": "gregdorcey@example.com"
}
}
}
}
}
}
}
},
{
"header": {
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
"contentType": "application/vnd.adobe.xed-full+json;{SCHEMA_VERSION}"
},
"imsOrgId": "{ORG_ID}",
"datasetId": "{DATASET_ID}",
"createdAt": 1526283801869
},
"body": {
"xdmMeta": {
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
"contentType": "application/vnd.adobe.xed-full+json;{SCHEMA_VERSION}"
}
},
"xdmEntity": {
"_id": "7af6adcc-dc9e-4692-b826-55d2abe68c11",
"timestamp": "2019-02-23T22:07:31Z",
"environment": {
"browserDetails": {
"userAgent": "Mozilla/5.0 (Windows NT 5.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/29.0.1547.57 Safari/537.36 OPR/16.0.1196.62",
"acceptLanguage": "en-US",
"cookiesEnabled": true,
"javaScriptVersion": "1.6",
"javaEnabled": true
},
"colorDepth": 32,
"viewportHeight": 799,
"viewportWidth": 414
},
"productListItems": [
{
"SKU": "CC",
"name": "Carmine Santiago",
"quantity": 10,
"priceTotal": 5.5
}
],
"commerce": {
"productViews": {
"value": 1
}
},
"_experience": {
"campaign": {
"message": {
"profileSnapshot": {
"workEmail": {
"address": "emilyong@example.com"
}
}
}
}
}
}
}
}
]
}'
Antwort
Eine erfolgreiche Antwort gibt den HTTP-Status 207 (Multi-Status) zurück. Bei der Überprüfung des Antworttextes werden weitere Details zum Erfolg oder Misserfolg der einzelnen in der Anfrage ausgeführten Methoden angezeigt. Für jedes Element des Anfragemeldungs-Arrays wird eine Antwort zurückgegeben. Nachfolgend sehen Sie ein Beispiel für eine erfolgreiche Antwort ohne Nachrichtenfehler:
{
"inletId": "9b0cb233972f3b0092992284c7353f5eead496218e8441a79b25e9421ea127f5",
"batchId": "1565628583792:1485:153",
"receivedTimeMs": 1565628583854,
"responses": [
{
"xactionId": "1565628583792:1485:153:0"
},
{
"xactionId": "1565628583792:1485:153:1"
}
]
}
Weitere Informationen zu Status-Codes finden Sie in der Tabelle zu Antwort-Codes im Anhang dieses Tutorials.
Identifizieren von fehlgeschlagenen Nachrichten
Im Vergleich zum Senden einer Anfrage mit einer einzelnen Nachricht gibt es beim Senden einer HTTP-Anfrage mit mehreren Nachrichten weitere Faktoren, die in Betracht gezogen werden sollten, z. B. wie zu identifizieren ist, wann Daten nicht gesendet wurden, welche spezifischen Nachrichten nicht gesendet wurden und wie sie abgerufen werden können und was mit Daten passiert, die erfolgreich sind, wenn andere Nachrichten in derselben Anfrage fehlschlagen.
Bevor Sie mit diesem Tutorial fortfahren, sollten Sie zunächst das Handbuch zum Abrufen fehlgeschlagener Batches lesen.
Senden von Anfrage-Payload mit gültigen und ungültigen Nachrichten
Das folgende Beispiel zeigt, was passiert, wenn der Batch gültige und ungültige Meldungen enthält.
Die Anfrage-Payload ist ein Array von JSON-Objekten, die das Ereignis im XDM-Schema darstellen. Beachten Sie, dass für eine erfolgreiche Validierung der Nachricht folgende Bedingungen erfüllt sein müssen:
- Das Feld
imsOrgIdin der Kopfzeile der Nachricht muss mit der Inlet-Definition übereinstimmen. Wenn die Anfrage-Payload keinimsOrgId-Feld enthält, fügt der Data Collection Core Service (DCCS) das Feld automatisch hinzu. - Die Kopfzeile der Nachricht sollte auf ein vorhandenes XDM-Schema verweisen, das in der Platform -Benutzeroberfläche erstellt wurde.
- Das Feld
datasetIdmuss auf einen vorhandenen Datensatz in Platform verweisen und sein Schema muss mit dem Schema übereinstimmen, das imheader-Objekt innerhalb jeder Nachricht im Anfragetext bereitgestellt wird.
API-Format
POST /collection/batch/{CONNECTION_ID}
{CONNECTION_ID}Anfrage
curl -X POST https://dcs.adobedc.net/collection/batch/{CONNECTION_ID} \
-H 'Content-Type: application/json' \
-d '{
"messages": [
{
"header": {
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
"contentType": "application/vnd.adobe.xed-full+json;{SCHEMA_VERSION}"
},
"imsOrgId": "{ORG_ID}",
"datasetId": "{DATASET_ID}",
"createdAt": 1526283801869
},
"body": {
"xdmMeta": {
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
"contentType": "application/vnd.adobe.xed-full+json;{SCHEMA_VERSION}"
}
},
"xdmEntity": {
"_id": "9af5adcc-db9c-4692-b826-65d3abe68c22",
"timestamp": "2019-02-23T22:07:01Z",
"environment": {
"browserDetails": {
"userAgent": "Mozilla/5.0 (Windows NT 5.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/29.0.1547.57 Safari/537.36 OPR/16.0.1196.62",
"acceptLanguage": "en-US",
"cookiesEnabled": true,
"javaScriptVersion": "1.6",
"javaEnabled": true
},
"colorDepth": 32,
"viewportHeight": 799,
"viewportWidth": 414
},
"productListItems": [
{
"SKU": "CC",
"name": "Tip Top Collection",
"quantity": 15,
"priceTotal": 9.5
}
],
"commerce": {
"productViews": {
"value": 1
}
},
"_experience": {
"campaign": {
"message": {
"profileSnapshot": {
"workEmail": {
"address": "rogerkanagawa@example.com"
}
}
}
}
}
}
}
},
{
"header": {
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
"contentType": "application/vnd.adobe.xed-full+json;{SCHEMA_VERSION}"
},
"imsOrgId": "{ORG_ID}",
"datasetId": "{DATASET_ID}",
"createdAt": 1526283801869
}
},
{
"header": {
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
"contentType": "application/vnd.adobe.xed-full+json;{SCHEMA_VERSION}"
},
"imsOrgId": "invalidIMSOrg@AdobeOrg",
"datasetId": "{DATASET_ID}",
"createdAt": 1526283801869
},
"body": {
"xdmMeta": {
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
"contentType": "application/vnd.adobe.xed-full+json;{SCHEMA_VERSION}"
}
},
"xdmEntity": {
"_id": "9af5adcc-db9c-4692-b826-65d3abe68c22",
"timestamp": "2019-02-23T22:07:01Z",
"environment": {
"browserDetails": {
"userAgent": "Mozilla/5.0 (Windows NT 5.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/29.0.1547.57 Safari/537.36 OPR/16.0.1196.62",
"acceptLanguage": "en-US",
"cookiesEnabled": true,
"javaScriptVersion": "1.6",
"javaEnabled": true
},
"colorDepth": 32,
"viewportHeight": 799,
"viewportWidth": 414
},
"productListItems": [
{
"SKU": "CC",
"name": "Carmine Santiago",
"quantity": 10,
"priceTotal": 5.5
}
],
"commerce": {
"productViews": {
"value": 1
}
},
"_experience": {
"campaign": {
"message": {
"profileSnapshot": {
"workEmail": {
"address": "mohandeewar@example.com"
}
}
}
}
}
}
}
},
{
"header": {
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
"contentType": "application/vnd.adobe.xed-full+json;{SCHEMA_VERSION}"
},
"imsOrgId": "{ORG_ID}",
"datasetId": "{DATASET_ID}",
"createdAt": 1526283801869
},
"body": {
"xdmMeta": {
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
"contentType": "application/vnd.adobe.xed-full+json;{SCHEMA_VERSION}"
}
},
"xdmEntity": {
"_id": "9af5adcc-db9c-4692-b826-65d3abe68c22",
"timestamp": "2019-02-23T22:07:01Z",
"environment": {
"browserDetails": {
"userAgent": "Mozilla/5.0 (Windows NT 5.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/29.0.1547.57 Safari/537.36 OPR/16.0.1196.62",
"acceptLanguage": "en-US",
"cookiesEnabled": true,
"javaScriptVersion": "1.6",
"javaEnabled": true
},
"colorDepth": 32,
"viewportHeight": 799,
"viewportWidth": 414
},
"productListItems": [
{
"SKU": "CC",
"name": "Tip Top Collection",
"quantity": 15,
"priceTotal": 9.5
}
],
"commerce": {
"productViews": {
"value": 1
}
}
}
}
},
{
"header": {
"msgType": "xdmEntityCreate",
"msgId": "79d2e715-f25f-4c36",
"xdmSchema": {
"name": "_xdm.context.experienceevent"
},
"imsOrgId": "{ORG_ID}",
"datasetId": "{DATASET_ID}",
"createdAt": 1526283801869
},
"body": {
"xdmMeta": {
"xdmSchema": {
"name": "_xdm.context.experienceevent"
}
},
"xdmEntity": {
"_id": "abc",
"dataSource": {
"_id": "http://abc.com/abc"
},
"timestamp": "2018-05-18T15:28:25Z",
"endUserIDs": {
"_vendor": {
"adobe": {
"experience": {
"mcId": {
"id": "http://abc.com/abc"
}
}
}
}
}
}
}
}
]
}'
Antwort
Die Antwort-Payload enthält einen Status für jede Nachricht zusammen mit einer GUID in der xactionId, die für die Verfolgung verwendet werden kann.
{
"inletId": "9b0cb233972f3b0092992284c7353f5eead496218e8441a79b25e9421ea127f5",
"batchId": "1565638336649:1750:244",
"receivedTimeMs": 1565638336705,
"responses": [
{
"xactionId": "1565650704337:2124:92:3"
},
{
"statusCode": 400,
"message": "inletId: [9b0cb233972f3b0092992284c7353f5eead496218e8441a79b25e9421ea127f5] imsOrgId: [{ORG_ID}] Message has unknown xdm format"
},
{
"statusCode": 400,
"message": "inletId: [9b0cb233972f3b0092992284c7353f5eead496218e8441a79b25e9421ea127f5] imsOrgId: [{ORG_ID}] Message has an absent or wrong ims org in the header"
},
{
"statusCode": 400,
"message": "inletId: [9b0cb233972f3b0092992284c7353f5eead496218e8441a79b25e9421ea127f5] imsOrgId: [{ORG_ID}] Message has unknown xdm format"
}
]
}
Die obige Beispielantwort zeigt Fehlermeldungen für die vorherige Anfrage. Ein Vergleich dieser Antwort mit der vorherigen gültigen Antwort ergibt, dass die Anfrage teilweise erfolgreich war. Eine Nachricht wurde erfolgreich aufgenommen und drei Nachrichten führten zu einem Fehler. Beachten Sie, dass beide Antworten den Status-Code „207“ zurückgeben. Weitere Informationen zu Status-Codes finden Sie in der Tabelle zu Antwort-Codes im Anhang dieses Tutorials.
Die erste Nachricht wurde erfolgreich an Platform gesendet und ist von den Ergebnissen der anderen Nachrichten nicht betroffen. Daher müssen Sie diese Nachricht nicht erneut einschließen, wenn Sie versuchen, die fehlgeschlagenen Nachrichten erneut zu senden.
Die zweite Nachricht schlug fehl, weil der Nachrichtentext fehlte. Die Erfassungsanfrage erwartet, dass Nachrichtenelemente gültige Kopfzeilen- und Textabschnitte aufweisen. Durch Hinzufügen des folgenden Codes nach der Kopfzeile in der zweiten Nachricht wird die Anfrage korrigiert, sodass die zweite Nachricht die Überprüfung besteht:
"body": {
"xdmMeta": {
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
"contentType": "application/vnd.adobe.xed-full+json;{SCHEMA_VERSION}"
}
},
"xdmEntity": {
"_id": "9af5adcc-db9c-4692-b826-65d3abe68c22",
"timestamp": "2019-02-23T22:07:01Z",
}
},
Die dritte Nachricht schlug fehl, weil in der Kopfzeile eine ungültige Organisations-ID verwendet wurde. Die Organisation muss mit dem {CONNECTION_ID} übereinstimmen, das Sie veröffentlichen möchten. Um festzustellen, welche Organisations-ID mit der verwendeten Streaming-Verbindung übereinstimmt, können Sie eine GET inlet -Anfrage mit dem Streaming Ingestion API ausführen. Ein Beispiel zum Abrufen zuvor erstellter Streaming-Verbindungen finden Sie unter Abrufen einer Streaming-Verbindung.
Die vierte Meldung ist fehlgeschlagen, da sie nicht dem erwarteten XDM-Schema entsprach. Das xdmSchema, das in der Kopfzeile und im Text der Anfrage enthalten ist, stimmt nicht mit dem XDM-Schema der {DATASET_ID} überein. Durch die Korrektur des Schemas im Nachrichtenkopf und -text kann die DCCS-Validierung übergeben und erfolgreich an Platform gesendet werden. Der Nachrichtentext muss auch so aktualisiert werden, dass er mit dem XDM-Schema der {DATASET_ID} übereinstimmt, damit er die Streaming-Validierung auf Platform übergibt. Weitere Informationen zu Nachrichten, die erfolgreich an Platform gesendet werden, finden Sie im Abschnitt Bestätigen von aufgenommenen Nachrichten in diesem Tutorial.
Abrufen fehlgeschlagener Nachrichten von Platform
Fehlgeschlagene Nachrichten werden durch einen Fehlerstatus-Code im Antwort-Array identifiziert.
Die ungültigen Nachrichten werden in einem „Fehler“-Batch innerhalb des von der {DATASET_ID} angegebenen Datensatzes erfasst und gespeichert.
Weitere Informationen zum Wiederherstellen von fehlgeschlagenen Batch-Nachrichten finden Sie der Anleitung zum Abrufen fehlgeschlagener Batches.
Bestätigen von aufgenommenen Nachrichten
Nachrichten, die die DCCS-Validierung bestehen, werden an Platform gestreamt. Bei Platform werden die Batch-Nachrichten durch Streaming-Validierung getestet, bevor sie in den Data Lake aufgenommen werden. Der Status von Batches, ob erfolgreich oder nicht, wird in dem von der {DATASET_ID} angegebenen Datensatz angezeigt.
Sie können den Status von Batch-Nachrichten, die erfolgreich an Platform gestreamt werden, über die Experience Platform-Benutzeroberfläche anzeigen, indem Sie zur Registerkarte Datensätze navigieren, auf den Datensatz klicken, an den Sie streamen, und die Registerkarte Datensatzaktivität überprüfen.
Batch-Nachrichten, die die Streaming-Validierung auf Platform bestehen, werden in die Data Lake aufgenommen. Die Nachrichten stehen dann für die Analyse oder den Export zur Verfügung.
Nächste Schritte
Nachdem Sie nun wissen, wie Sie mehrere Nachrichten in einer einzelnen Anfrage senden und überprüfen können, wann Nachrichten erfolgreich in den Zieldatensatz aufgenommen wurden, können Sie mit dem Streaming Ihrer eigenen Daten an Platform beginnen. Eine Übersicht über die Abfrage und den Abruf erfasster Daten von Platform finden Sie im Data Access -Handbuch.
Anhang
Dieser Abschnitt enthält zusätzliche Informationen zum Tutorial.
Antwort-Codes
Die folgende Tabelle zeigt Status-Codes, die von erfolgreichen und fehlgeschlagenen Antwortnachrichten zurückgegeben werden.