Consultar definiciones de esquema

  • Artículo

Las aplicaciones creadas usando Dataverse tienen que ser capaces de adaptarse a los cambios en las definiciones de esquema. Se pueden agregar o cambiar nuevas tablas, columnas, relaciones y etiquetas a través de la configuración o importando una solución. Dado que las aplicaciones deben poder responder a estos cambios, con frecuencia dependen de la recuperación de las definiciones de esquema cuando se inician. Sin embargo, la cantidad total de datos que describen el esquema de una organización de Dataverse puede ser muy grande. Necesita poder saber cómo obtener solo los datos que necesita.

El mensaje RetrieveMetadataChanges proporciona dos capacidades:

  1. Consulta: redacte una sola consulta para recuperar solo los datos del esquema que necesita. Este artículo se centra en la redacción de consultas.
  2. Administración de caché : si almacena en caché los datos de definición de esquema con su aplicación, puede usar RetrieveMetadataChanges para recuperar eficientemente solo los cambios desde su última consulta. Utilice la información sobre estos cambios para agregar o quitar elementos en su caché. El almacenamiento en caché puede resultar en una mejora significativa del tiempo de inicio de su aplicación. La administración de la caché está cubierta en Almacenar en caché datos de esquema.

Evaluar otras opciones para recuperar definiciones de esquema

Al redactar una consulta para recuperar definiciones de esquema, el mensaje RetrieveMetadataChanges brinda la ventaja de definir una sola solicitud que puede abarcar varias definiciones de tabla y devolver detalles para tipos derivados y administrar un caché a lo largo del tiempo.

En la siguiente tabla se resumen otras maneras en que puede recuperar definiciones de esquema, pero ninguna de ellas ofrece capacidades para administrar una memoria caché a lo largo del tiempo.

Publicación Descripción y limitaciones
RetrieveAllEntities Recupera datos para todas las tablas, incluidas todas las columnas, privilegios y relaciones si lo desea.
Consulte: clases RetrieveAllEntitiesRequest y RetrieveAllEntitiesResponse

Limitaciones: si bien puede usar el parámetro EntityFilters para excluir algunas partes, es una operación muy costosa.
RetrieveEntity Puede recuperar la definición de cualquier tabla individual, incluidas todas las columnas, privilegios y relaciones si lo desea.
Consulte: Recuperar y actualizar una tabla

Limitaciones: si bien puede usar el parámetro EntityFilters para excluir algunos datos, no puede seleccionar qué propiedades específicas desea, sigue siendo una operación costosa.
RetrieveAttribute Puede recuperar la definición completa de cualquier atributo único.
Consulte: Recuperar una columna

Limitaciones: no puede seleccionar qué propiedades específicas desea.
RetrieveRelationship Puede recuperar la definición completa de cualquier relación única.
Consulte Recuperar relaciones de fila de tabla

Limitaciones: no puede seleccionar qué propiedades específicas desea.
RetrieveAllOptionSets Puede recuperar información acerca de todas las opciones globales definidas en la organización.
Consulte: Insertar, actualizar, eliminar y ordenar opciones globales

Limitaciones: no se incluyen las opciones que solo se definen localmente dentro de una columna.
RetrieveEntityKey Puede recuperar la definición de cualquier clave alternativa para una tabla específica.
Consulte: Recuperar y eliminar claves alternativas

Ejemplo de RetrieveMetadataChanges básico

Para ver un ejemplo sencillo de lo que puede hacer con RetrieveMetadataChanges, compare lo que puede hacer con la API web y el conjunto de entidades EntityDefinitions.

Con la API web, puede redactar una consulta como esta:

GET [Organization URI]/api/data/v9.2/EntityDefinitions?$select=SchemaName&$filter=LogicalName eq 'account' or LogicalName eq 'contact'&$expand=Attributes($select=LogicalName;$filter=IsValidForCreate eq true)

Esta consulta devuelve datos de las definiciones de la tabla de cuentas y contactos, y expande todas las definiciones de columna donde IsValidForCreate es verdadero.

Los siguientes ejemplos muestran cómo redactar la misma consulta usando RetrieveMetadataChanges.

/// <summary>
/// Get the SchemaName for the account and contact tables together with
/// the LogicalName of any attributes which are valid for create
/// </summary>
/// <param name="service"></param>
static void SimpleRetrieveMetadataChangesExample(IOrganizationService service) {

    var query = new EntityQueryExpression
    {
        Properties = new MetadataPropertiesExpression("SchemaName", "Attributes"),
        Criteria = new MetadataFilterExpression(filterOperator: LogicalOperator.Or)
        {
            Conditions = {
                {
                    new MetadataConditionExpression(
                        propertyName:"LogicalName",
                        conditionOperator: MetadataConditionOperator.Equals,
                        value:"account")
                },
                {
                    new MetadataConditionExpression(
                        propertyName:"LogicalName",
                        conditionOperator: MetadataConditionOperator.Equals,
                        value:"contact")
                }
            }, 
        },
        AttributeQuery = new AttributeQueryExpression
        {
            Properties = new MetadataPropertiesExpression("LogicalName"),
            Criteria = new MetadataFilterExpression(filterOperator: LogicalOperator.And)
            {
                Conditions = {
                    {
                        new MetadataConditionExpression(
                        propertyName:"IsValidForCreate",
                        conditionOperator: MetadataConditionOperator.Equals,
                        value:true)
                    }
                }
            }            
        },
        LabelQuery = new LabelQueryExpression { 
             FilterLanguages = {
                { 1033 }
            } 
        }
        
    };

    var request = new RetrieveMetadataChangesRequest
    {
        Query = query
    };

    var response = (RetrieveMetadataChangesResponse)service.Execute(request);

    response.EntityMetadata.ToList().ForEach(em => {

        Console.WriteLine($"Entity SchemaName:{em.SchemaName}");
        em.Attributes.ToList().ForEach(a => {
            Console.WriteLine($"\tAttribute LogicalName:{a.LogicalName}");
        });
    });
}

Salida:

Entity SchemaName:Account
        Attribute LogicalName:emailaddress3
        Attribute LogicalName:emailaddress1
        Attribute LogicalName:address1_city
    <List truncated for brevity>
Entity SchemaName:Contact
        Attribute LogicalName:contactid
        Attribute LogicalName:emailaddress3
        Attribute LogicalName:emailaddress2
    <List truncated for brevity>

Crean una consulta utilizando EntityQueryExpression

Use EntityQueryExpression para establecer la propiedad Query RetrieveMetadataChanges.

EntityQueryExpression tiene las siguientes propiedades:

Property Type Descripción
Properties MetadataPropertiesExpression Establece PropertyNames en una lista de nombres de propiedad para devolver. O puede establecer AllProperties en verdadero para devolver todas las propiedades. Para los artículos que los tienen, no necesita agregar el MetadataId, LogicalName, o HasChanged nombres de propiedades. Estas propiedades siempre se incluirán.
Criteria MetadataFilterExpression Consulte Limitar los datos devueltos usando MetadataFilterExpression
AttributeQuery AttributeQueryExpression Sigue el mismo patrón que EntityQueryExpression. AttributeQueryExpression también tiene Properties y Criteria para controlar qué definiciones de columna devolver.

Nota: cuando usa AttributeQuery, Attributes debe ser uno de las Properties solicitadas para el EntityQueryExpression.
RelationshipQuery RelationshipQueryExpression Sigue el mismo patrón que EntityQueryExpression. RelationshipQueryExpression también tiene Properties y Criteria para controlar qué definiciones de relación devolver.

Nota: cuando usa , RelationshipQuery, OneToManyRelationships, ManyToOneRelationships o ManyToManyRelationships debe ser uno de las Properties solicitadas para EntityQueryExpression.
KeyQuery EntityKeyQueryExpression Sigue el mismo patrón que EntityQueryExpression. EntityKeyQueryExpression también tiene Properties y Criteria para controlar qué definiciones de clave alternativa devolver.

Nota: cuando usa KeyQuery, Keys debe ser uno de las Properties solicitadas para el EntityQueryExpression.
LabelQuery LabelQueryExpression Utilice la propiedad FilterLanguages para limitar los idiomas que se devuelven. Si una organización tiene muchos idiomas aprovisionados, recibirá etiquetas para todos los idiomas que podrían aumentar considerablemente los datos devueltos. Si su aplicación es para un usuario individual, debe incluir el código de idioma LCID preferido del usuario. Consulte Recuperar el código de idioma preferido del usuario

Nota

El parámetro Query es opcional, por lo que puede usar RetrieveMetadataChanges sin ningún filtro, pero esto es equivalente a usar RetrieveAllEntities, una operación muy costosa.

Limitar los datos devueltos usando MetadataFilterExpression

Use MetadataFilterExpression para la propiedad Criteria para EntityQueryExpression, AttributeQueryExpression, RelationshipQueryExpression y EntityKeyQueryExpression.

MetadataFilterExpression tiene las siguientes propiedades:

Property Type Descripción
FilterOperator LogicalOperator Controla cómo se evalúan las Conditions, And o Or.
Conditions DataCollection<MetadataConditionExpression> Una colección de condiciones para evaluar. Consulte Establecer condiciones usando MetadataConditionExpression
Filters DataCollection<MetadataFilterExpression> Más filtros para aplicar a una consulta más compleja.

Establecer condiciones usando MetadataConditionExpression

Use MetadataConditionExpression para la propiedad Conditions MetadataFilterExpression.

MetadataConditionExpression tiene las siguientes propiedades:

Property Type Descripción
ConditionOperator MetadataConditionOperator Describe el tipo de comparación que se aplicará a la propiedad Value.
PropertyName string El nombre de la propiedad que se evaluará
Value objeto El valor (o valores) que se compararán.

En general, solo puede usar propiedades que representen tipos de datos simples, enumeraciones, BooleanManagedPropertyBooleanManagedProperty, o AttributeRequiredLevelManagedProperty en un MetadataFilterExpression. No puede establecer condiciones en ninguna propiedad que sea una colección o una etiqueta. Cuando se especifica BooleanManagedProperty o AttributeRequiredLevelManagedProperty, solo se evalúa la propiedad Value. Filtrar con la propiedad AttributeMetadata.SourceType no es compatible.

Valores de enumeración de MetadataConditionOperator

Enum de MetadataConditionOperator tiene los siguientes miembros:

Campo Descripción
Equals Los valores se comparan para igualdad.
NotEquals Los dos valores no son iguales.
In El valor existe en una lista de valores.
NotIn El valor dado no coincide con un valor en una lista.
GreaterThan El valor es mayor que el valor comparado.
LessThan El valor es menor que el valor comparado.

Procesar datos devueltos

RetrieveMetadataChangesResponse tiene las siguientes propiedades:

Property Type Descripción
EntityMetadata EntityMetadataCollection Las definiciones de tabla solicitadas. Cuando está consultando datos o al inicializar un caché, este valor se puede tratar igual que la respuesta del mensaje RetrieveAllEntities. Si desea acceder a una columna, relación o definición de clave alternativa específica, debe devolver la definición de la tabla que las contiene.
ServerVersionStamp string Un identificador de marca de tiempo para los metadatos recuperados. Cuando administre una memoria caché de definiciones de esquema, use este valor como la propiedad ClientVersionStamp en solicitudes posteriores para que solo se devuelvan los cambios desde la solicitud anterior.
DeletedMetadata DeletedMetadataCollection Datos de los elementos eliminados desde la solicitud anterior. Este valor solo contiene datos cuando RetrieveMetadataChanges se envía con los parámetros ClientVersionStamp y DeletedMetadataFilters. Para obtener más información, consulte Almacenar en caché datos de esquema

Recuperar el código de idioma preferido del usuario

Los siguientes ejemplos muestran cómo puede recuperar el código de idioma LCID preferido del usuario.

Puede recuperar el idioma preferido del usuario desde la columna UserSettings.UILanguageId.

static int? RetrieveUserUILanguageCode(IOrganizationService service)
{
   // To get the current user's systemuserid
   var whoIAm = (WhoAmIResponse)service.Execute(new WhoAmIRequest());

   var query = new QueryExpression("usersettings")
   {
         ColumnSet = new ColumnSet("uilanguageid", "systemuserid"),
         Criteria = new FilterExpression
         {
            Conditions = {
                  {
                     new ConditionExpression(
                        attributeName:"systemuserid",
                        conditionOperator:ConditionOperator.Equal,
                        value: whoIAm.UserId)
                  }
            }
         },
         TopCount = 1
   };

   EntityCollection userSettings = service.RetrieveMultiple(query: query);
   if (userSettings.Entities.Count > 0)
   {
         return (int)userSettings.Entities[0]["uilanguageid"];
   }
   return null;
}

Consulte también

Almacenar en caché datos de esquema
API web, consultar definiciones de esquema y detectar ejemplo de cambios (C#)
SDK para definiciones de esquema de consulta .NET y detectar ejemplo de cambios (C#)
SDK para .NET: Definiciones de tabla en Microsoft Dataverse
Consultar definiciones de tabla con la API web

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).