Soạn các yêu cầu HTTP và xử lý lỗi cho API Web cổng thông tin
- Bài viết
- 12/01/2021
- 5 phút để đọc
- 1 contributor
Trang này có hữu ích không?
Có Không
Bạn còn phản hồi nào nữa không?
Ý kiến phản hồi sẽ được gửi đến Microsoft: Bằng cách nhấn nút gửi, ý kiến phản hồi của bạn sẽ được sử dụng để cải thiện các sản phẩm và dịch vụ của Microsoft. Chính sách về quyền riêng tư.
Gửi
Cảm ơn bạn.
Trong bài viết này
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 của bạn phải từ 9.3.3.x trở lên để tính năng này 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.
Giao thức | // |
URL Cơ sở | |
Đường dẫn API Web | _api |
Tài nguyên | Tên 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:
//contoso.powerappsportals.com/_api/case
Tất cả các tài nguyên API Web sẽ tuân theo quyền bảng cổng thông tin trong ngữ cảnh với các 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:
Lấy | Sử dụng khi lấy dữ liệu từ bảng. |
Post | Sử dụng khi tạo bảng và gọi các hành động. |
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. |
Delete | Sử dụng khi xóa bảng hoặc thuộc tính riêng lẻ của bảng. |
Put | Sử dụng trong các tình huống hạn chế để cập nhật thuộc tính riêng lẻ của bảng. |
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 không có sự mơ hồ 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.0Ví 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 do API Web cổng thông tin trả về bao gồm:
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
Hãy 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.
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
Tổng quan API web cổng thông tin
Các hoạt động ghi, cập nhật và xóa cổng sử dụng API Web
Cổng đọc các thao tác sử dụng API Web