Compartir a través de

Defina claves alternativas para una entidad

  • Artículo

Todos los registros de Dynamics 365 Customer Engagement (on-premises) tienen ID únicos definidos como GUID. Éstos son clave principal para cada entidad. Si necesita integrarse con un almacén de datos externos, es posible que pueda agregar una columna a las tablas de base de datos externas para incluir una referencia al identificador único de Customer Engagement. Esto permite tener una referencia local al vínculo con el registro de Customer Engagement. Sin embargo, a veces no puede modificar la base de datos externa. Con claves alternativas, ahora puede definir un atributo de una entidad de aplicaciones Customer Engagement para que corresponda a un identificador único (o una combinación única de columnas) usado por el almacén de datos externos. Esta clave alternativa se puede usar para identificar de manera única un registro en Customer Engagement en lugar de la clave principal. Debe poder definir qué atributos representan una única identidad para sus registros. Una vez identifique los atributos que son únicos con la entidad, puede declararlos como claves alternativas con la interfaz de usuario de personalización (UI) o en el código. En este tema se proporciona información acerca de la definición de claves alternativas en el modelo de datos.

Crear claves alternativas

Puede crear claves alternativas mediante programación o usando las herramientas de personalizaciones. Para obtener más información sobre el uso de las herramientas de personalización, vea Definir claves alternativas para hacer referencia a registros de CRM.

Para definir claves alternativas mediante programación, primero tiene que crear un tipo de objeto EntityKeyMetadata (o usar EntityKeyMetadata EntityType si trabaja con la API web). Esta clase contiene los atributos clave. Una vez que se establecen los atributos clave, puede usar CreateEntityKey para crear las claves para una entidad. Este mensaje toma el nombre de la entidad y los valores de EntityKeyMetadata como entrada para crear la clave.

Debe conocer las siguientes restricciones al crear claves alternativas:

  • Tipos de atributos válidos en definiciones de clave

    Solo los atributos de los siguientes tipos se pueden incluir en definiciones de clave alternativa:

    Tipo de atributo Nombre
    DecimalAttributeMetadata Número decimal
    IntegerAttributeMetadata Número entero
    StringAttributeMetadata Línea única de texto
    DateTimeAttributeMetadata Fecha y hora
    LookupAttributeMetadata Lookup
    PicklistAttributeMetadata Los atributos de lista desplegable

Nota

Los atributos Fecha y hora, Búsqueda y Lista de selección no están disponibles para las versiones locales de Dynamics 365 Customer Engagement.

  • Los atributos deben ser válidos para crear y actualizar

    Cada atributo usado en una clave debe admitir crear y actualizar. Más información: Operaciones válidas en atributos

  • Los atributos no deben tener seguridad de nivel de campo aplicada

  • Los atributos no deben ser lógicos o heredados

    La mayoría de los atributos lógicos y heredados están configurados como de solo lectura. Sin embargo, muchos de los atributos que contienen información de dirección en entidades como Cuenta y Contacto son lógicos y no se pueden usar en una clave, aunque se pueden escribir. Más información: Atributos lógicos

  • Tamaño de clave válido

    Cuando se crea una clave, el sistema valida que la plataforma puede admitir la clave, incluido que el tamaño total de la clave no infringe restricciones de índice basadas en SQL como 900 bytes por clave y 16 columnas por clave. Si el tamaño de la clave no cumple las restricciones, un mensaje de error se mostrará.

  • Número máximo de definiciones de clave alternativa para una entidad

    Puede haber un máximo de 5 definiciones de clave alternativa para una entidad en una instancia de Customer Engagement.

  • Caracteres especiales en valor de clave

    Si los datos en un campo que se usa en una clave alternativa contienen uno de los caracteres siguientes /,<,>,*,%,&,:,\\ las acciones get y patch no funcionarán. Si solo necesita unicidad, este método funciona, pero si necesita usar estas claves como parte de la integración de datos, entonces es mejor crear la clave en los campos que no tendrán datos con dichos caracteres.

Recuperar y eliminar claves alternativas

Si necesita recuperar o eliminar claves alternativas, puede usar la interfaz de usuario de personalización para ello, sin necesidad de escribir código. Sin embargo, el SDK proporciona los dos mensajes siguientes para recuperar y eliminar claves alternativas mediante programación.

Clase de solicitud de mensajes Descripción
RetrieveEntityKeyRequest Recupera la clave alternativa especificada.
DeleteEntityKeyRequest Elimina la clave alternativa especificada.

Para recuperar todas las claves para una entidad, use la nueva propiedad Keys de EntityMetadata (clase EntityMetadata EntityType o EntityMetadata). Obtiene una matriz de claves para una entidad.

Supervisar la creación del índice para claves alternativas

Las claves alternativas utilizan índices de base de datos para forzar exclusividad y para optimizar el rendimiento de búsqueda. Si hay muchos registros existentes en una tabla, la creación del índice puede ser un proceso largo. Puede aumentar la capacidad de respuesta de la interfaz de usuario de personalización y la importación de soluciones realizando la creación de índices como un proceso en segundo plano. La propiedad EntityKeyMetadata.AsyncJob (EntityMetadata EntityType o EntityKeyMetadata) hace referencia a los trabajos asincrónicos que realiza la creación de índice. La propiedad EntityKeyMetadata.EntityKeyIndexStatus especifica el estado de la clave mientras progresa su trabajo de creación de índice. El estado podría ser cualquiera de los siguientes:

  • Pendiente
  • En curso
  • Activo
  • Incorrecto

Cuando se crea una clave alternativa con la API, si se produce un error en la creación del índice, puede analizar los detalles sobre la causa del error, corregir los problemas y reactivar la solicitud de clave con ReactivateEntityKey (mensaje Acción ReactivateEntityKey o ReactivateEntityKeyRequest).

Si se elimina la clave alternativa mientras un trabajo de creación de índice sigue pendiente o en progreso, el trabajo se cancela y se elimina el índice.

Vea también

Uso de claves alternativas
Uso del seguimiento de cambios para sincronizar los datos con sistemas externos
Use Upsert para insertar o actualizar un registro