Métodos de ação e função do dataverse para páginas generativas

Use os métodos de ação e função do dataApi objeto para invocar APIs personalizadas do Dataverse associadas à página.

Observação

Os métodos de ação e função são opcionais no contrato compartilhado dataApi . Alguns hosts não os implementam, portanto, verifique se existe um método antes de chamá-lo. Um método presente não significa que a operação esteja associada à página, habilitada para o runtime ou permitida para o usuário atual. Ao contrário dos métodos de conector, esses métodos nunca são gerados para falhas esperadas; eles resolvem com ok: false e um código de erro em vez disso. Manipule as propriedades e error o ok resultado explicitamente.

listBoundActions retorna as ações e funções que a configuração de runtime atual permite para a página quando essa descoberta está habilitada; não é uma garantia de que o usuário atual detém os privilégios do Dataverse necessários para executar todas as operações listadas.

Método	Description
executeAction	Invoca uma API personalizada do Dataverse associada à página como uma ação.
executeFunction	Invoca uma API personalizada do Dataverse associada à página como uma função.
listBoundActions	Lista as APIs personalizadas do Dataverse (ações e funções) associadas à página.

método executeAction

Invoca uma API personalizada do Dataverse que um criador vinculou à página como uma ação (uma mensagem que pode alterar os dados).

Parameters

Defina um valor para esse parâmetro necessário.

Name	Tipo	Description
request	DataverseActionRequest	A ação a ser invocada e seus parâmetros de entrada.

DataverseActionRequest

Name	Tipo	Description
name	string	O nome exclusivo da API personalizada, prefixado pelo editor, como new_ApproveExpenseReport.
parameters	object	(Opcional) Os parâmetros de entrada exigidos pela ação, chaveados pelo nome exclusivo do parâmetro.
boundTo	object	(Opcional) Uma referência de linha de destino (entityName e id) para ações associadas à entidade. Omita para ações globais (desvinculadas).

Returns

Uma promessa que contém um DataverseActionResult. Esse método nunca gera falhas esperadas (como um erro de permissão 403, um parâmetro 400 inválido ou a operação não está sendo associada ou habilitada) — verifique a ok propriedade em vez disso.

DataverseActionResult

Name	Tipo	Description
ok	boolean	Indica se a ação foi bem-sucedida.
status	number	O código de status HTTP retornado pelo Dataverse ou 0 quando nenhum status HTTP está disponível. Um 0 status pode significar que o runtime rejeitou a chamada antes de enviá-la (por exemplo, not_enabled, not_bound, not_permitted, , wrong_operation_kindinvalid_parameterou invalid_bound_to), a solicitação falhou sem uma resposta HTTP ou o resultado é desconhecido (indeterminate étrue). Use error.code e indeterminate para diferenciar esses casos.
outputs	object	Os parâmetros de saída retornados pela ação, chaveados pelo nome exclusivo. Vazio para ações sem saídas.
indeterminate	boolean	(Opcional) true quando um tempo limite ou outra falha pós-expedição significa que o servidor pode ter confirmado a ação; não tente novamente automaticamente.
error	object	(Opcional) Detalhes do erro quando ok estiver false, incluindo um computador legível code e um sanitizado message. codeé um dos códigos de status HTTP da ação como uma cadeia de not_enabledinvalid_parameterinvalid_bound_tonetworkwrong_operation_kindnot_permittedindeterminatenot_boundcaracteres (por exemplo, "404") quando o Dataverse retornou uma resposta de erro ou "0" quando nenhum status HTTP estava disponível. not_permitted significa que a ação ou função não está na lista de permissões do ambiente para páginas gerativas. Isso não indica se o usuário atual detém os privilégios do Dataverse para executá-lo. Uma falha de privilégio normalmente aparece como status: 403 com o código "403"de erro; se o host não puder determinar o status HTTP, ele retornará status: 0 .

exemplo 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 uma API personalizada do Dataverse associada à página como uma função (uma mensagem somente leitura com semântica GET).

Parameters

Defina um valor para esse parâmetro necessário.

Name	Tipo	Description
request	DataverseFunctionRequest	A função a ser invocada e seus parâmetros de entrada.

DataverseFunctionRequest

Name	Tipo	Description
name	string	O nome exclusivo da API personalizada, prefixado pelo editor, como new_GetExchangeRate.
parameters	object	(Opcional) Os parâmetros de entrada exigidos pela função, chaveados pelo nome exclusivo do parâmetro.
boundTo	object	(Opcional) Uma referência de linha de destino (entityName e id) para funções associadas à entidade. Omita para funções globais (não associados).

Returns

Uma promessa que contém um DataverseActionResult. Assim como acontece, executeActionesse método nunca é gerado para falhas esperadas – verifique a ok propriedade em vez disso.

exemplo de 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

Lista as APIs personalizadas do Dataverse (ações e funções) que um criador vinculou à página.

Parameters

None.

Returns

Uma promessa que contém uma matriz de entradas DataverseActionInfo . Retorna uma matriz vazia quando a descoberta não está habilitada para o runtime.

DataverseActionInfo

DataverseActionInfo reflete o que o criador da página vinculou a essa ação ou função, não metadados dinâmicos do Dataverse. Não use-o para criar formulários de entrada ou validar saídas – verifique os requisitos de parâmetro e as formas de saída em relação à definição real da API personalizada do Dataverse.

Name	Tipo	Description
name	string	O nome exclusivo (lógico) da API personalizada do Dataverse.
displayName	string	O nome de exibição de uma API personalizada.
isFunction	boolean	true se a API personalizada do Dataverse for uma função (somente leitura); false se for uma ação, inclusive quando esse valor não foi registrado no momento da associação.
bindingType	string	O tipo de associação: "Global" ou "Entity".
boundEntityLogicalName	string	(Opcional) A tabela à qual a ação ou função está associada, quando bindingType é "Entity".
parameters	Object[]	Os parâmetros de entrada registrados quando a API personalizada do Dataverse foi associada à página, cada um com um name e declaredKind. type é sempre "unknown" e optional é sempre false — nem reflete os metadados reais da API personalizada do Dataverse.
outputs	Object[]	Sempre uma matriz vazia. A descoberta de associação não registra parâmetros de saída.

listBoundActions exemplo

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