编写 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 仅支持下表中的方法：

方法	用法
Get	从表中检索数据时使用。
公告	创建记录时使用。
修补	更新表或执行 upsert 操作时使用。
Delete	删除记录或单个记录字段值时使用。
Put	在有限的情况下用于更新记录的各个字段。

HTTP 标头

Web API 仅支持 JSON。每个 HTTP 标题必须包含：

应用程序/json 的接受标头值（即使不需要响应正文）。
如果请求在请求正文中包含 JSON 数据，则必须包含值为application/json 的内容类型标题。

当前 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 正常	当您的操作将在响应正文中返回数据时，出现此响应。	成功
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 的未处理错误的响应将返回错误“处理请求时发生意外错误”。

通过