Copiar dados de uma fonte OData usando o Azure Data Factory ou o Synapse Analytics

Artigo
01/05/2024

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 em um pipeline do Azure Data Factory ou do Synapse Analytics para copiar dados de uma fonte OData. O artigo baseia-se na Atividade de Cópia, que apresenta uma visão geral da Atividade de Cópia.

Capacidades suportadas

Este conector OData é 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.

Especificamente, este conector OData suporta:

OData versão 2.0, 3.0 e 4.0.
Copiar dados usando uma das seguintes autenticações: Anônimo, Básico, Windows e entidade de serviço do Microsoft Entra.

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 um repositório OData usando a interface do usuário

Use as etapas a seguir para criar um serviço vinculado a um repositório OData 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, em seguida, selecione Novo:
- Fábrica de Dados do Azure
- Azure Synapse
Procure OData e selecione o conector OData.
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 do Data Factory que são específicas para um conector OData.

Propriedades do serviço vinculado

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

Propriedade	Descrição	Necessário
tipo	A propriedade type deve ser definida como OData.	Sim
URL	A URL raiz do serviço OData.	Sim
authenticationType	O tipo de autenticação usado para se conectar à fonte OData. Os valores permitidos são Anonymous, Basic, Windows e AadServicePrincipal. OAuth baseado no usuário não é suportado. Além disso, você pode configurar cabeçalhos de autenticação na `authHeader` propriedade.	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
nome de utilizador	Especifique userName se você usar a autenticação Básica ou do Windows.	Não
password	Especifique a senha para a conta de usuário que você especificou para 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.	Não
servicePrincipalId	Especifique a ID do cliente do aplicativo Microsoft Entra.	Não
aadServicePrincipalCredentialType	Especifique o tipo de credencial a ser usado para autenticação da entidade de serviço. Os valores permitidos são: `ServicePrincipalKey` ou `ServicePrincipalCert`.	Não
servicePrincipalKey	Especifique a chave do aplicativo Microsoft Entra. Marque este campo como um SecureString para armazená-lo com segurança ou faça referência a um segredo armazenado no Cofre de Chaves do Azure.	Não
serviçoPrincipalEmbeddedCert	Especifique o certificado codificado base64 do seu aplicativo registrado no Microsoft Entra ID e verifique se o tipo de conteúdo do certificado é PKCS #12. Marque este campo como um SecureString para armazená-lo com segurança ou faça referência a um segredo armazenado no Cofre de Chaves do Azure.	Não
servicePrincipalEmbeddedCertPassword	Especifique a senha do seu certificado se ele estiver protegido com uma senha. Marque este campo como um SecureString para armazená-lo com segurança ou faça referência a um segredo armazenado no Cofre de Chaves do Azure.	Não
inquilino	Especifique as informações do locatário (nome de domínio ou ID do locatário) sob as quais seu aplicativo reside. Recupere-o passando o mouse no canto superior direito do portal do Azure.	Não
aadResourceId	Especifique o recurso do Microsoft Entra que você está solicitando para autorização.	Não
azureCloudType	Para autenticação da entidade de serviço, especifique o tipo de ambiente de nuvem do Azure no qual seu aplicativo Microsoft Entra está registrado. Os valores permitidos são AzurePublic, AzureChina, AzureUsGovernment e AzureGermany. Por padrão, o ambiente de nuvem do serviço é usado.	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

Exemplo 1: Usando a autenticação anônima

{
    "name": "ODataLinkedService",
    "properties": {
        "type": "OData",
        "typeProperties": {
            "url": "https://services.odata.org/OData/OData.svc",
            "authenticationType": "Anonymous"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Exemplo 2: Usando a autenticação básica

{
    "name": "ODataLinkedService",
    "properties": {
        "type": "OData",
        "typeProperties": {
            "url": "<endpoint of OData source>",
            "authenticationType": "Basic",
            "userName": "<user name>",
            "password": {
                "type": "SecureString",
                "value": "<password>"
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Exemplo 3: Usando a autenticação do Windows

{
    "name": "ODataLinkedService",
    "properties": {
        "type": "OData",
        "typeProperties": {
            "url": "<endpoint of OData source>",
            "authenticationType": "Windows",
            "userName": "<domain>\\<user>",
            "password": {
                "type": "SecureString",
                "value": "<password>"
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Exemplo 4: Usando a autenticação de chave da entidade de serviço

{
    "name": "ODataLinkedService",
    "properties": {
        "type": "OData",
        "typeProperties": {
            "url": "<endpoint of OData source>",
            "authenticationType": "AadServicePrincipal",
            "servicePrincipalId": "<service principal id>",
            "aadServicePrincipalCredentialType": "ServicePrincipalKey",
            "servicePrincipalKey": {
                "type": "SecureString",
                "value": "<service principal key>"
            },
            "tenant": "<tenant info, e.g. microsoft.onmicrosoft.com>",
            "aadResourceId": "<AAD resource URL>"
        }
    },
    "connectVia": {
        "referenceName": "<name of Integration Runtime>",
        "type": "IntegrationRuntimeReference"
    }
}

Exemplo 5: Usando a autenticação cert da entidade de serviço

{
    "name": "ODataLinkedService",
    "properties": {
        "type": "OData",
        "typeProperties": {
            "url": "<endpoint of OData source>",
            "authenticationType": "AadServicePrincipal",
            "servicePrincipalId": "<service principal id>",
            "aadServicePrincipalCredentialType": "ServicePrincipalCert",
            "servicePrincipalEmbeddedCert": { 
                "type": "SecureString", 
                "value": "<base64 encoded string of (.pfx) certificate data>"
            },
            "servicePrincipalEmbeddedCertPassword": { 
                "type": "SecureString", 
                "value": "<password of your certificate>"
            },
            "tenant": "<tenant info, e.g. microsoft.onmicrosoft.com>",
            "aadResourceId": "<AAD resource e.g. https://tenant.sharepoint.com>"
        }
    },
    "connectVia": {
        "referenceName": "<name of Integration Runtime>",
        "type": "IntegrationRuntimeReference"
    }
}

Exemplo 6: Usando a autenticação de chave de API

{
    "name": "ODataLinkedService",
    "properties": {
        "type": "OData",
        "typeProperties": {
            "url": "<endpoint of OData source>",
            "authenticationType": "Anonymous",
            "authHeader": {
                "APIKey": {
                    "type": "SecureString",
                    "value": "<API key>"
                }
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Propriedades do conjunto de dados

Esta seção fornece uma lista de propriedades que o conjunto de dados OData suporta.

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

Para copiar dados de OData, defina a propriedade type do conjunto de dados como ODataResource. As seguintes propriedades são suportadas:

Propriedade	Descrição	Necessário
tipo	A propriedade type do conjunto de dados deve ser definida como ODataResource.	Sim
path	O caminho para o recurso OData.	Sim

Exemplo

{
    "name": "ODataDataset",
    "properties":
    {
        "type": "ODataResource",
        "schema": [],
        "linkedServiceName": {
            "referenceName": "<OData linked service name>",
            "type": "LinkedServiceReference"
        },
        "typeProperties":
        {
            "path": "Products"
        }
    }
}

Copiar propriedades da atividade

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

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

OData como fonte

Para copiar dados do OData, as seguintes propriedades são suportadas na seção Copiar fonte de atividade:

Propriedade	Descrição	Necessário
tipo	A propriedade type da fonte Copy Activity deve ser definida como ODataSource.	Sim
query	Opções de consulta OData para filtrar dados. Exemplo: `"$select=Name,Description&$top=5"`. Nota: O conector OData copia dados da URL combinada: `[URL specified in linked service]/[path specified in dataset]?[query specified in copy activity source]`. Para obter mais informações, consulte Componentes de URL OData.	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. Se não for especificado, o valor padrão será 00:30:00 (30 minutos).	Não

Exemplo

"activities":[
    {
        "name": "CopyFromOData",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<OData input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "ODataSource",
                "query": "$select=Name,Description&$top=5"
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

Se você estava usando RelationalSource fonte digitada, ela ainda é suportada como está, enquanto você é sugerido para usar a nova no futuro.

Mapeamento de tipo de dados para OData

Quando você copia dados do OData, os mapeamentos a seguir são usados entre tipos de dados OData e tipos de dados provisórios usados internamente no serviço. Para saber como Copiar atividade mapeia o esquema de origem e o tipo de dados para o coletor, consulte Mapeamentos de esquema e tipo de dados.

Tipo de dados OData	Tipo de dados de serviço provisório
Edm.Binário	Byte[]
Edm.Boolean	Bool
Edm.Byte	Byte[]
Edm.DateTime	DateTime
Edm.Decimal	Decimal
Edm.Double	Duplo
Edm.Single	Única
Edm.Guid	GUID
Edm.Int16	Int16
Edm.Int32	Int32
Edm.Int64	Int64
Edm.SByte	Int16
Edm.String	String
Edm.Time	TimeSpan
Edm.DateTimeOffset	DateTimeOffset

Nota

Não há suporte para tipos de dados complexos OData (como Object).

Copiar dados do Project Online

O Project Online requer OAuth baseado no usuário, que não é suportado pelo Azure Data Factory. Para copiar dados do Project Online, você pode usar o conector OData e um token de acesso obtido de ferramentas como o Postman.

Atenção

O token de acesso expira em 1 hora por padrão, você precisa obter um novo token de acesso quando ele expirar.

Use o Postman para obter o token de acesso:
1. Navegue até a guia Autorização no site do carteiro.
2. Na caixa Tipo, selecione OAuth 2.0 e, na caixa Adicionar dados de autorização a, selecione Cabeçalhos de Solicitação.
3. Preencha as seguintes informações na página Configurar Novo Token para obter um novo token de acesso:
  - Tipo de concessão: Selecione Código de autorização.
  - URL de retorno de chamada: digite https://www.localhost.com/.
  - URL de autenticação: digite https://login.microsoftonline.com/common/oauth2/authorize?resource=https://<your tenant name>.sharepoint.com. Substitua <your tenant name> pelo seu próprio nome de inquilino.
  - URL do token de acesso: digite https://login.microsoftonline.com/common/oauth2/token.
  - ID do cliente: insira o ID da entidade de serviço do Microsoft Entra.
  - Segredo do cliente: insira o segredo principal do serviço.
  - Autenticação do cliente: Selecione Enviar como cabeçalho de autenticação básica.
4. Ser-lhe-á pedido que inicie sessão com o seu nome de utilizador e palavra-passe.
5. Depois de obter seu token de acesso, copie-o e salve-o para a próxima etapa.
Crie o serviço vinculado OData:
- URL do serviço: digite https://<your tenant name>.sharepoint.com/sites/pwa/_api/Projectdata. Substitua <your tenant name> pelo seu próprio nome de inquilino.
- Tipo de autenticação: Selecione Anônimo.
- Cabeçalhos de autenticação:
  - Nome da propriedade: Escolha Autorização.
  - Valor: DigiteBearer <access token from step 1> .
- Teste o serviço vinculado.
Crie o conjunto de dados OData:
1. Crie o conjunto de dados com o serviço vinculado OData criado na etapa 2.
2. Pré-visualizar dados.

Propriedades da atividade de pesquisa

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

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.