客户端 API Dataverse 记录、文件和图像

$pages.webAPI 对象

使用 Power Pages 客户端 API $pages.webAPI 对象创建、检索、更新和删除 Dataverse 记录，以及处理存储在文件和图像列中的内容。

方法	说明
`createRecord`	在指定的表中创建新记录。
`retrieveRecord`	按记录的唯一标识符检索记录。
`retrieveMultipleRecords`	基于提供的查询选项检索多个记录。
`updateRecord`	更新指定表中的现有记录。
`deleteRecord`	从指定表中删除记录。
`updateSingleProperty`	更新现有记录的单个列值。
`deleteSingleProperty`	通过将单个列设置为 null，清除现有记录中的单个列的值。
`associateRecord`	使用集合值导航属性在两个记录之间创建关联。
`disassociateRecord`	删除两条记录之间的关联。
`getRecordCount`	返回指定表中的记录总数。
`uploadFileToColumn`	将文件或图像上传到现有记录的文件列或图像列。
`downloadFileFromColumn`	下载文件列的二进制内容或现有记录的图像列。

createRecord 方法

在指定的表中创建新记录。

语法：$pages.webAPI.createRecord(entitySetName: string, data: object): Promise<string>
返回：解析为所创建记录的 ID 的 Promise 。

createRecord 方法参数

提供表示要创建的记录的目标表和数据对象。

Parameter	类型	说明
`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>
返回：解析为记录对象的 Promise 。

retrieveRecord 方法参数

指定表、记录 ID 和可选的 OData $select 查询选项以调整响应。

Parameter	类型	说明
`entitySetName`	字符串	实体集的名称。了解 Dataverse Web API 中的实体集名称。
`id`	字符串	记录的唯一标识符。
`options`	字符串（可选）	可选的 OData `$select` 查询字符串，用于限制返回的数据。

注释

虽然参数 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>
返回：解析为 OData 响应对象的 Promise 。响应 value 的属性包含记录数组。

retrieveMultipleRecords 方法参数

指定表和可选的 OData 查询以筛选结果并限制返回的列。

Parameter	类型	说明
`entitySetName`	字符串	实体集的名称。
`options`	字符串（可选）	用于控制返回数据的 OData 查询选项字符串。详细了解 Dataverse Web API 支持的 OData 查询选项

注释

虽然参数 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>
返回：更新记录时解析的 Promise 。

updateRecord 方法参数

指定要更新的表、要更新的记录以及要设置的列值。

Parameter	类型	说明
`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>
返回：在删除记录时解析的 Promise 。

deleteRecord 方法参数

指定要删除的表和记录。

Parameter	类型	说明
`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>
返回：更新列时解析的 Promise 。

updateSingleProperty 方法参数

指定要更新的表、记录、列以及新值。

Parameter	类型	说明
`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>
返回：清除列值时解析的 Promise 。

deleteSingleProperty 方法参数

指定要清除的表、记录和列。

Parameter	类型	说明
`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>
返回：一个承诺，用于解析与记录关联的时间。

associateRecord 方法参数

首先指定父记录，然后指定导航属性和相关记录。

Parameter	类型	说明
`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>
返回：删除关联时解析的 Promise 。

disassociateRecord 方法参数

首先指定父记录，然后指定导航属性和相关记录。

Parameter	类型	说明
`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>
返回：解析为记录数的 Promise 。

getRecordCount 方法参数

指定要在其中对记录进行计数的表。

Parameter	类型	说明
`entitySetName`	字符串	实体集的名称。

注释

服务器返回的最大计数为 5,000。当表包含超过 5,000 条记录时，结果为 5,000。若要将记录及其总计数一起检索，请改用带有查询选项的$count=trueretrieveMultipleRecords 方法。该方法返回响应属性中的 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>
返回：上传文件时解析的 Promise 。

uploadFileToColumn 方法参数

指定要上传的表、记录、列和文件。

Parameter	类型	说明
`entitySetName`	字符串	实体集的名称。
`id`	字符串	记录的唯一标识符。
`columnName`	字符串	文件或图像列的逻辑名称。
`file`	文件	要上传的文件。

注释

可以将此方法用于图像列。 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 方法参数

指定要从中下载的表、记录和列。

Parameter	类型	说明
`entitySetName`	字符串	实体集的名称。
`id`	字符串	记录的唯一标识符。
`columnName`	字符串	文件或图像列的逻辑名称。
`options`	对象（可选）	下载的选项。该 `size` 属性适用于图像列，并接受 `full` 下载原始图像或 `thumbnail` 下载 Dataverse 生成的缩略图。默认值为 `full`。

注释

响应不包括文件名。若要获取文件名，请使用 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' }
    );
});

反馈

此页面是否有帮助？

上次更新时间为 2026-09-21