Copia de datos en Salesforce con origen y destino mediante Azure Data Factory o Azure Synapse Analytics (versión heredada)

Artículo
05/11/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 resume el uso de la actividad de copia en canalizaciones de Azure Data Factory y Azure Synapse para copiar datos con Salesforce como origen y destino. El documento se basa en el artículo de introducción a la actividad de copia que presenta información general de la actividad de copia.

Importante

El nuevo conector de Salesforce proporciona compatibilidad nativa mejorada con Salesforce. Si va a usar el conector de Salesforce heredado en la solución, actualice el conector de Salesforce antes del 11 de octubre de 2024. Consulte esta sección para más información sobre la diferencia entre la versión heredada y la versión más reciente.

Funcionalidades admitidas

Este conector de Salesforce es compatible con las funcionalidades siguientes:

Funcionalidades admitidas	IR
Actividad de copia (origen/receptor)	① ②
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 o receptores, consulte la tabla de almacenes de datos admitidos.

En concreto, este conector de Salesforce admite:

Ediciones de Salesforce Developer, Professional, Enterprise o Unlimited.
La copia de datos desde y hacia producción, espacio aislado y dominio personalizado de Salesforce.

Nota

Esta función admite la copia de cualquier esquema de los entornos de Salesforce mencionados anteriormente, incluido el Nonprofit Success Pack (NPSP).

El conector de Salesforce se basa en la API REST/Bulk de Salesforce. Al copiar datos desde Salesforce, el conector elige automáticamente entre REST y las API masivas en función del tamaño de los datos; cuando el conjunto de resultados es grande, se usa la API masiva para mejorar el rendimiento. Puede establecer explícitamente la versión de API que se usa para leer y escribir datos mediante la propiedad apiVersion en el servicio vinculado. Al copiar datos a Salesforce, el conector usa la API BULK v1.

Nota:

El conector ya no establece la versión predeterminada para Salesforce API. Por compatibilidad con versiones anteriores, si se estableció una versión de API predeterminada antes, sigue funcionando. El valor predeterminado es 45,0 para source y 40,0 para sink.

Prerrequisitos

El permiso API debe estar habilitado en Salesforce.

Límites de solicitudes de Salesforce

Salesforce tiene límites para el número total de solicitudes de API y el de solicitudes de API simultáneas. Tenga en cuenta los siguientes puntos:

Si el número de solicitudes simultáneas supera el límite, se produce la limitación y verá errores aleatorios.
Si el número total de solicitudes supera el límite, la cuenta de Salesforce se bloqueará durante 24 horas.

También podría recibir el mensaje de error "REQUEST_LIMIT_EXCEEDED" en ambos escenarios. Consulte la sección "API Request Limits" (Límites de solicitudes de API) en Salesforce Developer Limits (Límites de Salesforce Developer) para más información.

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 Salesforce mediante la interfaz de usuario

Siga estos pasos para crear un servicio vinculado a Salesforce en la interfaz de usuario de Azure Portal.

Vaya a la pestaña Administrar del área de trabajo de Azure Data Factory o Synapse y seleccione Servicios vinculados; luego haga clic en Nuevo:
- Azure Data Factory
- Azure Synapse
Busque Salesforce y seleccione el conector de Salesforce.
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 se usan para definir entidades específicas para el conector de Salesforce.

Propiedades del servicio vinculado

Las siguientes propiedades son compatibles con el servicio vinculado Salesforce.

Propiedad	Descripción	Obligatorio
type	La propiedad type debe establecerse en: Salesforce.	Sí
environmentUrl	Especifique la URL de la instancia de Salesforce. - El valor predeterminado es `"https://login.salesforce.com"`. - Para copiar datos desde el espacio aislado, especifique `"https://test.salesforce.com"`. - Para copiar datos del dominio personalizado, especifique, por ejemplo, `"https://[domain].my.salesforce.com"`.	No
username	Especifique el nombre de usuario de la cuenta de usuario.	Sí
password	Especifique la contraseña para la cuenta de usuario. Marque este campo como SecureString para almacenarlo de forma segura, o bien haga referencia a un secreto almacenado en Azure Key Vault.	Sí
securityToken	Especifique el token de seguridad para la cuenta de usuario. Para más información acerca de los tokens de seguridad en general, consulte Security and the API(Seguridad y la API). El token de seguridad solo se puede omitir si agrega la dirección IP de Integration Runtime a la lista de direcciones IP de confianza en Salesforce. Cuando use Azure IR, consulte Direcciones IP de Azure Integration Runtime. Para obtener instrucciones sobre cómo restablecer u obtener un token de seguridad consulte el artículo sobre obtención de un token de seguridad. Marque este campo como SecureString para almacenarlo de forma segura, o bien haga referencia a un secreto almacenado en Azure Key Vault.	No
apiVersion	Especifique la versión de la API REST/Bulk de Salesforce que se va a usar, por ejemplo, `52.0`.	No
connectVia	El entorno de ejecución de integración que se usará para conectarse al almacén de datos. Si no se especifica, se usará Azure Integration Runtime.	No

Ejemplo: Almacenamiento de credenciales

{
    "name": "SalesforceLinkedService",
    "properties": {
        "type": "Salesforce",
        "typeProperties": {
            "username": "<username>",
            "password": {
                "type": "SecureString",
                "value": "<password>"
            },
            "securityToken": {
                "type": "SecureString",
                "value": "<security token>"
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Ejemplo: Almacenamiento de credenciales en Key Vault

{
    "name": "SalesforceLinkedService",
    "properties": {
        "type": "Salesforce",
        "typeProperties": {
            "username": "<username>",
            "password": {
                "type": "AzureKeyVaultSecret",
                "secretName": "<secret name of password in AKV>",
                "store":{
                    "referenceName": "<Azure Key Vault linked service>",
                    "type": "LinkedServiceReference"
                }
            },
            "securityToken": {
                "type": "AzureKeyVaultSecret",
                "secretName": "<secret name of security token in AKV>",
                "store":{
                    "referenceName": "<Azure Key Vault linked service>",
                    "type": "LinkedServiceReference"
                }
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Ejemplo: Almacenar credenciales en Key Vault, así como environmentUrl y nombre de usuario

Tenga en cuenta que, al hacerlo, ya no podrá usar la interfaz de usuario para editar la configuración. La casilla Especificar contenido dinámico en formato JSON se activará y tendrá que editar esta configuración por completo a mano. La ventaja es que puede derivar TODAS las opciones de configuración de Key Vault en lugar de parametrizar nada aquí.

{
    "name": "SalesforceLinkedService",
    "properties": {
        "type": "Salesforce",
        "typeProperties": {
            "environmentUrl": {
                "type": "AzureKeyVaultSecret",
                "secretName": "<secret name of environment URL in AKV>",
                "store": {
                    "referenceName": "<Azure Key Vault linked service>",
                    "type": "LinkedServiceReference"
                },
            },
            "username": {
                "type": "AzureKeyVaultSecret",
                "secretName": "<secret name of username in AKV>",
                "store": {
                    "referenceName": "<Azure Key Vault linked service>",
                    "type": "LinkedServiceReference"
                },
            },
            "password": {
                "type": "AzureKeyVaultSecret",
                "secretName": "<secret name of password in AKV>",
                "store":{
                    "referenceName": "<Azure Key Vault linked service>",
                    "type": "LinkedServiceReference"
                }
            },
            "securityToken": {
                "type": "AzureKeyVaultSecret",
                "secretName": "<secret name of security token in AKV>",
                "store":{
                    "referenceName": "<Azure Key Vault linked service>",
                    "type": "LinkedServiceReference"
                }
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Propiedades del conjunto de datos

Si desea ver una lista completa de las secciones y propiedades disponibles para definir conjuntos de datos, consulte el artículo sobre conjuntos de datos. En esta sección se proporciona una lista de las propiedades que admite el conjunto de datos de Salesforce.

Para copiar datos desde y hacia Salesforce, establezca la propiedad type del conjunto de datos en SalesforceObject. Se admiten las siguientes propiedades.

Propiedad	Descripción	Obligatorio
type	La propiedad type debe establecerse en SalesforceObject.	Sí
objectApiName	El nombre del objeto de Salesforce desde el que se van a recuperar los datos.	No para el origen, sí para el receptor

Importante

La parte "__c" del nombre de la API es necesaria para cualquier objeto personalizado.

Captura de pantalla en la que se muestra el nombre de la API de conexión de Salesforce.

Ejemplo:

{
    "name": "SalesforceDataset",
    "properties": {
        "type": "SalesforceObject",
        "typeProperties": {
            "objectApiName": "MyTable__c"
        },
        "schema": [],
        "linkedServiceName": {
            "referenceName": "<Salesforce linked service name>",
            "type": "LinkedServiceReference"
        }
    }
}

Nota

Por compatibilidad con versiones anteriores: Cuando se copian datos de Salesforce, se podrá seguir usando el conjunto de datos de tipo "RelationalTable" anterior, pero se sugiere cambiar al nuevo tipo "SalesforceObject".

Propiedad	Descripción	Obligatorio
type	La propiedad type del conjunto de datos debe establecerse en: RelationalTable.	Sí
tableName	Nombre de la tabla de Salesforce.	No (si se especifica "query" en el origen de la actividad)

Propiedades de la actividad de copia

Si desea ver una lista completa de las secciones y propiedades disponibles para definir actividades, consulte el artículo sobre canalizaciones. En esta sección se proporciona una lista de las propiedades admitidas por el origen y el receptor de Salesforce.

Salesforce como tipo de origen

Para copiar datos desde Salesforce, establezca el tipo de origen de la actividad de copia en SalesforceSource. 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 debe establecerse en: SalesforceSource.	Sí
Query	Utilice la consulta personalizada para leer los datos. Puede usar una consulta de SQL-92 o de Salesforce Object Query Language (SOQL). Consulte más sugerencias en la sección Sugerencias de consulta. Si no se especifica la consulta, se recuperarán todos los datos del objeto de Salesforce especificado en "objectApiName" en el conjunto de datos.	No (si se especifica "objectApiName" en el conjunto de datos)
readBehavior	Indica si se van a consultar los registros existentes o todos, incluso los que se eliminaron. Si no se especifica, el comportamiento predeterminado es el primero. Valores permitidos: query (valor predeterminado), queryAll.	No

Importante

La parte "__c" del nombre de la API es necesaria para cualquier objeto personalizado.

Captura de pantalla en la que se muestra la lista Nombre de la API de conexión de Salesforce.

Ejemplo:

"activities":[
    {
        "name": "CopyFromSalesforce",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<Salesforce input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "SalesforceSource",
                "query": "SELECT Col_Currency__c, Col_Date__c, Col_Email__c FROM AllDataType__c"
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

Nota

Por compatibilidad con versiones anteriores: Cuando se copian datos de Salesforce, se podrá seguir usando la copia de tipo "RelationalSource" anterior, pero se sugiere cambiar al nuevo tipo "SalesforceSource".

Nota:

El origen de Salesforce no admite la configuración de proxy en el entorno de ejecución de integración autohospedado, pero sí lo hace el receptor.

Salesforce como tipo de receptor

Para copiar datos hacia Salesforce, establezca el tipo de receptor de la actividad de copia en SalesforceSink. En la sección sink de la actividad de copia se admiten las siguientes propiedades.

Propiedad	Descripción	Obligatorio
type	La propiedad type del receptor de la actividad de copia debe establecerse en: SalesforceSink.	Sí
writeBehavior	El comportamiento de escritura de la operación. Los valores permitidos son: Insert y Upsert.	No (el valor predeterminado es Insert)
externalIdFieldName	El nombre del campo de identificador externo para la operación de upsert. El campo especificado debe definirse como "Campo de identificador externo" en el objeto de Salesforce. No puede tener valores NULL en los datos de entrada correspondientes.	Sí para "Upsert"
writeBatchSize	El recuento de filas de datos escritos en Salesforce en cada lote.	No (el valor predeterminado es 5000)
ignoreNullValues	Indica si se omiten los valores NULL de los datos de entrada durante la operación de escritura. Los valores permitidos son true y false. - True: deje los datos del objeto de destino sin cambiar cuando realice una operación upsert o update. Inserta un valor predeterminado definido al realizar una operación insert. - False: actualice los datos del objeto de destino a NULL cuando realice una operación upsert o update. Inserta un valor NULL al realizar una operación insert.	No (el valor predeterminado es false)
maxConcurrentConnections	Número máximo de conexiones simultáneas establecidas en el almacén de datos durante la ejecución de la actividad. Especifique un valor solo cuando quiera limitar las conexiones simultáneas.	No

Ejemplo: receptor de Salesforce en la actividad de copia

"activities":[
    {
        "name": "CopyToSalesforce",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<Salesforce output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "<source type>"
            },
            "sink": {
                "type": "SalesforceSink",
                "writeBehavior": "Upsert",
                "externalIdFieldName": "CustomerId__c",
                "writeBatchSize": 10000,
                "ignoreNullValues": true
            }
        }
    }
]

Sugerencias de consulta

Recuperación de datos a partir de un informe de Salesforce

Puede recuperar datos de informes de Salesforce especificando una consulta como {call "<report name>"}. Un ejemplo es "query": "{call \"TestReport\"}".

Recuperación de los registros eliminados desde la papelera de reciclaje de Salesforce

Para consultar los registros eliminados temporalmente de la papelera de reciclaje de Salesforce, puede especificar readBehavior como queryAll.

Diferencias entre la sintaxis de consulta SQL y SOQL

Al copiar datos desde Salesforce, puede usar consultas SOQL o consultas SQL. Tenga en cuenta que estas dos tienen diferente compatibilidad con sintaxis y funciones, no las mezcle. Es recomendable usar la consulta SOQL, que se admite de forma nativa en Salesforce. En la tabla siguiente se muestran las diferencias principales:

Sintaxis	Modo SOQL	Modo SQL
Selección de columnas	Necesita enumerar los campos que se van a copiar en la consulta, por ejemplo `SELECT field1, filed2 FROM objectname`.	`SELECT *` se admite además de la selección de columna.
Comillas	Los nombres de objetos o de campos no pueden entrecomillarse.	Los nombres de objetos o de campos no pueden entrecomillarse, por ejemplo `SELECT "id" FROM "Account"`.
Formato de fecha y hora	Consulte más detalles aquí y ejemplos en la sección siguiente.	Consulte más detalles aquí y ejemplos en la sección siguiente.
Valores booleanos	Se representan como `False` y `True`, por ejemplo, `SELECT … WHERE IsDeleted=True`.	Se representan como 0 o 1, por ejemplo `SELECT … WHERE IsDeleted=1`.
Cambio del nombre de la columna	No compatible.	Admitido, por ejemplo: `SELECT a AS b FROM …`.
Relación	Admitido, por ejemplo: `Account_vod__r.nvs_Country__c`.	No compatible.

Recuperación de datos mediante el uso de una cláusula where en la columna DateTime

Cuando se especifica la consulta SQL o SOQL, preste atención a la diferencia del formato de fecha y hora. Por ejemplo:

Ejemplo SOQL:SELECT Id, Name, BillingCity FROM Account WHERE LastModifiedDate >= @{formatDateTime(pipeline().parameters.StartTime,'yyyy-MM-ddTHH:mm:ssZ')} AND LastModifiedDate < @{formatDateTime(pipeline().parameters.EndTime,'yyyy-MM-ddTHH:mm:ssZ')}
Ejemplo de SQL: SELECT * FROM Account WHERE LastModifiedDate >= {ts'@{formatDateTime(pipeline().parameters.StartTime,'yyyy-MM-dd HH:mm:ss')}'} AND LastModifiedDate < {ts'@{formatDateTime(pipeline().parameters.EndTime,'yyyy-MM-dd HH:mm:ss')}'}

Error de MALFORMED_QUERY: Truncated

Si aparece un error "MALFORMED_QUERY: Truncated", normalmente se debe a que tiene la columna de tipo JunctionIdList en datos y Salesforce tiene una restricción en cuanto a la admisión de tales datos con un gran número de filas. Para solucionarlo, pruebe a excluir la columna JunctionIdList o limite el número de filas que desea copiar (puede dividir el proceso en varias ejecuciones de la actividad de copia).

Asignación de tipos de datos para Salesforce

Al copiar datos desde Salesforce, se usan las siguientes asignaciones de tipos de datos de Salesforce en los tipos de datos provisionales del servicio. Para más información acerca de la forma en que la actividad de copia asigna el tipo de datos y el esquema de origen al receptor, consulte el artículo sobre asignaciones de tipos de datos y esquema.

Tipos de datos de Salesforce	Tipo de datos provisional del servicio
Numeración automática	String
Casilla de verificación	Boolean
Moneda	Decimal
Date	DateTime
Fecha y hora	DateTime
Email	String
ID	String
Relación de búsqueda	String
Lista desplegable de selección múltiple	String
Number	Decimal
Percent	Decimal
Teléfono	String
Lista desplegable	String
Texto	String
Área de texto	String
Área de texto (largo)	String
Área de texto (enriquecido)	String
Texto (cifrado)	String
URL	String

Nota:

El tipo de número de Salesforce se asigna al tipo decimal en Azure Data Factory y en canalizaciones de Azure Synapse como un tipo de datos provisional de servicio. El tipo decimal respeta la precisión y la escala definidas. En el caso de los datos cuyas posiciones decimales superen la escala definida, el valor se redondeará en los datos y la copia de vista previa. Para evitar la pérdida de precisión en las canalizaciones de Azure Data Factory y Azure Synapse, considere la posibilidad de aumentar las posiciones decimales a un valor razonablemente alto en la página Edición de definición de campo personalizado de Salesforce.

Propiedades de la actividad de búsqueda

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

Pasos siguientes

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

Compartir a través de

Copia de datos en Salesforce con origen y destino mediante Azure Data Factory o Azure Synapse Analytics (versión heredada)

Funcionalidades admitidas

Prerrequisitos

Límites de solicitudes de Salesforce

Introducción

Creación de un servicio vinculado a Salesforce mediante la interfaz de usuario

Detalles de configuración del conector

Propiedades del servicio vinculado

Propiedades del conjunto de datos

Propiedades de la actividad de copia

Salesforce como tipo de origen

Salesforce como tipo de receptor

Sugerencias de consulta

Recuperación de datos a partir de un informe de Salesforce

Recuperación de los registros eliminados desde la papelera de reciclaje de Salesforce

Diferencias entre la sintaxis de consulta SQL y SOQL

Recuperación de datos mediante el uso de una cláusula where en la columna DateTime

Error de MALFORMED_QUERY: Truncated

Asignación de tipos de datos para Salesforce

Propiedades de la actividad de búsqueda

Pasos siguientes

Comentarios

Recursos adicionales