共用方式為


編寫 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/jsonAccept 標頭值,即使不應有任何回覆主體也一樣。
  • 如果此要求將 JSON 資料包含在要求本文中,您就必須加入其值為 application/jsonContent-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 禁止 下列類型的錯誤預期會是此回應:
  • AccessDenied
  • AttributePermissionIsMissing
  • TablePermissionWriteIsMissingDuringUpdate
  • TablePermissionCreateIsMissing
  • TablePermissionDeleteIsMissing
  • TablePermissionAppendIsMissngDuringAssociationChange
  • TablePermissionAppendToIsMissingDuringAssociateChange
用戶端錯誤
401 未授權 下列類型的錯誤預期會是此回應:
  • MissingPortalRequestVerificationToken
  • MissingPortalSessionCookie
用戶端錯誤
413 檔案太大 要求長度過長時,預期會是此回應。 用戶端錯誤
400 錯誤要求 引數無效時,預期會是此回應。
InvalidAttribute
用戶端錯誤
404 找不到 資源不存在時,預期會是此回應。
資料表未針對 Web API 公開。
用戶端錯誤
405 不允許的方法 不正確的方法與資源組合,會發生此錯誤。 例如,您不可在資料表集合上使用 DELETE 或 PATCH。 此狀況可能會因下列類型的錯誤而發生:
  • InvalidOperation
  • NotSupported
用戶端錯誤
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 的入口網站讀取作業

注意

是否能請您告知您偏好的慣用文件語言? 請填寫問卷。 (請注意,本問卷為英文版)

完成問卷大約需要七分鐘。 本問卷將不會收集個人資料 (隱私權聲明)。