Copiar dados da fonte do OData utilizando o Azure Data Factory ou Synapse Analytics

Artigo
01/05/2024

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

Funcionalidades com suporte

Há suporte para o conector do OData para as 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.

Especificamente, este conector OData dá suporte:

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 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 a um armazenamento OData com a interface do usuário

Use as etapas abaixo para criar um serviço vinculado ao armazenamento OData na interface do usuário do portal do Microsoft Azure.

Navegue até a guia Gerenciar no workspace do Azure Data Factory ou do Synapse e selecione Serviços Vinculados. Depois, selecione Novo:
- Azure Data Factory
- Azure Synapse
Pesquise OData e selecione o conector correspondente.
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 do Data Factory específicas do conector OData.

Propriedades do serviço vinculado

As propriedades a seguir são compatíveis com o serviço vinculado do OData:

Propriedade	Descrição	Obrigatório
type	A propriedade type precisa 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 Anônimo, Básico, Windows e AadServicePrincipal. OAuth baseado no usuário não tem suporte. Além disso, você pode configurar cabeçalhos de autenticação na propriedade `authHeader`.	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
userName	Especifique o userName se estiver usando a autenticação Básica ou do Windows.	Não
password	Especifique a senha da conta de usuário que você especificou para userName. Marque esse campo como um tipoSecureString para armazená-lo com segurança. Você também pode referenciar um segredo armazenado no Azure Key Vault.	Não
servicePrincipalId	Especifique a ID do cliente do aplicativo do Microsoft Entra.	Não
aadServicePrincipalCredentialType	Especifique o tipo de credencial a ser usada para autenticação da entidade de serviço. Os valores permitidos são: `ServicePrincipalKey` ou `ServicePrincipalCert`.	Não
servicePrincipalKey	Especifique a chave do aplicativo do Microsoft Entra. Marque esse campo como SecureString para armazená-lo com segurança ou referencie um segredo armazenado no Azure Key Vault.	Não
servicePrincipalEmbeddedCert	Especifique o certificado codificado em base64 do aplicativo registrado no Microsoft Entra ID e cerifique-se de que o tipo de conteúdo do certificado é PKCS #12. Marque esse campo como SecureString para armazená-lo com segurança ou referencie um segredo armazenado no Azure Key Vault.	Não
servicePrincipalEmbeddedCertPassword	Especifique a senha de seu certificado se o certificado for protegido por senha. Marque esse campo como SecureString para armazená-lo com segurança ou referencie um segredo armazenado no Azure Key Vault.	Não
locatário	Especifique as informações de locatário (domínio nome ou ID do Locatário) em que o aplicativo reside. Para recuperá-lo, passe 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 em nuvem do Azure em que seu aplicativo do Microsoft Entra está registrado. Os valores permitidos são AzurePublic, AzureChina, AzureUsGovernment e AzureGermany. Por padrão, é usado o ambiente de nuvem do serviço.	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

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: usar a autenticação com chave de 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: usar a autenticação com certificado de 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: usar 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 compatíveis com o conjunto de dados OData.

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

Para copiar dados do OData, defina a propriedade type do conjunto de dados como ODataResource. Há suporte para as seguintes propriedades:

Propriedade	Descrição	Obrigatório
type	A propriedade type do conjunto de dados precisa ser definida como ODataResource.	Sim
caminho	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"
        }
    }
}

Propriedades da Atividade de Cópia

Esta seção fornece uma lista de propriedades compatíveis com a fonte OData.

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

OData como fonte

Para copiar dados do OData, as seguintes propriedades têm suporte na seção de origem Atividade de Cópia:

Propriedade	Descrição	Obrigatório
type	A propriedade type da origem Atividade de Cópia não deve ser definida para ODataSource.	Sim
Consulta	Opções de consulta OData para filtrar dados. Exemplo: `"$select=Name,Description&$top=5"`. Observação: o conector do OData copia os dados da URL combinada: `[URL specified in linked service]/[path specified in dataset]?[query specified in copy activity source]`. Para saber mais, confira as Componentes da URL do OData.	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. 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 a fonte com tipos RelationalSource, ela ainda tem suporte como está, mas é recomendável usar a nova no futuro.

Mapeamento de tipo de dados para o OData

Ao copiar dados do OData, os seguintes mapeamentos são usados entre os tipos de dados OData e os tipos de dados provisórios usados pelo serviço internamente. Para saber como a Atividade de Cópia mapeia o esquema de origem e o tipo de dados para o coletor, confira Esquema e mapeamentos de tipo de dados.

Tipo de dados OData	Tipo de dados provisório do serviço
Edm.Binary	Byte[]
Edm.Boolean	Bool
Edm.Byte	Byte[]
Edm.DateTime	Datetime
Edm.Decimal	Decimal
Edm.Double	Double
Edm.Single	Single
Edm.Guid	Guid
Edm.Int16	Int16
Edm.Int32	Int32
Edm.Int64	Int64
Edm.SByte	Int16
Edm.String	String
Edm.Time	TimeSpan
Edm.DateTimeOffset	DateTimeOffset

Observação

Tipos de dados complexos do OData (como Objeto) não têm suporte.

Copiar dados do Project Online

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

Cuidado

O token de acesso expirará em uma hora por padrão, e você precisará 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 Postman.
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 o Código de Autorização.
  - URL de Retorno de Chamada: insira https://www.localhost.com/.
  - URL de Autenticação: insira https://login.microsoftonline.com/common/oauth2/authorize?resource=https://<your tenant name>.sharepoint.com. Substitua <your tenant name> pelo nome de seu locatário.
  - URL do Token de Acesso: insira https://login.microsoftonline.com/common/oauth2/token.
  - ID do Cliente: Insira sua ID da entidade de serviço do Microsoft Entra.
  - Segredo do Cliente: insira o segredo da entidade de serviço.
  - Autenticação do Cliente: selecione Enviar como Cabeçalho de Autenticação Básica.
4. Será solicitado que você entre com seu nome de usuário e sua senha.
5. Depois de obter seu token de acesso, copie-o e salve-o na próxima etapa.
Crie o serviço vinculado OData:
- URL do Serviço: insira https://<your tenant name>.sharepoint.com/sites/pwa/_api/Projectdata. Substitua <your tenant name> pelo nome de seu locatário.
- Tipo de autenticação: selecione Anônimo.
- Cabeçalhos de autenticação:
  - Nome da propriedade: escolha Autorização.
  - Valor: Insira Bearer <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. Visualize os dados.

Pesquisar propriedades de atividade

Para saber detalhes sobre as propriedades, verifique Pesquisar atividade.

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.