Copie os dados de um ponto final HTTP utilizando a Azure Data Factory ou a Azure Synapse Analytics

APLICA-SE A: Azure Data Factory Azure Synapse Analytics

Este artigo descreve como utilizar a Copy Activity na Azure Data Factory e na Azure Synapse para copiar dados de um ponto final HTTP. O artigo baseia-se na Copy Activity, que apresenta uma visão geral da Atividade de Cópia.

A diferença entre este conector HTTP, o conector REST e o conector de mesa Web são:

  • O conector REST suporta especificamente os dados de cópia de APIs RESTful;
  • O conector HTTP é genérico para obter dados de qualquer ponto final HTTP, por exemplo, para descarregar ficheiros. Antes de o conector REST ficar disponível, pode por acaso utilizar o conector HTTP para copiar dados da API RESTful, que é suportado mas menos funcional em comparação com o conector REST.
  • O conector da tabela web extrai o conteúdo da tabela a partir de uma página web HTML.

Capacidades suportadas

Este conector HTTP é suportado para as seguintes atividades:

Pode copiar dados de uma fonte HTTP para qualquer loja de dados de lavatórios suportados. Para obter uma lista de lojas de dados que a Copy Activity suporta como fontes e sumidouros, consulte lojas e formatos de dados suportados.

Pode utilizar este conector HTTP para:

  • Obtenha dados de um ponto final HTTP/S utilizando os métodos HTTP GET ou POST.
  • Recupere os dados utilizando uma das seguintes autenticações: Anónimo, Básico, Digest, Windows ou ClientCertificate.
  • Copie a resposta HTTP como é ou analise-a utilizando formatos de ficheiros suportados e codecs de compressão.

Dica

Para testar um pedido HTTP de recuperação de dados antes de configurar o conector HTTP, saiba mais sobre a especificação API para os requisitos do cabeçalho e do corpo. Você pode usar ferramentas como o Carteiro ou um navegador web para validar.

Pré-requisitos

Se a sua loja de dados estiver localizada dentro de uma rede no local, de uma rede virtual Azure ou da Amazon Virtual Private Cloud, é necessário configurar um tempo de integração auto-hospedado para se ligar a ela.

Se a sua loja de dados for um serviço de dados em nuvem gerido, pode utilizar o Tempo de Execução da Integração Azure. Se o acesso for restrito aos IPs aprovados nas regras de firewall, pode adicionar IPs de Runtime de Integração Azure à lista de permitir.

Também pode utilizar a funcionalidade de execução de integração de rede virtual gerida na Azure Data Factory para aceder à rede de acesso no local sem instalar e configurar um tempo de integração auto-hospedado.

Para obter mais informações sobre os mecanismos e opções de segurança da rede suportados pela Data Factory, consulte as estratégias de acesso aos dados.

Introdução

Para realizar a atividade Copy com um pipeline, pode utilizar uma das seguintes ferramentas ou SDKs:

Criar um serviço ligado a uma fonte HTTP utilizando uI

Utilize os seguintes passos para criar um serviço ligado a uma fonte HTTP no portal Azure UI.

  1. Navegue no separador Gerir na sua Fábrica de Dados Azure ou no espaço de trabalho synapse e selecione Serviços Ligados e, em seguida, clique em Novo:

  2. Procure em HTTP e selecione o conector HTTP.

    Screenshot do conector HTTP.

  3. Configure os detalhes do serviço, teste a ligação e crie o novo serviço ligado.

    Screenshot da configuração para um serviço ligado HTTP.

Detalhes da configuração do conector

As seguintes secções fornecem detalhes sobre propriedades que pode usar para definir entidades específicas do conector HTTP.

Propriedades de serviço ligadas

As seguintes propriedades são suportadas para o serviço http linked:

Propriedade Descrição Obrigatório
tipo A propriedade tipo deve ser definida para HttpServer. Yes
url O URL base para o servidor web. Yes
enableServerCertificateValidation Especificar se deve ativar a validação do certificado TLS/SSL do servidor quando ligar a um ponto final HTTP. Se o seu servidor HTTPS utilizar um certificado auto-assinado, descreva esta propriedade como falsa. No
(o padrão é verdadeiro)
authenticationType Especifica o tipo de autenticação. Os valores permitidos são Anónimos, Básicos, Digest, Windows e ClientCertificate. O OAuth baseado no utilizador não é suportado. Pode ainda configurar cabeçalhos de autenticação em authHeader propriedade. Consulte as secções que seguem esta tabela para obter mais propriedades e amostras JSON para estes tipos de autenticação. Yes
authHeaders Cabeçalhos adicionais de pedido DE HTTP para autenticação.
Por exemplo, para utilizar a autenticação da chave API, pode selecionar o tipo de autenticação como "Anónimo" e especificar a tecla API no cabeçalho.
No
connectVia O Tempo de Execução de Integração para ligar à loja de dados. Saiba mais na secção Pré-Requisitos. Se não for especificado, utiliza-se o tempo de execução de integração Azure predefinido. No

Utilização da autenticação básica, digestiva ou Windows

Desa estação A propriedade da autenticaçãoType é básica, digesta ou Windows. Além das propriedades genéricas descritas na secção anterior, especifique as seguintes propriedades:

Propriedade Descrição Obrigatório
userName O nome de utilizador a utilizar para aceder ao ponto final HTTP. Yes
palavra-passe A palavra-passe para o utilizador (o valor do nome do utilizador). Marque este campo como um tipo SecureString para armazená-lo de forma segura. Também pode fazer referência a um segredo armazenado no Cofre da Chave Azure. Yes

Exemplo

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

Utilização da autenticação Do ClienteCertificado

Para utilizar a autenticação ClientCertificate, desafie a propriedade autenticaçãoType ao ClientCertificate. Além das propriedades genéricas descritas na secção anterior, especifique as seguintes propriedades:

Propriedade Descrição Obrigatório
EmbeddedCertData Dados de certificado codificados de base64. Especifique o CertifiData incorporado ou o certificadoThumbprint.
certThumbprint A impressão digital do certificado instalado na loja de cert da sua máquina de execução de integração auto-hospedada. Aplica-se apenas quando o tipo de tempo de execução de integração auto-alojado é especificado na propriedade connectVia. Especifique o CertifiData incorporado ou o certificadoThumbprint.
palavra-passe A senha que está associada ao certificado. Marque este campo como um tipo SecureString para armazená-lo de forma segura. Também pode fazer referência a um segredo armazenado no Cofre da Chave Azure. No

Se utilizar o certThumbprint para autenticação e o certificado estiver instalado na loja pessoal do computador local, conceda permissões de leitura ao tempo de execução de integração auto-hospedado:

  1. Abra a Consola de Gestão da Microsoft (MMC). Adicione o encaixe de certificados que visa o Computador Local.
  2. Expandir Certificados > Pessoais e, em seguida, selecionar Certificados.
  3. Clique com o botão direito no certificado da loja pessoal e, em seguida, selecione Todas as Tarefas > Gerencie as Teclas Privadas.
  4. No separador Segurança, adicione a conta de utilizador sob a qual está a funcionar o Serviço de Anfitriões de Integração (DIAHostService), com acesso lido ao certificado.

Exemplo 1: Utilização 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"
        }
    }
}

Exemplo 2: Utilização incorporada DoCertData

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

Utilização de cabeçalhos de autenticação

Além disso, pode configurar os cabeçalhos de pedido para autenticação juntamente com os tipos de autenticação incorporado.

Exemplo: Utilização da autenticação da chave 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"
        }
    }
}

Dataset properties (Propriedades do conjunto de dados)

Para obter uma lista completa de secções e propriedades disponíveis para definir conjuntos de dados, consulte o artigo Datasets.

A Azure Data Factory suporta os seguintes formatos de ficheiros. Consulte cada artigo para obter definições baseadas em formato.

As seguintes propriedades são suportadas para HTTP em location definições no conjunto de dados baseado em formato:

Propriedade Descrição Obrigatório
tipo A propriedade tipo location em conjunto de dados deve ser definida para HttpServerLocation. Yes
relativoUrl Um URL relativo ao recurso que contém os dados. O conector HTTP copia os dados do URL combinado: [URL specified in linked service][relative URL specified in dataset] . No

Nota

O tamanho da carga útil do pedido HTTP suportado é de cerca de 500 KB. Se o tamanho da carga útil que pretende passar para o seu ponto final da web for superior a 500 KB, considere a lotação útil em pedaços menores.

Exemplo:

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

Propriedades de Atividade de Cópia

Esta secção fornece uma lista de propriedades que a fonte HTTP suporta.

Para obter uma lista completa de secções e propriedades disponíveis para definir atividades, consulte Pipelines.

HTTP como fonte

A Azure Data Factory suporta os seguintes formatos de ficheiros. Consulte cada artigo para obter definições baseadas em formato.

As seguintes propriedades são suportadas para HTTP em storeSettings definições na fonte de cópia baseada em formato:

Propriedade Descrição Obrigatório
tipo A propriedade tipo em baixo storeSettings deve ser definida para HttpReadSettings. Yes
requestMethod O método HTTP.
Os valores permitidos são Get (predefinido) e Post.
No
cabeçalhos adicionais Cabeçalhos de pedido HTTP adicionais. No
requestCorp O corpo para o pedido HTTP. No
httpRequestTimeout O tempo limite (o valor TimeSpan) para o pedido HTTP obter uma resposta. Este valor é o tempo limite para obter uma resposta, não o tempo limite para ler dados de resposta. O valor predefinido é 00:01:40. No
maxConcurrentConnections O limite superior das ligações simultâneas estabelecidas na loja de dados durante a atividade. Especifique um valor apenas quando pretende limitar ligações simultâneas. No

Exemplo:

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

Propriedades de atividade de procura

Para obter detalhes sobre as propriedades, consulte a atividade de Lookup.

Modelos legados

Nota

Os modelos seguintes ainda são suportados como é para retrocompatibilidade. É sugerido que utilize o novo modelo mencionado nas secções acima, e a UI de autoria passou a gerar o novo modelo.

Modelo de conjunto de dados legado

Propriedade Descrição Obrigatório
tipo A propriedade tipo do conjunto de dados deve ser definida para HttpFile. Yes
relativoUrl Um URL relativo ao recurso que contém os dados. Quando esta propriedade não é especificada, apenas é utilizado o URL especificado na definição de serviço ligado. No
requestMethod O método HTTP. Os valores permitidos são Get (predefinido) e Post. No
cabeçalhos adicionais Cabeçalhos de pedido HTTP adicionais. No
requestCorp O corpo para o pedido HTTP. No
formato Se pretender obter dados do ponto final HTTP como-é sem analisá-los e, em seguida, copiar os dados para uma loja baseada em ficheiros, salte a secção de formato nas definições de conjunto de dados de entrada e saída.

Se pretender analisar o conteúdo de resposta HTTP durante a cópia, suportam-se os seguintes tipos de formato de ficheiro: TextFormat, JsonFormat, AvroFormat, OrcFormat e ParquetFormat. Em formato, desateia a propriedade tipo a um destes valores. Para mais informações, consulte o formato JSON, formato de texto, formato Avro, formato Orce formato Parquet.
No
compressão Especifique o tipo e o nível de compressão para os dados. Para obter mais informações, consulte formatos de ficheiros suportados e codecs de compressão.

Tipos suportados: GZip, Deflate, BZip2 e ZipDeflate.
Níveis suportados: Ideal e Mais Rápido.
No

Nota

O tamanho da carga útil do pedido HTTP suportado é de cerca de 500 KB. Se o tamanho da carga útil que pretende passar para o seu ponto final da web for superior a 500 KB, considere a lotação útil em pedaços menores.

Exemplo 1: Utilização do método Get (padrão)

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

Exemplo 2: Utilização do 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 origem de origem de atividade de cópia de legado

Propriedade Descrição Obrigatório
tipo A propriedade tipo da fonte de atividade de cópia deve ser definida para HttpSource. Yes
httpRequestTimeout O tempo limite (o valor TimeSpan) para o pedido HTTP obter uma resposta. Este valor é o tempo limite para obter uma resposta, não o tempo limite para ler dados de resposta. O valor predefinido é 00:01:40. No

Exemplo

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

Passos seguintes

Para obter uma lista de lojas de dados que a Copy Activity suporta como fontes e sumidouros, consulte lojas e formatos de dados suportados.