Mètodes d'acció i funció Dataverse per a pàgines generatives

Utilitza els mètodes d'acció i funció de l'objecte dataApi per invocar APIs personalitzades de Dataverse vinculades a la pàgina.

Nota

Els mètodes d'acció i funció són opcionals en el contracte compartit dataApi . Alguns hosts no els implementen, així que comprova que existeix un mètode abans de cridar-lo. Que un mètode sigui present no vol dir que l'operació estigui vinculada a la pàgina, habilitada per a l'execució o permesa per a l'usuari actual. A diferència dels mètodes de connectors, aquests mètodes mai es llancen per fallades esperades; es resolen amb ok: false i un codi d'error en lloc d'això. Gestiona explícitament els resultats ok i error propietats.

listBoundActions retorna les accions i funcions que la configuració actual d'execució permet per a la pàgina quan aquest descobriment està activat; no garanteix que l'usuari actual tingui els privilegis de Dataverse necessaris per executar cada operació llistada.

Mètode	Descripció
executeAction	Invoca una API personalitzada de Dataverse vinculada a la pàgina com a acció.
executeFunction	Invoca una API personalitzada de Dataverse vinculada a la pàgina com a funció.
listBoundActions	Llista les APIs personalitzades de Dataverse (accions i funcions) vinculades a la pàgina.

executeAction mètode

Invoca una API personalitzada de Dataverse que un creador vincula a la pàgina com una acció (un missatge que podria canviar dades).

Paràmetres

Estableix un valor per a aquest paràmetre requerit.

Nom	Tipus	Descripció
request	DataverseActionRequest	L'acció a invocar i els seus paràmetres d'entrada.

DataverseActionRequest

Nom	Tipus	Descripció
name	string	El nom únic de l'API personalitzada, prefixat per editor, com new_ApproveExpenseReportara .
parameters	object	(Opcional) Els paràmetres d'entrada requerits per l'acció, codificats pel nom únic del paràmetre.
boundTo	object	(Opcional) Una referència de fila objectiu (entityName i id) per a accions vinculades a entitats. S'ometen les accions globals (no vinculades).

Devolucions

Una promesa que conté un DataverseActionResultat. Aquest mètode mai llança fallades esperades (com un error de permisos 403, un paràmetre 400 malament, o que l'operació no estigui vinculada o habilitada) — comprova la ok propietat en canvi.

DataverseActionResult

Nom	Tipus	Descripció
ok	boolean	Indica si l'acció va tenir èxit.
status	number	El codi d'estat HTTP retornat per Dataverse, o 0 quan no hi ha estat HTTP disponible. Un estat pot significar que el temps d'execució ha rebutjat la trucada abans d'enviar-la (per exemple, not_enabled, not_bound, not_permitted, wrong_operation_kind, invalid_parameter, o invalid_bound_to), la petició ha 0 fallat sense resposta HTTP, o que el resultat és desconegut (indeterminate és true). Utilitza error.code i indeterminate distingeix aquests casos.
outputs	object	Els paràmetres de sortida retornats per l'acció, codificats per un nom únic. Buit per a accions sense sortides.
indeterminate	boolean	(Opcional) true Quan un temps d'espera o una altra fallada després de l'enviament significa que el servidor podria haver comès l'acció; no ho tornis a intentar automàticament.
error	object	(Opcional) L'error detalla quan ok és false, incloent-hi un llegible code per màquina i un .message codeés un dels , , , , , , , , o network, o el codi d'estat HTTP de l'acció com a cadena (per exemple, "404") quan Dataverse retornava una resposta d'error, o "0" quan no hi havia cap estat HTTP disponible. indeterminateinvalid_bound_toinvalid_parameterwrong_operation_kindnot_permittednot_boundnot_enabled not_permitted vol dir que l'acció o funció no està a la llista de permís de l'entorn per a pàgines generatives — no indica si l'usuari actual té els privilegis de Dataverse per executar-la. Un error de privilegi normalment apareix com status: 403 amb el codi "403"d'error ; si l'amfitrió no pot determinar l'estat HTTP, el retorna status: 0 en el seu lloc.

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

executeFunction mètode

Invoca una API personalitzada de Dataverse que un maker vincula a la pàgina com a funció (un missatge de només lectura amb semàntica GET).

Paràmetres

Estableix un valor per a aquest paràmetre requerit.

Nom	Tipus	Descripció
request	DataverseFunctionRequest	La funció a invocar i els seus paràmetres d'entrada.

DataverseFunctionRequest

Nom	Tipus	Descripció
name	string	El nom únic de l'API personalitzada, prefixat per editor, com new_GetExchangeRateara .
parameters	object	(Opcional) Els paràmetres d'entrada requerits per la funció, codificats pel nom únic del paràmetre.
boundTo	object	(Opcional) Una referència de fila objectiu (entityName i id) per a funcions unides a entitats. S'omet les funcions globals (no lligades).

Devolucions

Una promesa que conté un DataverseActionResultat. Com amb executeAction, aquest mètode mai descarta fallades esperades — comprova la propietat en comptes d'això ok .

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

listBoundActions mètode

Llista les APIs personalitzades de Dataverse (accions i funcions) que un creador vincula a la pàgina.

Paràmetres

Cap.

Devolucions

Una promesa que conté una sèrie d'entrades DataverseActionInfo . Retorna un array buit quan el descobriment no està activat per a l'execució.

DataverseActionInfo

DataverseActionInfo reflecteix el que el creador de la pàgina ha assignat per a aquesta acció o funció, no les metadades en temps real de Dataverse. No l'utilitzis per construir formularis d'entrada ni validar sortides — verifica els requisits de paràmetres i les formes de sortida amb la definició real de l'API personalitzada de Dataverse.

Nom	Tipus	Descripció
name	string	El nom únic (lògic) de l'API personalitzada de Dataverse.
displayName	string	El nom de visualització d'una API personalitzada.
isFunction	boolean	true si l'API personalitzada de Dataverse és una funció (només lectura); false si és una acció, incloent-hi quan aquest valor no es va registrar en temps d'enllaç.
bindingType	string	El tipus d'enllaç: "Global" o "Entity".
boundEntityLogicalName	string	(Opcional) La taula a la qual l'acció o funció està lligada, quan bindingType és "Entity".
parameters	Object[]	Els paràmetres d'entrada enregistrats quan l'API personalitzada de Dataverse estava vinculada a la pàgina, cadascun amb un name i declaredKind. type és sempre "unknown" i optional és sempre false — cap dels dos reflecteix les metadades reals de l'API personalitzada de Dataverse.
outputs	Object[]	Sempre una matriu buida. El descobriment d'enllaços no registra els paràmetres de sortida.

listBoundActions Exemple

const actions = await dataApi.listBoundActions?.();