Cómo: Obtener metadatos para tablas de Dataverse (versión preliminar)

Los metadatos de la tabla contienen personalizaciones aplicadas a las tablas de Dataverse. Los metadatos también contienen etiquetas localizadas cuando la organización admite varios idiomas. El uso de metadatos en la aplicación de código significa que la aplicación puede adaptarse a los cambios de personalización o localización sin tener que cambiar el código.

Utilice la función getMetadata para recuperar metadatos de tabla de Dataverse (entidad) en tiempo de ejecución. Esta función cubre ligeramente las capacidades descritas en Definiciones de tabla de consulta utilizando la API web y proporciona acceso con tipado fuerte a definiciones de entidad, atributos y relaciones.

Firma getMetadata

La getMetadata función requiere una instancia de GetEntityMetadataOptions para definir los datos que se van a devolver.

AccountsService.getMetadata(
  options?: GetEntityMetadataOptions<Account>
): Promise<IOperationResult<Partial<EntityMetadata>>>

Nota:

Debe seguir los pasos descritos en Configuración de la aplicación de código en Conexión a Dataverse para inicializar power SDK e importar el archivo de servicio antes de llamar a getMetadata.

Parámetro GetEntityMetadataOptions

Establezca el parámetro getMetadataoptions para seleccionar los metadatos que desea recuperar:

interface GetEntityMetadataOptions {
  metadata?: Array<String>;
  schema?: {
    columns?: "all" | Array<String>;
    oneToMany?: boolean;
    manyToOne?: boolean;
    manyToMany?: boolean;
  };
}

• metadata: matriz de propiedades de nivel de entidad para obtener, como ["Privileges","DisplayName","IsCustomizable"]. Consulte Propiedades de EntityMetadata para obtener una lista completa de propiedades de tabla consultables.

• schema:

  • columns: Recuperar metadatos de columna (atributo) - "all" o una matriz de nombres lógicos de columna como ["name","telephone1","createdon"]. Consulte AttributeMetadata properties (Propiedades attributeMetadata ) para obtener una lista completa de las propiedades de atributo consultables.

    Nota:

    No se pueden especificar las propiedades que no se incluyen en AttributeMetadata. Las propiedades definidas por tipos derivados no están disponibles. Esto significa que no se puede acceder a propiedades como opciones de columna de elección (lista desplegable) porque se definen mediante un tipo derivado.

  • oneToMany, , manyToOnemanyToMany: establezca valores booleanos para incluir metadatos de relación.

La respuesta incluye matrices denominadas Attributes de tipo AttributeMetadata, OneToManyRelationships de tipo OneToManyRelationshipMetadata, ManyToOneRelationships de tipo OneToManyRelationshipMetadata y ManyToManyRelationships de tipo ManyToManyRelationshipMetadata cuando se solicita.

Examples

En los ejemplos siguientes se muestran formas comunes de recuperar y usar metadatos de tabla.

Obtención de etiquetas localizadas por el usuario para todas las columnas

Recupere los nombres mostrados en el idioma del usuario. Use estas etiquetas para controlar etiquetas de formulario, encabezados de tabla y texto de accesibilidad.

async function getColumnDisplayNames() {
// Request all column metadata
const { data } = await AccountsService.getMetadata({
   schema: { columns: 'all' }
});

const columnDisplayNames: Record<string, string> = {};
if (data.Attributes) {
   for (const attr of data.Attributes) {
      const label = attr.DisplayName?.UserLocalizedLabel?.Label;
      if (label) {
      columnDisplayNames[attr.LogicalName] = label;
      }
   }
}

console.log(columnDisplayNames);
// Output: { "accountid": "Account", "name": "Account Name", ... }
return columnDisplayNames;
}

Identificación de campos obligatorios para la validación de formularios

Busque los atributos necesarios en los formularios para crear reglas de validación del lado cliente basadas en metadatos en lugar de codificar de forma rígida.

async function getRequiredFields() {
const { data } = await AccountsService.getMetadata({
   schema: { columns: 'all' }
});
if (!data.Attributes) return [];

// Filter attributes that are required for forms
const requiredColumns = data.Attributes
   .filter(attr => attr.IsRequiredForForm)
   .map(attr => ({
      logicalName: attr.LogicalName,
      displayName: attr.DisplayName?.UserLocalizedLabel?.Label,
      attributeType: attr.AttributeTypeName?.Value
   }));

console.log('Required fields:', requiredColumns);
// Output: [
//   { logicalName: "name", displayName: "Account Name", attributeType: "StringType" },
//   { logicalName: "ownerid", displayName: "Owner", attributeType: "OwnerType" }
// ]

return requiredColumns;
}

Mapear tipos de columna para la validación del lado del cliente

Obtenga los tipos de atributo para la validación y el control de la interfaz de usuario. Elija el control de interfaz de usuario adecuado (por ejemplo: selector de fechas, dinero, elección) y valide los valores de forma coherente.

async function getColumnTypes() {
  const { data } = await AccountsService.getMetadata({
    schema: { columns: 'all' }
  });

  if (!data.Attributes) return [];

  // Map attributes to their types for validation
  const columnTypes = data.Attributes.map(attr => ({
    logicalName: attr.LogicalName,
    attributeType: attr.AttributeTypeName?.Value,
  }));

  console.log('Column types:', columnTypes);
  // Output: [
  //   {
  //     logicalName: "accountid",
  //     attributeType: "UniqueidentifierType",
  //   },
  //   {
  //     logicalName: "name",
  //     attributeType: "StringType",
  //   },
  //   {
  //     logicalName: "revenue",
  //     attributeType: "MoneyType",
  //   },
  //   {
  //     logicalName: "createdon",
  //     attributeType: "DateTimeType",
  //   }
  // ]
  
  return columnTypes;
}

Detección de relaciones de búsqueda (varios a uno)

Busque qué campos de búsqueda apuntan a otras tablas para crear dinámicamente la interfaz de usuario de búsqueda y la navegación en función de las relaciones.

async function getLookupRelationships() {
  const { data } = await AccountsService.getMetadata({
    metadata: ['LogicalName', 'DisplayName'],
    schema: { 
      manyToOne: true  // Get lookup relationships
    }
  });

  if (!data.ManyToOneRelationships) return [];

  // Get all lookup fields pointing to other tables
  const lookupRelationships = data.ManyToOneRelationships.map(rel => ({
    lookupField: rel.ReferencingAttribute,
    relatedTable: rel.ReferencedEntity,
    relatedTableAttribute: rel.ReferencedAttribute,
    relationshipName: rel.SchemaName,
  }));

  console.log('Lookup relationships:', lookupRelationships);
  // Output: [
  //   {
  //     lookupField: "primarycontactid",
  //     relatedTable: "contact",
  //     relatedTableAttribute: "contactid",
  //     relationshipName: "account_primary_contact",
  //   },
  //   {
  //     lookupField: "ownerid",
  //     relatedTable: "systemuser",
  //     relatedTableAttribute: "systemuserid",
  //     relationshipName: "owner_accounts",
  //   }
  // ]
  
  return lookupRelationships;

procedimientos recomendados

• Metadatos de caché : las llamadas a metadatos pueden ser pesadas. Caché en el inicio de la aplicación o por sesión.
• Solicite solo lo que necesita : prefiera una lista de columnas sobre "all" para mejorar el rendimiento.
• Acceso defensivo : compruebe la existencia de propiedades antes de acceder a los valores anidados (por ejemplo: DisplayName?.UserLocalizedLabel?.Label).
• Usar tipos de TypeScript : Confíe en los tipos generados de la API Web de Dataverse para obtener código más seguro.