Client API Dataverse records, files, and images (preview)

[Bài viết này là tài liệu trước khi phát hành và có thể thay đổi.]

Quan trọng

  • Đây là một tính năng xem trước.
  • Các tính năng xem trước không được dùng cho sản xuất và có thể có chức năng bị hạn chế. Các tính năng này tuân theo các điều khoản sử dụng bổ sung và có sẵn trước khi phát hành chính thức để khách hàng có thể truy cập sớm và cung cấp phản hồi.

$pages.webAPI

Sử dụng đối Power Pages API Client để $pages.webAPI tạo, truy xuất, cập nhật và xóa các bản ghi Dataverse và để làm việc với nội dung được lưu trữ trong các cột tệp và hình ảnh.

Phương pháp Mô tả
createRecord Tạo bản ghi mới trong bảng đã xác định.
retrieveRecord Truy xuất bản ghi theo mã định danh duy nhất của nó.
retrieveMultipleRecords Truy xuất nhiều bản ghi dựa trên các tùy chọn truy vấn được cung cấp.
updateRecord Cập nhật bản ghi hiện có trong bảng đã xác định.
deleteRecord Xóa bỏ bản ghi khỏi bảng đã xác định.
updateSingleProperty Cập nhật giá trị cột đơn của bản ghi hiện có.
deleteSingleProperty Xóa giá trị của một cột đơn trong bản ghi hiện có bằng cách đặt nó thành null.
associateRecord Tạo liên kết giữa hai bản ghi bằng cách sử dụng thuộc tính dẫn hướng có giá trị bộ sưu tập.
disassociateRecord Loại bỏ liên kết giữa hai bản ghi.
getRecordCount Trả về tổng số bản ghi trong bảng đã xác định.
uploadFileToColumn Tải tệp hoặc hình ảnh lên cột tệp hoặc cột hình ảnh của bản ghi hiện có.
downloadFileFromColumn Tải xuống nội dung nhị phân của cột tệp hoặc cột hình ảnh của bản ghi hiện có.

phương pháp createRecord

Tạo bản ghi mới trong bảng đã xác định.

Cú pháp: $pages.webAPI.createRecord(entitySetName: string, data: object): Promise<string>
Trả về: Một Promise giải quyết id của bản ghi đã tạo.

tham số phương pháp createRecord

Cung cấp bảng đích và đối tượng dữ liệu đại diện cho bản ghi cần tạo.

Tham số Type Mô tả
entitySetName chuỗi Tên của bộ thực thể. Tìm hiểu về tên bộ thực thể trong API Web Dataverse
data đối tượng Dữ liệu bản ghi cần tạo.

ví dụ về phương pháp createRecord

Ví dụ này minh họa việc gọi createRecord với tên tập hợp thực thể và đối tượng dữ liệu tối thiểu.

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

phương pháp retrieveRecord

Truy xuất bản ghi theo mã định danh duy nhất của nó.

Cú pháp: $pages.webAPI.retrieveRecord(entitySetName: string, id: string, options?: string): Promise<object>
Trả về: Một Promise giải quyết đối với đối tượng bản ghi.

tham số phương pháp retrieveRecord

Xác định bảng, ID bản ghi và tùy chọn truy vấn OData $select tùy chọn để định hình phản hồi.

Tham số Type Mô tả
entitySetName chuỗi Tên của bộ thực thể. Tìm hiểu về tên bộ thực thể trong API Web Dataverse.
id chuỗi Mã định danh duy nhất của bản ghi.
options chuỗi (tùy chọn) Chuỗi truy vấn OData tùy $select chọn để giới hạn dữ liệu được trả về.

Lưu ý

Mặc dù tham options số là tùy chọn nhưng để có hiệu suất tốt nhất luôn giới hạn số lượng giá trị cột được trả về bằng cách sử dụng tùy $select chọn này.

ví dụ về phương pháp retrieveRecord

Ví dụ này truy xuất một bản ghi đơn theo ID và giới hạn các cột được trả về bằng cách sử dụng tùy chọn truy vấn OData $select .

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

phương pháp retrieveMultipleRecords

Truy xuất nhiều bản ghi dựa trên các tùy chọn truy vấn được cung cấp.

Cú pháp: $pages.webAPI.retrieveMultipleRecords(entitySetName: string, options?: string): Promise<object>
Trả về: Một Promise giải quyết đối tượng phản hồi OData. Thuộc value tính của phản hồi chứa mảng bản ghi.

tham số phương pháp retrieveMultipleRecords

Xác định bảng và truy vấn OData tùy chọn để lọc kết quả và giới hạn cột trả về.

Tham số Type Mô tả
entitySetName chuỗi Tên của bộ thực thể.
options chuỗi (tùy chọn) Chuỗi tùy chọn truy vấn OData để điều khiển dữ liệu được trả về. Tìm hiểu thêm về các tùy chọn truy vấn OData được API Web Dataverse hỗ trợ

Lưu ý

Mặc dù tham options số là tùy chọn nhưng để có hiệu suất tốt nhất luôn giới hạn số lượng giá trị cột được trả về bằng cách sử dụng tùy $select chọn này.

ví dụ về phương pháp retrieveMultipleRecords

Ví dụ này truy xuất nhiều bản ghi và sử dụng OData cũng như $select để giới $top hạn số cột và số hàng được trả về.

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

phương pháp updateRecord

Cập nhật bản ghi hiện có trong bảng đã xác định.

Cú pháp: $pages.webAPI.updateRecord(entitySetName: string, id: string, data: object): Promise<void>
Trả về: Một Promise giải quyết khi cập nhật bản ghi.

tham số phương pháp updateRecord

Xác định bảng, bản ghi cần cập nhật và các giá trị cột cần thiết lập.

Tham số Type Mô tả
entitySetName chuỗi Tên của bộ thực thể.
id chuỗi Mã định danh duy nhất của bản ghi cần cập nhật.
data đối tượng Các cột và giá trị cần cập nhật.

ví dụ về phương pháp updateRecord

Ví dụ này sẽ cập nhật tên của hồ sơ tài khoản.

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

phương pháp deleteRecord

Xóa bỏ bản ghi khỏi bảng đã xác định.

Cú pháp: $pages.webAPI.deleteRecord(entitySetName: string, id: string): Promise<void>
Trả về: Một Promise giải quyết khi bản ghi bị xóa.

tham số phương pháp deleteRecord

Xác định bảng và bản ghi cần xóa.

Tham số Type Mô tả
entitySetName chuỗi Tên của bộ thực thể.
id chuỗi Mã định danh duy nhất của bản ghi cần xóa.

ví dụ về phương pháp deleteRecord

Ví dụ này sẽ xóa một bản ghi tài khoản.

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

phương pháp updateSingleProperty

Cập nhật giá trị cột đơn của bản ghi hiện có.

Cú pháp: $pages.webAPI.updateSingleProperty(entitySetName: string, id: string, property: string, value: unknown): Promise<void>
Trả về: Hàm Promise giải quyết khi cập nhật cột.

các tham số phương pháp updateSingleProperty

Xác định bảng, bản ghi, cột cần cập nhật và giá trị mới.

Tham số Type Mô tả
entitySetName chuỗi Tên của bộ thực thể.
id chuỗi Mã định danh duy nhất của bản ghi.
property chuỗi Tên của cột cần cập nhật.
value không xác định Giá trị mới cho cột.

ví dụ về phương pháp updateSingleProperty

Ví dụ này sẽ cập nhật cột tên của bản ghi tài khoản.

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

phương pháp deleteSingleProperty

Xóa giá trị của một cột đơn trong bản ghi hiện có bằng cách đặt nó thành null.

Cú pháp: $pages.webAPI.deleteSingleProperty(entitySetName: string, id: string, property: string): Promise<void>
Trả về: Hàm Promise giải quyết khi giá trị cột bị xóa.

deleteSingleProperty method parameters

Xác định bảng, bản ghi và cột cần xóa.

Tham số Type Mô tả
entitySetName chuỗi Tên của bộ thực thể.
id chuỗi Mã định danh duy nhất của bản ghi.
property chuỗi Tên của cột cần xóa.

ví dụ về phương pháp deleteSingleProperty

Ví dụ này sẽ xóa cột mô tả của bản ghi tài khoản.

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

phương pháp associateRecord

Tạo liên kết giữa hai bản ghi bằng cách sử dụng thuộc tính dẫn hướng có giá trị bộ sưu tập. Phương pháp này sử dụng thao tác OData $ref để tạo nối kết.

Cú pháp: $pages.webAPI.associateRecord(entitySetName: string, id: string, navigationProperty: string, relatedEntitySetName: string, relatedId: string): Promise<void>
Trả về: Một Promise giải quyết khi các bản ghi được liên kết.

tham số phương pháp associateRecord

Trước tiên hãy xác định bản ghi mẹ, sau đó là thuộc tính dẫn hướng và bản ghi liên quan.

Tham số Type Mô tả
entitySetName chuỗi Tên bộ thực thể của bản ghi mẹ ở một bên của mối quan hệ.
id chuỗi Mã định danh duy nhất của bản ghi mẹ.
navigationProperty chuỗi Tên của thuộc tính dẫn hướng có giá trị bộ sưu tập xác định mối quan hệ.
relatedEntitySetName chuỗi Tên bộ thực thể của bản ghi liên quan ở phía nhiều của mối quan hệ.
relatedId chuỗi Mã định danh duy nhất của bản ghi liên quan cần liên kết.

Quan trọng

Luôn xác định bản ghi mẹ ở một bên của mối quan hệ trước tiên, bằng cách sử dụng các entitySetName tham id số và.

ví dụ về phương pháp associateRecord

Ví dụ này liên kết một bản ghi liên hệ với một bản ghi tài khoản bằng cách sử dụng thuộc contact_association tính dẫn hướng.

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

phương pháp disassociateRecord

Loại bỏ liên kết giữa hai bản ghi.

Cú pháp: $pages.webAPI.disassociateRecord(entitySetName: string, id: string, navigationProperty: string, relatedEntitySetName: string, relatedId: string): Promise<void>
Trả về: Một Promise giải quyết khi liên kết bị loại bỏ.

tham số phương pháp disassociateRecord

Trước tiên hãy xác định bản ghi mẹ, sau đó là thuộc tính dẫn hướng và bản ghi liên quan.

Tham số Type Mô tả
entitySetName chuỗi Tên bộ thực thể của bản ghi mẹ ở một bên của mối quan hệ.
id chuỗi Mã định danh duy nhất của bản ghi mẹ.
navigationProperty chuỗi Tên của thuộc tính dẫn hướng có giá trị bộ sưu tập xác định mối quan hệ.
relatedEntitySetName chuỗi Tên bộ thực thể của bản ghi liên quan.
relatedId chuỗi Mã định danh duy nhất của bản ghi liên quan cần hủy liên kết.

Quan trọng

Luôn xác định bản ghi mẹ ở một bên của mối quan hệ trước tiên, bằng cách sử dụng các entitySetName tham id số và.

ví dụ về phương pháp disassociateRecord

Ví dụ này loại bỏ liên kết giữa bản ghi tài khoản và bản ghi liên hệ.

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

phương pháp getRecordCount

Trả về tổng số bản ghi trong bảng đã xác định. Phương pháp này gọi điểm cuối OData /$count , trả về một số nguyên thay vì một tập hợp các bản ghi.

Cú pháp: $pages.webAPI.getRecordCount(entitySetName: string): Promise<number>
Trả về: Một Promise giải quyết cho số lượng bản ghi.

tham số phương pháp getRecordCount

Xác định bảng để đếm số bản ghi trong đó.

Tham số Type Mô tả
entitySetName chuỗi Tên của bộ thực thể.

Lưu ý

Máy chủ trả về số lượng tối đa là 5.000. Khi bảng chứa hơn 5.000 bản ghi, kết quả sẽ là 5.000. Để truy xuất các bản ghi cùng với tổng số đếm của chúng, thay vào đó hãy dùng phương pháp retrieveMultipleRecords với tùy$count=true chọn truy vấn. Phương pháp đó trả về bộ sưu tập value trong thuộc tính của phản hồi và tổng số đếm trong thuộc @odata.count tính.

ví dụ về phương pháp getRecordCount

Ví dụ này trả về tổng số bản ghi tài khoản.

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

phương pháp uploadFileToColumn

Tải tệp hoặc hình ảnh lên cột tệp hoặc cột hình ảnh của bản ghi hiện có. Dataverse lưu trữ nội dung nhị phân và tự động cập {columnName}_Name nhật cột với tên tệp.

Cú pháp: $pages.webAPI.uploadFileToColumn(entitySetName: string, id: string, columnName: string, file: File): Promise<void>
Trả về: Một Promise giải quyết khi tệp được tải lên.

các tham số phương pháp uploadFileToColumn

Xác định bảng, bản ghi, cột và tệp cần tải lên.

Tham số Type Mô tả
entitySetName chuỗi Tên của bộ thực thể.
id chuỗi Mã định danh duy nhất của bản ghi.
columnName chuỗi Tên lô-gic của cột tệp hoặc hình ảnh.
file Tệp Tệp cần tải lên.

Lưu ý

Bạn có thể dùng phương pháp này với các cột hình ảnh. Dataverse loại bỏ siêu dữ liệu EXIF trên máy chủ và tự động tạo ra một hình thu nhỏ. Sử dụng phương pháp downloadFileFromColumn để tải xuống toàn bộ hình ảnh hoặc hình thu nhỏ.

ví dụ về phương pháp uploadFileToColumn

Ví dụ này tải lên tệp mà ai đó chọn bằng cách sử dụng thành phần nhập tệp.

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

phương pháp downloadFileFromColumn

Tải xuống nội dung nhị phân của cột tệp hoặc cột hình ảnh của bản ghi hiện có. Các tệp lớn được tải xuống trong các đoạn 4 MB và được kết hợp tự động thành một Blob duy nhất.

Cú pháp: $pages.webAPI.downloadFileFromColumn(entitySetName: string, id: string, columnName: string, options?: object): Promise<Blob>
Trả về: Một Promise giải quyết thành Blob có chứa dữ liệu nhị phân. Thuộc type tính của Blob chứa kiểu MIME mà máy chủ trả về.

downloadFileFromColumn method parameters

Xác định bảng, bản ghi và cột để tải xuống từ đó.

Tham số Type Mô tả
entitySetName chuỗi Tên của bộ thực thể.
id chuỗi Mã định danh duy nhất của bản ghi.
columnName chuỗi Tên lô-gic của cột tệp hoặc hình ảnh.
options đối tượng (tùy chọn) Các tùy chọn để tải xuống. Thuộc size tính này áp dụng cho các cột hình ảnh và chấp full nhận tải xuống hình ảnh gốc thumbnail hoặc tải xuống hình thu nhỏ mà Dataverse tạo ra. Giá trị mặc định là full.

Lưu ý

Phản hồi không bao gồm tên tệp. Để lấy tên tệp, hãy sử dụng phương pháp retrieveRecord để truy vấn {columnName}_Name cột của bản ghi.

ví dụ về phương pháp downloadFileFromColumn

Ví dụ này sẽ tải xuống tệp từ cột tệp và nhắc trình duyệt lưu tệp đó.

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

Ví dụ này tải xuống toàn bộ hình ảnh và hình thu nhỏ từ một cột hình ảnh.

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' }
    );
});
  • Last updated on