生成式頁面的 dataApi 參考

當你 用自然語言產生頁面時，AI 會用 TypeScript 建立一個 React 頁面。 生成的頁面涵蓋前端使用者體驗，透過選擇合適的元件並決定最佳版面配置，以及相應的業務邏輯。

你可以查看並編輯產生的程式碼來精煉輸出。 資料操作使用 dataApi 一個物件，該物件會暴露以下公開方法：

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

createRow 方法

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

參數

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

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

退貨

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

Example

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

updateRow 方法

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

參數

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

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

退貨

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

Example

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

deleteRow 方法

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

參數

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

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

退貨

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

Example

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

retrieveRow 方法

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

參數

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

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

RetrieveRowOptions

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

退貨

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

Example

// 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'],
});

queryTable 方法

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

參數

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

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

QueryTableOptions

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

退貨

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

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

Example

// 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`);
}

備註

備註

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

getChoices 方法

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

參數

這是必要參數。

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

退貨

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

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

Example

// 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');