Erstellen eines Datenflusses für Cloud-Speicherquellen mit der Flow Service-API
In diesem Tutorial werden die Schritte zum Abrufen von Daten aus einer Cloud-Speicherquelle und zum Übertragen dieser Daten in Platform mithilfe der Flow Service -API behandelt.
Erste Schritte
Dieses Tutorial setzt ein Grundverständnis der folgenden Komponenten von Adobe Experience Platform voraus:
-
Experience Data Model (XDM) System: Das standardisierte Framework, mit dem Experience Platform Kundenerlebnisdaten ordnet.
- Grundlagen der Schemakomposition: Machen Sie sich mit den grundlegenden Bausteinen von XDM-Schemata vertraut, einschließlich der wichtigsten Prinzipien und Best Practices bei der Schemakomposition.
- Entwicklerhandbuch zur Schema Registry: Enthält wichtige Informationen, die Sie benötigen, um die Schema Registry API erfolgreich aufrufen zu können. Diese umfassen Ihre
{TENANT_ID}
, das Konzept sogenannter „Container“ und die für Anfragen erforderlichen Kopfzeilen, von denen insbesondere die Accept-Kopfzeile und deren mögliche Werte wichtig sind.
-
Catalog Service: Der Katalog ist das „System of Record“ für den Speicherort und die Herkunft von Daten in Experience Platform.
-
Batch ingestion: Mit der Batch-Aufnahme-API können Sie Daten in Form von Batch-Dateien in Experience Platform aufnehmen.
-
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.
Verwenden von Platform-APIs
Informationen darüber, wie Sie Platform-APIs erfolgreich aufrufen können, finden Sie im Handbuch unter Erste Schritte mit Platform-APIs.
Erstellen einer Quellverbindung source
Sie können eine Quellverbindung erstellen, indem Sie eine POST-Anfrage an den sourceConnections
-Endpunkt der Flow Service -API richten und dabei Ihre Basisverbindungs-ID, den Pfad zur Quelldatei, die Sie erfassen möchten, und die entsprechende Verbindungsspezifikations-ID Ihrer Quelle angeben.
Beim Erstellen einer Quellverbindung müssen Sie auch einen Enum-Wert für das Datenformat-Attribut definieren.
Verwenden Sie die folgenden Aufzählungswerte für dateibasierte Quellen:
delimited
json
parquet
Setzen Sie für alle tabellenbasierten Quellen den Wert auf tabular
.
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": "Cloud Storage source connection",
"description: "Source connection for a cloud storage source",
"baseConnectionId": "1f164d1b-debe-4b39-b4a9-df767f7d6f7c",
"data": {
"format": "delimited",
"properties": {
"columnDelimiter": "{COLUMN_DELIMITER}",
"encoding": "{ENCODING}",
"compressionType": "{COMPRESSION_TYPE}"
}
},
"params": {
"path": "/acme/summerCampaign/account.csv",
"type": "file"
},
"connectionSpec": {
"id": "4c10e202-c428-4796-9208-5f1f5732b1cf",
"version": "1.0"
}
}'
baseConnectionId
data.format
delimited
, JSON
und parquet
.data.properties
data.properties.columnDelimiter
,
) als Standardwert verwendet. Hinweis: Die columnDelimiter
-Eigenschaft kann nur bei der Aufnahme von getrennten Dateien verwendet werden.data.properties.encoding
UTF-8
und ISO-8859-1
. Hinweis: Der Parameter encoding
ist nur verfügbar, wenn CSV-Dateien mit Trennzeichen aufgenommen werden. Andere Dateitypen werden mit der Standardkodierung UTF-8
erfasst.data.properties.compressionType
bzip2
, gzip
, deflate
, zipDeflate
, tarGzip
und tar
. Hinweis: Die Eigenschaft compressionType
kann nur bei der Erfassung von getrennten oder JSON-Dateien verwendet werden.params.path
/acme/summerCampaign/*.csv
nimmt den gesamten Ordner /acme/summerCampaign/
auf.params.type
file
", um eine einzelne Datei zu erfassen, und verwenden Sie den Typ "folder
", um einen ganzen Ordner aufzunehmen.connectionSpec.id
Antwort
Eine erfolgreiche Antwort gibt die eindeutige Kennung (id
) der neu erstellten Quellverbindung zurück. Diese ID ist in einem späteren Schritt erforderlich, um einen Datenfluss zu erstellen.
{
"id": "26b53912-1005-49f0-b539-12100559f0e2",
"etag": "\"11004d97-0000-0200-0000-5f3c3b140000\""
}
Verwenden Sie reguläre Ausdrücke, um einen bestimmten Dateisatz für die Aufnahme auszuwählen. regex
Sie können beim Erstellen einer Quellverbindung reguläre Ausdrücke verwenden, um einen bestimmten Dateisatz von Ihrer Quelle an Platform zu erfassen.
API-Format
POST /sourceConnections
Anfrage
Im folgenden Beispiel wird der reguläre Ausdruck im Dateipfad verwendet, um die Aufnahme aller CSV-Dateien anzugeben, deren Name premium
enthält.
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": "Cloud Storage source connection",
"description: "Source connection for a cloud storage source",
"baseConnectionId": "1f164d1b-debe-4b39-b4a9-df767f7d6f7c",
"data": {
"format": "delimited"
},
"params": {
"path": "/acme/summerCampaign/*premium*.csv",
"type": "folder"
},
"connectionSpec": {
"id": "4c10e202-c428-4796-9208-5f1f5732b1cf",
"version": "1.0"
}
}'
Quellverbindung zur rekursiven Erfassung von Daten konfigurieren
Beim Erstellen einer Quellverbindung können Sie den Parameter recursive
verwenden, um Daten aus tief verschachtelten Ordnern zu erfassen.
API-Format
POST /sourceConnections
Anfrage
Im folgenden Beispiel informiert der Parameter recursive: true
Flow Service darüber, dass während des Aufnahmevorgangs alle Unterordner rekursiv gelesen werden sollen.
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": "Cloud Storage source connection",
"description: "Source connection for a cloud storage source with recursive ingestion",
"baseConnectionId": "1f164d1b-debe-4b39-b4a9-df767f7d6f7c",
"data": {
"format": "delimited"
},
"params": {
"path": "/acme/summerCampaign/customers/premium/buyers/recursive",
"type": "folder",
"recursive": true
},
"connectionSpec": {
"id": "4c10e202-c428-4796-9208-5f1f5732b1cf",
"version": "1.0"
}
}'
Erstellen eines XDM-Zielschemas target-schema
Damit die Quelldaten in Platform verwendet werden können, muss ein Zielschema erstellt werden, das die Quelldaten entsprechend Ihren Anforderungen strukturiert. Das Zielschema wird dann verwendet, um einen Platform-Datensatz zu erstellen, in dem die Quelldaten enthalten sind.
Ein Ziel-XDM-Schema kann erstellt werden, indem eine POST-Anfrage an die Schema-Registrierungs-API durchgeführt wird.
Ausführliche Schritte zum Erstellen eines XDM-Zielschemas finden Sie im Tutorial zum Erstellen eines Schemas mithilfe der API.
Erstellen eines Zieldatensatzes target-dataset
Ein Zieldatensatz kann erstellt werden, indem eine POST-Anfrage an die Catalog Service API durchgeführt wird, wodurch die ID des Zielschemas in der Payload angegeben wird.
Ausführliche Anweisungen zum Erstellen eines Zieldatensatzes finden Sie im Tutorial zu Erstellen eines Datensatzes mithilfe der API.
Erstellen einer Zielverbindung target-connection
Eine Zielverbindung stellt die Verbindung zum Ziel dar, in das die aufgenommenen Daten übernommen werden. Um eine Zielverbindung zu erstellen, müssen Sie die festgelegte Verbindungsspezifikations-ID angeben, die dem Data Lake zugeordnet ist. Diese Verbindungsspezifikations-ID lautet: c604ff05-7f1a-43c0-8e18-33bf874cb11c
.
Sie verfügen jetzt über die eindeutigen Kennungen eines Zielschemas, eines Zieldatensatzes und der Verbindungsspezifikations-ID zum Data Lake. Mithilfe dieser Kennungen können Sie über die Flow Service-API eine Zielverbindung erstellen, um den Datensatz anzugeben, der die eingehenden Quelldaten enthalten wird.
API-Format
POST /targetConnections
Anfrage
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/targetConnections' \
-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": "Target Connection for a Cloud Storage connector",
"description": "Target Connection for a Cloud Storage connector",
"data": {
"schema": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/995dabbea86d58e346ff91bd8aa741a9f36f29b1019138d4",
"version": "application/vnd.adobe.xed-full+json;version=1"
}
},
"params": {
"dataSetId": "5f3c3cedb2805c194ff0b69a"
},
"connectionSpec": {
"id": "c604ff05-7f1a-43c0-8e18-33bf874cb11c",
"version": "1.0"
}
}'
data.schema.id
$id
des XDM-Zielschemas.data.schema.version
application/vnd.adobe.xed-full+json;version=1
festgelegt werden, wodurch die neueste Nebenversion des Schemas zurückgegeben wird.params.dataSetId
connectionSpec.id
c604ff05-7f1a-43c0-8e18-33bf874cb11c
.Antwort
Eine erfolgreiche Antwort gibt die eindeutige Kennung der neuen Zielverbindung an (id
). Diese ID ist in späteren Schritten erforderlich.
{
"id": "dbc5c132-bc2a-4625-85c1-32bc2a262558",
"etag": "\"8e000533-0000-0200-0000-5f3c40fd0000\""
}
Erstellen einer Zuordnung mapping
Damit die Quelldaten in einen Zieldatensatz aufgenommen werden können, müssen sie zunächst dem Zielschema zugeordnet werden, zu dem der Zieldatensatz gehört.
Um einen Zuordnungssatz zu erstellen, stellen Sie eine POST-Anfrage an den Endpunkt mappingSets
der Data Prep -API und geben dabei Ihr Ziel-XDM-Schema $id
und die Details der zu erstellenden Zuordnungssätze an.
API-Format
POST /conversion/mappingSets
Anfrage
curl -X POST \
'https://platform.adobe.io/data/foundation/conversion/mappingSets' \
-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 '{
"version": 0,
"xdmSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/995dabbea86d58e346ff91bd8aa741a9f36f29b1019138d4",
"xdmVersion": "1.0",
"id": null,
"mappings": [
{
"destinationXdmPath": "_id",
"sourceAttribute": "Id",
"identity": false,
"identityGroup": null,
"namespaceCode": null,
"version": 0
},
{
"destinationXdmPath": "person.name.firstName",
"sourceAttribute": "FirstName",
"identity": false,
"identityGroup": null,
"namespaceCode": null,
"version": 0
},
{
"destinationXdmPath": "person.name.lastName",
"sourceAttribute": "LastName",
"identity": false,
"identityGroup": null,
"namespaceCode": null,
"version": 0
}
]
}'
xdmSchema
Antwort
Eine erfolgreiche Antwort gibt Details zur neu erstellten Zuordnung an, einschließlich der eindeutigen Kennung (id
). Dieser Wert ist in einem späteren Schritt zum Erstellen eines Datenflusses erforderlich.
{
"id": "bf5286a9c1ad4266baca76ba3adc9366",
"version": 0,
"createdDate": 1597784069368,
"modifiedDate": 1597784069368,
"createdBy": "{CREATED_BY}",
"modifiedBy": "{MODIFIED_BY}"
}
Abrufen von Datenflussspezifikationen specs
Ein Datenfluss ist für die Erfassung von Daten aus Quellen und deren Aufnahme in Platform zuständig. Um einen Datenfluss zu erstellen, müssen Sie zunächst die Datenflussspezifikationen abrufen, die für die Erfassung von Cloud-Speicherdaten zuständig sind.
API-Format
GET /flowSpecs?property=name=="CloudStorageToAEP"
Anfrage
curl -X GET \
'https://platform.adobe.io/data/foundation/flowservice/flowSpecs?property=name==%22CloudStorageToAEP%22' \
-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 werden die Details der Datenflussspezifikation zurückgegeben, die für die Übermittlung von Daten aus Ihrer Quelle an Platform sorgt. Die Antwort enthält die eindeutige Flussspezifikation id
, die erforderlich ist, um einen neuen Datenfluss zu erstellen.
code language-json |
---|
|
Erstellen eines Datenflusses
Der letzte Schritt bei der Erfassung von Cloud-Speicherdaten besteht darin, einen Datenfluss zu erstellen. Bislang haben Sie die folgenden erforderlichen Werte vorbereitet:
Ein Datenfluss ist für die Planung und Erfassung von Daten aus einer Quelle verantwortlich. Sie können einen Datenfluss erstellen, indem Sie eine POST-Anfrage ausführen und dabei die oben genannten Werte in der Payload angeben.
Um eine Aufnahme zu planen, legen Sie zunächst den Startzeitwert auf die Epochenzeit in Sekunden fest. Anschließend müssen Sie den Frequenzwert auf eine der fünf Optionen festlegen: once
, minute
, hour
, day
oder week
. Der Intervallwert gibt den Zeitraum zwischen zwei aufeinanderfolgenden Aufnahmen an. Bei der Erstellung einer einmaligen Aufnahme ist kein Intervall erforderlich. Für alle anderen Frequenzen muss der Intervallwert auf gleich oder größer als 15
festgelegt werden.
API-Format
POST /flows
Anfrage
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/flows' \
-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": "Cloud Storage flow to Platform",
"description": "Cloud Storage flow to Platform",
"flowSpec": {
"id": "9753525b-82c7-4dce-8a9b-5ccfce2b9876",
"version": "1.0"
},
"sourceConnectionIds": [
"26b53912-1005-49f0-b539-12100559f0e2"
],
"targetConnectionIds": [
"f7eb08fa-5f04-4e45-ab08-fa5f046e45ee"
],
"transformations": [
{
"name": "Mapping",
"params": {
"mappingId": "bf5286a9c1ad4266baca76ba3adc9366",
"mappingVersion": 0
}
}
],
"scheduleParams": {
"startTime": "1597784298",
"frequency":"minute",
"interval":"30"
}
}'
flowSpec.id
sourceConnectionIds
targetConnectionIds
transformations.params.mappingId
scheduleParams.startTime
scheduleParams.frequency
once
, minute
, hour
, day
oder week
.scheduleParams.interval
Das Intervall bezeichnet den Zeitraum zwischen zwei aufeinanderfolgenden Datenflussausführungen. Der Wert des Intervalls sollte eine Ganzzahl ungleich null sein. Der akzeptierte Mindestintervallwert für jede Frequenz lautet wie folgt:
- Einmal: nicht zutreffend
- Minute: 15
- Hour: 1
- Tag: 1
- Woche: 1
Antwort
Bei einer erfolgreichen Antwort wird die ID (id
) des neu erstellten Datenflusses angegeben.
{
"id": "dbc5c132-bc2a-4625-85c1-32bc2a262558",
"etag": "\"8e000533-0000-0200-0000-5f3c40fd0000\""
}
Überwachen Ihres Datenflusses
Nachdem Ihr Datenfluss erstellt wurde, können Sie die Datenaufnahme überwachen, um Informationen über die Datenflussausführungen, den Abschlussstatus und Fehler anzuzeigen. Weitere Informationen zum Überwachen von Datenflüssen finden Sie im Tutorial Überwachen von Datenflüssen in der API
Nächste Schritte
In diesem Tutorial haben Sie einen Quell-Connector erstellt, um Daten aus Ihrem Cloud-Speicherplatz planmäßig zu erfassen. Eingehende Daten können jetzt von nachgelagerten Platform-Services wie Real-Time Customer Profile und Data Science Workspace verwendet werden. Weiterführende Informationen finden Sie in folgenden Dokumenten:
Anhang appendix
Im folgenden Abschnitt finden Sie die verschiedenen Quell-Connectoren für Cloud-Speicher und deren Verbindungsspezifikationen.
Verbindungsspezifikation
ecadc60c-7455-4d87-84dc-2a0e293d997b
86043421-563b-46ec-8e6c-e23184711bf6
4c10e202-c428-4796-9208-5f1f5732b1cf
b3ba5556-48be-44b7-8b85-ff2b69b46dc4
bf9f5905-92b7-48bf-bf20-455bc6b60a4e
be5ec48c-5b78-49d5-b8fa-7c89ec4569b8
32e8f412-cdf7-464c-9885-78184cb113fd
54e221aa-d342-4707-bcff-7a4bceef0001
c85f9425-fb21-426c-ad0b-405e9bd8a46c
bf367b0d-3d9b-4060-b67b-0d3d9bd06094