Conectar Data Landing Zone a Adobe Experience Platform mediante la API de Flow Service
Creado para:
- Desarrollador
IMPORTANTData Landing Zone es una función de almacenamiento de archivos segura y basada en la nube que permite traer archivos a Adobe Experience Platform. Los datos se eliminan automáticamente de Data Landing Zone pasados siete días.
Este tutorial lo guiará por los pasos para crear una conexión de origen de Data Landing Zone mediante la Flow Service API. Este tutorial también proporciona instrucciones sobre cómo recuperar su Data Landing Zone, así como ver y actualizar sus credenciales.
Introducción
Esta guía requiere una comprensión práctica de los siguientes componentes de Experience Platform:
- Fuentes: El Experience Platform permite la ingesta de datos de varias fuentes, al tiempo que le ofrece la capacidad de estructurar, etiquetar y mejorar los datos entrantes mediante los servicios de Platform.
- Zonas protegidas: El Experience Platform proporciona zonas protegidas virtuales que dividen una sola instancia de Platform en entornos virtuales independientes para ayudar a desarrollar y evolucionar aplicaciones de experiencia digital.
Este tutorial también requiere que lea la guía de introducción a las API de Platform para aprender a autenticarse en las API de Platform e interpretar las llamadas de ejemplo proporcionadas en la documentación.
Las secciones siguientes proporcionan información adicional que necesitará conocer para crear correctamente una conexión de origen de Data Landing Zone mediante la API Flow Service.
Recuperación de una zona de aterrizaje utilizable
IMPORTANTtype=user_drop_zone. Para obtener más información, lea la descripción general del control de acceso o póngase en contacto con el administrador del producto para obtener los permisos necesarios.El primer paso para usar las API para obtener acceso a Data Landing Zone es realizar una solicitud de GET al extremo /landingzone de la API Connectors y, al mismo tiempo, proporcionar type=user_drop_zone como parte del encabezado de la solicitud.
Formato de API
GET /data/foundation/connectors/landingzone?type=user_drop_zone
user_drop_zoneuser_drop_zone permite a la API distinguir un contenedor de zona de aterrizaje de otros tipos de contenedores disponibles para usted.Solicitud
La siguiente solicitud recupera una zona de aterrizaje existente.
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'
Respuesta
Según el proveedor, una solicitud correcta devuelve lo siguiente:
{
"containerName": "dlz-user-container",
"containerTTL": "7"
}
containerNamecontainerTTL{
"dlzPath": {
"bucketName": "dlz-prod-sandboxName",
"dlzFolder": "dlz-adf-connectors"
},
"dataTTL": {
"timeUnit": "days",
"timeQuantity": 7
},
"dlzProvider": "Amazon S3"
}
Recuperar credenciales de Data Landing Zone
Para recuperar las credenciales de un(a) Data Landing Zone, realice una solicitud de GET al extremo /credentials de la API Connectors.
Formato de API
GET /data/foundation/connectors/landingzone/credentials?type=user_drop_zone
Solicitud
El siguiente ejemplo de solicitud recupera las credenciales de una zona de aterrizaje existente.
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' \
Respuesta
Según el proveedor, una solicitud correcta devuelve lo siguiente:
{
"containerName": "dlz-user-container",
"SASToken": "sv=2020-04-08&si=dlz-ed86a61d-201f-4b50-b10f-a1bf173066fd&sr=c&sp=racwdlm&sig=4yTba8voU3L0wlcLAv9mZLdZ7NlMahbfYYPTMkQ6ZGU%3D",
"storageAccountName": "dlblobstore99hh25i3dflek",
"SASUri": "https://dlblobstore99hh25i3dflek.blob.core.windows.net/dlz-user-container?sv=2020-04-08&si=dlz-ed86a61d-201f-4b50-b10f-a1bf173066fd&sr=c&sp=racwdlm&sig=4yTba8voU3L0wlcLAv9mZLdZ7NlMahbfYYPTMkQ6ZGU%3D",
"expiryDate": "2024-01-06"
}
containerNameSASTokenstorageAccountNameSASUriexpiryDate{
"credentials": {
"clientId": "example-client-id",
"awsAccessKeyId": "example-access-key-id",
"awsSecretAccessKey": "example-secret-access-key",
"awsSessionToken": "example-session-token"
},
"dlzPath": {
"bucketName": "dlz-prod-sandboxName",
"dlzFolder": "user_drop_zone"
},
"dlzProvider": "Amazon S3",
"expiryTime": 1735689599
}
credentials.clientIdcredentials.awsAccessKeyIdcredentials.awsSecretAccessKeycredentials.awsSessionTokendlzPath.bucketNamedlzPath.dlzFolderdlzProviderexpiryTimeRecuperación de los campos obligatorios mediante API
Después de generar el token, puede recuperar los campos obligatorios mediante programación utilizando los ejemplos de solicitud que se muestran a continuación:
import requests
# API endpoint
url = "https://platform.adobe.io/data/foundation/connectors/landingzone/credentials?type=user_drop_zone"
headers = {
"Authorization": "{TOKEN}",
"Content-Type": "application/json",
"x-gw-ims-org-id": "{ORG_ID}",
"x-api-key": "{API_KEY}"
}
# Send GET request to the API
response = requests.get(url, headers=headers)
# Check if the request was successful
if response.status_code == 200:
# Parse the response as JSON (if applicable)
data = response.json()
# Print or work with the fetched data
print(" Sas Token:", data['SASToken'])
print(" Container Name:", data['containerName'])
print("\n")
else:
# Print an error message if the request failed
print(f"Failed to fetch data. Status code: {response.status_code}")
print(f"Response: {response.text}")
package org.example;
import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import org.apache.http.HttpResponse;
import org.apache.http.client.ClientProtocolException;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.impl.client.DefaultHttpClient;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
public class Main {
public static void main(String[] args) {
ObjectMapper objectMapper = new ObjectMapper();
try {
DefaultHttpClient httpClient = new DefaultHttpClient();
HttpGet getRequest = new HttpGet(
"https://platform.adobe.io/data/foundation/connectors/landingzone/credentials?type=user_drop_zone");
getRequest.addHeader("accept", "application/json");
getRequest.addHeader("Authorization","<TOKEN>");
getRequest.addHeader("Content-Type", "application/json");
getRequest.addHeader("x-gw-ims-org-id", "<ORG_ID>");
getRequest.addHeader("x-api-key", "<API_KEY>");
HttpResponse response = httpClient.execute(getRequest);
if (response.getStatusLine().getStatusCode() != 200) {
throw new RuntimeException("Failed : HTTP error code : "
+ response.getStatusLine().getStatusCode());
}
final JsonNode jsonResponse = objectMapper.readTree(response.getEntity().getContent());
System.out.println("\nOutput from API Response .... \n");
System.out.printf("ContainerName: %s%n", jsonResponse.at("/containerName").textValue());
System.out.printf("SASToken: %s%n", jsonResponse.at("/SASToken").textValue());
httpClient.getConnectionManager().shutdown();
} catch (ClientProtocolException e) {
e.printStackTrace();
} catch (IOException e) {
e.printStackTrace();
}
}
}
Actualizar credenciales de Data Landing Zone
Puede actualizar su SASToken realizando una solicitud de POST al extremo /credentials de la API Connectors.
Formato de API
POST /data/foundation/connectors/landingzone/credentials?type=user_drop_zone&action=refresh
user_drop_zoneuser_drop_zone permite a la API distinguir un contenedor de zona de aterrizaje de otros tipos de contenedores disponibles para usted.refreshrefresh le permite restablecer las credenciales de su zona de aterrizaje y generar automáticamente un nuevo SASToken.Solicitud
La siguiente solicitud actualiza las credenciales de la zona de aterrizaje.
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' \
Respuesta
La siguiente respuesta devuelve valores actualizados para su SASToken y SASUri.
{
"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"
}
Explorar la estructura y el contenido del archivo de zona de aterrizaje
Puede explorar la estructura de archivos y el contenido de su zona de aterrizaje realizando una solicitud de GET al extremo connectionSpecs de la API Flow Service.
Formato de API
GET /connectionSpecs/{CONNECTION_SPEC_ID}/explore?objectType=root
{CONNECTION_SPEC_ID}26f526f2-58f4-4712-961d-e41bf1ccc0e8.Solicitud
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}'
Respuesta
Una respuesta correcta devuelve una matriz de archivos y carpetas encontrados dentro del directorio consultado. Tome nota de la propiedad path del archivo que desea cargar, ya que debe proporcionarla en el siguiente paso para inspeccionar su estructura.
[
{
"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
}
]
Previsualizar la estructura y el contenido del archivo de zona de aterrizaje
Para inspeccionar la estructura de un archivo en la zona de aterrizaje, realice una solicitud de GET y proporcione la ruta y el tipo del archivo como parámetro de consulta.
Formato de API
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}delimitedjsonparquet
{PREVIEW}-
true -
false
Solicitud
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}'
Respuesta
Una respuesta correcta devuelve la estructura del archivo consultado, incluidos los nombres de archivo y los tipos de datos.
{
"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"
}
]
}
Usar determineProperties para detectar automáticamente la información de propiedad de archivo de un Data Landing Zone
Puede usar el parámetro determineProperties para detectar automáticamente la información de propiedad del contenido del archivo de su Data Landing Zone al realizar una llamada de GET para explorar el contenido y la estructura de su origen.
determineProperties casos de uso
En la tabla siguiente se describen diferentes escenarios que se pueden encontrar al usar el parámetro de consulta determineProperties o al proporcionar manualmente información sobre el archivo.
determinePropertiesqueryParamsdetermineProperties como parámetro de consulta, se detectarán las propiedades del archivo y la respuesta devolverá una nueva clave properties que incluye información sobre el tipo de archivo, el tipo de compresión y el delimitador de columna.queryParams, se utilizarán para generar el esquema y se devolverán las mismas propiedades como parte de la respuesta.Formato de API
GET /connectionSpecs/{CONNECTION_SPEC_ID}/explore?objectType=file&object={OBJECT}&fileType={FILE_TYPE}&preview={PREVIEW}&determineProperties=true
determinePropertiestrueSolicitud
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}'
Respuesta
Una respuesta correcta devuelve la estructura del archivo consultado, incluidos los nombres de archivo y los tipos de datos, así como una clave properties, que contiene información sobre fileType, compressionType y columnDelimiter.
{
"properties": {
"fileType": "delimited",
"compressionType": "tarGzip",
"columnDelimiter": "~"
},
"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": "birthday",
"type": "string",
"xdm": {
"type": "string"
}
}
]
},
"data": [
{
"birthday": "1313-0505-19731973",
"firstName": "Yvonne",
"lastName": "Thilda",
"id": "100",
"email": "Yvonne.Thilda@yopmail.com"
},
{
"birthday": "1515-1212-19731973",
"firstName": "Mary",
"lastName": "Pillsbury",
"id": "101",
"email": "Mary.Pillsbury@yopmail.com"
},
{
"birthday": "0505-1010-19751975",
"firstName": "Corene",
"lastName": "Joeann",
"id": "102",
"email": "Corene.Joeann@yopmail.com"
},
{
"birthday": "2727-0303-19901990",
"firstName": "Dari",
"lastName": "Greenwald",
"id": "103",
"email": "Dari.Greenwald@yopmail.com"
},
{
"birthday": "1717-0404-19651965",
"firstName": "Lucy",
"lastName": "Magdalen",
"id": "199",
"email": "Lucy.Magdalen@yopmail.com"
}
]
}
properties.fileTypedelimited, json y parquet.properties.compressionTypeEl tipo de compresión correspondiente utilizado para el archivo consultado. Los tipos de compresión admitidos son:
bzip2gzipzipDeflatetarGziptar
properties.columnDelimiter(,).Crear una conexión de origen
Una conexión de origen crea y administra la conexión con el origen externo desde el que se incorporan los datos. Una conexión de origen consta de información como el origen de datos, el formato de datos y el ID de conexión de origen necesario para crear un flujo de datos. Una instancia de conexión de origen es específica de un inquilino y una organización.
Para crear una conexión de origen, realice una solicitud de POST al extremo /sourceConnections de la API Flow Service.
Formato de API
POST /sourceConnections
Solicitud
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"
}
}'
namedata.formatparams.pathconnectionSpec.id26f526f2-58f4-4712-961d-e41bf1ccc0e8.Respuesta
Una respuesta correcta devuelve el identificador único (id) de la conexión de origen recién creada. Este ID es necesario en el siguiente tutorial para crear un flujo de datos.
{
"id": "f5b46949-8c8d-4613-80cc-52c9c039e8b9",
"etag": "\"1400d460-0000-0200-0000-613be3520000\""
}
Pasos siguientes
Al seguir este tutorial, ha recuperado las credenciales de Data Landing Zone, ha explorado su estructura de archivos para encontrar el archivo que desea llevar a Platform y ha creado una conexión de origen para empezar a llevar los datos a Platform. Ahora puede continuar con el siguiente tutorial, donde aprenderá a crear un flujo de datos para llevar datos de almacenamiento en la nube a Platform mediante la Flow Service API.