Cómo: Agregar una acción o función de Dataverse a la aplicación de código

En esta guía se muestra cómo detectar y agregar operaciones de Dataverse (acciones y funciones) a una aplicación de código de Power Apps mediante los comandos de la CLI de find-dataverse-api y add-dataverse-api.

Prerrequisitos

• Una aplicación de código Power Apps inicializada con npx power-apps init
• @microsoft/power-apps versión 1.1.1 o posterior en el package.json
• Sesión de la CLI autentificada (npx power-apps se muestra si es necesario)
• Acceso al entorno de Dataverse que contiene la operación que desea usar

Paso 1: Detección de operaciones disponibles

Use find-dataverse-api para buscar operaciones en el entorno por su nombre:

npx power-apps find-dataverse-api --search "WhoAmI"

La salida muestra las operaciones coincidentes con su tipo (Acción o Función), parámetros, entidad de enlace (si existe) y tipo de valor devuelto:

====================================================================================================
Dataverse Operations
====================================================================================================

  WhoAmI  (Function)
  Returns: mscrm.WhoAmIResponse

----------------------------------------------------------------------------------------------------
Total: 1 operation(s)
====================================================================================================

También puede buscar acciones. Por ejemplo, para buscar la AddToQueue acción:

npx power-apps find-dataverse-api --search "AddToQueue"

====================================================================================================
Dataverse Operations
====================================================================================================

  AddToQueue  (Action)
  Bound to: mscrm.queue
  Parameters:
    - Target: mscrm.crmbaseentity
    - SourceQueue?: mscrm.queue
    - QueueItemProperties?: mscrm.queueitem
  Returns: mscrm.AddToQueueResponse

----------------------------------------------------------------------------------------------------
Total: 1 operation(s)
====================================================================================================

Para obtener el JSON sin formato (útil para scripting y para agentes de programación), agregue --json:

npx power-apps find-dataverse-api --search "WhoAmI" --json

La búsqueda es una búsqueda de subcadena sin distinción entre mayúsculas y minúsculas en el nombre de la operación.

Paso 2: Agregar la operación a la aplicación

Después de encontrar el nombre de la operación, ejecute el siguiente comando:

npx power-apps add-dataverse-api --api-name WhoAmI
# or using the short alias:
npx power-apps add-dataverse-api -n WhoAmI

El comando:

1. Captura la definición de la operación de Dataverse $metadatadel entorno.
2. Escribe un archivo de esquema en <schemaPath>/dataverse/WhoAmI.Schema.json.
3. Guarda los archivos de esquema de las entidades de Dataverse a las que hacen referencia los parámetros de la operación o el tipo de valor devuelto (omite si ya existen).
4. Actualizaciones power.config.json:
   • Agrega databaseReferences["default.cds"] si aún no está presente.
   • Para las operaciones enlazadas, agrega la entidad de enlace a dataSources si aún no está presente.
5. Se regenera dataSourcesInfo.ts para incluir la nueva operación.
6. Genera un modelo de TypeScript y una clase de servicio en <codeGenPath>/generated/.

Si se realiza correctamente, verá lo siguiente:

Dataverse API 'WhoAmI' added successfully.
Hint: Run 'npx power-apps run' to test locally, or 'npx power-apps push' to deploy.

Paso 3: Uso del servicio generado en el código de la aplicación

El comando genera una clase dedicada <ApiName>Service para la operación. Por ejemplo, después de agregar WhoAmI, importe WhoAmIService desde el directorio de servicios generados:

import { WhoAmIService } from './generated/services/WhoAmIService';

El servicio expone un método estático tipado que lleva el nombre de la operación. Por ejemplo:

const result = await WhoAmIService.WhoAmI();
// result.value contains: { BusinessUnitId: string, UserId: string, OrganizationId: string }

Para una acción enlazada como AddToQueue, el primer argumento es siempre el GUID del registro en el que operar:

import { AddToQueueService } from './generated/services/AddToQueueService';

const result = await AddToQueueService.AddToQueue(
  queueId,    // string (GUID of the destination queue)
  target,     // Record<string, unknown> (the activity to add)
  sourceQueue,         // Record<string, unknown> | undefined
  queueItemProperties  // Record<string, unknown> | undefined
);
// result.value contains: { QueueItemId: string }

Los tipos de parámetro y valor devuelto proceden del esquema de Dataverse:

• Los parámetros GUID se escriben como string.
• Los parámetros de búsqueda que hacen referencia a una entidad de Dataverse se escriben como Record<string, unknown>.
• Las operaciones sin ningún valor devuelto generan Promise<IOperationResult<void>>.
• Las operaciones que devuelven un escalar (por ejemplo, boolean, number) generan Promise<IOperationResult<T>> con el tipo TypeScript correspondiente.
• Las operaciones que devuelven un tipo complejo o una entidad generan Promise<IOperationResult<Record<string, unknown>>>.

Volver a ejecutar para la misma operación

Ejecutar add-dataverse-api nuevamente con la misma --api-name es seguro e idempotente:

• El comando sobrescribe el archivo de esquema con la definición más reciente de Dataverse.
• dataSourcesInfo.tsRegenera .
• Quita entradas duplicadas en power.config.json : no agrega duplicados.
• No sobrescribe los archivos de esquema de entidad que ya existen.

Use este comando para recoger los cambios en la firma de una operación después de una actualización en el entorno.

Archivos creados o modificados

El add-dataverse-api comando crea o actualiza los siguientes archivos en el proyecto:

Operaciones enlazadas frente a operaciones sin enlazar

Las operaciones enlazadas se limitan a un registro de entidad específico. El método generado siempre toma un id: string parámetro como primer argumento, que es el GUID del registro en el que operar.

Las operaciones no vinculadas son aplicables a todo el entorno y no requieren un ID de registro. Sus métodos toman solo los parámetros declarados.

Ambos tipos se agregan con el mismo comando: la CLI detecta automáticamente el tipo de operación.

Solución de problemas

"No se encontró ninguna operación": la búsqueda no distingue entre mayúsculas y minúsculas, pero solo coincide con el nombre de la operación. Pruebe un término más corto o diferente. Use --json para confirmar la respuesta sin procesar.

Archivos generados obsoletos: si cambió el nombre o quitó una operación y los archivos generados antiguos permanecen, elimínelos manualmente y vuelva a ejecutar add-dataverse-api para volver a generarlo.

pac code add-data-source omite la acción o función: los archivos de esquema generados por add-dataverse-api usan un tipo Microsoft.PowerApps/dataverseOperation que no reconoce la CLI de PAC. Si hay algún archivo de esquema de operación presente en la carpeta de esquema de Dataverse, pac code add-data-source los omite.

Skipping unsupported Dataverse operation schema '...AddRecurrence.Schema.json':

Este comportamiento significa que la CLI de PAC no admite el tipo de esquema Microsoft.PowerApps/dataverseOperation, por lo que omite estos archivos en lugar de fallar. La CLI de PAC sigue admitiendo los otros archivos de esquema que representan orígenes de datos o conectores de entidad de Dataverse, y puede agregarlos mediante pac code add-data-source.

Artículos relacionados

Usar acciones de la API web
Uso de funciones de API web