Truy vấn dữ liệu bằng API Web cổng thông tin
Bạn có thể sử dụng các hoạt động API Web có sẵn trong Power Pages. Các thao tác API Web bao gồm các yêu cầu và phản hồi HTTP. Bài viết này cung cấp các thao tác đọc mẫu, phương thức, URI và JSON mẫu mà bạn có thể dùng trong yêu cầu HTTP.
Điều kiện tiên quyết
Phiên bản website của bạn phải từ 9.4.1.x trở lên.
Bật bảng và trường cho các hoạt động API Web. Thông tin khác: Thiết đặt trang web cho API Web
API Web cổng thông tin truy cập các bản ghi bảng và tuân theo các quyền đối với bảng được cấp cho người dùng thông qua các vai trò web được liên kết. Đảm bảo rằng bạn đặt cấu hình đúng các quyền đối với bảng. Thông tin khác: Tạo các vai trò web
Lưu ý
Khi đề cập đến bảng Dataverse sử dụng API Web cổng thông tin, bạn cần sử dụng EntitySetName, ví dụ như để truy cập vào bảng tài khoản, cú pháp mã sẽ sử dụng EntitySetName của tài khoản.
Truy vấn bản ghi
Ví dụ sau đây truy vấn bản ghi tài khoản:
| Thao tác | Phương thức | URI |
|---|---|---|
| Truy xuất bản ghi bảng | GET | [Portal URI]/_api/accountsVí dụ:https://contoso.powerappsportals.com/_api/accounts |
Phản hồi mẫu
{
"value": [
{
"@odata.etag": "W/\"1066412\"",
"name": "Fourth Coffee (sample)",
"accountid": "d2e11ba8-92f6-eb11-94ef-000d3a5aa607"
},
{
"@odata.etag": "W/\"1066413\"",
"name": "Litware, Inc. (sample)",
"accountid": "d4e11ba8-92f6-eb11-94ef-000d3a5aa607"
}
]
}
Sử dụng các tùy chọn truy vấn hệ thống $select và $top để trả về thuộc tính tên cho ba tài khoản đầu tiên:
| Thao tác | Phương thức | URI |
|---|---|---|
| Truy xuất ba bản ghi thực thể đầu tiên | GET | [Portal URI]/_api/accounts?$select=name,revenue&$top=3Ví dụ:https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$top=3 |
Truy xuất tài khoản bằng cách sử dụng ID tài khoản:
| Thao tác | Phương thức | URI |
|---|---|---|
| Truy xuất thuộc tính cụ thể cho một bản ghi | GET | [Portal URI]/_api/accounts(e0e11ba8-92f6-eb11-94ef-000d3a5aa607)?$select=nameVí dụ:https://contoso.powerappsportals.com/_api/accounts(e0e11ba8-92f6-eb11-94ef-000d3a5aa607)?$select=name |
Phản hồi mẫu
{
"@odata.etag": "W/\"1066414\"",
"name": "Adventure Works (sample)",
"accountid": "d6e11ba8-92f6-eb11-94ef-000d3a5aa607"
}
Áp dụng các tùy chọn truy vấn hệ thống
Mỗi tùy chọn truy vấn hệ thống mà bạn gắn thêm vào URL cho nhóm thực thể được thêm bằng cú pháp cho chuỗi truy vấn. Tùy chọn truy vấn đầu tiên được thêm vào sau [?] và các tùy chọn truy vấn sau được phân tách bằng [&]. Tất cả các tùy chọn truy vấn đều phân biệt chữ hoa chữ thường như trong ví dụ sau đây:
| Phương thức | URI |
|---|---|
| GET | [Portal URI]/_api/accounts?$select=name,revenue&$filter=revenue gt 90000&$top=3Ví dụ:https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$filter=revenue gt 90000&$top=3 |
Yêu cầu các thuộc tính cụ thể
Sử dụng tùy chọn truy vấn hệ thống $select để giới hạn các thuộc tính được trả về như trong ví dụ sau đây:
| Phương thức | URI |
|---|---|
| GET | [Portal URI]/_api/accounts?$select=name,revenue&$top=3Ví dụ:https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$top=3 |
Quan trọng
Đây là thực tiễn tốt nhất về hiệu năng. Nếu thuộc tính không được chỉ định và bạn đã đặt cấu hình giá trị thiết đặt trang web Webapi/<table name>/fields thành * thì tất cả các thuộc tính sẽ được trả về bằng $select. Nếu không có thuộc tính nào được chỉ định thì lỗi sẽ được trả về.
Kết quả lọc
Sử dụng tùy chọn truy vấn hệ thống $filter để đặt tiêu chí cho các hàng sẽ được trả về.
Toán tử bộ lọc tiêu chuẩn
API Web hỗ trợ các toán tử bộ lọc OData tiêu chuẩn được liệt kê trong bảng sau đây:
| Toán tử | Mô tả | Ví dụ: |
|---|---|---|
| Toán tử so sánh | ||
| eq | Bằng | $filter=revenue eq 100000 |
| ne | Không bằng | $filter=revenue ne 100000 |
| gt | Lớn hơn | $filter=revenue gt 100000 |
| ge | Lớn hơn hoặc bằng | $filter=revenue ge 100000 |
| lt | Nhỏ hơn | $filter=revenue lt 100000 |
| le | Nhỏ hơn hoặc bằng | $filter=revenue le 100000 |
| Toán tử lô-gic | ||
| và | Lô-gic and | $filter=revenue lt 100000 and revenue gt 2000 |
| or | Lô-gic or | $filter=contains(name,'(sample)') or contains(name,'test') |
| not | Lô-gic phủ định | $filter=not contains(name,'sample') |
| Nhóm các toán tử | ||
| ( ) | Nhóm ưu tiên | (contains(name,'sample') or contains(name,'test')) and revenue gt 5000 |
Các hàm truy vấn tiêu chuẩn
API Web hỗ trợ những hàm truy vấn chuỗi OData tiêu chuẩn này:
| Hàm | Ví dụ: |
|---|---|
| chứa | $filter=contains(name,'(sample)') |
| kết thúc bằng | $filter=endswith(name,'Inc.') |
| bắt đầu bằng | $filter=startswith(name,'a') |
Các hàm truy vấn Dataverse
API Web hỗ trợ các hàm truy vấn Dataverse để lọc kết quả. Để biết thêm thông tin, hãy xem Tham chiếu hàm truy vấn API Web.
Sắp xếp kết quả
Chỉ định thứ tự mà các mục được trả về bằng tùy chọn truy vấn hệ thống $orderby. Sử dụng hậu tố asc hoặc desc để chỉ định thứ tự tăng dần hoặc giảm dần tương ứng. Mặc định là tăng dần nếu hậu tố không được áp dụng. Ví dụ sau cho thấy việc truy xuất tên và thuộc tính doanh thu của các tài khoản được sắp xếp theo doanh thu tăng dần và theo tên giảm dần.
| Phương thức | URI |
|---|---|
| GET | [Portal URI]/_api/accounts?$select=name,revenue&$orderby=name asc,revenue desc&$filter=revenue gt 90000Ví dụ:https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$orderby=name asc,revenue desc&$filter=revenue gt 90000 |
Tổng hợp và nhóm các kết quả
Bằng cách sử dụng $apply, bạn có thể tổng hợp và nhóm dữ liệu của mình một cách linh động như trong các ví dụ sau đây:
| Kịch bản | Ví dụ: |
|---|---|
| Danh sách các trạng thái duy nhất trong truy vấn | accounts?$apply=groupby((statuscode)) |
| Tổng hợp tổng của giá trị ước tính | opportunities?$apply=aggregate(estimatedvalue with sum as total) |
| Quy mô trung bình của giao dịch dựa trên giá trị ước tính và trạng thái | opportunities?$apply=groupby((statuscode),aggregate(estimatedvalue with average as averagevalue) |
| Tổng giá trị ước tính dựa trên trạng thái | opportunities?$apply=groupby((statuscode),aggregate(estimatedvalue with sum as total)) |
| Tổng doanh thu cơ hội theo tên tài khoản | opportunities?$apply=groupby((parentaccountid/name),aggregate(estimatedvalue with sum as total)) |
| Tên liên hệ chính cho các tài khoản trong 'WA' | accounts?$apply=filter(address1_stateorprovince eq 'WA')/groupby((primarycontactid/fullname)) |
| Ngày và giờ tạo bản ghi cuối cùng | accounts?$apply=aggregate(createdon with max as lastCreate) |
| Ngày và giờ tạo bản ghi đầu tiên | accounts?$apply=aggregate(createdon with min as firstCreate) |
Truy xuất số lượng hàng
Sử dụng tùy chọn truy vấn hệ thống $count với giá trị true để bao gồm số lượng thực thể phù hợp với tiêu chí bộ lọc lên đến 5.000.
| Phương thức | URI |
|---|---|
| GET | [Portal URI/_api/accounts?$select=name&$filter=contains(name,'sample')&$count=trueVí dụ:https://contoso.powerappsportals.com/_api/accounts?$select=name&$filter=contains(name,'sample')&$count=true |
Phản hồi mẫu
{
"@odata.count": 10,
"value": [
{
"@odata.etag": "W/\"1066412\"",
"name": "Fourth Coffee (sample)",
"accountid": "d2e11ba8-92f6-eb11-94ef-000d3a5aa607"
},
{
"@odata.etag": "W/\"1066413\"",
"name": "Litware, Inc. (sample)",
"accountid": "d4e11ba8-92f6-eb11-94ef-000d3a5aa607"
},
{
"@odata.etag": "W/\"1066414\"",
"name": "Adventure Works (sample)",
"accountid": "d6e11ba8-92f6-eb11-94ef-000d3a5aa607"
}
]
}
Nếu bạn không muốn trả về bất kỳ dữ liệu nào ngoại trừ số lượng, bạn có thể áp dụng $count cho bất kỳ bộ sưu tập nào để chỉ nhận được giá trị.
| Phương thức | URI |
|---|---|
| GET | [Portal URI/_api/accounts/$countVí dụ:https://contoso.powerappsportals.com/_api/accounts/$count |
Phản hồi mẫu
3
So sánh cột
Ví dụ sau đây cho thấy cách so sánh các cột bằng API Web:
| Phương thức | URI |
|---|---|
| GET | [Portal URI]/_api/contacts?$select=firstname&$filter=firstname eq lastnameVí dụ:https://contoso.powerappsportals.com/_api/contacts?$select=firstname&$filter=firstname eq lastname |
Truy xuất các bản ghi bảng có liên quan bằng một truy vấn
Sử dụng tùy chọn truy vấn hệ thống $expand trong các thuộc tính điều hướng để kiểm soát dữ liệu nào từ các thực thể liên quan được trả về.
Thuộc tính điều hướng được liên kết tra cứu
Bạn sẽ cần sử dụng Microsoft.Dynamics.CRM.associatednavigationproperty làm thuộc tính tra cứu khi sử dụng tùy chọn truy vấn $expand.
Để xác định Microsoft.Dynamics.CRM.associatednavigationproperty của một thuộc tính, bạn có thể thực hiện yêu cầu NHẬN http sau đây cho cột bằng cách sử dụng quy ước đặt tên sau đây: _name_value.
Trong ví dụ sau đây, chúng tôi có thể xác định thuộc tính điều hướng được liên kết của cột Liên hệ chính của bảng Tài khoản bằng cách chỉ định tên cột primarycontactid bằng cách định dạng tên trong yêu cầu: _primarycontactid_value.
| Phương thức | URI |
|---|---|
| GET | [Portal URI]/_api/accounts?$select=_primarycontactid_valueVí dụhttps://contoso.powerappsportals.com/_api/accounts?$select=_primarycontactid_value |
Phản hồi mẫu
{
"value": [
{
"@odata.etag": "W/\"2465216\"",
"_primarycontactid_value@OData.Community.Display.V1.FormattedValue": "Yvonne McKay (sample)",
"_primarycontactid_value@Microsoft.Dynamics.CRM.associatednavigationproperty": "primarycontactid",
"_primarycontactid_value@Microsoft.Dynamics.CRM.lookuplogicalname": "contact",
"_primarycontactid_value": "417319b5-cd18-ed11-b83c-000d3af4d812",
"accountid": "2d7319b5-cd18-ed11-b83c-000d3af4d812"
}
]
}
Từ phản hồi, chúng tôi thấy rằng thuộc tính điều hướng được liên kết là primarycontactid. Thuộc tính điều hướng được liên kết có thể là tên lô-gic hoặc tên sơ đồ của cột tra cứu, tùy thuộc vào cách tạo bảng.
Để biết thêm thông tin, hãy xem Truy xuất dữ liệu về các thuộc tính tra cứu.
Truy xuất các bản ghi bảng có liên quan bằng cách mở rộng các thuộc tính điều hướng có giá trị đơn
Ví dụ sau đây cho thấy cách truy xuất liên hệ cho tất cả các bản ghi tài khoản. Đối với các bản ghi liên hệ có liên quan, chúng tôi chỉ truy xuất contactid và fullname.
| Phương thức | URI |
|---|---|
| GET | [Portal URI]/_api/accounts?$select=name&$expand=primarycontactid($select=contactid,fullname)Ví dụ:https://contoso.powerappsportals.com/_api/accounts?$select=name&$expand=primarycontactid($select=contactid,fullname) |
Phản hồi mẫu
{
"value": [
{
"@odata.etag": "W/\"1066412\"",
"name": "Fourth Coffee (sample)",
"accountid": "d2e11ba8-92f6-eb11-94ef-000d3a5aa607",
"primarycontactid": {
"contactid": "e6e11ba8-92f6-eb11-94ef-000d3a5aa607",
"fullname": "Yvonne McKay (sample)"
}
},
{
"@odata.etag": "W/\"1066413\"",
"name": "Litware, Inc. (sample)",
"accountid": "d4e11ba8-92f6-eb11-94ef-000d3a5aa607",
"primarycontactid": {
"contactid": "e8e11ba8-92f6-eb11-94ef-000d3a5aa607",
"fullname": "Susanna Stubberod (sample)"
}
}
]
}
Truy xuất các bảng có liên quan bằng cách mở rộng các thuộc tính điều hướng có giá trị tập hợp
Nếu bạn mở rộng các tham số điều hướng có giá trị tập hợp để truy xuất các bảng có liên quan cho các nhóm thực thể, thì chỉ một mức độ sâu được trả về nếu có dữ liệu. Nếu không, bộ sưu tập sẽ trả về một mảng trống.
| Phương thức | URI |
|---|---|
| GET | [Portal URI]/_api/accounts?$top=5&$select=name&$expand=Account_Tasks($select=subject,scheduledstart)Ví dụ:https://contoso.powerappsportals.com/_api/accounts?$top=5&$select=name&$expand=Account_Tasks($select=subject,scheduledstart) |
Truy xuất các bảng có liên quan bằng cách mở rộng cả thuộc tính điều hướng có giá trị đơn và thuộc tính điều hướng có giá trị tập hợp
Ví dụ sau đây minh họa cách bạn có thể mở rộng các thực thể có liên quan cho các nhóm thực thể sử dụng cả thuộc tính điều hướng có giá trị đơn và thuộc tính điều hướng có giá trị tập hợp. Bạn sẽ cần chỉ định tên mối quan hệ bảng trong cú pháp mã của bạn.
| Phương thức | URI |
|---|---|
| GET | [Portal URI]/_api/accounts?$top=5&$select=name&$expand=primarycontactid($select=contactid,fullname),Account_Tasks($select=subject,scheduledstart)Ví dụ:https://contoso.powerappsportals.com/_api/accounts?$top=5&$select=name&$expand=primarycontactid($select=contactid,fullname),Account_Tasks($select=subject,scheduledstart) |
Bước tiếp theo
Thao tác ghi, cập nhật và xóa cổng thông tin bằng Web API
Xem thêm
Phản hồi
Sắp ra mắt: Trong năm 2024, chúng tôi sẽ dần gỡ bỏ Sự cố với GitHub dưới dạng cơ chế phản hồi cho nội dung và thay thế bằng hệ thống phản hồi mới. Để biết thêm thông tin, hãy xem: https://aka.ms/ContentUserFeedback.
Gửi và xem ý kiến phản hồi dành cho