Copiar dados de um ponto de extremidade HTTP usando o Azure Data Factory ou o Azure Synapse Analytics

APLICA-SE A: Azure Data Factory Azure Synapse Analytics

Gorjeta

Experimente o Data Factory no Microsoft Fabric, uma solução de análise tudo-em-um para empresas. O Microsoft Fabric abrange tudo, desde a movimentação de dados até ciência de dados, análises em tempo real, business intelligence e relatórios. Saiba como iniciar uma nova avaliação gratuitamente!

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

A diferença entre esse conector HTTP, o conector REST e o conector de tabela da Web são:

• O conector REST suporta especificamente a cópia de dados de APIs RESTful;
• O conector HTTP é genérico para recuperar dados de qualquer ponto de extremidade HTTP, por exemplo, para baixar arquivos. Antes do conector REST ficar disponível, você pode usar o conector HTTP para copiar dados de APIs RESTful, que é suportado, mas menos funcional em comparação com o conector REST.
• O conector da tabela Web extrai o conteúdo da tabela de uma página Web HTML.

Capacidades suportadas

Este conector HTTP é suportado para os seguintes recursos:

Capacidades suportadas	IR
Atividade de cópia (fonte/-)	(1) (2)
Atividade de Pesquisa	(1) (2)

(1) Tempo de execução de integração do Azure (2) Tempo de execução de integração auto-hospedado

Para obter uma lista de armazenamentos de dados suportados como fontes/coletores, consulte Armazenamentos de dados suportados.

Você pode usar esse conector HTTP para:

• Recupere dados de um ponto de extremidade HTTP/S usando os métodos HTTP GET ou POST .
• Recupere dados usando uma das seguintes autenticações: Anonymous, Basic, Digest, Windows ou ClientCertificate.
• Copie a resposta HTTP no estado em que se encontra ou analise-a usando formatos de arquivo e codecs de compactação suportados.

Gorjeta

Para testar uma solicitação HTTP para recuperação de dados antes de configurar o conector HTTP, saiba mais sobre a especificação da API para requisitos de cabeçalho e corpo. Você pode usar ferramentas como Visual Studio, Invoke-RestMethod do PowerShell ou um navegador da Web para validar.

Pré-requisitos

Se seu armazenamento de dados estiver localizado dentro de uma rede local, uma rede virtual do Azure ou a Amazon Virtual Private Cloud, você precisará configurar um tempo de execução de integração auto-hospedado para se conectar a ele.

Se o seu armazenamento de dados for um serviço de dados de nuvem gerenciado, você poderá usar o Tempo de Execução de Integração do Azure. Se o acesso for restrito a IPs aprovados nas regras de firewall, você poderá adicionar IPs do Azure Integration Runtime à lista de permissões.

Você também pode usar o recurso de tempo de execução de integração de rede virtual gerenciada no Azure Data Factory para acessar a rede local sem instalar e configurar um tempo de execução de integração auto-hospedado.

Para obter mais informações sobre os mecanismos de segurança de rede e as opções suportadas pelo Data Factory, consulte Estratégias de acesso a dados.

Começar agora

Para executar a atividade Copiar com um pipeline, você pode usar uma das seguintes ferramentas ou SDKs:

• A ferramenta Copiar dados
• O portal do Azure
• O SDK do .NET
• O SDK do Python
• Azure PowerShell
• A API REST
• O modelo do Azure Resource Manager

Criar um serviço vinculado a uma fonte HTTP usando a interface do usuário

Use as etapas a seguir para criar um serviço vinculado a uma fonte HTTP na interface do usuário do portal do Azure.

1. Navegue até a guia Gerenciar em seu espaço de trabalho do Azure Data Factory ou Synapse e selecione Serviços Vinculados e clique em Novo:

   Fábrica de Dados do Azure

   

   Azure Synapse

   

2. Procure HTTP e selecione o conector HTTP.

   

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

   

Detalhes de configuração do conector

As seções a seguir fornecem detalhes sobre as propriedades que você pode usar para definir entidades específicas para o conector HTTP.

Propriedades do serviço vinculado

As seguintes propriedades são suportadas para o serviço vinculado HTTP:

Property	Descrição	Obrigatório
tipo	A propriedade type deve ser definida como HttpServer.	Sim
url	O URL base para o servidor Web.	Sim
enableServerCertificateValidation	Especifique se deseja habilitar a validação do certificado TLS/SSL do servidor quando você se conectar a um ponto de extremidade HTTP. Se o servidor HTTPS usar um certificado autoassinado, defina essa propriedade como false.	Não (o padrão é true)
authenticationType	Especifica o tipo de autenticação. Os valores permitidos são Anonymous, Basic, Digest, Windows e ClientCertificate. Além disso, você pode configurar cabeçalhos de autenticação na authHeader propriedade. Consulte as seções que seguem esta tabela para obter mais propriedades e exemplos JSON para esses tipos de autenticação.	Sim
authCabeçalhos	Cabeçalhos de solicitação HTTP adicionais para autenticação. Por exemplo, para usar a autenticação de chave de API, você pode selecionar o tipo de autenticação como "Anônimo" e especificar a chave de API no cabeçalho.	Não
ConecteVia	O tempo de execução de integração a ser usado para se conectar ao armazenamento de dados. Saiba mais na seção Pré-requisitos . Se não for especificado, o Tempo de Execução de Integração do Azure padrão será usado.	Não

Usando a autenticação Básica, Digest ou do Windows

Defina a propriedade authenticationType como Basic, Digest ou Windows. Além das propriedades genéricas descritas na seção anterior, especifique as seguintes propriedades:

Property	Descrição	Obrigatório
nome de utilizador	O nome de usuário a ser usado para acessar o ponto de extremidade HTTP.	Sim
password	A senha do usuário (o valor userName ). Marque este campo como um tipo SecureString para armazená-lo com segurança. Você também pode fazer referência a um segredo armazenado no Cofre da Chave do Azure.	Sim

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

Usando a autenticação ClientCertificate

Para usar a autenticação ClientCertificate, defina a propriedade authenticationType como ClientCertificate. Além das propriedades genéricas descritas na seção anterior, especifique as seguintes propriedades:

Property	Descrição	Obrigatório
embeddedCertData	Dados de certificado codificados em Base64.	Especifique embeddedCertData ou certThumbprint.
certImpressão digital	A impressão digital do certificado instalado no armazenamento de certificados da máquina do Integration Runtime auto-hospedada. Aplica-se somente quando o tipo auto-hospedado de Integration Runtime é especificado na propriedade connectVia .	Especifique embeddedCertData ou certThumbprint.
password	A senha associada ao certificado. Marque este campo como um tipo SecureString para armazená-lo com segurança. Você também pode fazer referência a um segredo armazenado no Cofre da Chave do Azure.	Não

Se você usar certThumbprint para autenticação e o certificado estiver instalado no armazenamento pessoal do computador local, conceda permissões de leitura ao Tempo de Execução de Integração auto-hospedado:

1. Abra o MMC (Console de Gerenciamento Microsoft). Adicione o snap-in Certificados destinado ao Computador Local.
2. Expanda Certificados>Pessoais e selecione Certificados.
3. Clique com o botão direito do rato no certificado do arquivo pessoal e, em seguida, selecione Todas as Tarefas Gerir Chaves Privadas>.
4. Na guia Segurança, adicione a conta de usuário sob a qual o Serviço de Host do Integration Runtime (DIAHostService) está sendo executado, com acesso de leitura ao certificado.
5. O conector HTTP carrega apenas certificados confiáveis. Se você estiver usando um certificado emitido por CA autoassinado ou não integrado, para habilitar a confiança, o certificado também deverá ser instalado em um dos seguintes armazenamentos:
   • Pessoas de confiança
   • Autoridades de certificação raiz de terceiros
   • Autoridades de Certificação de Raiz Fidedigna

Exemplo 1: Usando 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: Usando 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"
        }
    }
}

Usando cabeçalhos de autenticação

Além disso, você pode configurar cabeçalhos de solicitação para autenticação junto com os tipos de autenticação internos.

Exemplo: Usando a autenticação de chave 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"
        }
    }
}

Propriedades do conjunto de dados

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

O Azure Data Factory suporta os seguintes formatos de ficheiro. Consulte cada artigo para obter as configurações baseadas em formato.

• Formato Avro
• Formato binário
• Formato de texto delimitado
• Formato Excel
• Formato JSON
• Formato ORC
• Formato Parquet
• Formato XML

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

Property	Descrição	Obrigatório
tipo	A propriedade type em location no dataset deve ser definida como HttpServerLocation.	Sim
relativeUrl	Uma URL relativa ao recurso que contém os dados. O conector HTTP copia dados da URL combinada: [URL specified in linked service][relative URL specified in dataset].	Não

Nota

O tamanho da carga útil da solicitação HTTP suportada é de cerca de 500 KB. Se o tamanho da carga útil que você deseja passar para seu ponto de extremidade da Web for maior que 500 KB, considere agrupar a carga em partes 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"
        }
    }
}

Copiar propriedades da atividade

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

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

HTTP como fonte

O Azure Data Factory suporta os seguintes formatos de ficheiro. Consulte cada artigo para obter as configurações baseadas em formato.

• Formato Avro
• Formato binário
• Formato de texto delimitado
• Formato Excel
• Formato JSON
• Formato ORC
• Formato Parquet
• Formato XML

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

Property	Descrição	Obrigatório
tipo	A propriedade type under storeSettings deve ser definida como HttpReadSettings.	Sim
requestMethod	O método HTTP. Os valores permitidos são Get (padrão) e Post.	Não
additionalHeaders	Cabeçalhos de solicitação HTTP adicionais.	Não
requestBody [en]	O corpo da solicitação HTTP.	Não
httpRequestTimeout	O tempo limite (o valor TimeSpan ) para a solicitação HTTP obter uma resposta. Esse valor é o tempo limite para obter uma resposta, não o tempo limite para ler os dados da resposta. O valor padrão é 00:01:40.	Não
maxConcurrentConnections	O limite superior de conexões simultâneas estabelecidas para o armazenamento de dados durante a execução da atividade. Especifique um valor somente quando quiser limitar conexões simultâneas.	Não

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 da atividade de pesquisa

Para saber detalhes sobre as propriedades, verifique Atividade de pesquisa.

Modelos antigos

Nota

Os modelos a seguir ainda são suportados no estado em que se encontram para compatibilidade com versões anteriores. Sugere-se que você use o novo modelo mencionado nas seções acima daqui para frente, e a interface do usuário de criação mudou para gerar o novo modelo.

Modelo de conjunto de dados herdado

Property	Descrição	Obrigatório
tipo	A propriedade type do conjunto de dados deve ser definida como HttpFile.	Sim
relativeUrl	Uma URL relativa ao recurso que contém os dados. Quando essa propriedade não é especificada, somente a URL especificada na definição de serviço vinculado é usada.	Não
requestMethod	O método HTTP. Os valores permitidos são Get (padrão) e Post.	Não
additionalHeaders	Cabeçalhos de solicitação HTTP adicionais.	Não
requestBody [en]	O corpo da solicitação HTTP.	Não
format	Se você quiser recuperar dados do ponto de extremidade HTTP como está sem analisá-los e, em seguida, copiar os dados para um armazenamento baseado em arquivo, ignore a seção de formato nas definições de conjunto de dados de entrada e saída. Se você quiser analisar o conteúdo da resposta HTTP durante a cópia, os seguintes tipos de formato de arquivo são suportados: TextFormat, JsonFormat, AvroFormat, OrcFormat e ParquetFormat. Em formato, defina a propriedade type como um desses valores. Para obter mais informações, consulte Formato JSON, Formato de texto, Formato Avro, Formato Orc e Formato Parquet.	Não
compressão	Especifique o tipo e o nível de compactação dos dados. Para obter mais informações, consulte Formatos de arquivo e codecs de compactação suportados. Tipos suportados: GZip, Deflate, BZip2 e ZipDeflate. Níveis suportados: Ótimo e mais rápido.	Não

Nota

O tamanho da carga útil da solicitação HTTP suportada é de cerca de 500 KB. Se o tamanho da carga útil que você deseja passar para seu ponto de extremidade da Web for maior que 500 KB, considere agrupar a carga em partes menores.

Exemplo 1: Usando o 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: Usando o 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 da atividade de cópia herdada

Property	Descrição	Obrigatório
tipo	A propriedade type da fonte de atividade de cópia deve ser definida como HttpSource.	Sim
httpRequestTimeout	O tempo limite (o valor TimeSpan ) para a solicitação HTTP obter uma resposta. Esse valor é o tempo limite para obter uma resposta, não o tempo limite para ler os dados da resposta. O valor padrão é 00:01:40.	Não

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

Conteúdos relacionados

Para obter uma lista de armazenamentos de dados que a Atividade de Cópia suporta como fontes e coletores, consulte Formatos e armazenamentos de dados suportados.