用戶端 API Dataverse 記錄、檔案與映像

$pages.webAPI 物件

使用 Power Pages 用戶端 API $pages.webAPI 物件來建立、檢索、更新及刪除 Dataverse 紀錄，並處理儲存在檔案與影像欄位中的內容。

方法 Description
createRecord 在指定的資料表中建立新紀錄。
retrieveRecord 透過唯一識別碼檢索紀錄。
retrieveMultipleRecords 根據提供的查詢選項擷取多筆紀錄。
updateRecord 更新指定資料表中現有的紀錄。
deleteRecord 從指定的表格中刪除記錄。
updateSingleProperty 更新現有紀錄的單一欄位值。
deleteSingleProperty 透過將現有紀錄中的單一欄位設為 null 來清除該欄位的值。
associateRecord 透過使用集合值的導覽屬性，建立兩個紀錄之間的關聯。
disassociateRecord 移除兩筆紀錄之間的關聯。
getRecordCount 回傳指定表格中記錄的總數。
uploadFileToColumn 將檔案或影像上傳至檔案欄位或現有紀錄的影像欄位。
downloadFileFromColumn 下載檔案欄位或現有紀錄影像欄位的二進位內容。

createRecord 方法

在指定的資料表中建立新紀錄。

語法：$pages.webAPI.createRecord(entitySetName: string, data: object): Promise<string>
Returns：一個可解決為所建立紀錄 ID 的 承諾 。

createRecord 方法參數

提供目標資料表及代表該紀錄的資料物件。

參數 類型 Description
entitySetName 字串 實體集的名稱。 了解 Dataverse Web API 中的實體集合名稱
data 物件 要建立紀錄資料。

createRecord 方法範例

此範例示範使用實體集合名稱與最小資料物件的呼叫 createRecord 方式。

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    $pages.webAPI.createRecord('contacts', {
        firstName: 'User',
        lastName: 'Test'
    });
});

retrieveRecord 方法

透過唯一識別碼檢索紀錄。

語法：$pages.webAPI.retrieveRecord(entitySetName: string, id: string, options?: string): Promise<object>
Returns：一個會解析到記錄物件的 承諾 。

retrieveRecord 方法參數

指定表格、記錄 ID 及可選的 OData $select 查詢選項以塑造回應。

參數 類型 Description
entitySetName 字串 實體集的名稱。 了解 Dataverse Web API 中的實體集合名稱。
id 字串 紀錄的唯一識別碼。
options 字串 (選擇性) 可選的 OData $select 查詢字串用來限制回傳的資料。

Note

雖然參數options是可選的，但為了最佳效能，使用該$select選項時必須限制回傳的欄位數值。

retrieveRecord 方法範例

此範例以 ID 檢索單一紀錄，並透過 OData $select 查詢選項限制回傳欄位。

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    let record = await $pages.webAPI.retrieveRecord('accounts', 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',  '$select=name');
});

retrieveMultipleRecords 方法

根據提供的查詢選項擷取多筆紀錄。

語法：$pages.webAPI.retrieveMultipleRecords(entitySetName: string, options?: string): Promise<object>
Returns：一個可解析為 OData 回應物件的 承諾 。 value回應的屬性包含記錄陣列。

retrieveMultipleRecords 方法參數

指定表格及可選的 OData 查詢以篩選結果並限制回傳欄位。

參數 類型 Description
entitySetName 字串 實體集的名稱。
options 字串 (選擇性) 用 OData 查詢選項字串來控制回傳的資料。 了解更多 Dataverse Web API 支援的 OData 查詢選項

Note

雖然參數options是可選的，但為了最佳效能，使用該$select選項時必須限制回傳的欄位數值。

retrieveMultipleRecords 方法範例

此範例可檢索多筆紀錄，並使用 OData $select 並 $top 限制回傳欄位與列數。

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    let response = await $pages.webAPI.retrieveMultipleRecords('accounts', '$select=name&$top=3');
    let records = response.value;
    console.log(`Retrieved ${records.length} records.`);
});

updateRecord 方法

更新指定資料表中現有的紀錄。

語法：$pages.webAPI.updateRecord(entitySetName: string, id: string, data: object): Promise<void>
Returns：當紀錄更新時即解決的 承諾 。

updateRecord 方法參數

指定表格、要更新的記錄，以及要設定的欄位值。

參數 類型 Description
entitySetName 字串 實體集的名稱。
id 字串 記錄的唯一識別碼以更新。
data 物件 欄位和數值需要更新。

updateRecord 方法範例

此範例更新帳戶記錄名稱。

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    await $pages.webAPI.updateRecord('accounts', 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb', { name: 'Updated Name' });
});

deleteRecord 方法

從指定的表格中刪除記錄。

語法：$pages.webAPI.deleteRecord(entitySetName: string, id: string): Promise<void>
Returns：當紀錄被刪除時，承諾會解決。

deleteRecord 方法參數

指定要刪除的資料表和記錄。

參數 類型 Description
entitySetName 字串 實體集的名稱。
id 字串 刪除記錄的唯一識別碼。

deleteRecord 方法範例

這個例子刪除了帳戶紀錄。

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    await $pages.webAPI.deleteRecord('accounts', 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb');
});

updateSingleProperty 方法

更新現有紀錄的單一欄位值。

語法：$pages.webAPI.updateSingleProperty(entitySetName: string, id: string, property: string, value: unknown): Promise<void>
返回：當欄位更新時會解決的 承諾 。

updateSingleProperty 方法參數

指定表格、記錄、要更新的欄位和新值。

參數 類型 Description
entitySetName 字串 實體集的名稱。
id 字串 記錄的唯一識別碼
property 字串 待更新的專欄名稱。
value 未知 欄位的新值。

updateSingleProperty 方法範例

此範例更新帳戶紀錄的名稱欄位。

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    await $pages.webAPI.updateSingleProperty('accounts', 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb', 'name', 'New Name');
});

deleteSingleProperty 方法

透過將現有紀錄中的單一欄位設為 null 來清除該欄位的值。

語法：$pages.webAPI.deleteSingleProperty(entitySetName: string, id: string, property: string): Promise<void>
返回：當欄位值被清除時，承諾會被解析。

deleteSingleProperty 方法的參數

指定要清除的資料表、記錄和欄位。

參數 類型 Description
entitySetName 字串 實體集的名稱。
id 字串 記錄的唯一識別碼
property 字串 要清理的欄位名稱。

deleteSingleProperty 方法範例

此範例會清除帳戶記錄的描述欄。

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    await $pages.webAPI.deleteSingleProperty('accounts', 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb', 'description');
});

associateRecord 方法

透過使用集合值的導覽屬性，建立兩個紀錄之間的關聯。 此方法使用 OData $ref 操作來建立連結。

語法：$pages.webAPI.associateRecord(entitySetName: string, id: string, navigationProperty: string, relatedEntitySetName: string, relatedId: string): Promise<void>
Returns：當紀錄被關聯時，承諾即告解決。

associateRecord 方法參數

先指定父記錄，然後是導航屬性和相關記錄。

參數 類型 Description
entitySetName 字串 該實體將父紀錄的名稱設定在關係的一方。
id 字串 父紀錄的唯一識別碼。
navigationProperty 字串 定義關係的集合值導航屬性名稱。
relatedEntitySetName 字串 該實體在關係的多方上設定了相關紀錄的名稱。
relatedId 字串 關聯紀錄的唯一識別碼。

Important

務必先指定關係一側的父記錄，並使用 entitySetName 與 id 參數。

associateRecord 方法範例

此範例透過導航 contact_association 屬性將聯絡記錄與帳戶記錄關聯起來。

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    await $pages.webAPI.associateRecord(
        'accounts',
        'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
        'contact_association',
        'contacts',
        'cccccccc-0000-1111-2222-dddddddddddd'
    );
});

disassociateRecord 方法

移除兩筆紀錄之間的關聯。

語法：$pages.webAPI.disassociateRecord(entitySetName: string, id: string, navigationProperty: string, relatedEntitySetName: string, relatedId: string): Promise<void>
退貨：當關聯被移除時即會生效的 承諾 。

disassociateRecord 方法參數

先指定父記錄，然後是導航屬性和相關記錄。

參數 類型 Description
entitySetName 字串 該實體將父紀錄的名稱設定在關係的一方。
id 字串 父紀錄的唯一識別碼。
navigationProperty 字串 定義關係的集合值導航屬性名稱。
relatedEntitySetName 字串 該實體設定了相關紀錄的名稱。
relatedId 字串 相關紀錄的唯一識別碼，要解除關聯。

Important

務必先指定關係一側的父記錄，並使用 entitySetName 與 id 參數。

disassociateRecord 方法範例

此範例移除了帳戶紀錄與聯絡記錄之間的關聯。

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    await $pages.webAPI.disassociateRecord(
        'accounts',
        'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
        'contact_association',
        'contacts',
        'cccccccc-0000-1111-2222-dddddddddddd'
    );
});

getRecordCount 方法

回傳指定表格中記錄的總數。 此方法呼叫 OData /$count 端點，回傳整數而非記錄集合。

語法：$pages.webAPI.getRecordCount(entitySetName: string): Promise<number>
退還：一個以記錄數量為結 算的承諾 。

getRecordCount 方法參數

指定要計數紀錄的表格。

參數 類型 Description
entitySetName 字串 實體集的名稱。

Note

伺服器回傳最多 5,000 個。 當一個資料表包含超過 5,000 筆紀錄時，結果為 5,000 筆。 若要連同記錄數量一併檢索，請使用 returnMultipleRecords 方法 搭配 $count=true 查詢選項 。 該方法會回傳回應屬性中的 value 集合，以及該 @odata.count 屬性中的總計數。

getRecordCount 方法範例

此範例回傳帳戶記錄總數。

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    const total = await $pages.webAPI.getRecordCount('accounts');
    console.log(`Total accounts: ${total}`);
});

uploadFileToColumn 方法

將檔案或影像上傳至檔案欄位或現有紀錄的影像欄位。 Dataverse 會儲存二進位內容，並自動更新帶有檔案名稱的欄位。{columnName}_Name

語法：$pages.webAPI.uploadFileToColumn(entitySetName: string, id: string, columnName: string, file: File): Promise<void>
Returns：檔案上傳時即終止的 承諾 。

uploadFileToColumn 方法參數

指定要上傳的資料表、記錄、欄位和檔案。

參數 類型 Description
entitySetName 字串 實體集的名稱。
id 字串 記錄的唯一識別碼
columnName 字串 檔案或影像欄位的邏輯名稱。
file File 要上傳的檔案。

Note

你可以用這個方法來處理圖片欄位。 Dataverse 會移除伺服器上的 EXIF 元資料，並自動產生縮圖。 使用 downloadFileFromColumn 的方法 來下載完整圖片或縮圖。

uploadFileToColumn 方法範例

這個範例是上傳一個檔案，有人透過檔案輸入元素選擇該檔案。

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    const fileInput = document.querySelector('input[type="file"]');

    if (!fileInput || fileInput.files.length === 0) {
        return;
    }

    const file = fileInput.files[0];
    await $pages.webAPI.uploadFileToColumn('accounts', 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb', 'new_attachment', file);
});

downloadFileFromColumn 方法

下載檔案欄位或現有紀錄影像欄位的二進位內容。 大型檔案會以 4 MB 的區塊下載，並自動合併成一個 Blob。

語法：$pages.webAPI.downloadFileFromColumn(entitySetName: string, id: string, columnName: string, options?: object): Promise<Blob>
返回：一個 承諾，解析 為包含二進位資料的 Blob 。 type Blob 的屬性包含伺服器回傳的 MIME 類型。

downloadFileFromColumn 方法參數

指定要下載的資料表、記錄和欄位。

參數 類型 Description
entitySetName 字串 實體集的名稱。
id 字串 記錄的唯一識別碼
columnName 字串 檔案或影像欄位的邏輯名稱。
options 物件（可選） 下載選項。 此 size 屬性適用於圖片欄位，並可 full 下載原始圖片或 thumbnail Dataverse 產生的縮圖。 預設值為 full。

Note

回覆中沒有包含檔案名稱。 要取得檔案名稱，請使用 retrieveRecord 方法 查詢記錄的欄位 {columnName}_Name 。

downloadFileFromColumn 方法範例

此範例從檔案欄位下載檔案，並提示瀏覽器儲存。

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    const blob = await $pages.webAPI.downloadFileFromColumn('accounts', 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb', 'new_attachment');

    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = 'downloaded_file';
    a.click();
    URL.revokeObjectURL(url);
});

此範例是從圖片欄下載完整圖片和縮圖。

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    // Full-resolution image, which is the default.
    const fullBlob = await $pages.webAPI.downloadFileFromColumn('accounts', 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb', 'entityimage');

    // Thumbnail that Dataverse generates.
    const thumbnailBlob = await $pages.webAPI.downloadFileFromColumn(
        'accounts',
        'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
        'entityimage',
        { size: 'thumbnail' }
    );
});
  • 上次更新時間：