Cómo conectar tu aplicación de código a Dataverse (versión preliminar)

Esta guía ayuda a los desarrolladores a usar el SDK de Power Apps para conectar su aplicación de código a Microsoft Dataverse.

Nota:

Las características en vista previa no se han diseñado para un uso de producción y pueden tener una funcionalidad restringida. Estas características están disponibles antes de una versión oficial para que los clientes puedan obtener acceso anticipado y proporcionar comentarios.

Prerrequisitos

• SDK de aplicaciones de código de Power Apps @microsoft/power-apps: paquete npm
• CLI de Power Apps (CLI de PAC) versión 1.46 o posterior
• Un entorno con Dataverse habilitado
• Debe estar conectado al entorno mediante la CLI de PAC.

Steps

1. Asegúrese de que está conectado a su entorno mediante la CLI de PAC.

2. Use el comando pac code add-data-source para agregar Dataverse como origen de datos a la aplicación de código.

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

   Reemplace por <table-logical-name> el nombre lógico de la tabla de Dataverse a la que desea conectarse.

Escenarios admitidos

Se admiten los siguientes escenarios al conectarse a Dataverse mediante el SDK de Power Apps:

• Adición de entidades de Dataverse a aplicaciones de código mediante la CLI de PAC

• Realizar operaciones CRUD:

  • Create
  • Recuperar
  • RetrieveMultiple
  • Update
  • Delete

• Delegación para:

  • Filter
  • Sort
  • Consultas de Top

• Compatibilidad con paginación

Configura tu aplicación de codificación

Antes de realizar operaciones de creación, lectura, actualización y eliminación (CRUD) en la aplicación de código, complete estos dos pasos de configuración.

1. Deberá asegurarse de que se ha realizado la inicialización del SDK de Power Apps antes de las llamadas a datos

   En el App.tsx archivo, implemente lógica que espere a que el SDK de Power Apps se inicialice completamente antes de realizar operaciones de datos. Esto evita errores causados por servicios no inicializados o contexto que falta.

   Use una función asincrónica o una administración de estado para confirmar la inicialización antes de realizar llamadas API. Por ejemplo:

   useEffect(() => {
   // Define an async function to initialize the Power Apps SDK
   const init = async () => {
         try {
               await initialize(); // Wait for SDK initialization
               setIsInitialized(true); // Mark the app as ready for data operations
         } catch (err) {
               setError('Failed to initialize Power Apps SDK'); // Handle initialization errors
               setLoading(false); // Stop any loading indicators
         }
   };
   
   init(); // Call the initialization function when the component mounts
   }, []);
   
   useEffect(() => {
   // Prevent data operations until the SDK is fully initialized
   if (!isInitialized) return;
   
   // Place your data reading logic here
   }, []);
   

2. Importación de tipos y servicios necesarios

   Al agregar un origen de datos, los archivos de modelo y servicio se generan y colocan automáticamente en la /generated/services/ carpeta . Por ejemplo, si agrega la tabla Accounts integrada como origen de datos, se crean los siguientes archivos:

   • AccountsModel.ts : define el modelo de datos para la tabla Accounts.

   • AccountsService.ts : proporciona métodos de servicio para interactuar con los datos de cuentas.

   Puede importarlos y usarlos en el código de la siguiente manera:

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

Crear registros

1. Creación del objeto de registro mediante el modelo generado

   Los modelos generados reflejan el esquema de la tabla de Dataverse y deben usarse para crear objetos de registro.

   Nota:

   Al crear un registro, excluya columnas administradas por el sistema o de solo lectura, como las claves principales y los campos de propiedad. Examinar las definiciones de tablas en tu entorno describe una herramienta que puedes usar para entender qué columnas son de solo lectura. Por ejemplo, en la tabla Cuentas, no incluya los siguientes campos:

   • accountid
   • ID del Propietario
   • owneridname
   • owneridtype
   • owneridyominame

   Forme un registro solo con los campos que desea rellenar. Por ejemplo, para la entidad Accounts:

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

2. Envío del registro mediante el servicio generado

   Use las funciones del archivo de servicio generado para enviar el registro. Por ejemplo, para la entidad Accounts:

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

Leer datos

Puede recuperar un único registro o redactar una consulta para devolver varios registros.

Recuperación de un único registro

Para recuperar un único registro, necesita su clave principal (por ejemplo, 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);
}

Recuperación de varios registros

Para recuperar todos los registros de una tabla de Dataverse, use el 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);
}

El getAll método acepta un parámetro opcional que implementa la IGetAllOptions interfaz . Use estas opciones para personalizar la 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
}

Importante

Limite siempre el número de columnas que va a recuperar con el select parámetro .

Este es un ejemplo con varias opciones:

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

Actualizar registros

Para actualizar un registro, necesita:

1. Valor de clave principal del registro. Por ejemplo, con la tabla de cuenta, el valor accountid.
2. Los cambios que desea realizar.

Importante

Al actualizar un registro, incluya solo las propiedades que va a cambiar en la solicitud. Solo tiene que establecer algunas propiedades modificadas de un registro que recuperó anteriormente e incluir esos datos en la solicitud actualiza todas las propiedades aunque sus valores no cambiaran. Las actualizaciones falsas como estas pueden desencadenar lógica de negocios que espera los valores modificados o pueden dañar los datos de auditoría para indicar que alguien cambió los datos que no cambiaron.

En este ejemplo se actualizan las propiedades name y telephone1 del registro de la cuenta.

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

Eliminación de registros en Dataverse

Para eliminar un registro, necesita el valor de clave principal del registro. Por ejemplo, con la tabla de cuenta, el valor accountid.

Por ejemplo:

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

Escenarios no soportados

Todavía no se admiten las siguientes características:

• Recuperación de valores con formato o nombres para mostrar para conjuntos de opciones
• Campos de búsqueda (incluidas las búsquedas polimórficas)
• Acciones y funciones de Dataverse
• Eliminación de orígenes de datos de Dataverse mediante la CLI de PAC
• Definición de esquema CRUD (metadatos de entidad)
• Compatibilidad con FetchXML
• Compatibilidad con claves alternativas

Información relacionada

• Cómo conectar tu aplicación de código a los datos
• Power Apps CLI