Verbinden von Data Landing Zone mit Adobe Experience Platform mithilfe der Flow Service-API
Data Landing Zone ist eine sichere, Cloud-basierte Dateispeichereinrichtung, um Dateien in Adobe Experience Platform zu importieren. Daten werden nach sieben Tagen automatisch aus dem Data Landing Zone gelöscht.
Dieses Tutorial führt Sie durch die Schritte zum Erstellen einer Data Landing Zone-Quellverbindung mithilfe der Flow Service API. Dieses Tutorial enthält auch Anweisungen zum Abrufen Ihrer Data Landing Zone sowie zum Anzeigen und Aktualisieren Ihrer Anmeldeinformationen.
Erste Schritte
Dieses Handbuch setzt ein Verständnis der folgenden Komponenten von Experience Platform voraus:
- Quellen: Experience Platform ermöglicht die Aufnahme von Daten aus verschiedenen Quellen und bietet Ihnen die Möglichkeit, die eingehenden Daten mithilfe von Platform-Services zu strukturieren, zu kennzeichnen und anzureichern.
- Sandboxes: Experience Platform bietet virtuelle Sandboxes, die eine einzelne Platform-Instanz in separate virtuelle Umgebungen unterteilen, damit Sie Programme für digitale Erlebnisse entwickeln und weiterentwickeln können.
Für dieses Tutorial müssen Sie auch das Handbuch Erste Schritte mit Platform-APIs“ lesen um zu erfahren, wie Sie sich bei Platform-APIs authentifizieren und die in der Dokumentation bereitgestellten Beispielaufrufe interpretieren.
Die folgenden Abschnitte enthalten zusätzliche Informationen, die Sie benötigen, um mithilfe der Flow Service-API erfolgreich eine Data Landing Zone-Quellverbindung erstellen zu können.
Abrufen einer verwendbaren Landing Zone
type=user_drop_zone
abrufen zu können. Weitere Informationen finden Sie unter Zugriffskontrolle - Übersicht oder wenden Sie sich an Ihren Produktadministrator, um die erforderlichen Berechtigungen zu erhalten.Der erste Schritt bei der Verwendung von APIs für den Zugriff auf Data Landing Zone besteht darin, eine GET-Anfrage an den /landingzone
-Endpunkt der Connectors-API zu stellen und dabei type=user_drop_zone
als Teil Ihres Anfrage-Headers bereitzustellen.
API-Format
GET /data/foundation/connectors/landingzone?type=user_drop_zone
user_drop_zone
user_drop_zone
ermöglicht es der API, einen Landing Zone-Container von den anderen Containertypen zu unterscheiden, die Ihnen zur Verfügung stehen.Anfrage
Mit der folgenden Anfrage wird eine vorhandene Landing Zone abgerufen.
curl -X GET \
'https://platform.adobe.io/data/foundation/connectors/landingzone?type=user_drop_zone' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json'
Antwort
Je nach Anbieter gibt eine erfolgreiche Anfrage Folgendes zurück:
code language-json |
---|
|
table 0-row-2 1-row-2 2-row-2 | |
---|---|
Eigenschaft | Beschreibung |
containerName |
Der Name der Landing Zone, die Sie abgerufen haben. |
containerTTL |
Die Gültigkeitsdauer (in Tagen), die auf Ihre Daten in der Landing Zone angewendet wird. Alle innerhalb einer bestimmten Landing Zone werden nach sieben Tagen gelöscht. |
code language-json |
---|
|
Data Landing Zone abrufen
Um Anmeldeinformationen für eine Data Landing Zone abzurufen, stellen Sie eine GET-Anfrage an den /credentials
-Endpunkt der Connectors-API.
API-Format
GET /data/foundation/connectors/landingzone/credentials?type=user_drop_zone
Anfrage
Im folgenden Anfragebeispiel werden Anmeldeinformationen für eine vorhandene Landing Zone abgerufen.
curl -X GET \
'https://platform.adobe.io/data/foundation/connectors/landingzone/credentials?type=user_drop_zone' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
Antwort
Je nach Anbieter gibt eine erfolgreiche Anfrage Folgendes zurück:
code language-json |
---|
|
table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 | |
---|---|
Eigenschaft | Beschreibung |
containerName |
Der Name Ihres Data Landing Zone. |
SASToken |
Das Shared Access Signature Token für Ihre Data Landing Zone. Diese Zeichenfolge enthält alle Informationen, die zum Autorisieren einer Anfrage erforderlich sind. |
storageAccountName |
Der Name Ihres Speicherkontos. |
SASUri |
Der Shared Access Signature-URI für Ihre Data Landing Zone. Diese Zeichenfolge ist eine Kombination aus dem URI zum Data Landing Zone, für den Sie authentifiziert werden, und dem entsprechenden SAS-Token. |
expiryDate |
Das Datum, an dem Ihr SAS-Token abläuft. Sie müssen Ihr Token vor dem Ablaufdatum aktualisieren, um es weiterhin in Ihrer Anwendung zum Hochladen von Daten in die Data Landing Zone verwenden zu können. Wenn Sie Ihr Token nicht vor dem angegebenen Ablaufdatum manuell aktualisieren, wird es automatisch aktualisiert und ein neues Token bereitgestellt, wenn der Aufruf der GET-Anmeldeinformationen durchgeführt wird. |
code language-json |
---|
|
table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 6-row-2 7-row-2 8-row-2 | |
---|---|
Eigenschaft | Beschreibung |
credentials.clientId |
Die Client-ID Ihres Data Landing Zone in AWS. |
credentials.awsAccessKeyId |
Die Zugriffsschlüssel-ID Ihres Data Landing Zone in AWS. |
credentials.awsSecretAccessKey |
Der geheime Zugriffsschlüssel Ihrer Data Landing Zone in AWS. |
credentials.awsSessionToken |
Ihr AWS-Sitzungs-Token. |
dlzPath.bucketName |
Der Name Ihres AWS-Buckets. |
dlzPath.dlzFolder |
Der Data Landing Zone Ordner, auf den Sie zugreifen. |
dlzProvider |
Der Data Landing Zone, den Sie verwenden. Für Amazon wird dies Amazon S3. |
expiryTime |
Die Ablaufzeit in Unix-Zeit. |
Abrufen der erforderlichen Felder mithilfe von APIs
Nachdem Sie Ihr Token generiert haben, können Sie die erforderlichen Felder programmgesteuert abrufen, indem Sie die folgenden Anfragebeispiele verwenden:
code language-py |
---|
|
code language-java |
---|
|
Aktualisieren Data Landing Zone Anmeldeinformationen
Sie können Ihre SASToken
aktualisieren, indem Sie eine POST-Anfrage an den /credentials
-Endpunkt der Connectors-API stellen.
API-Format
POST /data/foundation/connectors/landingzone/credentials?type=user_drop_zone&action=refresh
user_drop_zone
user_drop_zone
ermöglicht es der API, einen Landing Zone-Container von den anderen Containertypen zu unterscheiden, die Ihnen zur Verfügung stehen.refresh
refresh
Aktion können Sie Ihre Anmeldeinformationen für die Landing Zone zurücksetzen und automatisch eine neue SASToken
generieren.Anfrage
Die folgende Anfrage aktualisiert Ihre Anmeldeinformationen für die Landing Zone.
curl -X POST \
'https://platform.adobe.io/data/foundation/connectors/landingzone/credentials?type=user_drop_zone&action=refresh' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
Antwort
Die folgende Antwort gibt aktualisierte Werte für Ihre SASToken
und SASUri
zurück.
{
"containerName": "dlz-user-container",
"SASToken": "sv=2020-04-08&si=dlz-9c4d03b8-a6ff-41be-9dcf-20123e717e99&sr=c&sp=racwdlm&sig=JbRMoDmFHQU4OWOpgrKdbZ1d%2BkvslO35%2FXTqBO%2FgbRA%3D",
"storageAccountName": "dlblobstore99hh25i3dflek",
"SASUri": "https://dlblobstore99hh25i3dflek.blob.core.windows.net/dlz-user-container?sv=2020-04-08&si=dlz-9c4d03b8-a6ff-41be-9dcf-20123e717e99&sr=c&sp=racwdlm&sig=JbRMoDmFHQU4OWOpgrKdbZ1d%2BkvslO35%2FXTqBO%2FgbRA%3D",
"expiryDate": "2024-01-06"
}
Dateistruktur und Inhalte der Landing Zone erkunden
Sie können die Dateistruktur und den Inhalt Ihrer Landing Zone untersuchen, indem Sie eine GET-Anfrage an den connectionSpecs
-Endpunkt der Flow Service-API stellen.
API-Format
GET /connectionSpecs/{CONNECTION_SPEC_ID}/explore?objectType=root
{CONNECTION_SPEC_ID}
26f526f2-58f4-4712-961d-e41bf1ccc0e8
.Anfrage
curl -X GET \
'http://platform.adobe.io/data/foundation/flowservice/connectionSpecs/26f526f2-58f4-4712-961d-e41bf1ccc0e8/explore?objectType=root' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Antwort
Eine erfolgreiche Antwort gibt ein Array von Dateien und Ordnern zurück, die im abgefragten Verzeichnis gefunden wurden. Notieren Sie sich die path
-Eigenschaft der Datei, die Sie hochladen möchten, da Sie sie im nächsten Schritt bereitstellen müssen, um ihre Struktur zu überprüfen.
[
{
"type": "file",
"name": "account.csv",
"path": "dlz-user-container/account.csv",
"canPreview": true,
"canFetchSchema": true
},
{
"type": "file",
"name": "data8.csv",
"path": "dlz-user-container/data8.csv",
"canPreview": true,
"canFetchSchema": true
},
{
"type": "folder",
"name": "userdata1",
"path": "dlz-user-container/userdata1/",
"canPreview": false,
"canFetchSchema": false
}
]
Vorschau der Dateistruktur und des Inhalts der Landing Zone
Um die Dateistruktur in Ihrer Landing Zone zu überprüfen, führen Sie eine GET-Anfrage aus, wobei Sie den Dateipfad und den Typ als Abfrageparameter angeben.
API-Format
GET /connectionSpecs/{CONNECTION_SPEC_ID}/explore?objectType=file&object={OBJECT}&fileType={FILE_TYPE}&preview={PREVIEW}
{CONNECTION_SPEC_ID}
26f526f2-58f4-4712-961d-e41bf1ccc0e8
.{OBJECT_TYPE}
file
{OBJECT}
dlz-user-container/data8.csv
{FILE_TYPE}
delimited
json
parquet
{PREVIEW}
-
true
-
false
Anfrage
curl -X GET \
'http://platform.adobe.io/data/foundation/flowservice/connectionSpecs/26f526f2-58f4-4712-961d-e41bf1ccc0e8/explore?objectType=file&object=dlz-user-container/data8.csv&fileType=delimited&preview=true' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Antwort
Eine erfolgreiche Antwort gibt die Struktur der abgefragten Datei zurück, einschließlich Dateinamen und Datentypen.
{
"format": "flat",
"schema": {
"columns": [
{
"name": "Id",
"type": "string",
"xdm": {
"type": "string"
}
},
{
"name": "FirstName",
"type": "string",
"xdm": {
"type": "string"
}
},
{
"name": "LastName",
"type": "string",
"xdm": {
"type": "string"
}
},
{
"name": "Email",
"type": "string",
"xdm": {
"type": "string"
}
},
{
"name": "Phone",
"type": "string",
"xdm": {
"type": "string"
}
}
]
},
"data": [
{
"Email": "rsmith@abc.com",
"FirstName": "Richard",
"Phone": "111111111",
"Id": "12345",
"LastName": "Smith"
},
{
"Email": "morgan@bac.com",
"FirstName": "Morgan",
"Phone": "22222222222",
"Id": "67890",
"LastName": "Hart"
}
]
}
determineProperties
verwenden, um Dateieigenschaftsinformationen eines Data Landing Zone automatisch zu erkennen
Sie können den determineProperties
-Parameter verwenden, um Eigenschafteninformationen des Dateiinhalts Ihrer Data Landing Zone automatisch zu erkennen, wenn Sie einen GET-Aufruf ausführen, um den Inhalt und die Struktur Ihrer Quelle zu untersuchen.
determineProperties
Anwendungsfälle
In der folgenden Tabelle sind verschiedene Szenarien aufgeführt, auf die Sie stoßen können, wenn Sie den determineProperties
Abfrageparameter verwenden oder manuell Informationen zu Ihrer Datei angeben.
determineProperties
queryParams
determineProperties
als Abfrageparameter angegeben wird, erfolgt die Erkennung der Dateieigenschaften, und die Antwort gibt einen neuen properties
zurück, der Informationen zum Dateityp, zum Komprimierungstyp und zum Spaltentrennzeichen enthält.queryParams
bereitgestellt werden, werden sie zum Generieren des Schemas verwendet und dieselben Eigenschaften werden als Teil der Antwort zurückgegeben.API-Format
GET /connectionSpecs/{CONNECTION_SPEC_ID}/explore?objectType=file&object={OBJECT}&fileType={FILE_TYPE}&preview={PREVIEW}&determineProperties=true
determineProperties
true
Anfrage
curl -X GET \
'https://platform.adobe.io/data/foundation/flowservice/connectionSpecs/26f526f2-58f4-4712-961d-e41bf1ccc0e8/explore?objectType=file&object=dlz-user-container/garageWeek/file1&preview=true&determineProperties=true' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Antwort
Bei einer erfolgreichen Antwort wird die Struktur der abgefragten Datei zurückgegeben, einschließlich Dateinamen und Datentypen sowie eines properties
Schlüssels, der Informationen zu fileType
, compressionType
und columnDelimiter
enthält.
code language-json |
---|
|
properties.fileType
delimited
, json
und parquet
.properties.compressionType
Der entsprechende Komprimierungstyp, der für die abgefragte Datei verwendet wird. Folgende Komprimierungstypen werden unterstützt:
bzip2
gzip
zipDeflate
tarGzip
tar
properties.columnDelimiter
(,)
.Erstellen einer Quellverbindung
Eine Quellverbindung erstellt und verwaltet die Verbindung zu der externen Quelle, aus der Daten erfasst werden. Eine Quellverbindung besteht aus Informationen wie Datenquelle, Datenformat und der Quellverbindungs-ID, die zum Erstellen eines Datenflusses erforderlich sind. Eine Quellverbindungsinstanz ist für einen Mandanten und eine Organisation spezifisch.
Um eine Quellverbindung zu erstellen, stellen Sie eine POST-Anfrage an den /sourceConnections
-Endpunkt der Flow Service-API.
API-Format
POST /sourceConnections
Anfrage
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/sourceConnections' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
-d '{
"name": "Data Landing Zone source connection",
"data": {
"format": "delimited"
},
"params": {
"path": "dlz-user-container/data8.csv"
},
"connectionSpec": {
"id": "26f526f2-58f4-4712-961d-e41bf1ccc0e8",
"version": "1.0"
}
}'
name
data.format
params.path
connectionSpec.id
26f526f2-58f4-4712-961d-e41bf1ccc0e8
.Antwort
Eine erfolgreiche Antwort gibt die eindeutige Kennung (id
) der neu erstellten Quellverbindung zurück. Diese ID ist im nächsten Tutorial zum Erstellen eines Datenflusses erforderlich.
{
"id": "f5b46949-8c8d-4613-80cc-52c9c039e8b9",
"etag": "\"1400d460-0000-0200-0000-613be3520000\""
}
Nächste Schritte
In diesem Tutorial haben Sie Ihre Data Landing Zone-Anmeldeinformationen abgerufen, die Dateistruktur untersucht, um die Datei zu finden, die Sie in Platform importieren möchten, und eine Quellverbindung erstellt, um mit dem Übertragen Ihrer Daten an Platform zu beginnen. Sie können jetzt mit dem nächsten Tutorial fortfahren, in dem Sie erfahren, wie Sie einen Datenfluss erstellen, um Cloud-Speicherdaten mithilfe der - Flow Service in Platform zu.