Documentación Experience Platform Guía de conectores de origen

Ingesta de datos cifrados

Last update: Tue Jul 16 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

Temas:

Creado para:

Desarrollador

Puede introducir archivos de datos cifrados en Adobe Experience Platform mediante fuentes por lotes de almacenamiento en la nube. Con la ingesta de datos cifrados, puede aprovechar los mecanismos de cifrado asimétricos para transferir datos por lotes de forma segura a Experience Platform. Actualmente, los mecanismos de cifrado asimétrico admitidos son PGP y GPG.

El proceso de ingesta de datos cifrados es el siguiente:

Cree un par de claves de cifrado mediante las API de Experience Platform. El par de claves de cifrado consta de una clave privada y una clave pública. Una vez creada, puede copiar o descargar la clave pública, junto con su ID de clave pública y hora de caducidad correspondientes. Durante este proceso, el Experience Platform almacena la clave privada en un almacén seguro. NOTA: La clave pública de la respuesta está codificada en Base64 y debe descifrarse antes de usar.
Utilice la clave pública para cifrar el archivo de datos que desea introducir.
Coloque el archivo cifrado en el almacenamiento en la nube.
Una vez que el archivo cifrado esté listo, cree una conexión de origen y un flujo de datos para el origen de almacenamiento en la nube. Durante el paso de creación de flujo, debe proporcionar un parámetro encryption e incluir su ID de clave pública.
Experience Platform recupera la clave privada del almacén seguro para descifrar los datos en el momento de la ingesta.

IMPORTANT

El tamaño máximo de un solo archivo cifrado es de 1 GB. Por ejemplo, puede introducir datos de 2 GB en una sola ejecución de flujo de datos, pero cualquier archivo individual de esos datos no puede superar 1 GB.

Este documento proporciona pasos sobre cómo generar un par de claves de cifrado para cifrar los datos e introducir esos datos cifrados en Experience Platform mediante fuentes de almacenamiento en la nube.

Introducción get-started

Este tutorial requiere una comprensión práctica de los siguientes componentes de Adobe 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.
- Fuentes de almacenamiento en la nube: Cree un flujo de datos para llevar los datos por lotes de su fuente de almacenamiento en la nube al Experience 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.

Uso de API de Platform

Para obtener información sobre cómo realizar llamadas correctamente a las API de Platform, consulte la guía sobre introducción a las API de Platform.

Extensiones de archivo compatibles con archivos cifrados supported-file-extensions-for-encrypted-files

La lista de extensiones de archivo compatibles con los archivos cifrados es la siguiente:

.csv
.tsv
.json
.parquet
.csv.gpg
.tsv.gpg
.json.gpg
.parquet.gpg
.csv.pgp
.tsv.pgp
.json.pgp
.parquet.pgp
.gpg
.pgp

NOTE

La ingesta de archivos cifrados en fuentes de Adobe Experience Platform admite openPGP y no cualquier versión propietaria específica de PGP.

Crear par de claves de cifrado create-encryption-key-pair

El primer paso para la ingesta de datos cifrados en Experience Platform es crear el par de claves de cifrado realizando una solicitud del POST al extremo /encryption/keys de la API Connectors.

Formato de API

POST /data/foundation/connectors/encryption/keys

Solicitud

Ver solicitud de ejemplo

La siguiente solicitud genera un par de claves de cifrado mediante el algoritmo de cifrado PGP.

code language-shell

code language-shell
`curl -X POST \ 'https://platform.adobe.io/data/foundation/connectors/encryption/keys' \ -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 '{ "encryptionAlgorithm": "PGP", "params": { "passPhrase": "{{PASSPHRASE}}" } }'`

curl -X POST \
  'https://platform.adobe.io/data/foundation/connectors/encryption/keys' \
  -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 '{
      "encryptionAlgorithm": "PGP",
      "params": {
          "passPhrase": "{{PASSPHRASE}}"
      }
  }'

table 0-row-2 1-row-2 2-row-2
Parámetro	Descripción
`encryptionAlgorithm`	El tipo de algoritmo de cifrado que está utilizando. Los tipos de cifrado admitidos son `PGP` y `GPG`.
`params.passPhrase`	La frase de contraseña proporciona una capa adicional de protección para las claves de cifrado. Una vez creada, el Experience Platform almacena la frase de contraseña en un almacén seguro diferente de la clave pública. Debe proporcionar una cadena que no esté vacía como frase de contraseña.

Respuesta

Ver respuesta de ejemplo

Una respuesta correcta devuelve la clave pública codificada en Base64, el ID de clave pública y la hora de caducidad de las claves. La hora de caducidad se establece automáticamente en 180 días después de la fecha de generación de la clave. La hora de caducidad no se puede configurar actualmente.

code language-json
`{ "publicKey": "{PUBLIC_KEY}", "publicKeyId": "{PUBLIC_KEY_ID}", "expiryTime": "1684843168" }`

table 0-row-2 1-row-2 2-row-2 3-row-2
Propiedad	Descripción
`publicKey`	La clave pública se utiliza para cifrar los datos en el almacenamiento de la nube. Esta clave corresponde a la clave privada que también se creó durante este paso. Sin embargo, la clave privada se envía inmediatamente al Experience Platform.
`publicKeyId`	El ID de clave pública se utiliza para crear un flujo de datos e introducir los datos cifrados del almacenamiento en la nube en Experience Platform.
`expiryTime`	La hora de caducidad define la fecha de caducidad del par de claves de cifrado. Esta fecha se establece automáticamente en 180 días después de la fecha de generación de claves y se muestra en formato unix timestamp.

Recuperar claves de cifrado retrieve-encryption-keys

Para recuperar todas las claves de cifrado de su organización, realice una solicitud de GET al extremo /encryption/keys=nt.

Formato de API

GET /data/foundation/connectors/encryption/keys

Solicitud

Ver solicitud de ejemplo

La siguiente solicitud recupera todas las claves de cifrado de la organización.

code language-shell
`curl -X GET \ 'https://platform.adobe.io/data/foundation/connectors/encryption/keys' \ -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \ -H 'x-api-key: {{API_KEY}}' \ -H 'x-gw-ims-org-id: {{ORG_ID}}' \`

Respuesta

Ver respuesta de ejemplo

Una respuesta correcta devuelve el algoritmo de cifrado, la clave pública, el ID de clave pública y la hora de caducidad correspondiente de las claves.

code language-json
`{ "encryptionAlgorithm": "{ENCRYPTION_ALGORITHM}", "publicKeyId": "{PUBLIC_KEY_ID}", "publicKey": "{PUBLIC_KEY}", "expiryTime": "{EXPIRY_TIME}" }`

Recuperar claves de cifrado por identificador retrieve-encryption-keys-by-id

Para recuperar un conjunto específico de claves de cifrado, realice una solicitud de GET al extremo /encryption/keys y proporcione el identificador de clave pública como parámetro de encabezado.

Formato de API

GET /data/foundation/connectors/encryption/keys/{PUBLIC_KEY_ID}

Solicitud

Ver solicitud de ejemplo

code language-shell

code language-shell
`curl -X GET \ 'https://platform.adobe.io/data/foundation/connectors/encryption/keys/{publicKeyId}' \ -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \ -H 'x-api-key: {{API_KEY}}' \ -H 'x-gw-ims-org-id: {{ORG_ID}}' \`

curl -X GET \
  'https://platform.adobe.io/data/foundation/connectors/encryption/keys/{publicKeyId}' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -H 'x-api-key: {{API_KEY}}' \
  -H 'x-gw-ims-org-id: {{ORG_ID}}' \

Respuesta

Ver respuesta de ejemplo

Una respuesta correcta devuelve el algoritmo de cifrado, la clave pública, el ID de clave pública y la hora de caducidad correspondiente de las claves.

code language-json
`{ "encryptionAlgorithm": "{ENCRYPTION_ALGORITHM}", "publicKeyId": "{PUBLIC_KEY_ID}", "publicKey": "{PUBLIC_KEY}", "expiryTime": "{EXPIRY_TIME}" }`

Crear par de claves administrado por el cliente create-customer-managed-key-pair

Si lo desea, puede crear un par de claves de verificación de firma para firmar e introducir los datos cifrados.

Durante esta fase, debe generar su propia combinación de clave privada y clave pública y, a continuación, utilizar la clave privada para firmar los datos cifrados. A continuación, debe codificar la clave pública en Base64 y luego compartirla con Experience Platform para que Platform pueda comprobar su .

Compartir la clave pública con el Experience Platform

Para compartir la clave pública, realice una solicitud de POST al extremo /customer-keys y proporcione el algoritmo de cifrado y la clave pública codificada en Base64.

Formato de API

POST /data/foundation/connectors/encryption/customer-keys

Solicitud

Ver solicitud de ejemplo

code language-shell

code language-shell
`curl -X POST \ 'https://platform.adobe.io/data/foundation/connectors/encryption/customer-keys' \ -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 '{ "encryptionAlgorithm": {{ENCRYPTION_ALGORITHM}}, "publicKey": {{BASE_64_ENCODED_PUBLIC_KEY}} }'`

curl -X POST \
  'https://platform.adobe.io/data/foundation/connectors/encryption/customer-keys' \
  -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 '{
      "encryptionAlgorithm": {{ENCRYPTION_ALGORITHM}},
      "publicKey": {{BASE_64_ENCODED_PUBLIC_KEY}}
    }'

table 0-row-2 1-row-2 2-row-2
Parámetro	Descripción
`encryptionAlgorithm`	El tipo de algoritmo de cifrado que está utilizando. Los tipos de cifrado admitidos son `PGP` y `GPG`.
`publicKey`	La clave pública que corresponde a las claves administradas por el cliente utilizadas para firmar el cifrado. Esta clave debe tener codificación Base64.

Respuesta

Ver respuesta de ejemplo

code language-json
`{ "publicKeyId": "e31ae895-7896-469a-8e06-eb9207ddf1c2" }`

table 0-row-2 1-row-2
Propiedad	Descripción
`publicKeyId`	Este ID de clave pública se devuelve en respuesta a compartir la clave gestionada por el cliente con el Experience Platform. Puede proporcionar este ID de clave pública como ID de clave de verificación de firma al crear un flujo de datos para datos firmados y cifrados.

Conecte el origen de almacenamiento en la nube al Experience Platform mediante la API Flow Service

Una vez recuperado el par de claves de cifrado, ahora puede continuar y crear una conexión de origen para la fuente de almacenamiento en la nube y llevar los datos cifrados a Platform.

En primer lugar, debe crear una conexión base para autenticar el origen con Platform. Para crear una conexión base y autenticar el origen, seleccione el origen que desee utilizar en la lista siguiente:

Después de crear una conexión base, debe seguir los pasos descritos en el tutorial para crear una conexión de origen para un origen de almacenamiento en la nube para crear una conexión de origen, una conexión de destino y una asignación.

Creación de un flujo de datos para datos cifrados create-a-dataflow-for-encrypted-data

NOTE

Debe tener lo siguiente para crear un flujo de datos para la ingesta de datos cifrados:

Para crear un flujo de datos, realice una solicitud de POST al extremo /flows de la API Flow Service. Para introducir datos cifrados, debe agregar una sección encryption a la propiedad transformations e incluir publicKeyId que se creó en un paso anterior.

Formato de API

POST /flows

Crear un flujo de datos para la ingesta de datos cifrados

Solicitud

accordion

Ver solicitud de ejemplo

La siguiente solicitud crea un flujo de datos para introducir datos cifrados para una fuente de almacenamiento en la nube.

code language-shell

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": "ACME Customer Data",
    "description": "ACME Customer Data (Encrypted)",
    "flowSpec": {
        "id": "9753525b-82c7-4dce-8a9b-5ccfce2b9876",
        "version": "1.0"
    },
    "sourceConnectionIds": [
        "655f7c1b-1977-49b3-a429-51379ecf0e15"
    ],
    "targetConnectionIds": [
        "de688225-d619-481c-ae3b-40c250fd7c79"
    ],
    "transformations": [
        {
            "name": "Mapping",
            "params": {
                "mappingId": "6b6e24213dbe4f57bd8207d21034ff03",
                "mappingVersion":"0"
            }
        },
        {
            "name": "Encryption",
            "params": {
                "publicKeyId":"311ef6f8-9bcd-48cf-a9e9-d12c45fb7a17"
            }
        }
    ],
    "scheduleParams": {
        "startTime": "1675793392",
        "frequency": "once"
    }
}'

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 9-row-2
Propiedad	Descripción
`flowSpec.id`	ID de especificación de flujo que corresponde a las fuentes de almacenamiento en la nube.
`sourceConnectionIds`	Identificador de conexión de origen. Este ID representa la transferencia de datos de origen a Platform.
`targetConnectionIds`	El ID de conexión de destino. Este ID representa dónde aterrizan los datos una vez que se transfieren a Platform.
`transformations[x].params.mappingId`	ID de asignación.
`transformations.name`	Al ingerir archivos cifrados, debe proporcionar `Encryption` como parámetro de transformaciones adicional para el flujo de datos.
`transformations[x].params.publicKeyId`	El ID de clave pública que ha creado. Este ID es la mitad del par de claves de cifrado que se usa para cifrar los datos del almacenamiento en la nube.
`scheduleParams.startTime`	Hora de inicio del flujo de datos en tiempo epoch.
`scheduleParams.frequency`	Frecuencia con la que el flujo de datos recopilará datos. Los valores aceptables incluyen: `once`, `minute`, `hour`, `day` o `week`.
`scheduleParams.interval`	El intervalo designa el período entre dos ejecuciones de flujo consecutivas. El valor del intervalo debe ser un entero distinto de cero. El intervalo no es necesario cuando la frecuencia está establecida como `once` y debe ser mayor o igual que `15` para otros valores de frecuencia.

Respuesta

accordion

Ver respuesta de ejemplo

Una respuesta correcta devuelve el identificador (id) del flujo de datos recién creado para los datos cifrados.

code language-json
`{ "id": "dbc5c132-bc2a-4625-85c1-32bc2a262558", "etag": "\"8e000533-0000-0200-0000-5f3c40fd0000\"" }`

Cree un flujo de datos para introducir datos cifrados y firmados

Solicitud

accordion

Ver solicitud de ejemplo

code language-shell

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": "ACME Customer Data (with Sign Verification)",
    "description": "ACME Customer Data (with Sign Verification)",
    "flowSpec": {
        "id": "9753525b-82c7-4dce-8a9b-5ccfce2b9876",
        "version": "1.0"
    },
    "sourceConnectionIds": [
        "655f7c1b-1977-49b3-a429-51379ecf0e15"
    ],
    "targetConnectionIds": [
        "de688225-d619-481c-ae3b-40c250fd7c79"
    ],
    "transformations": [
        {
            "name": "Mapping",
            "params": {
                "mappingId": "6b6e24213dbe4f57bd8207d21034ff03",
                "mappingVersion":"0"
            }
        },
        {
            "name": "Encryption",
            "params": {
                "publicKeyId":"311ef6f8-9bcd-48cf-a9e9-d12c45fb7a17",
                "signVerificationKeyId":"e31ae895-7896-469a-8e06-eb9207ddf1c2"
            }
        }
    ],
    "scheduleParams": {
        "startTime": "1675793392",
        "frequency": "once"
    }
}'

table 0-row-2 1-row-2
Propiedad	Descripción
`params.signVerificationKeyId`	El ID de la clave de verificación de firma es el mismo que el ID de la clave pública recuperado después de compartir la clave pública codificada en Base64 con Experience Platform.

Respuesta

accordion

Ver respuesta de ejemplo

Una respuesta correcta devuelve el identificador (id) del flujo de datos recién creado para los datos cifrados.

code language-json
`{ "id": "dbc5c132-bc2a-4625-85c1-32bc2a262558", "etag": "\"8e000533-0000-0200-0000-5f3c40fd0000\"" }`

Eliminar claves de cifrado delete-encryption-keys

Para eliminar las claves de cifrado, realice una solicitud de DELETE al extremo /encryption/keys y proporcione el identificador de clave pública como parámetro de encabezado.

Formato de API

DELETE /data/foundation/connectors/encryption/keys/{PUBLIC_KEY_ID}

Solicitud

Ver solicitud de ejemplo

code language-shell

code language-shell
`curl -X DELETE \ 'https://platform.adobe.io/data/foundation/connectors/encryption/keys/{publicKeyId}' \ -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \ -H 'x-api-key: {{API_KEY}}' \ -H 'x-gw-ims-org-id: {{ORG_ID}}' \`

curl -X DELETE \
  'https://platform.adobe.io/data/foundation/connectors/encryption/keys/{publicKeyId}' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -H 'x-api-key: {{API_KEY}}' \
  -H 'x-gw-ims-org-id: {{ORG_ID}}' \

Respuesta

Una respuesta correcta devuelve el estado HTTP 204 (sin contenido) y un cuerpo en blanco.

Validar claves de cifrado validate-encryption-keys

Para validar las claves de cifrado, realice una solicitud de GET al extremo /encryption/keys/validate/ y proporcione el identificador de clave pública que desea validar como parámetro de encabezado.

GET /data/foundation/connectors/encryption/keys/validate/{PUBLIC_KEY_ID}

Solicitud

Ver solicitud de ejemplo

code language-shell

code language-shell
`curl -X GET \ 'https://platform.adobe.io/data/foundation/connectors/encryption/keys/validate/{publicKeyId}' \ -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \ -H 'x-api-key: {{API_KEY}}' \ -H 'x-gw-ims-org-id: {{ORG_ID}}' \`

curl -X GET \
  'https://platform.adobe.io/data/foundation/connectors/encryption/keys/validate/{publicKeyId}' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -H 'x-api-key: {{API_KEY}}' \
  -H 'x-gw-ims-org-id: {{ORG_ID}}' \

Respuesta

Una respuesta correcta devuelve una confirmación de que los ID son válidos o no son válidos.

Válido

Un identificador de clave pública válido devuelve el estado Active junto con el identificador de clave pública.

code language-json
`{ "publicKeyId": "{PUBLIC_KEY_ID}", "status": "Active" }`

No válido

Un identificador de clave pública no válido devuelve el estado Expired junto con el identificador de clave pública.

code language-json
`{ "publicKeyId": "{PUBLIC_KEY_ID}", "status": "Expired" }`

Restricciones en la ingesta recurrente restrictions-on-recurring-ingestion

La ingesta de datos cifrados no admite la ingesta de carpetas recurrentes o de varios niveles en las fuentes. Todos los archivos cifrados deben estar contenidos en una sola carpeta. Tampoco se admiten caracteres comodín con varias carpetas en una sola ruta de origen.

El siguiente es un ejemplo de una estructura de carpetas admitida, donde la ruta de origen es /ACME-customers/*.csv.gpg.

En esta situación, los archivos en negrita se incorporan al Experience Platform.

clientes de ACME
- Archivo1.csv.gpg
- File2.json.gpg
- Archivo3.csv.gpg
- File4.json
- Archivo5.csv.gpg

El siguiente es un ejemplo de una estructura de carpetas no compatible en la que la ruta de origen es /ACME-customers/*.

En este escenario, la ejecución del flujo fallará y devolverá un mensaje de error que indica que los datos no se pueden copiar desde el origen.

clientes de ACME
- File1.csv.gpg
- File2.json.gpg
- Subcarpeta1
  - File3.csv.gpg
  - File4.json.gpg
  - File5.csv.gpg
Lealtad a ACME
- File6.csv.gpg

Pasos siguientes

Siguiendo este tutorial, ha creado un par de claves de cifrado para los datos de almacenamiento en la nube y un flujo de datos para introducir los datos cifrados mediante Flow Service API. Para obtener actualizaciones de estado sobre la integridad, los errores y las métricas del flujo de datos, lee la guía sobre monitorización del flujo de datos mediante la Flow Service API.

recommendation-more-help

337b99bb-92fb-42ae-b6b7-c7042161d089