編寫 HTTP 要求並處理 Web API 入口網站的錯誤

發行項
03/16/2023

與 Web API 互動的過程，包括使用必要的標頭撰寫 HTTP 要求，以及處理 HTTP 回應 (包括任何錯誤)。

重要

您的入口網站版本必須為 9.3.3.x 或更新版本，才能使本功能運作。

Web API URL 和版本管理

使用下表中的格式構造 Web API URL。

部分	描述:
通訊協定	https://
基礎 URL	<入口網站 URL>
Web API 路徑	_api
資源	您所要使用之資料表的邏輯名稱

例如，當您參照案例時，請使用此格式：

https://contoso.powerappsportals.com/_api/case

所有的 Web API 資源都遵循 Web 角色內容中相應的資料表權限。

HTTP 方法

HTTP 要求可以使用不同類型的方法。但是，入口網站 Web API 只支援下表中的方法：

方法	使用狀況
取得 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 禁止	下列類型的錯誤預期會有此回應： 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 的未處理的錯誤回應將會傳回錯誤 - 處理要求時發生未預期的錯誤。

共用方式為