Como conectar seu aplicativo de código ao Dataverse

Este guia ajuda os desenvolvedores a usar a biblioteca de clientes Power Apps para aplicativos de código para conectar seu aplicativo de código ao Microsoft Dataverse.

Pré-requisitos

• Power Apps biblioteca de clientes para aplicativos de código
• Power Apps CLI (PAC CLI) versão 1.46 ou posterior
• Um ambiente com o Dataverse habilitado
• Você deve estar conectado ao ambiente usando a CLI do PAC

Steps

1. Verifique se você está conectado ao seu ambiente usando a CLI do PAC.

2. Use o comando pac code add-data-source para adicionar o Dataverse como uma fonte de dados ao seu aplicativo de código.

   pac code add-data-source -a dataverse -t <table-logical-name>
   

   Substitua <table-logical-name> pelo nome lógico da tabela Dataverse à qual você deseja se conectar.

Cenários com suporte

A biblioteca de clientes Power Apps para aplicativos de código dá suporte aos seguintes cenários ao se conectar ao Dataverse:

• Adicione entidades do Dataverse a aplicativos de código.

• Recupere valores formatados (rótulos) para valores de opção nos conjuntos de opções.

• Obter metadados para tabelas do Dataverse.

• Faça consultas. Atualmente, você precisa usar as diretrizes para associar a uma propriedade de navegação de valor único ou associar registros ao criar ao trabalhar com pesquisas. Um guia de instruções dedicado estará disponível em breve. A equipe de Power Apps está trabalhando ativamente para tornar as pesquisas mais fáceis de usar em aplicativos de código.

• Upload e download de imagem e arquivo (versão prévia). Quando você adiciona o Dataverse como uma fonte de dados usando o CLI baseado em npm, as funções geradas fazem parte de src/generated/services.

• Executar operações CRUD:

  • Create
  • Recuperar
  • RetrieveMultiple
  • Update
  • Delete

• Delegação para:

  • Filter
  • Sort
  • Consultas Top

• Suporte à paginação.

Configurar seu aplicativo de código

Antes de executar operações CRUD (criar, ler, atualizar e excluir) em seu aplicativo de código, importe os tipos e serviços necessários.

Quando você adiciona uma fonte de dados, o sistema gera automaticamente arquivos de modelo e serviço e os coloca na /generated/services/ pasta. Por exemplo, se você adicionar a tabela Contas internas como uma fonte de dados, os seguintes arquivos serão criados:

• AccountsModel.ts – Define o modelo de dados para a tabela Contas.
• AccountsService.ts – Fornece métodos de serviço para interagir com os dados de Contas.

Você pode importar e usar esses arquivos em seu código da seguinte maneira:

import { AccountsService } from './generated/services/AccountsService';
import type { Accounts } from './generated/models/AccountsModel';

Criar registros

Use os tipos de modelo gerados e os métodos de serviço para criar novos registros do Dataverse do seu aplicativo de código.

1. Criar o objeto de registro usando o modelo gerado

   Os modelos gerados refletem o esquema da tabela Dataverse. Use-os para criar objetos de registro.

   Observação

   Ao criar um registro, exclua colunas gerenciadas pelo sistema ou somente leitura, como chaves primárias e campos de propriedade. Para entender quais colunas são somente leitura, consulte Navegar pelas definições de tabela em seu ambiente. Por exemplo, na tabela Contas, não inclua os seguintes campos:

   • accountid
   • ID do proprietário
   • owneridname
   • owneridtype
   • owneridyominame

   Forme um registro com apenas os campos que você deseja preencher. Por exemplo, para a entidade Contas:

   
   const newAccount = {
      name: "New Account"
      statecode: 0,
      accountnumber: "ACCOO1"
      ...
   };
   

2. Enviar o registro usando o serviço gerado

   Use as funções no arquivo de serviço gerado para enviar seu registro. Por exemplo, para a entidade Contas:

   try {
   const result = await AccountsService.create(newAccount as Omit<Accounts, 'accountid'>);
   
   if (result.data) {
   console.log('Account created:', result.data);
   return result.data;
   }
   } catch (err) {
   console.error('Failed to create account:', err);
   throw err;
   };
   

Ler dados

Você pode recuperar um único registro ou redigir uma consulta para retornar vários registros.

Recuperar um único registro

Para recuperar um único registro, você precisa da chave primária (por exemplo, accountid).

const accountId = "<00000000-0000-0000-0000-000000000000>"; // Replace with actual ID value

try {
      const result = await AccountsService.get(accountId);
      if (result.data) {
            console.log('Account retrieved:', result.data);
      }
} catch (err) {
      console.error('Failed to retrieve account:', err);
}

Recuperar vários registros

Para recuperar todos os registros de uma tabela do Dataverse, use o getAll método:

try {
   const result = await AccountsService.getAll();
   if (result.data) {
         const accounts = result.data;
         console.log(`Retrieved ${accounts.length} accounts`);
   }
} catch (err) {
   console.error('Failed to retrieve accounts:', err);
}

O getAll método aceita um parâmetro opcional que implementa a IGetAllOptions interface. Use estas opções para personalizar a consulta:

interface IGetAllOptions {
   maxPageSize?: number;    // Maximum number of records per page
   select?: string[];       // Specific fields to retrieve
   filter?: string;         // OData filter string
   orderBy?: string[];     // Fields to sort by
   top?: number;           // Maximum number of records to retrieve
   skip?: number;          // Number of records to skip
   skipToken?: string;     // Token for pagination
}

Aqui está um exemplo com várias opções:

const fetchAccounts = async () => {
const options: IGetAllOptions = {
      select: ['name', 'accountnumber', 'address1_city'],
      filter: "address1_country eq 'USA'",
      orderBy: ['name asc'],
      top: 50
};

try {
      const result = await AccountsService.getAll(options);
      return result.data || [];
} catch (err) {
      console.error('Failed to fetch accounts:', err);
      return [];
}
};

Atualizar registros

Para atualizar um registro, você precisa:

1. O valor da chave primária do registro. Por exemplo, com a tabela de contas, o valor accountid.
2. As alterações que você deseja fazer.

Este exemplo atualiza as propriedades name e telephone1 do registro da conta.

const accountId = "<your-account-guid>";
const changes = {
      name: "Updated Account Name",
      telephone1: "555-0123"
};

try {
      await AccountsService.update(accountId, changes);
      console.log('Account updated successfully');
} catch (err) {
      console.error('Failed to update account:', err);
}

Excluir registros no Dataverse

Para excluir um registro, você precisa do valor da chave primária do registro. Por exemplo, com a tabela de contas, o valor accountid.

Por exemplo:

const accountId = "<00000000-0000-0000-0000-000000000000>"; // Replace with actual ID value

try {
  await AccountsService.delete(accountId);
  console.log('Account deleted successfully');
} catch (err) {
  console.error('Failed to delete account:', err);
}

Cenários sem suporte

Os seguintes recursos ainda não têm suporte:

• Pesquisas polimórficas
• Excluindo fontes de dados do Dataverse por meio da CLI do PAC
• Definição de esquema (metadados de entidade) CRUD
• Suporte a FetchXML
• Suporte à chave alternativa

Informações relacionadas

• Como conectar seu aplicativo de código a dados
• Power Apps CLI