Compartilhar via


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

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/-) ① ②
Atividade de pesquisa ① ②

① 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. É possível usar as ferramentas como o Visual Studio, o Invoke-RestMethod do PowerShell 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.

  1. Navegue até a guia Gerenciar no workspace do Azure Data Factory ou do Synapse, selecione Serviços Vinculados e clique em Novo:

  2. Pesquise por HTTP e selecione o conector HTTP.

    Captura de tela do conector HTTP.

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

    Captura de tela da configuração de um serviço vinculado do HTTP.

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:

  1. Abra o console de gerenciamento Microsoft (MMC). Adicione a certificados snap-in que tem como alvo computador Local.
  2. Expanda Certificados>Pessoal e, em seguida, selecione Certificados.
  3. Clique com o botão direito do mouse no certificado do armazenamento pessoal e selecione Todas as Tarefas>Gerenciar Chaves Particulares.
  4. 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.
  5. 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

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