Vorgehensweise: Abrufen von Metadaten für Dataverse-Tabellen (Vorschau)

Die Tabellenmetadaten enthalten Anpassungen, die auf Tabellen in Dataverse angewendet werden. Metadaten enthalten auch lokalisierte Bezeichnungen, wenn Ihre Organisation mehrere Sprachen unterstützt. Die Verwendung von Metadaten in Ihrer Code-App bedeutet, dass Ihre App sich an Anpassungs- oder Lokalisierungsänderungen anpassen kann, ohne den Code ändern zu müssen.

Verwenden Sie die getMetadata Funktion zum Abrufen von Dataverse-Tabellenmetadaten (Entitätsmetadaten) zur Laufzeit. Diese Funktion leicht umhüllt die in den Abfragetabellendefinitionen mittels der Web-API beschriebenen Fähigkeiten und bietet stark typisierte Zugriffsmöglichkeiten auf Entitätsdefinitionen, Attribute und Beziehungen.

getMetadata-Signatur

Die Funktion getMetadata erfordert eine Instanz von GetEntityMetadataOptions, um die zurückzugebenden Daten zu definieren.

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

Hinweis

Sie müssen die Schritte in "Einrichten Ihrer Code-App in Connect to Dataverse " ausführen, um das Power SDK zu initialisieren und die Dienstdatei vor dem Aufrufen zu getMetadataimportieren.

GetEntityMetadataOptions-Parameter

Legen Sie den getMetadata-Parameteroptions fest, um die Metadaten auszuwählen, die Sie abrufen möchten:

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

• metadata: Array von Eigenschaften auf Entitätsebene, die abgerufen werden sollen, wie z. B. ["Privileges","DisplayName","IsCustomizable"]. Eine vollständige Liste der abfragefähigen Tabelleneigenschaften finden Sie unter EntityMetadata-Eigenschaften .

• schema:

  • columns: Abrufen von Spaltenmetadaten (Attribut) - "all" oder ein Array von logischen Spaltennamen wie ["name","telephone1","createdon"]. Eine vollständige Liste der abfragefähigen Attributeigenschaften finden Sie unter AttributeMetadata-Eigenschaften .

    Hinweis

    Sie können keine Eigenschaften angeben, die AttributeMetadatanicht enthalten sind. Von abgeleiteten Typen definierte Eigenschaften sind nicht verfügbar. Dies bedeutet, dass Sie nicht auf Eigenschaften wie Auswahloptionen (Auswahlliste) zugreifen können, da sie von einem abgeleiteten Typ definiert sind.

  • oneToMany, manyToOne, manyToMany: Boolesche Werte festlegen, um Beziehungsmetadaten einzuschließen

Die Antwort enthält Arrays mit dem Namen Attributes vom Typ AttributeMetadata, OneToManyRelationships vom Typ OneToManyRelationshipMetadata, ManyToOneRelationships vom Typ OneToManyRelationshipMetadata und ManyToManyRelationships vom Typ ManyToManyRelationshipMetadata, wenn angefordert.

Examples

Die folgenden Beispiele zeigen allgemeine Methoden zum Abrufen und Verwenden von Tabellenmetadaten.

Lokalisierte Benutzerbeschriftungen für alle Spalten abrufen

Abrufen von Anzeigenamen in der Sprache des Benutzers. Verwenden Sie diese Bezeichnungen, um Formularbeschriftungen, Tabellenüberschriften und Barrierefreiheitstext zu steuern.

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

Identifizieren erforderlicher Felder für die Formularüberprüfung

Suchen Sie Attribute, die für Formulare erforderlich sind, um clientseitige Gültigkeitsprüfungsregeln basierend auf Metadaten zu erstellen, anstatt hartcodieren zu müssen.

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

Abbilden von Spaltentypen für die clientseitige Überprüfung

Rufen Sie Attributtypen ab, um die Überprüfung und Oberflächenelemente zu unterstützen. Wählen Sie das richtige UI-Steuerelement (z. B. Datumsauswahl, Geld, Auswahl) aus, und überprüfen Sie werte konsistent.

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

Ermitteln von Nachschlagebeziehungen (n:1)

Suchen Sie, welche Nachschlagefelder auf andere Tabellen verweisen, um die Nachschlage-UI und Navigation basierend auf Beziehungen dynamisch zu erstellen.

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;

Bewährte Methoden

• Cachemetadaten : Metadatenaufrufe können schwer sein. Zwischenspeichern beim Start der App oder pro Sitzung.
• Fordern Sie nur das an, was Sie benötigen: Bevorzugen Sie aus Leistungsgründen eine Spaltenliste gegenüber "all".
• Defensiver Zugriff : Überprüfen Sie vor dem Zugriff auf geschachtelte Werte auf Eigenschaftsexistenz (Beispiel: DisplayName?.UserLocalizedLabel?.Label).
• Verwenden Sie TypeScript-Typen: Verlassen Sie sich auf generierte Typen aus der Dataverse-Web-API, um sichereren Code zu erhalten.