編寫 HTTP 要求並處理 Web API 入口網站的錯誤
注意
自 2022 年 10 月 12 日起,Power Apps 入口網站為 Power Pages。 其他資訊:Microsoft Power Pages 現在已推出 (部落格)
我們很快就會遷移並將 Power Apps 入口網站文件與 Power Pages 文件併合。
與 Web API 互動的過程,包括使用必要的標頭撰寫 HTTP 要求,以及處理 HTTP 回應 (包括任何錯誤)。
重要
- 您的入口網站版本必須為 9.3.3.x 或更新版本,才能使本功能運作。
Web API URL 和版本管理
使用下表中的格式構造 Web API URL。
部分 | 名描述 |
---|---|
通訊協定 | https:// |
基礎 URL | <portal URL> |
Web API 路徑 | _api |
資源 | 您所要使用之資料表的邏輯名稱 |
例如,當您參照案例時,請使用此格式:
https://contoso.powerappsportals.com/_api/case
所有的 Web API 資源將遵循 Web 角色內容中的對應入口網站資料表權限。
HTTP 方法
HTTP 要求可以使用不同類型的方法。 但是,入口網站 Web API 只支援下表中的方法:
Method | 使用狀況 |
---|---|
取得 Yammer | 從資料表中擷取資料時使用。 |
Post | 在建立記錄時使用。 |
Patch | 在更新表格或執行 upsert 作業時使用。 |
删除 | 在刪除記錄或記錄的個別欄位值時使用。 |
Put | 在受限情況下用來更新記錄的個別欄位。 |
HTTP 標頭
Web API 只支援 JSON。 每個 HTTP 標頭都必須包含:
- application/json 的 Accept 標頭值,即使不應有任何回覆主體也一樣。
- 如果此要求將 JSON 資料包含在要求本文中,您就必須加入其值為
application/json
的 Content-Type 標頭。
最新的 OData 版本為 4.0,但是未來的版本可能納入新功能。 使用以下語法可確保將來套用於程式碼的 OData 版本不會造成模稜兩可的情形:
語法
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
範例:CSRF 標記的包裝 AJAX 函數
(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)
範例:擷取資料表資料
webapi.safeAjax({
type: "GET",
url: "/_api/contacts?$select=firstname,lastname",
contentType: "application/json",
success: function (res) {
console.log(res);
}
});
範例:建立資料表資料
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"))
}
});
範例:更新資料表資料
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);
}
});
範例:刪除資料表資料
webapi.safeAjax({
type: "DELETE",
url: "/_api/accounts(00000000-0000-0000-0000-000000000001)",
contentType: "application/json",
success: function (res) {
console.log(res);
}
});
識別狀態碼
每個 HTTP 要求回應都會包含狀態碼。 入口網站 Web API 傳回的狀態碼包含下列內容:
代碼 | Description | 類型 |
---|---|---|
200 OK | 如果您的作業會在回應本文中傳回資料,則預期會是此回應。 | 成功 |
204 無內容 | 如果您的作業成功,但未在回應本文中傳回資料,則預期會是此回應。 | 成功 |
403 禁止 | 下列類型的錯誤預期會是此回應:
|
用戶端錯誤 |
401 未授權 | 下列類型的錯誤預期會是此回應:
|
用戶端錯誤 |
413 檔案太大 | 要求長度過長時,預期會是此回應。 | 用戶端錯誤 |
400 錯誤要求 | 引數無效時,預期會是此回應。 InvalidAttribute |
用戶端錯誤 |
404 找不到 | 資源不存在時,預期會是此回應。 資料表未針對 Web API 公開。 |
用戶端錯誤 |
405 不允許的方法 | 不正確的方法與資源組合,會發生此錯誤。 例如,您不可在資料表集合上使用 DELETE 或 PATCH。 此狀況可能會因下列類型的錯誤而發生:
|
用戶端錯誤 |
501 未實作 | 某些要求的作業未實作時,預期會是此回應。 | 伺服器錯誤 |
503 服務無法使用 | 當 Web API 服務無法使用時,預期會是此回應。 | 伺服器錯誤 |
從回應剖析錯誤
試想下列仍包含內部錯誤的範例 HTTP 回應:
{
"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.."
}
}
}
錯誤代碼
對於所有已處理的案例,錯誤碼都會以十六進位格式顯示。 下表列出每個錯誤代碼及其各自的名稱和訊息。
錯誤碼 | 錯誤名稱 | 錯誤訊息 |
---|---|---|
900400FF | NoAttributesForTableCreate | 沒有可用於建立資料表動作的屬性。 |
90040100 | InvalidAttribute | 找不到資料表 {1} 的 {0} 屬性。 |
90040101 | AttributePermissionIsMissing | 未對 Web API 啟用資料表 {1} 的 {0} 屬性。 |
90040102 | TablePermissionWriteIsMissingDuringUpdate | 您沒有更新 {0} 實體的權限。 |
90040103 | TablePermissionCreateIsMissing | 您沒有建立 {0} 實體的權限。 |
90040104 | TablePermissionDeleteIsMissing | 您沒有刪除 {0) 實體的權限。 |
90040105 | TablePermissionAppendIsMissngDuringAssociationChange | 您沒有將資料表 {0} 與 {1} 關聯或解除關聯的權限。 |
90040106 | TablePermissionAppendToIsMissingDuringAssociationChange | 您沒有將資料表 {1} 關聯至 {0} 或解除關聯的權限 |
90040107 | HttpAntiForgeryException | 防偽 Cookie 語彙基元與表單欄位語彙基元不相符。 |
90040109 | MissingPortalSessionCookie | 無效的工作階段權杖已傳遞至擲回的方法中。 |
9004010C | ResourceDoesNotExists | 找不到區段 '{0}' 的資源。 |
9004010D | CDSError | 發生 CDS 錯誤。 |
HTTP 狀態碼為 500 的未處理的錯誤回應將會傳回錯誤 - 處理要求時發生未預期的錯誤。
請參閱
入口網站 Web API 概觀
入口網站使用 Web API 寫入、更新和刪除作業
使用 Web API 的入口網站讀取作業