Dataverse 生成頁面的表格方法

使用物件的 dataApi 表格方法來建立、檢索、更新及刪除 Dataverse 的資料表列與查詢選擇欄位。

方法	Description
createRow	在指定的資料表中建立一列新資料。
deleteRow	刪除指定資料表中的一列。
getChoices	取得指定選擇欄位名稱的選擇。
queryTable	查詢具有指定選項的表格。
retrieveRow	從指定資料表中取得一列，並取得指定選項。
updateRow	更新指定資料表中現有的一列。

createRow 方法

在指定的資料表中建立一列新資料。

Parameters

為這些所需參數設定數值。

Name	類型	Description
tableName	字串	建立該列的表格邏輯名稱。
row	物件	建立列資料。

Returns

一個包含操作結果的 承諾 。 當操作成功時，結果即為所建立列的 ID（Guid）值。

createRow 範例

// Define the row data to create new account
var row =
    {
        "name": "Sample Account",
        "creditonhold": false,
        "address1_latitude": 47.639583,
        "description": "This is the description of the sample account",
        "revenue": 5000000,
        "accountcategorycode": 1,
    }

try {
  // Create a new account record
  const newAccountId = await dataApi.createRow("account", row);
  console.log("Account created with ID: " + newAccountId);

  // Create a contact with a lookup to an account
  const newContactId = await dataApi.createRow('contact', {
    firstname: 'John',
    lastname: 'Doe',
    emailaddress1: 'john.doe@contoso.com',
    "parentcustomerid@odata.bind": `/account(${newAccountId})`, // Lookup format
  });
}
catch (error) {
  console.log(error.message);
}

deleteRow 方法

刪除指定資料表中的一列。

Parameters

為這些所需參數設定數值。

Name	類型	Description
tableName	字串	刪除該列的表格邏輯名稱。
rowId	字串	要刪除的列的 ID。

Returns

一個包含操作結果的 承諾 。 當操作成功時，則不會回傳任何值。

deleteRow 範例

let rowId = "5531d753-95af-e711-a94e-000d3a11e605";
try {
  await dataApi.deleteRow("account", rowId);
}
catch (error) {
  console.log(error.message);
}

getChoices 方法

取得指定選擇欄位名稱的選擇。

Parameters

此為必要參數。

Name	類型	Description
enumName	string	格式中選擇欄的名稱 tablename-columnname

Returns

一個包含操作結果的 承諾 。 當操作成功時，會回傳一個選項陣列。 每個選項具有以下特性：

Name	類型	Description
label	字串	選擇權的在地標籤價值。
value	number	選擇權的數值。

getChoices 範例

// Returns the accountcategorycode column options from the account table
const categoryChoices = await dataApi.getChoices("account-accountcategorycode");
// Returns the statecode column options from the contact table
const stateChoices = await dataApi.getChoices('contact-statecode');
// Returns the statuscode column options from the account table
const statusChoices = await dataApi.getChoices('account-statuscode');

queryTable 方法

透過使用指定的選項查詢資料表。

Parameters

為這些所需參數設定數值。

Name	類型	Description
tableName	string	查詢表的邏輯名稱
query	QueryTableOptions	查詢表格的選項

QueryTableOptions

Name	類型	Description
select	string[]	（推薦）一組欄位名稱陣列，需取回。
filter	string	（可選）OData 濾波器表達式（例如 statecode eq 0）。
orderBy	string	（可選）OData 的階數表達式（例如 name asc， ， createdon desc）。
pageSize	number	（可選）每頁最多可返回的列數。

Returns

一個包含操作結果的 承諾 。 當操作成功時，承諾會回傳一個包含資料表的物件，結果具有以下屬性：

Name	類型	Description
rows	Object[]	列資料陣列
hasMoreRows	boolean	表示是否有更多可用列
loadMoreRows	function	功能載入下一頁結果。 (選擇性)

queryTable 範例

// Query tasks with options
const result = await dataApi.queryTable("task", {
    select: ["activityid", "subject", "scheduledend", "prioritycode", "statecode"],
    orderBy: "scheduledend asc",
    pageSize: 50,
    filter: "statecode eq 0"
});

// Query accounts with pagination
const pagedAccounts = await dataApi.queryTable('account', {
  select: ['name'],
  pageSize: 50,
});

console.log(`Page 1: ${pagedAccounts.rows.length} accounts`);

if (pagedAccounts.hasMoreRows && pagedAccounts.loadMoreRows) {
  const nextPage = await pagedAccounts.loadMoreRows();
  console.log(`Page 2: ${nextPage.rows.length} accounts`);
}

Remarks

備註

為了達到最佳效能，請始終使用 QueryTableOptionsselect 屬性限制回傳欄位數量。

retrieveRow 方法

利用指定的選項從指定資料表中取得一列。

Parameters

為這些所需參數設定數值。

Name	類型	Description
tableName	string	要從 取回的表格邏輯名稱
options	RetrieveRowOptions	取回該列的選項

RetrieveRowOptions

Name	類型	Description
id	string	要取回的列的 ID（Guid）
select	string[]	（推薦）一組欄位名稱陣列，需取回。 如果省略，則會傳回所有資料行。

Returns

一個包含操作結果的 承諾 。 當操作成功時，會回傳一個包含記錄資料的物件，包含所有被選取的欄位。

retrieveRow 範例

// Retrieve an account with all columns
const account = await dataApi.retrieveRow('account', {
  id: '30dc51e9-947d-47d8-ad48-4fc48fba4a95',
});

// Retrieve specific columns only
const contact = await dataApi.retrieveRow('contact', {
  id: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  select: ['firstname', 'lastname', '_parentcustomerid_value'],
});

updateRow 方法

更新指定資料表中現有的一列。

Parameters

為這些所需參數設定數值。

Name	類型	Description
tableName	字串	更新該資料列的表格邏輯名稱。
rowId	字串	要更新的列ID。
row	物件	要更新資料列。

Returns

一個包含操作結果的 承諾 。 當操作成功時，則不會回傳任何值。

updateRow 範例

let rowId = "5531d753-95af-e711-a94e-000d3a11e605"

// Define the row to update a record
var row =
    {
        "name": "Updated Sample Account ",
        "creditonhold": true,
        "address1_latitude": 47.639583,
        "description": "This is the updated description of the sample account",
        "revenue": 6000000,
        "accountcategorycode": 2
    }

// update the record

try {
   await dataApi.updateRow("account", rowId, row);
}
catch (error){
  console.log(error.message);
}