Copia de datos de un origen de OData con Azure Data Factory o Synapse Analytics

Artículo
01/05/2024

SE APLICA A: Azure Data Factory Azure Synapse Analytics

Sugerencia

Pruebe Data Factory en Microsoft Fabric, una solución de análisis todo en uno para empresas. Microsoft Fabric abarca todo, desde el movimiento de datos hasta la ciencia de datos, el análisis en tiempo real, la inteligencia empresarial y los informes. Obtenga información sobre cómo iniciar una nueva evaluación gratuita.

En este artículo se describe el uso de la actividad de copia en una canalización de Synapse Analytics o Azure Data Factory para copiar datos de un origen de OData. El artículo se basa en Actividad de copia, en el que se ofrece información general acerca de la actividad de copia.

Funcionalidades admitidas

El conector OData es compatible con las siguientes funcionalidades:

Funcionalidades admitidas	IR
Actividad de copia (origen/-)	① ②
Actividad de búsqueda	① ②

① Azure Integration Runtime ② Entorno de ejecución de integración autohospedado

Para obtener una lista de los almacenes de datos que se admiten como orígenes y receptores, consulte la tabla de almacenes de datos admitidos.

En concreto, este conector OData admite las siguientes funcionalidades:

OData versión 2.0, 3.0 y 4.0.
Copiar datos mediante el uso de una de las autenticaciones siguientes: Anónima, Básica, Windows y Entidad de servicio de Microsoft Entra.

Requisitos previos

Si el almacén de datos se encuentra en una red local, una red virtual de Azure o una nube privada virtual de Amazon, debe configurar un entorno de ejecución de integración autohospedado para conectarse a él.

Si el almacén de datos es un servicio de datos en la nube administrado, puede usar Azure Integration Runtime. Si el acceso está restringido a las direcciones IP que están aprobadas en las reglas de firewall, puede agregar direcciones IP de Azure Integration Runtime a la lista de permitidos.

También puede usar la característica del entorno de ejecución de integración de red virtual administrada de Azure Data Factory para acceder a la red local sin instalar ni configurar un entorno de ejecución de integración autohospedado.

Consulte Estrategias de acceso a datos para más información sobre los mecanismos de seguridad de red y las opciones que admite Data Factory.

Introducción

Para realizar la actividad de copia con una canalización, puede usar una de los siguientes herramientas o SDK:

Creación de un servicio vinculado a un almacén de OData mediante la interfaz de usuario

Siga estos pasos para crear un servicio vinculado a un almacén de OData en la interfaz de usuario de Azure Portal.

Vaya a la pestaña Administrar de su área de trabajo de Azure Data Factory o Synapse, y seleccione Servicios vinculados; a continuación, seleccione Nuevo:
- Azure Data Factory
- Azure Synapse
Busque OData y seleccione su conector.
Configure los detalles del servicio, pruebe la conexión y cree el nuevo servicio vinculado.

Detalles de configuración del conector

En las secciones siguientes se proporcionan detalles sobre las propiedades que puede usar para definir entidades de Data Factory específicas del conector de OData.

Propiedades del servicio vinculado

Las siguientes propiedades son compatibles con un servicio vinculado de OData:

Propiedad	Descripción	Obligatorio
type	La propiedad type debe establecerse en OData.	Sí
url	Dirección URL raíz del servicio de OData.	Sí
authenticationType	Tipo de autenticación que se usa para conectarse al origen de OData. Los valores permitidos son Anónima, Básica, Windows y AadServicePrincipal. No se admiten usuarios basados en OAuth. Además, puede configurar encabezados de autenticación en la propiedad `authHeader`.	Sí
authHeaders	Encabezados de solicitud HTTP adicionales para la autenticación. Por ejemplo, para usar la autenticación de clave de API, puede seleccionar el tipo de autenticación "Anónima" y especificar la clave de API en el encabezado.	No
userName	Especifique userName si se usa la autenticación Básica o de Windows.	No
password	Especifique la contraseña de la cuenta de usuario que se especificó para userName. Marque este campo como un tipo SecureString para almacenarlo de forma segura. También puede hacer referencia a un secreto almacenado en Azure Key Vault.	No
servicePrincipalId	Especifique el ID de cliente de la aplicación Microsoft Entra.	No
aadServicePrincipalCredentialType	Especifique el tipo de credencial que se usará para la autenticación de entidad de servicio. Los valores permitidos son: `ServicePrincipalKey` o `ServicePrincipalCert`.	No
servicePrincipalKey	Especifique la clave de la aplicación Microsoft Entra. Marque este campo como SecureString para almacenarlo de forma segura, o bien haga referencia a un secreto almacenado en Azure Key Vault.	No
servicePrincipalEmbeddedCert	Especifique el certificado codificado en base64 de la aplicación registrada en Microsoft Entra ID y asegúrese de que el tipo de contenido del certificado es PKCS #12. Marque este campo como SecureString para almacenarlo de forma segura, o bien haga referencia a un secreto almacenado en Azure Key Vault.	No
servicePrincipalEmbeddedCertPassword	Especifique la contraseña del certificado si el certificado está protegido por una. Marque este campo como SecureString para almacenarlo de forma segura, o bien haga referencia a un secreto almacenado en Azure Key Vault.	No
tenant	Especifique la información del inquilino (nombre de dominio o identificador de inquilino) en el que reside la aplicación. Para recuperarla, mantenga el puntero del mouse en la esquina superior derecha de Azure Portal.	No
aadResourceId	Especifique el recurso de Microsoft Entra para el que solicita autorización.	No
azureCloudType	Para la autenticación de la entidad de servicio, especifique el tipo de entorno de nube de Azure en el que está registrada la aplicación de Microsoft Entra. Los valores permitidos son AzurePublic, AzureChina, AzureUsGovernment y AzureGermany. De forma predeterminada, se usa el entorno de nube del servicio.	No
connectVia	Instancia de Integration Runtime que se usará para conectarse al almacén de datos. Obtenga más información en la sección Requisitos previos. Si no se especifica, se usa el valor predeterminado de Azure Integration Runtime.	No

Ejemplo 1: Uso de autenticación 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"
        }
    }
}

Ejemplo 2: Uso de autenticación 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"
        }
    }
}

Ejemplo 3: Uso de la autenticación de 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"
        }
    }
}

Ejemplo 4: Uso de la autenticación de la clave de entidad de servicio

{
    "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"
    }
}

Ejemplo 5: Uso de la autenticación de certificados de entidad de servicio

{
    "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"
    }
}

Ejemplo 6: Autenticación mediante clave 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"
        }
    }
}

Propiedades del conjunto de datos

En esta sección se proporciona una lista de las propiedades que admite el conjunto de datos de OData.

Para ver una lista completa de las secciones y propiedades disponibles para definir conjuntos de datos, consulte Conjuntos de datos y servicios vinculados.

Para copiar datos desde OData, establezca la propiedad type del conjunto de datos en ODataResource. Se admiten las siguientes propiedades:

Propiedad	Descripción	Obligatorio
type	La propiedad type del conjunto de datos debe establecerse en ODataResource.	Sí
path	Ruta de acceso al recurso de OData.	Sí

Ejemplo

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

Propiedades de la actividad de copia

En esta sección se proporciona una lista de las propiedades que admite el origen de OData.

Para ver una lista completa de las secciones y propiedades que hay disponibles para definir actividades, consulte Canalizaciones.

OData como origen

Para copiar datos desde OData, en la sección source de la actividad de copia se admiten las siguientes propiedades:

Propiedad	Descripción	Obligatorio
type	La propiedad type del origen de la actividad de copia se debe establecer en ODataSource.	Sí
Query	Opciones de consulta de OData para filtrar datos. Ejemplo: `"$select=Name,Description&$top=5"`. Nota: el conector OData copia datos de la dirección URL combinada: `[URL specified in linked service]/[path specified in dataset]?[query specified in copy activity source]`. Para más información, consulte el artículo sobre componentes de URL de OData.	No
httpRequestTimeout	El tiempo de espera (el valor TimeSpan) para que la solicitud HTTP obtenga una respuesta. Este valor es el tiempo de espera para obtener una respuesta, no para leer los datos de la respuesta. Si no se especifica, el valor predeterminado es 00:30:00 (30 minutos).	No

Ejemplo

"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>"
            }
        }
    }
]

Si estaba usando un origen de tipo RelationalSource, todavía se admite tal cual, aunque se aconseja usar el nuevo en el futuro.

Asignación de tipos de datos de OData

Al copiar datos desde OData, se utilizan las siguientes asignaciones entre tipos de datos de OData y tipos de datos provisionales usados dentro del servicio internamente. Para obtener información acerca de la forma en que la actividad de copia asigna el esquema de origen y el tipo de datos al receptor, consulte Asignación de esquemas en la actividad de copia.

Tipo de datos de OData	Tipo de datos de servicio provisional
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

Nota

No se admiten tipos de datos complejos de OData (por ejemplo, Object).

Copia de datos de Project Online

Project Online requiere OAuth basado en el usuario, que no es compatible con Azure Data Factory. Para copiar datos de Project Online, puede usar el conector OData y un token de acceso obtenido de herramientas como Postman.

Precaución

El token de acceso expira en 1 hora de manera predeterminada; debe obtener uno nuevo en cuanto expire.

Use Postman para obtener el token de acceso:
1. Vaya a la pestaña Authorization (Autorización) en el sitio web de Postman.
2. En el cuadro Type (Tipo), seleccione OAuth 2.0 y, en el cuadro Add authorization data to (Agregar datos de autorización a), seleccione Request Headers (Encabezados de solicitud).
3. Rellene la siguiente información en la página Configure New Token (Configurar nuevo token) para obtener un nuevo token de acceso:
  - Grant type (Tipo de concesión): seleccione Authorization Code (Código de autorización).
  - Callback URL (Dirección URL de devolución de llamada): escriba https://www.localhost.com/.
  - Auth URL (Dirección URL de autenticación): escriba https://login.microsoftonline.com/common/oauth2/authorize?resource=https://<your tenant name>.sharepoint.com. Reemplace <your tenant name> por su propio nombre de inquilino.
  - Access Token URL (Dirección URL de token de acceso): escriba https://login.microsoftonline.com/common/oauth2/token.
  - Client ID (Identificador de cliente): escriba el identificador de la entidad de servicio de Microsoft Entra.
  - Client Secret (Secreto de cliente): escriba el secreto de la entidad de servicio.
  - Client Authentication (Autenticación de cliente): seleccione Send as Basic Auth header (Enviar como encabezado de autenticación básica).
4. Se le va a pedir que inicie sesión con su nombre de usuario y contraseña.
5. Una vez que obtenga el token de acceso, cópielo y guárdelo para el siguiente paso.
Cree el servicio vinculado de OData:
- URL de servicio: escriba https://<your tenant name>.sharepoint.com/sites/pwa/_api/Projectdata. Reemplace <your tenant name> por su propio nombre de inquilino.
- Tipo de autenticación: seleccione Anónimo.
- Encabezados de autenticación:
  - Nombre de propiedad: seleccione Autorización.
  - Valor: escriba Bearer <access token from step 1>.
- Pruebe el servicio vinculado.
Cree el conjunto de datos de OData:
1. Cree el conjunto de datos con el servicio vinculado de OData creado en el paso 2.
2. Obtenga una vista previa de los datos.

Propiedades de la actividad de búsqueda

Para obtener información detallada sobre las propiedades, consulte Actividad de búsqueda.

Para obtener una lista de almacenes de datos que la actividad de copia admite como orígenes y receptores, consulte Almacenes de datos y formatos que se admiten.