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

Artigo
10/20/2023

APLICA-SE A: Azure Data Factory Azure Synapse Analytics

Dica

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

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

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

conector REST dá suporte especificamente à 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 o arquivo. Antes desse conector REST ser disponibilizado, talvez você use o conector HTTP para copiar dados das APIs RESTful, o que tem suporte, mas é menos funcional em comparação ao conector REST.
O conector da tabela da Web extrai o conteúdo da tabela de uma página da Web em HTML.

Funcionalidades com suporte

Há suporte para este conector HTTP nas seguintes funcionalidades:

Funcionalidades com suporte	IR
Atividade de cópia (origem/-)	6/6
Atividade de pesquisa	6/6

① Runtime de integração do Azure ② Runtime de integração auto-hospedada

Para obter uma lista de armazenamentos de dados com suporte como origens/coletores, consulte Armazenamentos de dados com suporte.

Você pode usar esse conector HTTP para:

Recuperar dados de um endpoint HTTP / S usando os métodos HTTP GET ou POST.
Recupere dados usando uma das seguintes autenticações: Anônimo, Básico, Resumo, Windows ou ClientCertificate.
Copie a resposta HTTP como está ou analise-a usando formatos de arquivo suportados e codecs de compactação.

Dica

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 os requisitos de cabeçalho e corpo. Você pode usar ferramentas como o Postman ou um navegador da Web para validar.

Pré-requisitos

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

Se o armazenamento de dados for um serviço de dados de nuvem gerenciado, você poderá usar o Azure Integration Runtime. Se o acesso for restrito aos IPs que estão 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 runtime de integração da rede virtual gerenciada no Azure Data Factory para acessar a rede local sem instalar e configurar um runtime de integração auto-hospedada.

Para obter mais informações sobre os mecanismos de segurança de rede e as opções compatíveis com o Data Factory, consulte Estratégias de acesso a dados.

Introdução

Para executar a atividade de Cópia com um pipeline, será possível usar as ferramentas ou os SDKs abaixo:

Criar um serviço vinculado para uma origem HTTP usando a IU

Use as etapas a seguir para criar um serviço vinculado a uma origem HTTP na IU do portal do Azure.

Navegue até a guia Gerenciar no workspace do Azure Data Factory ou do Synapse, selecione Serviços Vinculados e clique em Novo:
- Azure Data Factory
- Azure Synapse
Pesquise por HTTP e selecione o conector HTTP.
Configure os detalhes do serviço, teste a conexão e crie o novo serviço vinculado.

Detalhes da configuração do conector

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

Propriedades do serviço vinculado

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

Propriedade	Descrição	Obrigatório
type	O tipo propriedade deve ser definida como HttpServer.	Sim
url	A URL base para o servidor web.	Sim
enableServerCertificateValidation	Especifique se deseja ativar a validação do certificado TLS/SSL do servidor ao se conectar a um terminal HTTP. Se seu servidor HTTPS usa um certificado autoassinado, defina essa propriedade como falsos.	Não (o padrão é verdadeiro)
authenticationType	Especifica o tipo de autenticação. Os valores permitidos são Anonymous, Basic, Digest, Windows e ClientCertificate. Também é possível configurar cabeçalhos de autenticação na propriedade `authHeader`. Veja as seções que seguem esta tabela para mais propriedades e amostras JSON para esses tipos de autenticação.	Sim
authHeaders	Cabeçalhos de solicitação HTTP adicionais para autenticação. Por exemplo, para usar a autenticação de chave de API, você poderá selecionar o tipo de autenticação como “Anônimo” e especificar a chave de API no cabeçalho.	Não
connectVia	O runtime de integração a ser usado para se conectar ao armazenamento de dados. Saiba mais na seção Pré-requisitos. Se não especificado, o Azure Integration Runtime padrão será usado.	Não

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

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

Propriedade	Descrição	Obrigatório
userName	O nome de usuário a ser usada para acessar o ponto de extremidade HTTP.	Sim
password	A senha do usuário (o nome de usuário valor). Marque esse campo como um tipoSecureString para armazená-lo com segurança. Você também pode referenciar um segredo armazenado no Cofre de Chaves 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:

Propriedade	Descrição	Obrigatório
embeddedCertData	Dados de certificado codificados em Base64.	Especificar embeddedCertData ou certThumbprint.
certThumbprint	A impressão digital do certificado que está instalado no armazenamento de certificados da sua máquina de Automação do Runtime Integration. Aplica-se apenas quando o tipo de runtime de integração auto-hospedada é especificado na propriedade connectVia.	Especificar embeddedCertData ou certThumbprint.
password	A senha associada com o certificado. Marque esse campo como um tipoSecureString para armazená-lo com segurança. Você também pode referenciar um segredo armazenado no Cofre de Chaves 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 runtime de integração auto-hospedada:

Abra o console de gerenciamento Microsoft (MMC). Adicione a certificados snap-in que tem como alvo computador Local.
Expanda Certificados>Pessoal e, em seguida, selecione Certificados.
Clique com o botão direito do mouse no certificado do armazenamento pessoal e selecione Todas as Tarefas>Gerenciar Chaves Particulares.
Na guia Segurança, adicione a conta de usuário na qual o Serviço de Host do Integration Runtime (DIAHostService) está em execução, com acesso de leitura ao certificado.
O conector HTTP carrega somente certificados confiáveis. Se você estiver usando um certificado emitido por AC autoassinado ou não integrado, para habilitar a confiança, o certificado também precisará ser instalado em um dos seguintes repositórios:
- Pessoas de Confiança
- Autoridades de Certificação Raiz de Terceiros
- Autoridades de Certificação Confiáveis

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

Usar cabeçalhos de autenticação

Também é possível configurar cabeçalhos de solicitação para autenticação junto com os tipos de autenticação internos.

Exemplo: Usar 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 das seções e propriedades disponíveis para definir os conjuntos de dados, confira o artigo sobre Conjuntos de Dados.

O Azure Data Factory é compatível com os formatos de arquivo a seguir. Confira cada artigo para obter configurações baseadas em formato.

As seguintes propriedades são compatíveis com HTTP em configurações de location no conjunto de dados com base em formato:

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

Observação

O tamanho da carga útil do pedido HTTP suportado é 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 útil 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"
        }
    }
}

Propriedades da Atividade de Cópia

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

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

HTTP como fonte

O Azure Data Factory é compatível com os formatos de arquivo a seguir. Confira cada artigo para obter configurações baseadas em formato.

As seguintes propriedades são compatíveis com HTTP em configurações storeSettings na origem de cópia baseada em formato:

Propriedade	Descrição	Obrigatório
type	A propriedade type em `storeSettings` deve ser definida como HttpReadSettings.	Sim
requestMethod	O método HTTP. Valores permitidos são Obtenha (padrão) e Post.	Não
additionalHeaders	Cabeçalhos de solicitação HTTP adicionais.	Não
requestBody	O corpo da solicitação HTTP.	Não
httpRequestTimeout	O tempo limite (o valor TimeSpan) para a solicitação HTTP para 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 é 01:00:40.	Não
maxConcurrentConnections	O limite superior de conexões simultâneas estabelecidas com o armazenamento de dados durante a execução da atividade. Especifique um valor somente quando desejar limitar as 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>"
            }
        }
    }
]

Pesquisar propriedades de atividade

Para saber detalhes sobre as propriedades, verifique Pesquisar atividade.

Modelos herdados

Observação

Os modelos a seguir ainda têm suporte no estado em que se encontram, para compatibilidade com versões anteriores. É recomendável usar o novo modelo mencionado nas seções acima no futuro, e a interface do usuário de criação mudou para gerar o novo modelo.

Modelo de conjunto de dados herdado

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

Observação

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 de atividade de cópia herdado

Propriedade	Descrição	Obrigatório
type	A propriedade tipo da origem da atividade de cópia deve ser configurada para HttpSource.	Sim
httpRequestTimeout	O tempo limite (o valor TimeSpan) para a solicitação HTTP para 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 é 01:00: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>"
            }
        }
    }
]

Para obter uma lista de armazenamentos de dados que o Copy Activity suporta como fontes e coletores, consulte Armazenamentos de dados e formatos compatíveis.

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

Funcionalidades com suporte

Pré-requisitos

Introdução

Criar um serviço vinculado para uma origem HTTP usando a IU

Detalhes da configuração do conector

Propriedades do serviço vinculado

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

Usando a autenticação ClientCertificate

Usar cabeçalhos de autenticação

Propriedades do conjunto de dados

Propriedades da Atividade de Cópia

HTTP como fonte

Pesquisar propriedades de atividade

Modelos herdados

Modelo de conjunto de dados herdado

Modelo de origem de atividade de cópia herdado

Conteúdo relacionado

Recursos adicionais