Trabajar con claves alternativas

Las claves alternativas de Microsoft Dataverse permiten identificar de forma única las filas de tabla mediante columnas de negocio en lugar de solo una clave principal GUID. Estos identificadores son la clave principal de cada tabla. 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 una fila en Dataverse. Sin embargo, a veces no puede modificar la base de datos externa. Mediante el uso de claves alternativas, puede definir una columna en una tabla de Dataverse para que se corresponda con un identificador único (o una combinación única de columnas) utilizado por el almacén de datos externo. Esta clave alternativa puede identificar de forma única una fila en Dataverse en lugar de la clave principal. Debe poder definir qué columnas representan una única identidad para sus filas. Una vez identifique las columnas que son únicas de la tabla, puede declararlas como claves alternativas con la interfaz de usuario de personalización (UI) o en el código. En este artículo se proporciona información sobre cómo definir claves alternativas en el modelo de datos.

Crear claves alternativas

Puede crear claves alternativas mediante programación o mediante las herramientas de personalización. Para obtener más información sobre el uso de las herramientas de personalización, vea Definir claves alternativas utilizando Power Apps.

Para definir claves alternativas mediante programación, cree primero un objeto de tipo EntityKeyMetadata (o use EntityKeyMetadata EntityType si se trabaja con la API web). Esta clase contiene las columnas clave. Después de establecer las columnas de clave, use CreateEntityKey para crear las claves de una tabla. Este mensaje toma el nombre de la tabla y los valores de EntityKeyMetadata como entrada para crear la clave.

Tenga en cuenta las restricciones siguientes al crear claves alternativas:

• Columnas válidas en definiciones de tabla clave

  Incluya solo columnas de los siguientes tipos en definiciones de tabla de claves alternativas:

  Tipo de columna	Nombre para mostrar
  DecimalAttributeMetadata	Número decimal
  IntegerAttributeMetadata	Número entero
  StringAttributeMetadata	Línea única de texto
  DateTimeAttributeMetadata	Fecha y hora
  LookupAttributeMetadata	Búsqueda
  PicklistAttributeMetadata	Conjunto de opciones

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

• Tamaño de clave válido

  Al crear una clave, el sistema valida la clave, incluido que el tamaño total de la clave no infringe las 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, aparece un mensaje de error.

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

  Una tabla de una instancia de Dataverse puede tener hasta diez definiciones de tabla de clave alternativas.

• Caracteres Unicode en valor de clave

  Si los datos de una columna que se usan en una clave alternativa contienen uno de los siguientes caracteres /,<,>,*,%,&,:,\\,?,+, entonces las acciones de recuperar (GET), actualizar o hacer upsert (PATCH) no funcionan. Si solo necesita unicidad, este enfoque funciona, pero si necesita usar estas claves como parte de la integración de datos, es mejor crear la clave en las columnas que no tienen datos con esos caracteres.

• No se admite en tablas virtuales

  Las claves alternativas no se admiten en tablas virtuales porque el sistema no puede aplicar la unicidad cuando los datos están en otro sistema. Para obtener más información, consulte Introducción a las tablas virtuales (entidades).

Recuperar y eliminar claves alternativas

Para recuperar o eliminar claves alternativas, use la interfaz de usuario de personalización. No es necesario escribir ningún código. Sin embargo, el SDK proporciona los dos mensajes siguientes para recuperar y eliminar claves alternativas mediante programación:

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

Use esta consulta de API web para ver todas las tablas y ver cuáles tienen claves alternativas:

GET [Organization URI]/api/data/v9.2/EntityDefinitions?$select=SchemaName&$expand=Keys($select=KeyAttributes)

Algunos ejemplos devueltos por esta solicitud:

{
    "SchemaName": "Account",
    "MetadataId": "70816501-edb9-4740-a16c-6a5efbc05d84",
    "Keys": [
        {
            "KeyAttributes": [
                "accountnumber"
            ],
            "MetadataId": "1dc7b1d2-6beb-ec11-bb3d-0022482ea769"
        }
    ]
},
{
    "SchemaName": "example_Table",
    "MetadataId": "8f521e41-8934-ec11-b6e6-002248242f3b",
    "Keys": [
        {
            "KeyAttributes": [
                "example_key1",
                "example_key2"
            ],
            "MetadataId": "2f16d0c6-88ea-ec11-bb3d-0022482ea769"
        }
    ]
}

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 una tabla tiene muchos registros existentes, la creación de un índice puede tardar mucho tiempo. Para que la personalización de la interfaz de usuario y la importación de soluciones tengan mayor capacidad de respuesta, cree el índice en un proceso en segundo plano. La EntityKeyMetadata.AsyncJob propiedad (EntityKeyMetadata EntityType o EntityKeyMetadata) hace referencia al trabajo asincrónico que crea el índice. La propiedad EntityKeyMetadata.EntityKeyIndexStatus especifica el estado de la clave mientras progresa su trabajo de creación de índice. El estado puede ser cualquiera de los siguientes valores:

• Pendiente
• En curso
• Activo
• Fallido

Al crear una clave alternativa mediante la API, si se produce un error en la creación del índice, puede ver detalles sobre la causa del error, corregir los problemas y reactivar la solicitud de clave utilizando la acción ReactivateEntityKey o el mensaje ReactivateEntityKeyRequest.

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

Consulte también

Usar una clave alternativa para hacer referencia a un registro
Uso del seguimiento de cambios para sincronizar los datos con sistemas externos
Use Upsert para insertar o actualizar un registro
Definir claves alternativas para hacer referencia a registros