Guide pratique pour obtenir des métadonnées pour les tables Dataverse (préversion)

Les métadonnées de table contiennent des personnalisations appliquées aux tables dans Dataverse. Les métadonnées contiennent également des étiquettes localisées lorsque votre organisation prend en charge plusieurs langues. L’utilisation de métadonnées dans votre application de code signifie que votre application peut s’adapter aux modifications de personnalisation ou de localisation sans avoir à modifier votre code.

Utilisez la getMetadata fonction pour récupérer les métadonnées de table Dataverse (entité) au moment de l’exécution. Cette fonction encapsule légèrement les fonctionnalités décrites dans les définitions de table de requête à l’aide de l’API Web et fournit un accès fortement typé aux définitions d’entité, aux attributs et aux relations.

Signature de getMetadata

La fonction getMetadata nécessite une instance de GetEntityMetadataOptions pour définir les données à retourner.

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

Note

Vous devez suivre les étapes décrites dans Configurer votre application de code dans Se connecter à Dataverse pour initialiser le Kit de développement logiciel (SDK) Power et importer le fichier de service avant d’appeler getMetadata.

Paramètre GetEntityMetadataOptions

Définissez le paramètre getMetadataoptions pour sélectionner les métadonnées à récupérer :

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

• metadata : tableau de propriétés au niveau de l’entité à extraire, tel que ["Privileges","DisplayName","IsCustomizable"], par exemple. Consultez les propriétés EntityMetadata pour obtenir la liste complète des propriétés de table interrogeables.

• schema :

  • columns: Récupérer les métadonnées "all" de colonne (attribut) - ou un tableau de noms logiques de colonne tels que ["name","telephone1","createdon"]. Consultez les propriétés AttributeMetadata pour obtenir la liste complète des propriétés d’attribut interrogeables.

    Note

    Vous ne pouvez pas spécifier les propriétés qui ne sont pas incluses dans AttributeMetadata. Les propriétés définies par les types dérivés ne sont pas disponibles. Cela signifie que vous ne pouvez pas accéder aux propriétés telles que les options de colonne choix (liste de choix), car elles sont définies par un type dérivé.

  • oneToMany, , manyToOne: manyToManyDéfinir des valeurs booléennes pour inclure des métadonnées de relation

La réponse inclut des tableaux nommés Attributes de type AttributeMetadata, OneToManyRelationships de type OneToManyRelationshipMetadata, ManyToOneRelationships de type OneToManyRelationshipMetadata et ManyToManyRelationships de type ManyToManyRelationshipMetadata lors de la demande.

Examples

Les exemples suivants montrent des façons courantes de récupérer et d’utiliser les métadonnées de table.

Obtenir des étiquettes localisées par l’utilisateur pour toutes les colonnes

Récupérez les noms d’affichage dans la langue de l’utilisateur. Utilisez ces étiquettes pour générer des étiquettes de formulaire, des en-têtes de tableau et du texte d’accessibilité.

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;
}

Identifier les champs requis pour la validation de formulaire

Recherchez les attributs requis sur les formulaires pour créer des règles de validation côté client en fonction des métadonnées au lieu de coder en dur.

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;
}

Associer les types de colonnes pour la validation côté client

Obtenez des types d’attributs pour informer la validation et les contrôles d’interface utilisateur. Choisissez le contrôle d’interface utilisateur approprié (par exemple : sélecteur de dates, argent, choix) et validez les valeurs de manière cohérente.

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;
}

Découvrir les relations de recherche (plusieurs à un)

Recherchez les champs de recherche qui pointent vers d’autres tables pour générer dynamiquement l’interface utilisateur de recherche et la navigation en fonction des relations.

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;

Meilleures pratiques

• Métadonnées du cache : les appels de métadonnées peuvent être lourds. Mettre en cache au démarrage ou à la session de l’application.
• Demandez uniquement ce dont vous avez besoin : préférer une liste "all" de colonnes pour les performances.
• Accès défensif : vérifiez l’existence de la propriété avant d’accéder aux valeurs imbriquées (par exemple : DisplayName?.UserLocalizedLabel?.Label).
• Utilisez des types TypeScript : reposez sur des types générés à partir de l’API Web Dataverse pour un code plus sûr.