Soạn các yêu cầu HTTP và xử lý lỗi cho API Web cổng thông tin
Việc tương tác với API Web bao gồm việc tạo yêu cầu HTTP với các tiêu đề bắt buộc và xử lý các phản hồi HTTP, bao gồm mọi lỗi.
Quan trọng
- Phiên bản cổng thông tin phải từ 9.3.3.x trở lên thì tính năng này mới hoạt động.
URL API Web và cách tạo phiên bản
Tạo URL API Web bằng cách sử dụng định dạng trong bảng sau.
| Phần | Nội dung mô tả |
|---|---|
| Giao thức | https:// |
| URL Cơ sở | <URL cổng thông tin> |
| Đường dẫn API Web | _api |
| Tài nguyên | Tên logic của bảng bạn muốn sử dụng |
Ví dụ: sử dụng định dạng này khi tham chiếu một trường hợp:
https://contoso.powerappsportals.com/_api/case
Tất cả các tài nguyên API web sẽ tuân theo quyền của bảng tương ứng trong ngữ cảnh với vai trò web.
Phương thức HTTP
Các yêu cầu HTTP có thể dùng các loại phương thức khác nhau. Tuy nhiên, API Web cổng thông tin chỉ hỗ trợ các phương thức trong bảng sau:
| Phương thức | Mức sử dụng |
|---|---|
| Lấy | Sử dụng khi truy xuất dữ liệu từ bảng. |
| Bài đăng | Sử dụng khi đang tạo bản ghi. |
| Bản vá | Sử dụng khi cập nhật bảng hoặc thực hiện các thao tác upsert. |
| Xoá | Sử dụng khi xóa bản ghi hoặc giá trị trường riêng lẻ của bản ghi. |
| Put | Sử dụng trong các tình huống hạn chế để cập nhật các trường của bản ghi. |
Tiêu đề HTTP
API Web chỉ hỗ trợ JSON. Mỗi tiêu đề HTTP phải bao gồm:
- Giá trị tiêu đề Chấp nhận của ứng dụng/json, ngay cả khi không có nội dung phản hồi.
- Nếu yêu cầu bao gồm dữ liệu JSON trong nội dung yêu cầu, thì bạn phải thêm tiêu đề Content-Type với giá trị là
application/json.
Phiên bản OData hiện tại là 4.0, nhưng các phiên bản trong tương lai có thể cho phép các khả năng mới. Sử dụng cú pháp sau để đảm bảo rằng không có sự mơ hồ nào về phiên bản OData sẽ được áp dụng cho mã của bạn trong tương lai:
Cú pháp
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Ví dụ: Hàm AJAX gói cho mã thông báo CSRF
(function(webapi, $){
function safeAjax(ajaxOptions) {
var deferredAjax = $.Deferred();
shell.getTokenDeferred().done(function (token) {
// add headers for ajax
if (!ajaxOptions.headers) {
$.extend(ajaxOptions, {
headers: {
"__RequestVerificationToken": token
}
});
} else {
ajaxOptions.headers["__RequestVerificationToken"] = token;
}
$.ajax(ajaxOptions)
.done(function(data, textStatus, jqXHR) {
validateLoginSession(data, textStatus, jqXHR, deferredAjax.resolve);
}).fail(deferredAjax.reject); //ajax
}).fail(function () {
deferredAjax.rejectWith(this, arguments); // on token failure, pass the token ajax and args
});
return deferredAjax.promise();
}
webapi.safeAjax = safeAjax;
})(window.webapi = window.webapi || {}, jQuery)
Ví dụ: Truy xuất dữ liệu bảng
webapi.safeAjax({
type: "GET",
url: "/_api/contacts?$select=firstname,lastname",
contentType: "application/json",
success: function (res) {
console.log(res);
}
});
Ví dụ: Tạo dữ liệu bảng
webapi.safeAjax({
type: "POST",
url: "/_api/accounts",
contentType: "application/json",
data: JSON.stringify({
"name": "Sample Account"
}),
success: function (res, status, xhr) {
console.log("entityID: "+ xhr.getResponseHeader("entityid"))
}
});
Ví dụ: Cập nhật dữ liệu bảng
webapi.safeAjax({
type: "PATCH",
url: "/_api/accounts(00000000-0000-0000-0000-000000000001)",
contentType: "application/json",
data: JSON.stringify({
"name": "Sample Account - Updated"
}),
success: function (res) {
console.log(res);
}
});
Ví dụ: Xóa dữ liệu bảng
webapi.safeAjax({
type: "DELETE",
url: "/_api/accounts(00000000-0000-0000-0000-000000000001)",
contentType: "application/json",
success: function (res) {
console.log(res);
}
});
Xác định mã trạng thái
Mỗi phản hồi của yêu cầu HTTP bao gồm một mã trạng thái. Mã trạng thái được trả về bởi API Web cổng thông tin bao gồm các mục sau:
| Mã | Nội dung mô tả | Loại |
|---|---|---|
| 200 OK | Mong đợi phản hồi này khi thao tác của bạn sẽ trả về dữ liệu trong nội dung phản hồi. | Thành công |
| 204 Không có nội dung | Mong đợi phản hồi này khi thao tác của bạn thành công, nhưng không trả về dữ liệu trong nội dung phản hồi. | Thành công |
| 403 Bị cấm | Mong đợi phản hồi này cho các loại lỗi sau:
|
Lỗi máy khách |
| 401 Không được ủy quyền | Mong đợi phản hồi này cho các loại lỗi sau:
|
Lỗi máy khách |
| 413 Tải trọng quá lớn | Mong đợi phản hồi này khi độ dài yêu cầu quá lớn. | Lỗi máy khách |
| 400 Yêu cầu lỗi | Mong đợi phản hồi này khi một đối số không hợp lệ. InvalidAttribute |
Lỗi máy khách |
| 404 Không tìm thấy | Mong đợi phản hồi này khi tài nguyên không tồn tại. Bảng không được hiển thị cho API web. |
Lỗi máy khách |
| 405 Phương thức không được phép | Lỗi này xảy ra đối với những kiểu kết hợp phương thức và tài nguyên không chính xác. Ví dụ: bạn không thể sử dụng DELETE hoặc PATCH trên tập hợp bảng. Tình trạng này có thể xảy ra đối với các loại lỗi sau:
|
Lỗi máy khách |
| 501 Không được thực thi | Mong đợi phản hồi này khi một số thao tác đã yêu cầu không được thực thi. | Lỗi máy chủ |
| 503 Không có sẵn Dịch vụ | Mong đợi phản hồi này khi dịch vụ API Web không có sẵn. | Lỗi máy chủ |
Lỗi phân tích cú pháp từ phản hồi
Xem xét phản hồi HTTP mẫu sau đây vẫn bao gồm lỗi bên trong:
{
"error":{
"code": "This code is not related to the http status code and is frequently empty",
"message": "A message describing the error",
"cdscode": "Dataverse error code",
"innererror": {
"code": "800xxxx",
"message": "A message describing the error. This is frequently the same as the outer message.."
}
}
}
Mã lỗi
Mã lỗi hiển thị ở định dạng thập lục phân cho tất cả các kịch bản được xử lý. Bảng sau đây liệt kê từng mã lỗi với tên và thông báo tương ứng.
| Mã lỗi | Tên lỗi | Thông báo lỗi |
|---|---|---|
| 900400FF | NoAttributesForTableCreate | Không có thuộc tính cho hành động Tạo bảng. |
| 90040100 | InvalidAttribute | Không tìm thấy thuộc tính {0} cho bảng {1}. |
| 90040101 | AttributePermissionIsMissing | Thuộc tính {0} trong bảng {1} không được bật cho API Web. |
| 90040102 | TablePermissionWriteIsMissingDuringUpdate | Bạn không có quyền cập nhật thực thể {0}. |
| 90040103 | TablePermissionCreateIsMissing | Bạn không có quyền tạo thực thể {0}. |
| 90040104 | TablePermissionDeleteIsMissing | Bạn không có quyền xóa thực thể {0). |
| 90040105 | TablePermissionAppendIsMissngDuringAssociationChange | Bạn không có quyền để liên kết hoặc hủy liên kết bảng {0} với {1}. |
| 90040106 | TablePermissionAppendToIsMissingDuringAssociationChange | Bạn không có quyền để liên kết hoặc hủy liên kết bảng {1} với {0} |
| 90040107 | HttpAntiForgeryException | Mã thông báo cookie chống giả mạo và mã thông báo trường biểu mẫu không khớp. |
| 90040109 | MissingPortalSessionCookie | Mã thông báo phiên không hợp lệ đã được truyền vào phương thức ném. |
| 9004010C | ResourceDoesNotExists | Không tìm thấy tài nguyên cho phân đoạn "{0}". |
| 9004010D | CDSError | Đã xảy ra lỗi CDS. |
Phản hồi cho các lỗi chưa được xử lý với mã trạng thái HTTP 500 sẽ trả về lỗi "Đã xảy ra lỗi không mong muốn khi xử lý yêu cầu".
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