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

SE APLICA A: Azure Data Factory Azure Synapse Analytics

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 la API RESTful, lo cual se admite, pero 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 de HTTP es compatible con las actividades siguientes:

Puede copiar datos desde un origen HTTP a cualquier almacén de datos receptor compatible. 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.

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.

  1. 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":

  2. Busque HTTP y seleccione su conector.

    Captura de pantalla del conector HTTP

  3. Configure los detalles del servicio, pruebe la conexión y cree el servicio vinculado.

    Captura de pantalla de la configuración de un servicio vinculado HTTP

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.
url La dirección URL base para el servidor web.
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. No se admiten usuarios basados en OAuth. 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.
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.
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.

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):

  1. Abra Microsoft Management Console (MMC). Agregue el complemento Certificados que tenga como destino Equipo local.
  2. Expanda Certificados > Personal y, luego, seleccione Certificados.
  3. Haga clic con el botón derecho en el certificado del almacén personal y seleccione Todas las tareas > Administrar claves privadas.
  4. 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.

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.
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.
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.
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

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 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.
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

Ejemplo

"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>"
            }
        }
    }
]

Pasos siguientes

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.