Copiar dados de uma fonte OData usando o Azure Data FactoryCopy data from an OData source by using Azure Data Factory

APLICA-SE A: Azure Data Factory Azure Synapse Analytics

Este artigo descreve como usar a Atividade de Cópia no Azure Data Factory para copiar dados de uma fonte OData.This article outlines how to use Copy Activity in Azure Data Factory to copy data from an OData source. O artigo baseia-se em Atividade de Cópia no Azure Data Factory, que apresenta uma visão geral da Atividade de Cópia.The article builds on Copy Activity in Azure Data Factory, which presents a general overview of Copy Activity.

Funcionalidades com suporteSupported capabilities

Este conector OData tem suporte para as seguintes atividades:This OData connector is supported for the following activities:

Você pode copiar dados de uma origem OData para qualquer repositório de dados de coletor com suporte.You can copy data from an OData source to any supported sink data store. 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.For a list of data stores that Copy Activity supports as sources and sinks, see Supported data stores and formats.

Especificamente, este conector OData dá suporte:Specifically, this OData connector supports:

  • OData versão 3.0 e 4.0.OData version 3.0 and 4.0.
  • Copiar dados usando uma das autenticações a seguir: entidade de serviço anônima, básica, Windowse AAD.Copying data by using one of the following authentications: Anonymous, Basic, Windows, and AAD service principal.

Pré-requisitosPrerequisites

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.If your data store is located inside an on-premises network, an Azure virtual network, or Amazon Virtual Private Cloud, you need to configure a self-hosted integration runtime to connect to it.

Por outro lado, se o armazenamento de dados for um serviço de dados de nuvem gerenciado, você poderá usar o Azure Integration Runtime.Alternatively, if your data store is a managed cloud data service, you can use 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.If the access is restricted to IPs that are approved in the firewall rules, you can add Azure Integration Runtime IPs into the allow list.

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.For more information about the network security mechanisms and options supported by Data Factory, see Data access strategies.

IntroduçãoGet started

Para executar a atividade de Cópia com um pipeline, será possível usar as ferramentas ou os SDKs abaixo:To perform the Copy activity with a pipeline, you can use one of the following tools or SDKs:

As seções a seguir fornecem detalhes sobre propriedades que você pode usar para definir entidades do Data Factory específicas do conector OData.The following sections provide details about properties you can use to define Data Factory entities that are specific to an OData connector.

Propriedades do serviço vinculadoLinked service properties

As propriedades a seguir são compatíveis com o serviço vinculado do OData:The following properties are supported for an OData linked service:

PropriedadeProperty DescriçãoDescription ObrigatórioRequired
typetype A propriedade type precisa ser definida como OData.The type property must be set to OData. SimYes
urlurl A URL raiz do serviço OData.The root URL of the OData service. SimYes
authenticationTypeauthenticationType O tipo de autenticação usado para se conectar à fonte OData.The type of authentication used to connect to the OData source. Os valores permitidos são Anonymous, Basic, Windowse AadServicePrincipal.Allowed values are Anonymous, Basic, Windows, and AadServicePrincipal. Não há suporte para o OAuth baseado em usuário.User-based OAuth isn't supported. Além disso, você pode configurar cabeçalhos de autenticação na authHeader propriedade.You can additionally configure authentication headers in authHeader property. SimYes
authHeadersauthHeaders Cabeçalhos de solicitação HTTP adicionais para autenticação.Additional HTTP request headers for authentication.
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.For example, to use API key authentication, you can select authentication type as “Anonymous” and specify API key in the header.
NãoNo
userNameuserName Especifique o userName se estiver usando a autenticação Básica ou do Windows.Specify userName if you use Basic or Windows authentication. NãoNo
passwordpassword Especifique a senha da conta de usuário que você especificou para userName.Specify password for the user account you specified for userName. Marque esse campo como um tipo SecureString para armazená-lo com segurança no Data Factory.Mark this field as a SecureString type to store it securely in Data Factory. Você também pode referenciar um segredo armazenado no Azure Key Vault.You also can reference a secret stored in Azure Key Vault. NãoNo
servicePrincipalIdservicePrincipalId Especifique a ID do cliente do aplicativo do Azure Active Directory.Specify the Azure Active Directory application's client ID. NãoNo
aadServicePrincipalCredentialTypeaadServicePrincipalCredentialType Especifique o tipo de credencial a ser usada para autenticação da entidade de serviço.Specify the credential type to use for service principal authentication. Os valores permitidos são: ServicePrincipalKey ou ServicePrincipalCert.Allowed values are: ServicePrincipalKey or ServicePrincipalCert. NãoNo
servicePrincipalKeyservicePrincipalKey Especifique a chave do aplicativo do Azure Active Directory.Specify the Azure Active Directory application's key. Marque esse campo como SecureString para armazená-lo com segurança no Data Factory ou referencie um segredo armazenado no Cofre de Chaves do Azure.Mark this field as a SecureString to store it securely in Data Factory, or reference a secret stored in Azure Key Vault. NãoNo
servicePrincipalEmbeddedCertservicePrincipalEmbeddedCert Especifique o certificado codificado em base64 de seu aplicativo registrado no Azure Active Directory.Specify the base64 encoded certificate of your application registered in Azure Active Directory. Marque esse campo como SecureString para armazená-lo com segurança no Data Factory ou referencie um segredo armazenado no Cofre de Chaves do Azure.Mark this field as a SecureString to store it securely in Data Factory, or reference a secret stored in Azure Key Vault. NãoNo
servicePrincipalEmbeddedCertPasswordservicePrincipalEmbeddedCertPassword Especifique a senha de seu certificado se o certificado for protegido por senha.Specify the password of your certificate if your certificate is secured with a password. Marque esse campo como SecureString para armazená-lo com segurança no Data Factory ou referencie um segredo armazenado no Cofre de Chaves do Azure.Mark this field as a SecureString to store it securely in Data Factory, or reference a secret stored in Azure Key Vault. NãoNo
locatáriotenant Especifique as informações de locatário (domínio nome ou ID do Locatário) em que o aplicativo reside.Specify the tenant information (domain name or tenant ID) under which your application resides. Para recuperá-lo, passe o mouse no canto superior direito do portal do Azure.Retrieve it by hovering the mouse in the top-right corner of the Azure portal. NãoNo
aadResourceIdaadResourceId Especifique o recurso do AAD ao qual você está solicitando autorização.Specify the AAD resource you are requesting for authorization. NãoNo
azureCloudTypeazureCloudType Para autenticação de entidade de serviço, especifique o tipo de ambiente de nuvem do Azure no qual seu aplicativo do AAD está registrado.For service principal authentication, specify the type of Azure cloud environment to which your AAD application is registered.
Os valores permitidos são AzurePublic, AzureChina, AzureUsGovernmente AzureGermany.Allowed values are AzurePublic, AzureChina, AzureUsGovernment, and AzureGermany. Por padrão, o ambiente de nuvem do data factory é usado.By default, the data factory's cloud environment is used.
NãoNo
connectViaconnectVia O runtime de integração a ser usado para se conectar ao armazenamento de dados.The Integration Runtime to use to connect to the data store. Saiba mais na seção Pré-requisitos.Learn more from Prerequisites section. Se não especificado, o Azure Integration Runtime padrão será usado.If not specified, the default Azure Integration Runtime is used. NãoNo

Exemplo 1: usando a autenticação anônimaExample 1: Using Anonymous authentication

{
    "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ásicaExample 2: Using Basic authentication

{
    "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 WindowsExample 3: Using Windows authentication

{
    "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 de entidade de serviçoExample 4: Using service principal key authentication

{
    "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 de certificado da entidade de serviçoExample 5: Using service principal cert authentication

{
    "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 APIExample 6: Using API key authentication

{
    "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 dadosDataset properties

Esta seção fornece uma lista de propriedades compatíveis com o conjunto de dados OData.This section provides a list of properties that the OData dataset supports.

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.For a full list of sections and properties that are available for defining datasets, see Datasets and linked services.

Para copiar dados do OData, defina a propriedade type do conjunto de dados como ODataResource.To copy data from OData, set the type property of the dataset to ODataResource. Há suporte para as seguintes propriedades:The following properties are supported:

PropriedadeProperty DescriçãoDescription ObrigatórioRequired
typetype A propriedade type do conjunto de dados precisa ser definida como ODataResource.The type property of the dataset must be set to ODataResource. SimYes
caminhopath O caminho para o recurso OData.The path to the OData resource. SimYes

ExemploExample

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

Propriedades da Atividade de CópiaCopy Activity properties

Esta seção fornece uma lista de propriedades compatíveis com a fonte OData.This section provides a list of properties that the OData source supports.

Para obter uma lista completa de seções e propriedades que estão disponíveis para definir atividades, consulte Pipelines.For a full list of sections and properties that are available for defining activities, see Pipelines.

OData como fonteOData as source

Para copiar dados do OData, há suporte para as seguintes propriedades na seção origem da atividade de cópia:To copy data from OData, the following properties are supported in the Copy Activity source section:

PropriedadeProperty DescriçãoDescription ObrigatórioRequired
typetype A propriedade Type da fonte da atividade de cópia deve ser definida como OData.The type property of the Copy Activity source must be set to ODataSource. SimYes
Consultaquery Opções de consulta OData para filtrar dados.OData query options for filtering data. Exemplo: "$select=Name,Description&$top=5".Example: "$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].Note: The OData connector copies data from the combined URL: [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.For more information, see OData URL components.
NãoNo
httpRequestTimeouthttpRequestTimeout O tempo limite (o valor TimeSpan) para a solicitação HTTP para obter uma resposta.The timeout (the TimeSpan value) for the HTTP request to get a response. Esse valor é o tempo limite para obter uma resposta, não o tempo limite para ler os dados da resposta.This value is the timeout to get a response, not the timeout to read response data. Se não for especificado, o valor padrão será 00:30:00 (30 minutos).If not specified, the default value is 00:30:00 (30 minutes). NãoNo

ExemploExample

"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.If you were using RelationalSource typed source, it is still supported as-is, while you are suggested to use the new one going forward.

Mapeamento de tipo de dados para o ODataData type mapping for 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 do Azure Data Factory.When you copy data from OData, the following mappings are used between OData data types and Azure Data Factory interim data types. 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.To learn how Copy Activity maps the source schema and data type to the sink, see Schema and data type mappings.

Tipo de dados ODataOData data type Tipo de dados provisório do Data FactoryData Factory interim data type
Edm.BinaryEdm.Binary Byte[]Byte[]
Edm.BooleanEdm.Boolean BoolBool
Edm.ByteEdm.Byte Byte[]Byte[]
Edm.DateTimeEdm.DateTime DatetimeDateTime
Edm.DecimalEdm.Decimal DecimalDecimal
Edm.DoubleEdm.Double DoubleDouble
Edm.SingleEdm.Single SingleSingle
Edm.GuidEdm.Guid GuidGuid
Edm.Int16Edm.Int16 Int16Int16
Edm.Int32Edm.Int32 Int32Int32
Edm.Int64Edm.Int64 Int64Int64
Edm.SByteEdm.SByte Int16Int16
Edm.StringEdm.String StringString
Edm.TimeEdm.Time TimeSpanTimeSpan
Edm.DateTimeOffsetEdm.DateTimeOffset DateTimeOffsetDateTimeOffset

Observação

Tipos de dados complexos do OData (como Objeto) não têm suporte.OData complex data types (such as Object) aren't supported.

Pesquisar propriedades de atividadeLookup activity properties

Para saber detalhes sobre as propriedades, verifique Pesquisar atividade.To learn details about the properties, check Lookup activity.

Próximas etapasNext steps

Para obter uma lista de armazenamentos de dados que o Copy Activity suporta como fontes e coletores no Azure Data Factory, consulte Armazenamentos e formatos de dados compatíveis.For a list of data stores that Copy Activity supports as sources and sinks in Azure Data Factory, see Supported data stores and formats.