Metodi di azione e funzione di Dataverse per le pagine generative

Usare i metodi di azione e funzione dell'oggetto dataApi per richiamare le API personalizzate di Dataverse associate alla pagina.

Annotazioni

I metodi azione e funzione sono facoltativi nel contratto condiviso dataApi . Alcuni host non li implementano, quindi verificare che esista un metodo prima di chiamarlo. Un metodo presente non significa che l'operazione sia associata alla pagina, abilitata per il runtime o consentita per l'utente corrente. A differenza dei metodi del connettore, questi metodi non generano mai errori previsti; vengono risolti con ok: false e un codice di errore. Gestire in modo esplicito le proprietà e error del ok risultato.

listBoundActions restituisce le azioni e le funzioni la configurazione di runtime corrente consente la pagina quando tale individuazione è abilitata; non è una garanzia che l'utente corrente detiene i privilegi di Dataverse necessari per eseguire ogni operazione elencata.

Metodo	Description
executeAction	Richiama un'API personalizzata Dataverse associata alla pagina come azione.
executeFunction	Richiama un'API personalizzata dataverse associata alla pagina come funzione.
listBoundActions	Elenca le API personalizzate di Dataverse (azioni e funzioni) associate alla pagina.

Metodo executeAction

Richiama un'API personalizzata dataverse associata alla pagina come azione (un messaggio che potrebbe modificare i dati).

Parameters

Impostare un valore per questo parametro obbligatorio.

Name	Type	Description
request	DataverseActionRequest	Azione da richiamare e i relativi parametri di input.

DataverseActionRequest

Name	Type	Description
name	string	Nome univoco dell'API personalizzata, con prefisso publisher, ad esempio new_ApproveExpenseReport.
parameters	object	(Facoltativo) Parametri di input richiesti dall'azione, con chiave in base al nome univoco del parametro.
boundTo	object	(Facoltativo) Riferimento di riga di destinazione (entityName e id) per le azioni associate a entità. Omettere per le azioni globali (non associate).

Returns

Promessa contenente un oggetto DataverseActionResult. Questo metodo non genera mai errori previsti ,ad esempio un errore di autorizzazione 403, un parametro 400 non valido o l'operazione non associata o abilitata, controllare invece la ok proprietà .

DataverseActionResult

Name	Type	Description
ok	boolean	Indica se l'azione è riuscita.
status	number	Codice di stato HTTP restituito da Dataverse o 0 quando non è disponibile alcuno stato HTTP. Uno 0 stato può significare che il runtime ha rifiutato la chiamata prima di inviarla (ad esempio, not_enabled, invalid_parameternot_permittednot_boundwrong_operation_kindo invalid_bound_to), la richiesta non è riuscita senza una risposta HTTP oppure il risultato è sconosciuto (indeterminate è ).true Usare error.code e indeterminate per distinguere questi casi.
outputs	object	Parametri di output restituiti dall'azione, con chiave per nome univoco. Vuoto per le azioni senza output.
indeterminate	boolean	(Facoltativo) true quando un timeout o un altro errore post-invio indica che il server potrebbe aver eseguito il commit dell'azione; non riprovare automaticamente.
error	object	(Facoltativo) Dettagli dell'errore quando ok è false, inclusi un computer leggibile code e un oggetto sanificato message. codeè uno di not_enabled, not_boundinvalid_parameterindeterminateinvalid_bound_tonot_permittedwrong_operation_kindo networkil codice di stato HTTP dell'azione come stringa (ad esempio, "404") quando Dataverse ha restituito una risposta di errore o "0" quando non è disponibile alcuno stato HTTP. not_permitted indica che l'azione o la funzione non si trova nell'elenco di elementi consentiti dell'ambiente per le pagine generative. Non indica se l'utente corrente ha i privilegi dataverse per eseguirlo. Un errore di privilegio presenta in genere come status: 403 nel codice "403"di errore ; se l'host non è in grado di determinare lo stato HTTP, restituisce status: 0 invece.

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

Metodo executeFunction

Richiama un'API personalizzata dataverse associata alla pagina come funzione (un messaggio di sola lettura con semantica GET).

Parameters

Impostare un valore per questo parametro obbligatorio.

Name	Type	Description
request	DataverseFunctionRequest	Funzione da richiamare e i relativi parametri di input.

DataverseFunctionRequest

Name	Type	Description
name	string	Nome univoco dell'API personalizzata, con prefisso publisher, ad esempio new_GetExchangeRate.
parameters	object	(Facoltativo) Parametri di input richiesti dalla funzione, con chiave in base al nome univoco del parametro.
boundTo	object	(Facoltativo) Riferimento di riga di destinazione (entityName e id) per le funzioni associate a entità. Omettere per le funzioni globali (non associate).

Returns

Promessa contenente un oggetto DataverseActionResult. Come con executeAction, questo metodo non genera mai errori previsti. Controllare invece la ok proprietà .

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

Metodo listBoundActions

Elenca le API personalizzate di Dataverse (azioni e funzioni) associate a un autore alla pagina.

Parameters

None.

Returns

Promessa contenente una matrice di voci DataverseActionInfo. Restituisce una matrice vuota quando l'individuazione non è abilitata per il runtime.

DataverseActionInfo

DataverseActionInfo riflette ciò che il creatore della pagina ha associato per questa azione o funzione, non i metadati di Dataverse attivi. Non usarlo per compilare moduli di input o convalidare gli output. Verificare i requisiti dei parametri e le forme di output rispetto alla definizione effettiva dell'API personalizzata di Dataverse.

Name	Type	Description
name	string	Nome univoco (logico) dell'API personalizzata Dataverse.
displayName	string	Nome visualizzato di un'API personalizzata.
isFunction	boolean	true se l'API personalizzata Dataverse è una funzione (sola lettura); false se si tratta di un'azione, incluso quando questo valore non è stato registrato in fase di associazione.
bindingType	string	Tipo di associazione: "Global" o "Entity".
boundEntityLogicalName	string	(Facoltativo) La tabella a cui è associata l'azione o la funzione , quando bindingType è "Entity".
parameters	Object[]	I parametri di input registrati quando l'API personalizzata Dataverse è stata associata alla pagina, ognuna con e namedeclaredKind. typeè sempre e optional non è sempre "unknown"false , né riflette i metadati effettivi dell'API personalizzata dataverse.
outputs	Object[]	Sempre una matrice vuota. L'individuazione dell'associazione non registra i parametri di output.

listBoundActions Esempio

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