Obtención de metadatos para tablas de Dataverse

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 para recuperar metadatos de tabla de Dataverse (entidad) en tiempo de ejecución. Esta función envuelve ligeramente las capacidades descritas en Query table definitions using the Web API y proporciona acceso fuertemente tipado a definiciones de entidad, atributos y relaciones.

Firma getMetadata

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

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

Parámetro GetEntityMetadataOptions

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

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

• : matriz de propiedades de nivel de entidad para obtener, como . Consulte Propiedades de EntityMetadata para obtener una lista completa de propiedades de tabla consultables.

• :

  • : Recuperar metadatos de columna (atributo) - o una matriz de nombres lógicos de columna como . 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 . Las propiedades definidas por tipos derivados no están disponibles. Esto significa que no se puede acceder a propiedades como las opciones de columnas de selección (lista de selección) porque se definen mediante un tipo derivado.

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

La respuesta incluye matrices denominadas de tipo AttributeMetadata, de tipo OneToManyRelationshipMetadata, de tipo OneToManyRelationshipMetadata y 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 para mejorar el rendimiento.
• Defensive access: Verifique la existencia de propiedades antes de acceder a los valores anidados (por ejemplo, ).
• Usar tipos de TypeScript : Confíe en los tipos generados de la API Web de Dataverse para obtener código más seguro.