Como obter metadados para tabelas do Dataverse (versão prévia)

Os metadados da tabela contêm personalizações aplicadas a tabelas no Dataverse. Os metadados também contêm rótulos localizados quando sua organização dá suporte a vários idiomas. Usar metadados em seu aplicativo de código significa que seu aplicativo pode se adaptar às alterações de personalização ou localização sem precisar alterar seu código.

Use a função getMetadata para recuperar metadados de tabelas (entidades) do Dataverse em tempo de execução. Esta função empacota levemente as capacidades descritas em Definições da tabela de consulta usando a API web e dá acesso fortemente tipado a definições, atributos e relações de entidade.

assinatura do getMetadata

A função getMetadata requer uma instância de GetEntityMetadataOptions para definir os dados a serem retornados.

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

Observação

Você deve seguir as etapas em Configurar seu aplicativo de código no Connect to Dataverse para inicializar o SDK do Power e importar o arquivo de serviço antes de chamar getMetadata.

Parâmetro GetEntityMetadataOptions

Defina o parâmetro getMetadataoptions para selecionar os metadados que você deseja recuperar:

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

• metadata: matriz de propriedades no nível da entidade a serem buscadas, como ["Privileges","DisplayName","IsCustomizable"]. Consulte as propriedades EntityMetadata para obter uma lista completa das propriedades da tabela que podem ser consultadas.

• schema:

  • columns: Recuperar metadados da coluna (atributo) – "all" ou uma matriz de nomes lógicos da coluna, como ["name","telephone1","createdon"]. Consulte Propriedades AttributeMetadata para obter uma lista completa das propriedades de atributos consultáveis.

    Observação

    Você não pode especificar propriedades que não estão incluídas em AttributeMetadata. As propriedades definidas por tipos derivados não estão disponíveis. Isso significa que você não pode acessar propriedades como opções de coluna de escolha (lista de seleção) porque elas são definidas por um tipo derivado.

  • oneToMany, manyToOne, manyToMany: Definir valores boolianos para incluir metadados de relação

A resposta inclui matrizes nomeadas Attributes do tipo AttributeMetadata, OneToManyRelationships do tipo OneToManyRelationshipMetadata, ManyToOneRelationships do tipo OneToManyRelationshipMetadata e ManyToManyRelationships do tipo ManyToManyRelationshipMetadata quando solicitado.

Exemplos

Os exemplos a seguir mostram maneiras comuns de recuperar e usar metadados de tabela.

Obter rótulos localizados pelo usuário para todas as colunas

Recupere os nomes de exibição no idioma do usuário. Use esses rótulos para direcionar rótulos de formulário, cabeçalhos de tabela e texto de acessibilidade.

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

Identificar campos necessários para validação de formulário

Localize atributos necessários em formulários para criar regras de validação do lado do cliente com base em metadados em vez de codificação 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 coluna para validação do lado do cliente

Obtenha tipos de atributo para informar a validação e os controles de interface do usuário. Escolha o controle de interface do usuário correto (por exemplo: seletor de data, dinheiro, escolha) e valide os valores de forma consistente.

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

Descubra relacionamentos de pesquisa (muitos-para-um)

Localize quais campos de pesquisa apontam para outras tabelas para criar dinamicamente a interface do usuário de pesquisa e a navegação com base nas relações.

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;

Práticas recomendadas

• Metadados de cache : as chamadas de metadados podem ser pesadas. Cache no início do aplicativo ou por sessão.
• Solicite apenas o que você precisa : prefira uma lista de colunas em vez de "all" para melhorar o desempenho.
• Acesso defensivo : verifique a existência da propriedade antes de acessar valores aninhados (por exemplo: DisplayName?.UserLocalizedLabel?.Label).
• Usar tipos TypeScript : conte com tipos gerados da API Web do Dataverse para obter um código mais seguro.