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

Artigo
11/16/2023

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 que o conector REST fique 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/-)	① ②
Atividade de Pesquisa	① ②

(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 o Postman 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.

Introdução

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

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.

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
Procure HTTP e selecione o conector HTTP.
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:

Propriedade	Descrição	Necessá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 Basic, Digest ou 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:

Propriedade	Descrição	Necessá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:

Propriedade	Descrição	Necessá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:

Abra o MMC (Console de Gerenciamento Microsoft). Adicione o snap-in Certificados destinado ao Computador Local.
Expanda Certificados>Pessoais e selecione Certificados.
Clique com o botão direito do rato no certificado do arquivo pessoal e, em seguida, selecione Todas as Tarefas Gerir Chaves Privadas>.
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.
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.

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

Propriedade	Descrição	Necessá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.

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

Propriedade	Descrição	Necessá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

Propriedade	Descrição	Necessá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 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

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

Propriedade	Descrição	Necessá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>"
            }
        }
    }
]

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.

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

Capacidades suportadas

Pré-requisitos

Introdução

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

Detalhes de configuração do conector

Propriedades do serviço vinculado

Usando a autenticação Basic, Digest ou Windows

Usando a autenticação ClientCertificate

Usando cabeçalhos de autenticação

Propriedades do conjunto de dados

Copiar propriedades da atividade

HTTP como fonte

Propriedades da atividade de pesquisa

Modelos antigos

Modelo de conjunto de dados herdado

Modelo de origem da atividade de cópia herdada

Conteúdos relacionados

Recursos adicionais