Métodos de función y acción de Dataverse para páginas generativas

Use los métodos de acción y función del dataApi objeto para invocar las API personalizadas de Dataverse enlazadas a la página.

Note

Los métodos de acción y función son opcionales en el contrato compartido dataApi . Algunos hosts no los implementan, por lo que debe comprobar que existe un método antes de llamarlo. Un método que está presente no significa que la operación esté enlazada a la página, habilitada para el tiempo de ejecución o permitida para el usuario actual. A diferencia de los métodos del conector, estos métodos nunca inician errores esperados; se resuelven con ok: false y un código de error en su lugar. Controle explícitamente las propiedades y error del ok resultado.

listBoundActions devuelve las acciones y funciones que la configuración actual del entorno de ejecución permite la página cuando esa detección está habilitada; no es una garantía de que el usuario actual contenga los privilegios de Dataverse necesarios para ejecutar todas las operaciones enumeradas.

Método Description
executeAction Invoca una API personalizada de Dataverse enlazada a la página como una acción.
executeFunction Invoca una API personalizada de Dataverse enlazada a la página como una función.
listBoundActions Enumera las API personalizadas de Dataverse (acciones y funciones) enlazadas a la página.

método executeAction

Invoca una API personalizada de Dataverse que un creador enlaza a la página como una acción (un mensaje que podría cambiar los datos).

Parameters

Establezca un valor para este parámetro necesario.

Name Tipo Description
request DataverseActionRequest Acción que se va a invocar y sus parámetros de entrada.

DataverseActionRequest

Name Tipo Description
name string Nombre único de la API personalizada, prefijo del publicador, como new_ApproveExpenseReport.
parameters object (Opcional) Los parámetros de entrada requeridos por la acción, con clave por nombre único del parámetro.
boundTo object (Opcional) Referencia de fila de destino (entityName y id) para acciones enlazadas a entidades. Omita las acciones globales (sin enlazar).

Devoluciones

Promesa que contiene dataverseActionResult. Este método nunca produce errores esperados (como un error de permiso 403, un parámetro incorrecto 400 o la operación que no está enlazada o habilitada), compruebe la ok propiedad en su lugar.

DataverseActionResult

Name Tipo Description
ok boolean Indica si la acción se realizó correctamente.
status number Código de estado HTTP devuelto por Dataverse o 0 cuando no hay ningún estado HTTP disponible. Un 0 estado puede significar que el tiempo de ejecución rechazó la llamada antes de enviarlo (por ejemplo, not_enabled, , not_permittednot_bound, wrong_operation_kind, invalid_parametero invalid_bound_to), la solicitud produjo un error sin una respuesta HTTP o el resultado es desconocido (indeterminate es true). Use error.code y indeterminate para distinguir estos casos.
outputs object Los parámetros de salida devueltos por la acción, con clave por nombre único. Está vacío para las acciones sin salidas.
indeterminate boolean (Opcional) true cuando un tiempo de espera u otro error posterior al envío significa que el servidor podría haber confirmado la acción; no vuelva a intentarlo automáticamente.
error object (Opcional) Detalles del error cuando ok es false, incluido un objeto legible code por la máquina y un saneado message. codees uno de not_enabled, not_bound, not_permittedindeterminateinvalid_parameterwrong_operation_kindinvalid_bound_too networkel código de estado HTTP de la acción como una cadena (por ejemplo, "404") cuando Dataverse devolvió una respuesta de error o "0" cuando no había ningún estado HTTP disponible. not_permitted significa que la acción o función no está en la lista de permitidos del entorno para las páginas generativas; no indica si el usuario actual contiene los privilegios de Dataverse para ejecutarlo. Normalmente, un error de privilegios aparece como status: 403 con el código "403"de error ; si el host no puede determinar el estado HTTP, devuelve status: 0 en su lugar.

Ejemplo executeAction

if (!dataApi.executeAction) {
  throw new Error("executeAction isn't available on this page.");
}

const result = await dataApi.executeAction({
  name: "new_ApproveExpenseReport",
  parameters: { comments: "Approved by manager" },
  boundTo: { entityName: "new_expensereport", id: "30dc51e9-947d-47d8-ad48-4fc48fba4a95" },
});

if (result.ok) {
  console.log(result.outputs);
}
else {
  console.log(result.error?.code);
}

método executeFunction

Invoca una API personalizada de Dataverse que un creador enlaza a la página como una función (un mensaje de solo lectura con la semántica GET).

Parameters

Establezca un valor para este parámetro necesario.

Name Tipo Description
request DataverseFunctionRequest Función que se va a invocar y sus parámetros de entrada.

DataverseFunctionRequest

Name Tipo Description
name string Nombre único de la API personalizada, prefijo del publicador, como new_GetExchangeRate.
parameters object (Opcional) Los parámetros de entrada requeridos por la función, con clave por nombre único del parámetro.
boundTo object (Opcional) Referencia de fila de destino (entityName y id) para funciones enlazadas a entidades. Omita las funciones globales (sin enlazar).

Devoluciones

Promesa que contiene dataverseActionResult. Al igual que con executeAction, este método nunca produce errores esperados; compruebe la ok propiedad en su lugar.

Ejemplo executeFunction

if (!dataApi.executeFunction) {
  throw new Error("executeFunction isn't available on this page.");
}

const result = await dataApi.executeFunction({
  name: "new_GetExchangeRate",
  parameters: { currencyCode: "EUR" },
});

if (result.ok) {
  console.log(result.outputs);
}

método listBoundActions

Enumera las API personalizadas de Dataverse (acciones y funciones) que un creador enlaza a la página.

Parameters

None.

Devoluciones

Promesa que contiene una matriz de entradas dataverseActionInfo. Devuelve una matriz vacía cuando la detección no está habilitada para el tiempo de ejecución.

DataverseActionInfo

DataverseActionInfo refleja lo que el creador de la página enlaza para esta acción o función, no los metadatos dinámicos de Dataverse. No lo use para crear formularios de entrada o validar salidas: compruebe los requisitos de parámetro y las formas de salida en la definición de API personalizada de Dataverse real.

Name Tipo Description
name string Nombre único (lógico) de la API personalizada de Dataverse.
displayName string Nombre para mostrar de una API personalizada.
isFunction boolean true si la API personalizada de Dataverse es una función (de solo lectura); false si es una acción, incluido cuando este valor no se registró en el momento del enlace.
bindingType string Tipo de enlace: "Global" o "Entity".
boundEntityLogicalName string (Opcional) La tabla a la que está enlazada la acción o función, cuando bindingType es "Entity".
parameters Object[] Los parámetros de entrada registrados cuando la API personalizada de Dataverse estaba enlazada a la página, cada una con y namedeclaredKind. type es siempre "unknown" y optional siempre: false ninguno refleja los metadatos reales de la API personalizada de Dataverse.
outputs Object[] Siempre una matriz vacía. La detección de enlaces no registra parámetros de salida.

listBoundActions ejemplo

const actions = await dataApi.listBoundActions?.();
  • Se actualizó por última vez el