Usar una clave alternativa para hacer referencia a un registro

Utilizará claves alternativas con escenarios de integración de datos para realizar operaciones de datos donde no conoce el valor de la clave principal de un registro Dataverse. Solo puede usar claves alternativas para las tablas donde están definidas. La mayoría de las tablas de Dataverse no tendrán claves alternativas a menos que se hayan personalizado para incluirlas.

Para comprender cómo definir e identificar las claves alternativas para una tabla, consulte los artículos siguientes:

• Uso de Power Apps: Definir claves alternativas para hacer referencia a filas
• Uso de código: Trabajar con claves alternativas

Puede usar claves alternativas mediante la Dataverse API web o el SDK para .NET.

API web

Cuando usa la API web, hace referencia a un registro específico mediante una URL y luego usa los métodos POST, PATCH o DELETE Http para realizar la operación de datos. También usa URL para establecer valores para propiedades de navegación de un solo valor usando la sintaxis @odata.bind, o como parámetros para funciones y acciones.

La siguiente tabla proporciona ejemplos que muestran cómo hacer referencia a registros usando URL relativas:

Situación	Ejemplo
Con una clave principal	/accounts(00000000-0000-0000-0000-000000000001) O accounts(accountid=00000000-0000-0000-0000-000000000001) Consulte la siguiente nota sobre los tipos de entidad systemuser y team
Con clave alternativa única	/accounts(accountnumber='ABC123')
Con claves alternativas de varias partes	/contacts(firstname='Joe',emailaddress1='abc@example.com')
Con una clave alternativa que usa una columna de búsqueda	/accounts(_primarycontactid_value=00000000-0000-0000-0000-000000000002) Cuando se define un clave alternativa para una columna de búsqueda, debe usar el nombre de la Propiedad de búsqueda correspondiente. Una propiedad de búsqueda sigue la siguiente convención de nomenclatura: _<name of single-valued navigation property>_value.

Nota

Debido a lo que ocurre cuando los tipos de entidad systemuser y team heredan del tipo de entidad principal, no puede usar una clave principal con nombre para hacer referencia a estas entidades. Las claves principales para ambas entidades son ownerid, más bien que systemuserid o teamid. El tipo de entidad principal no es compatible con las operaciones GET. Más información: Herencia EntityType

Excepciones al utilizar claves alternativas con la API web

Es necesario conocer las siguientes condiciones y excepciones posibles para utilizar claves alternativas:

• Si especifica una columna establecida que no está definido como única clave, se lanza un error que indica que el uso de columnas de clave únicas es obligatorio. El mensaje de error es: The key in the request URI is not valid for resource 'Microsoft.Dynamics.CRM.<table logical name>'. Ensure that the names and number of key properties match the declared or alternate key properties for the resource 'Microsoft.Dynamics.CRM.<table logical name>'.
• Actualmente no se admiten los valores de clave alternativos con los siguientes caracteres: /,<,>,*,%,&,:,\\,?,+.

Más información: Recuperar registro mediante una clave alternativa

SDK para .NET

Cuando usa el SDK para .NET, hay dos formas de usar claves alternativas.

Uso de la clase Entity

Cuando crea una instancia de la clase de entidad, puede especificar las claves que se utilizarán para identificar el registro utilizando los siguientes constructores de entidad:

// For use with the primary key
public Entity (string logicalName, Guid id) {…} 
// For use with a single alternate key value
public Entity (string logicalName, string keyName, object keyValue) {…} 
// For use with multiple alternate key values
public Entity (string logicalName, KeyAttributeCollection keyAttributes) {…}  

Estos valores se agregan a la propiedad Entity.KeyAttributes, no a la propiedad Entity.Attributes. Los KeyAttributes se utilizan para identificar un registro. Attributes contiene los datos para el registro.

Por ejemplo, cuando una tabla tiene una clave alternativa que incluye dos columnas de clave alternativa, puede definir la entidad de esta manera.

KeyAttributeCollection keys = new KeyAttributeCollection() {
   { "example_key1", 5 },
   { "example_key2", 5 }
};

Entity thing = new Entity("example_thing", keys);
thing["example_name"] = "Test Name";

Uso de la clase EntityReference

Cuando crea una instancia de la clase EntityReference, puede especificar las claves que se usarán para identificar el registro utilizando los siguientes constructores de EntityReference que usan el mismo patrón que los clase de entidad constructores.

// For use with the primary key
public EntityReference(string logicalName, Guid id) {…}
// For use with a single alternate key value
public EntityReference(string logicalName, string keyName, object keyValue) {…} 
// For use with multiple alternate key values
public EntityReference(string logicalName, KeyAttributeCollection keyAttributeCollection) {…}    

• Puede usa EntityReference para establecer valores para las columnas de búsqueda de entidades. Cuando se usa para establecer una columna de búsqueda, los valores de clave se usan para encontrar el valor de clave principal; los valores de clave principales se almacenan en la base de datos.
• Puede usar EntityReference para mensajes que usan este tipo como una propiedad, como Delete usando la clase DeleteRequest.

Excepciones al utilizar claves alternativas con SDK para .NET

Es necesario conocer las siguientes condiciones y excepciones posibles para utilizar claves alternativas:

• La propiedad Entity.Id se utilizará si se proporciona. Si no se proporciona, examina el KeyAttributeCollection. Si no se proporciona KeyAttributeCollection, lanza un error.
• Si el KeyAttributeCollection proporcionado incluye una columna que es la clave principal de la tabla y el valor es válido, éste rellena la propiedad Entity.Id o EntityReference.Id Property con el valor proporcionado.
• Si se proporcionan las columnas de clave, el sistema trata de hacer coincidir el conjunto columnas suministrado con las claves definidas para la Entity. Si no encuentra una coincidencia, lanza un error. Si encuentra una coincidencia, valida los valores proporcionados para esas columnas. Si es válido, recupera el valor de la clave principal del registro que coincidió con los valores clave alternativa proporcionados y completa la propiedad Entity.Id o EntityReference.Id Propiedad con este valor.
• Si especifica una columna establecida que no está definido como única clave, se lanza un error que indica que el uso de columnas de clave únicas es obligatorio.

Consultar también

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

Nota

¿Puede indicarnos sus preferencias de idioma de documentación? Realice una breve encuesta. (tenga en cuenta que esta encuesta está en inglés)

La encuesta durará unos siete minutos. No se recopilan datos personales (declaración de privacidad).