生成页的 Dataverse 操作和函数方法

使用对象的操作和函数方法 dataApi 调用绑定到页面的 Dataverse 自定义 API 。

注释

操作和函数方法在共享 dataApi 协定中是可选的。 某些主机未实现它们，因此请在调用方法之前检查是否存在方法。 存在的方法并不意味着操作绑定到页面、为运行时启用或当前用户允许的操作。 与连接器方法不同，这些方法永远不会针对预期故障引发;它们改用 ok: false 和错误代码解决。 显式处理结果 ok 和 error 属性。

listBoundActions 返回当前运行时配置允许在该发现启用时的页面的操作和函数;它不能保证当前用户持有执行每个列出的操作所需的 Dataverse 权限。

方法	Description
executeAction	以操作的形式调用绑定到页面的 Dataverse 自定义 API。
executeFunction	以函数的形式调用绑定到页面的 Dataverse 自定义 API。
listBoundActions	列出绑定到页面的 Dataverse 自定义 API（操作和函数）。

executeAction 方法

调用一个 Dataverse 自定义 API，使创建者作为操作绑定到页面（可能会更改数据的消息）。

Parameters

设置此必需参数的值。

Name	类型	Description
request	DataverseActionRequest	要调用的操作及其输入参数。

DataverseActionRequest

Name	类型	Description
name	string	自定义 API 的唯一名称，以发布者为前缀，例如 new_ApproveExpenseReport。
parameters	object	（可选）操作所需的输入参数，按参数唯一名称键键。
boundTo	object	（可选）实体绑定操作的目标行引用 （entityName 和 id） 。 对于全局（未绑定）操作，请省略。

Returns

包含 DataverseActionResult的承诺。 此方法永远不会引发预期失败（例如 403 权限错误、400 错误参数或未绑定或启用操作）- 请改为检查 ok 属性。

DataverseActionResult

Name	类型	Description
ok	boolean	指示操作是否成功。
status	number	Dataverse 返回的 HTTP 状态代码，或者 0 当没有 HTTP 状态可用时。 0状态可能意味着运行时在发送调用之前拒绝了调用（例如，、not_enabled、not_boundnot_permitted、invalid_parameterwrong_operation_kind或invalid_bound_to），请求在没有 HTTP 响应的情况下失败，或者结果未知（indeterminate是true）。 使用 error.code 和 indeterminate 区分这些情况。
outputs	object	操作返回的输出参数，按唯一名称键键。 对于没有输出的操作，为空。
indeterminate	boolean	（可选） true 当超时或其他调度后失败意味着服务器可能已提交操作;不要自动重试。
error	object	（可选）错误详细信息（okfalse包括计算机可code读和清理message）。 code not_enabled invalid_parameter invalid_bound_to network wrong_operation_kind not_permitted indeterminate not_bound是 Dataverse 返回错误响应或没有 HTTP 状态时作为字符串（例如），或"0"操作的 HTTP 状态代码之一（例如"404"）之一。 not_permitted 表示操作或函数不在环境的生成页面允许列表中 ， 它不指示当前用户是否持有 Dataverse 权限来运行它。 特权失败通常显示为 status: 403 错误代码 "403";如果主机无法确定 HTTP 状态，它将返回 status: 0 。

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 方法

调用一个 Dataverse 自定义 API，该 API 由创建者作为函数绑定到页面（具有 GET 语义的只读消息）。

Parameters

设置此必需参数的值。

Name	类型	Description
request	DataverseFunctionRequest	要调用的函数及其输入参数。

DataverseFunctionRequest

Name	类型	Description
name	string	自定义 API 的唯一名称，以发布者为前缀，例如 new_GetExchangeRate。
parameters	object	（可选）函数所需的输入参数，按参数唯一名称键键。
boundTo	object	（可选）实体绑定函数的目标行引用 （entityName 和 id） 。 对于全局（未绑定）函数，请省略。

Returns

包含 DataverseActionResult的承诺。 与上述 executeAction方法一样，此方法永远不会针对预期失败引发 — 请改为检查 ok 属性。

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 方法

列出创建者绑定到页面的 Dataverse 自定义 API（操作和函数）。

Parameters

None.

Returns

包含 DataverseActionInfo 条目数组的 promise。 如果未为运行时启用发现，则返回空数组。

DataverseActionInfo

DataverseActionInfo 反映页面的创建者为此操作或函数绑定的内容，而不是实时 Dataverse 元数据。 不要使用它来生成输入窗体或验证输出 — 根据实际的 Dataverse 自定义 API 定义验证参数要求和输出形状。

Name	类型	Description
name	string	Dataverse 自定义 API 的唯一（逻辑）名称。
displayName	string	自定义 API 的显示名称。
isFunction	boolean	true 如果 Dataverse 自定义 API 是函数（只读）; false 如果它是一个操作，则包括绑定时未记录此值的时间。
bindingType	string	绑定类型： "Global" 或 "Entity"。
boundEntityLogicalName	string	（可选）操作或函数绑定到的表（何时bindingType"Entity"为 .
parameters	Object[]	当 Dataverse 自定义 API 绑定到页面时记录的输入参数，每个参数都有一个 name 和 declaredKind。 type始终且optional始终"unknown"false 是 - 既不反映 Dataverse 自定义 API 的实际元数据。
outputs	Object[]	始终为空数组。 绑定发现不会记录输出参数。

listBoundActions 示例

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