生成頁面的資料宇宙動作與功能方法

使用物件的 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 的唯一名稱，前綴為 publisher，例如 new_ApproveExpenseReport。
parameters	object	（可選）動作所需的輸入參數，並以唯一參數名稱作為鍵。
boundTo	object	（可選）一個用於實體綁定動作的目標列參考（entityNameid和 ）。 全域（未綁定）動作則省略。

Returns

一個包含 DataverseActionResult 的承諾。 此方法絕不會拋出預期失敗（例如 403 權限錯誤、400 錯誤參數，或操作未綁定或未啟用）——請檢查該 ok 屬性。

資料逆行動結果

Name	類型	Description
ok	boolean	表示行動是否成功。
status	number	Dataverse 回傳的 HTTP 狀態碼，或 0 在沒有 HTTP 狀態可用時。 0狀態可能表示執行時在發送呼叫前拒絕了該呼叫（例如，not_enabled， not_bound， wrong_operation_kindinvalid_parameternot_permitted或invalid_bound_to），請求在沒有 HTTP 回應的情況下失敗，或結果未知（indeterminate為 ）。true 使用 error.code 並 indeterminate 區分這些案例。
outputs	object	動作回傳的輸出參數，並以唯一名稱鍵結。 空的表示沒有輸出的行動。
indeterminate	boolean	（可選） true 當逾時或其他派遣後失敗表示伺服器可能已提交該動作時;不要自動重試。
error	object	（可選）當 ok 為 時 false，錯誤詳細說明，包括機讀 code 與淨化 message。 code是 not_enabled、 not_bound、 invalid_parameterindeterminateinvalid_bound_tonot_permittedwrong_operation_kind或 network，或是動作的 HTTP 狀態碼（例如 "404"），當 Dataverse 回傳錯誤回應或"0"沒有 HTTP 狀態時，會以字串形式呈現。 not_permitted 表示該動作或函式不在環境的生成頁面允許清單中——它不會顯示目前使用者是否擁有 Dataverse 執行權限。 權限失敗通常會像錯誤代碼"403"一樣出現status: 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，創作者將其綁定為函式（一個唯讀訊息，帶有 GET 語意）。

Parameters

為這個所需參數設定一個值。

Name	類型	Description
request	DataverseFunctionRequest	調用函式及其輸入參數。

DataverseFunctionRequest

Name	類型	Description
name	string	自訂 API 的唯一名稱，前綴為 publisher，例如 new_GetExchangeRate。
parameters	object	（可選）函式所需的輸入參數，並以唯一參數名稱作為鍵。
boundTo	object	（可選）實體綁定函數的目標列參考（entityNameid和 ）。 全域（未綁定）函數則省略。

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 條目陣列的承諾。 當執行時未啟用發現，會回傳一個空陣列。

資料行動資訊

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 綁定到頁面時，輸入參數記錄，每個參數都帶有 a name 和 declaredKind。 type總是且"unknown"optional總是——false兩者都不反映 Dataverse 自訂 API 的實際元資料。
outputs	Object[]	總是空的陣列。 綁定發現不會記錄輸出參數。

listBoundActions 範例

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