Copia de datos desde un punto de conexión HTTP mediante Azure Data Factory o Azure Synapse Analytics

Artículo
10/20/2023

SE APLICA A: Azure Data Factory Azure Synapse Analytics

Sugerencia

Pruebe Data Factory en Microsoft Fabric, una solución de análisis todo en uno para empresas. Microsoft Fabric abarca todo, desde el movimiento de datos hasta la ciencia de datos, el análisis en tiempo real, la inteligencia empresarial y los informes. Obtenga información sobre cómo iniciar una nueva evaluación gratuita.

En este artículo se explica cómo usar la actividad de copia de Azure Data Factory y Azure Synapse para copiar datos desde un punto de conexión HTTP. El artículo se basa en Actividad de copia, en el que se ofrece información general acerca de la actividad de copia.

Las diferencias entre este conector HTTP, el conector REST y el conector de tabla web son:

El conector REST admite específicamente la copia de datos desde API RESTful;
El conector HTTP es genérico y puede recuperar datos desde cualquier punto de conexión HTTP, por ejemplo, para descargar archivos. Antes de que esté disponible el conector REST, puede usar el conector HTTP para copiar datos de las API de RESTful, que, aunque se admite, es menos funcional en comparación con el conector REST.
El conector de tabla web extrae contenido de la tabla de una página web HTML.

Funcionalidades admitidas

Este conector HTTP se admite para las siguientes características:

Funcionalidades admitidas	IR
Actividad de copia (origen/-)	7,7
Actividad de búsqueda	7,7

① Azure Integration Runtime ② Entorno de ejecución de integración autohospedado

Para obtener una lista de los almacenes de datos que se admiten como orígenes y receptores, consulte la tabla de almacenes de datos admitidos.

Puede usar este conector HTTP para:

Recuperar datos desde un punto de conexión HTTP o HTTPS mediante los métodos HTTP GET o POST.
Recuperar datos con uno de los siguientes tipos de autenticación: Anónima, Básica, Implícita, Windows o ClientCertificate.
Copiar la respuesta HTTP tal cual, o bien analizarla con los códecs de compresión y los formatos de archivo compatibles.

Sugerencia

Si desea probar una solicitud HTTP para la recuperación de datos antes de configurar el conector HTTP, obtenga información acerca de la especificación de API con relación a los requisitos del cuerpo y del encabezado. Puede usar herramientas como Postman o un explorador web para validar.

Prerrequisitos

Si el almacén de datos se encuentra en una red local, una red virtual de Azure o una nube privada virtual de Amazon, debe configurar un entorno de ejecución de integración autohospedado para conectarse a él.

Si el almacén de datos es un servicio de datos en la nube administrado, puede usar Azure Integration Runtime. Si el acceso está restringido a las direcciones IP que están aprobadas en las reglas de firewall, puede agregar direcciones IP de Azure Integration Runtime a la lista de permitidos.

También puede usar la característica del entorno de ejecución de integración de red virtual administrada de Azure Data Factory para acceder a la red local sin instalar ni configurar un entorno de ejecución de integración autohospedado.

Consulte Estrategias de acceso a datos para más información sobre los mecanismos de seguridad de red y las opciones que admite Data Factory.

Introducción

Para realizar la actividad de copia con una canalización, puede usar una de los siguientes herramientas o SDK:

Creación de un servicio vinculado a un origen HTTP mediante la interfaz de usuario

Siga estos pasos para crear un servicio vinculado a un origen HTTP en la interfaz de usuario de Azure Portal.

Vaya a la pestaña "Administrar" de su área de trabajo de Azure Data Factory o Synapse y seleccione "Servicios vinculados"; a continuación, haga clic en "Nuevo":
- Azure Data Factory
- Azure Synapse
Busque HTTP y seleccione su conector.
Configure los detalles del servicio, pruebe la conexión y cree el nuevo servicio vinculado.

Detalles de configuración del conector

En las siguientes secciones se proporcionan detalles sobre las propiedades que puede usar para definir entidades específicas del conector HTTP.

Propiedades del servicio vinculado

Las siguientes propiedades son compatibles con el servicio vinculado de HTTP:

Propiedad	Descripción	Obligatorio
type	La propiedad type debe establecerse en: HttpServer.	Sí
url	La dirección URL base para el servidor web.	Sí
enableServerCertificateValidation	Especifique si desea habilitar la validación de certificados TLS/SSL al conectarse al punto de conexión HTTP. Si el servidor HTTPS usa un certificado autofirmado, establezca esta propiedad en false.	No (El valor predeterminado es: true)
authenticationType	Especifica el tipo de autenticación. Los valores permitidos son: Anonymous, Basic, Digest, Windows y ClientCertificate. Además, puede configurar encabezados de autenticación en la propiedad `authHeader`. Consulte las secciones que se encuentran después de esta tabla para obtener más propiedades y ejemplos de JSON para estos tipos de autenticación.	Sí
authHeaders	Encabezados de solicitud HTTP adicionales para la autenticación. Por ejemplo, para usar la autenticación de clave de API, puede seleccionar el tipo de autenticación "Anónima" y especificar la clave de API en el encabezado.	No
connectVia	Instancia de Integration Runtime que se usará para conectarse al almacén de datos. Obtenga más información en la sección Requisitos previos. Si no se especifica, se usa el valor predeterminado de Azure Integration Runtime.	No

Uso de la autenticación Basic, Digest o Windows

Establezca la propiedad authenticationType en Basic, Digest o Windows. Además de las propiedades genéricas descritas en las secciones anteriores, especifique las siguientes:

Propiedad	Descripción	Obligatorio
userName	El nombre de usuario para acceder al punto de conexión HTTP.	Sí
password	Contraseña del usuario (valor userName). Marque este campo como un tipo SecureString para almacenarlo de forma segura. También puede hacer referencia a un secreto almacenado en Azure Key Vault.	Sí

Ejemplo

{
    "name": "HttpLinkedService",
    "properties": {
        "type": "HttpServer",
        "typeProperties": {
            "authenticationType": "Basic",
            "url" : "<HTTP endpoint>",
            "userName": "<user name>",
            "password": {
                "type": "SecureString",
                "value": "<password>"
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Uso de la autenticación ClientCertificate

Para usar la autenticación ClientCertificate, establezca la propiedad authenticationType en ClientCertificate. Además de las propiedades genéricas descritas en las secciones anteriores, especifique las siguientes:

Propiedad	Descripción	Obligatorio
embeddedCertData	Datos del certificado con codificación Base64.	Especifique embeddedCertData o certThumbprint.
certThumbprint	La huella digital del certificado que se instaló en el almacén de certificados de la máquina Integration Runtime (autohospedado). Solo se aplica cuando se especifica el tipo autohospedado de un entorno Integration Runtime en la propiedad connectVia.	Especifique embeddedCertData o certThumbprint.
password	La contraseña asociada con el certificado. Marque este campo como un tipo SecureString para almacenarlo de forma segura. También puede hacer referencia a un secreto almacenado en Azure Key Vault.	No

Si utiliza certThumbprint para la autenticación y el certificado está instalado en el almacén personal del equipo local, conceda permisos de lectura al entorno Integration Runtime (autohospedado):

Abra Microsoft Management Console (MMC). Agregue el complemento Certificados que tenga como destino Equipo local.
Expanda Certificados>Personal y, luego, seleccione Certificados.
Haga clic con el botón derecho en el certificado del almacén personal y seleccione Todas las tareas>Administrar claves privadas.
En la pestaña Seguridad, agregue la cuenta de usuario en que se ejecuta el servicio de host del entorno Integration Runtime (DIAHostService) con acceso de lectura al certificado.
El conector HTTP solo carga certificados de confianza. Si usa un certificado autofirmado o emitido por una entidad de certificación no integrada, para habilitar la confianza, el certificado también debe instalarse en uno de los siguientes almacenes:
- Personas de confianza
- Entidades de certificación raíz de tercero
- Entidades de certificación raíz de confianza

Ejemplo 1: Uso de certThumbprint

{
    "name": "HttpLinkedService",
    "properties": {
        "type": "HttpServer",
        "typeProperties": {
            "authenticationType": "ClientCertificate",
            "url": "<HTTP endpoint>",
            "certThumbprint": "<thumbprint of certificate>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Ejemplo 2: Uso de embeddedCertData

{
    "name": "HttpLinkedService",
    "properties": {
        "type": "HttpServer",
        "typeProperties": {
            "authenticationType": "ClientCertificate",
            "url": "<HTTP endpoint>",
            "embeddedCertData": "<Base64-encoded cert data>",
            "password": {
                "type": "SecureString",
                "value": "password of cert"
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Uso de los encabezados de autenticación

Además, puede configurar los encabezados de solicitud para realizar la autenticación, junto con los tipos de autenticación integrados.

Ejemplo: uso de la autenticación mediante clave de API

{
    "name": "HttpLinkedService",
    "properties": {
        "type": "HttpServer",
        "typeProperties": {
            "url": "<HTTP endpoint>",
            "authenticationType": "Anonymous",
            "authHeader": {
                "x-api-key": {
                    "type": "SecureString",
                    "value": "<API key>"
                }
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Propiedades del conjunto de datos

Si desea ver una lista completa de las secciones y propiedades disponibles para definir conjuntos de datos, consulte el artículo sobre conjuntos de datos.

Azure Data Factory admite los siguientes formatos de archivo. Consulte los artículos para conocer la configuración basada en el formato.

Las propiedades siguientes se admiten para HTTP en la configuración location del conjunto de datos basado en formato:

Propiedad	Descripción	Obligatorio
type	La propiedad type de `location` en el conjunto de datos se debe establecer en HttpServerLocation.	Sí
relativeUrl	Dirección URL relativa al recurso que contiene los datos. El conector HTTP copia los datos de la dirección URL combinada: `[URL specified in linked service][relative URL specified in dataset]`.	No

Nota

El tamaño de carga de la solicitud HTTP admitido es aproximadamente 500 KB. Si el que desea pasar al punto de conexión web supera los 500 KB, considere la posibilidad de agrupar la carga en fragmentos menores.

Ejemplo:

{
    "name": "DelimitedTextDataset",
    "properties": {
        "type": "DelimitedText",
        "linkedServiceName": {
            "referenceName": "<HTTP linked service name>",
            "type": "LinkedServiceReference"
        },
        "schema": [ < physical schema, optional, auto retrieved during authoring > ],
        "typeProperties": {
            "location": {
                "type": "HttpServerLocation",
                "relativeUrl": "<relative url>"
            },
            "columnDelimiter": ",",
            "quoteChar": "\"",
            "firstRowAsHeader": true,
            "compressionCodec": "gzip"
        }
    }
}

Propiedades de la actividad de copia

En esta sección se proporciona una lista de las propiedades que admite el origen de HTTP.

Para ver una lista completa de las secciones y propiedades que hay disponibles para definir actividades, consulte Canalizaciones.

HTTP como origen

Azure Data Factory admite los siguientes formatos de archivo. Consulte los artículos para conocer la configuración basada en el formato.

Las propiedades siguientes se admiten para HTTP en la configuración storeSettings del origen de copia basado en formato:

Propiedad	Descripción	Obligatorio
type	La propiedad type de `storeSettings` se debe establecer en HttpReadSettings.	Sí
requestMethod	Método HTTP. Los valores permitidos son Get (valor predeterminado) y Post.	No
additionalHeaders	Encabezados de solicitud HTTP adicionales.	No
requestBody	Cuerpo de la solicitud HTTP.	No
httpRequestTimeout	El tiempo de espera (el valor TimeSpan) para que la solicitud HTTP obtenga una respuesta. Este valor es el tiempo de espera para obtener una respuesta, no para leer los datos de la respuesta. El valor predeterminado es 00:01:40.	No
maxConcurrentConnections	Número máximo de conexiones simultáneas establecidas en el almacén de datos durante la ejecución de la actividad. Especifique un valor solo cuando quiera limitar las conexiones simultáneas.	No

Ejemplo:

"activities":[
    {
        "name": "CopyFromHTTP",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<Delimited text input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "DelimitedTextSource",
                "formatSettings":{
                    "type": "DelimitedTextReadSettings",
                    "skipLineCount": 10
                },
                "storeSettings":{
                    "type": "HttpReadSettings",
                    "requestMethod": "Post",
                    "additionalHeaders": "<header key: header value>\n<header key: header value>\n",
                    "requestBody": "<body for POST HTTP request>"
                }
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

Propiedades de la actividad de búsqueda

Para obtener información detallada sobre las propiedades, consulte Actividad de búsqueda.

Modelos heredados

Nota

Estos modelos siguen siendo compatibles con versiones anteriores. Se recomienda usar de ahora en adelante el nuevo modelo que se menciona en las secciones anteriores; además, la interfaz de usuario de creación ha pasado a generar el nuevo modelo.

Modelo de conjunto de datos heredado

Propiedad	Descripción	Obligatorio
type	La propiedad type del conjunto de datos debe establecerse en HttpFile.	Sí
relativeUrl	Dirección URL relativa al recurso que contiene los datos. Cuando no se especifica la propiedad, solo se usa la dirección URL especificada en la definición del servicio vinculado.	No
requestMethod	Método HTTP. Los valores permitidos son Get (valor predeterminado) y Post.	No
additionalHeaders	Encabezados de solicitud HTTP adicionales.	No
requestBody	Cuerpo de la solicitud HTTP.	No
format	Si desea recuperar datos tal cual desde el punto de conexión HTTP sin analizarlos y, después, copiarlos en un almacén basado en archivos, ignore la sección de formato de las definiciones de los conjuntos de datos de entrada y salida. Si desea analizar el contenido de la respuesta HTTP durante la copia, se admiten los siguientes tipos de formato de archivos: TextFormat, JsonFormat, AvroFormat, OrcFormat y ParquetFormat. En formato, establezca la propiedad type de formato en uno de los siguientes valores. Para obtener más información, consulte las secciones sobre formato JSON, formato de texto, formato Avro, formato Orc y formato Parquet.	No
compression	Especifique el tipo y el nivel de compresión de los datos. Para más información, consulte el artículo sobre códecs de compresión y formatos de archivo compatibles. Tipos que se admiten: GZip, Deflate, BZip2 y ZipDeflate. Niveles que se admiten: Optimal y Fastest.	No

Nota

Ejemplo 1: Uso del método Get (valor predeterminado)

{
    "name": "HttpSourceDataInput",
    "properties": {
        "type": "HttpFile",
        "linkedServiceName": {
            "referenceName": "<HTTP linked service name>",
            "type": "LinkedServiceReference"
        },
        "typeProperties": {
            "relativeUrl": "<relative url>",
            "additionalHeaders": "Connection: keep-alive\nUser-Agent: Mozilla/5.0\n"
        }
    }
}

Ejemplo 2: Uso del método POST

{
    "name": "HttpSourceDataInput",
    "properties": {
        "type": "HttpFile",
        "linkedServiceName": {
            "referenceName": "<HTTP linked service name>",
            "type": "LinkedServiceReference"
        },
        "typeProperties": {
            "relativeUrl": "<relative url>",
            "requestMethod": "Post",
            "requestBody": "<body for POST HTTP request>"
        }
    }
}

Modelo de origen de la actividad de copia heredada

Propiedad	Descripción	Obligatorio
type	La propiedad type del origen de la actividad de copia debe establecerse en: HttpSource.	Sí
httpRequestTimeout	El tiempo de espera (el valor TimeSpan) para que la solicitud HTTP obtenga una respuesta. Este valor es el tiempo de espera para obtener una respuesta, no para leer los datos de la respuesta. El valor predeterminado es 00:01:40.	No

Los

"activities":[
    {
        "name": "CopyFromHTTP",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<HTTP input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "HttpSource",
                "httpRequestTimeout": "00:01:00"
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

Para obtener una lista de almacenes de datos que la actividad de copia admite como orígenes y receptores, consulte Almacenes de datos y formatos que se admiten.

Copia de datos desde un punto de conexión HTTP mediante Azure Data Factory o Azure Synapse Analytics

Funcionalidades admitidas

Prerrequisitos

Introducción

Creación de un servicio vinculado a un origen HTTP mediante la interfaz de usuario

Detalles de configuración del conector

Propiedades del servicio vinculado

Uso de la autenticación Basic, Digest o Windows

Uso de la autenticación ClientCertificate

Uso de los encabezados de autenticación

Propiedades del conjunto de datos

Propiedades de la actividad de copia

HTTP como origen

Propiedades de la actividad de búsqueda

Modelos heredados

Modelo de conjunto de datos heredado

Modelo de origen de la actividad de copia heredada

Contenido relacionado

Recursos adicionales