编写 HTTP 请求并处理错误

通过撰写和发送 HTTP 请求与 Web API 进行交互。需要了解如何设置相应的 HTTP 标头并处理响应中包含的任何错误。

Web API URL 和版本

若要查找环境的 Web API URL，请执行以下步骤：

登录到Power Apps，然后在右上角选择您的环境。
选择右上角的 “设置” 按钮，然后选择 “开发人员资源”。

在此处，可以复制 Web API 终结点的值。有关详细信息，请参阅查看开发人员资源。

下表描述了 URL 的各个部分：

组成部分	说明
协议	`https://`
环境名称	适用于您环境的唯一名称。如果公司名称为 Contoso，则可能是 `contoso`。
Region	你的环境通常位于地理位置靠近你的数据中心。对于北美来说，这是 `crm`。对于南美洲 `crm2`。对于日本 `crm7`。有关完整列表，请参阅数据中心区域。
基本网址	此值通常是 `dynamics.com.`，但某些数据中心使用不同的值。请参阅数据中心区域。
Web API 路径	Web API 的路径为 `/api/data/`.
版本	版本以这种方式表示： `v[Major_version].[Minor_version][PatchVersion]/` 当前版本为 `v9.2`。
资源	表的 `EntitySetName`，或您要使用的函数或操作的名称。

使用的 URL 由以下部分组成：

协议 + 环境名称 + 地区 + 基 URL + Web API 路径 + 版本 + 资源。

最大 URL 长度

接受的 URL 的最大长度为 32 KB（32,768 个字符）。此长度足以满足大多数类型的请求，但某些 GET 操作需要非常长的字符串查询参数，例如使用 FetchXml 的查询。如果在请求正文 $batch 内发送请求，则可以发送 URL 高达 64 KB（65,536 个字符）的请求。详细了解如何在$batch请求中发送 FetchXml。

最大 OData 段长度

OData 请求中任何单个段的最大长度为 260 个字符。如果 OData 请求的单个段长度超过 260 个字符，则请求返回 400 Bad Request - Invalid URL。段是 URL 的“资源”部分，包含描述终结点和任何内联参数所需的所有字符。

例如，如果请求是 api/data/v9.2/MyApi(MyParameter='longvalue')， MyApi(MyParameter='longvalue') 则为不能超过 260 个字符的段。始终对 OData 函数使用参数别名。例如，将函数组合为 /api/data/v9.2/MyApi(MyParameter=@alias)?@alias='longvalue' 将段缩短为 just MyApi(MyParameter=@alias)。详细了解如何将参数别名与 Web API 函数配合使用。

版本兼容性

此版本引入了以前版本不支持的功能。后续次要版本可能会提供更多早期次要版本不支持的功能。在 URL 中引用 v9.0 时，为 v9.0 编写的代码在将来版本中将继续工作。

随着新功能的引入，它们可能与早期版本冲突。这些重大变更是改进服务所必需的。大多数情况下，功能在版本之间保持不变，但不假定它们相同。

注释

与 v8.x 次要版本不同，将来的版本不会对早期版本应用新功能或其他更改。如果更改了所使用的版本，请注意所使用的服务版本并测试代码。

HTTP 方法

下表列出了可与 Dataverse Web API 一起使用的 HTTP 方法。

方法	用法
`GET`	检索数据（包括调用函数）时使用。成功检索的预期状态代码为 `200 OK`。
`POST`	创建实体或调用动作时使用。
`PATCH`	在更新实体或执行 upsert 操作时使用。
`DELETE`	在删除实体或实体属性时使用。
`PUT`	在有限情况下使用以更新实体的各个属性。更新大多数实体时，不建议使用此方法。更新表定义时使用 `PUT` 。详细信息：将 Web API 与表定义配合使用

HTTP 标头

所有 HTTP 请求都应至少包含以下标头。

Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0
If-None-Match: null

尽管 OData 协议同时允许 JSON 和 ATOM 格式，但 Web API 仅支持 JSON。每个请求都应包含 Accept 标头值 application/json，即使不期望有响应正文也是如此。 Web API 以 JSON 形式返回响应中的任何错误。尽管代码应正常工作，即使未包含此标头，但请将其作为最佳做法包含在内。

当前的 OData 版本为 4.0，但将来的版本可能会引入新功能。为了确保适用于代码的 OData 版本没有歧义，请始终包含当前 OData 版本的显式语句和最大版本。使用 OData-Version 和 OData-MaxVersion 两个标头，并将其设置为 4.0 的值。

展开集合值导航属性的查询可能会返回那些不反映最近更改的属性的缓存数据。在 If-None-Match: null 请求正文中包含标头，以替代 Web API 请求的浏览器缓存。有关详细信息，请参阅超文本传输协议（HTTP/1.1）：条件请求 3.2：If-None-Match。

请求正文中包含 JSON 数据的每个请求都必须包含 Content-Type 值为的 application/json标头。

Content-Type: application/json

可以使用其他标头启用特定功能。

首选标头

使用以下值的 Prefer 标头来指定首选项。

首选值	说明
`return=representation`	使用此选项可返回实体的创建（`POST`）或更新（`PATCH`）操作的数据。将此首选项应用于 `POST` 请求时，成功响应的状态 `201 Created` 为。对于`PATCH`请求，成功响应的状态为`200 OK.`。如果没有该首选项，这两个操作将返回状态`204 No Content`，以反映响应正文不包含任何数据。详细信息：使用返回的数据创建并使用返回的数据进行更新
`odata.include-annotations`	请参阅请求批注
`odata.maxpagesize`	使用此首选项可指定要在查询中返回的页面数。详细信息：页面结果
`odata.track-changes`	更改跟踪功能通过检测自最初提取或上次同步的数据以来更改的数据，使数据保持同步。详细信息：使用更改跟踪将数据与外部系统同步
`respond-async`	指定应异步处理请求。详细信息：后台操作（预览版）

注释

可以使用逗号分隔的值指定多个 Prefer 标头。例如：Prefer: respond-async,odata.include-annotations="*"

请求批注

可以通过使用 Prefer: odata.include-annotations 请求标头，要求在结果中返回不同的 OData 批注数据。可以选择返回所有批注或指定特定批注。下表描述了 Dataverse Web API 支持的注释：

注释	说明
`OData.Community.Display.V1.FormattedValue`	返回可在应用程序中使用的格式化字符串值。详细信息：格式化值
`Microsoft.Dynamics.CRM.associatednavigationproperty` `Microsoft.Dynamics.CRM.lookuplogicalname`	返回有关相关查找列的信息。详细信息：查找属性数据和多表查找
`Microsoft.Dynamics.CRM.totalrecordcount` `Microsoft.Dynamics.CRM.totalrecordcountlimitexceeded`	使用 `$count` 查询选项时， `@odata.count` 批注会告知记录数，但一次只能返回 5,000 条标准表记录。对于弹性表，页面大小限制为 500。 `Microsoft.Dynamics.CRM.totalrecordcountlimitexceeded`请求批注以获取一个布尔值，该值指示与查询匹配的记录总数是否超出了所使用的表类型的最大页大小限制。详细信息：对行数进行计数
`Microsoft.Dynamics.CRM.globalmetadataversion`	可以在应用程序中缓存此批注。值在发生任何架构更改时发生更改，指示可能需要刷新应用程序缓存的任何架构数据。详细信息：缓存架构数据
`Microsoft.PowerApps.CDS.ErrorDetails.OperationStatus` `Microsoft.PowerApps.CDS.ErrorDetails.SubErrorCode` `Microsoft.PowerApps.CDS.HelpLink` `Microsoft.PowerApps.CDS.TraceText` `Microsoft.PowerApps.CDS.InnerError.Message`	返回错误时，这些批注会提供更详细的信息。详细信息：包含更多有关错误的详细信息

若要请求特定批注，请将它们作为逗号分隔的值包含在内。还可以将“”*字符用作通配符。例如，以下 Prefer 请求标头仅包含经过格式化的值和任何附加的错误细节注释：

Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue,Microsoft.PowerApps.CDS.ErrorDetails*"

小窍门

若要返回所有批注，请使用 Prefer: odata.include-annotations="*" 请求标头。

其他标头

Header	价值	说明
`CallerObjectId`	用户 Microsoft Entra ID 对象 ID	当调用方具有执行此项操作的权限时，使用此请求头冒充另一个用户。将值设置为要模拟的用户 Microsoft Entra ID 对象 ID。此数据位于 User （SystemUser）表/实体 AzureActiveDirectoryObjectId 属性（column）中。详细信息：使用 Web API 模拟其他用户。
`If-Match`	`Etag` 值或 `*`	使用此标头应用乐观并发，以确保您不会覆盖自检索记录以来其他人在服务器上所做的更改。更多信息：应用乐观并发和 If-Match。您还可以将此标头与 `*` 一起使用，以防止 `PATCH` 操作创建记录。更多信息：防止 upsert 操作创建记录。
`If-None-Match`	`null` 或 `*`	此标头应用于所有请求，且其值应为`null`，如HTTP 标头中所述，但也可用于防止`POST`操作执行更新。更多信息：防止在 upsert 中更新和 If-None-Match。
`MSCRM.SolutionUniqueName`	解决方案唯一名称	如果要创建解决方案组件并将其与非托管解决方案相关联，请使用此标头。详细信息：使用 Web API 创建和更新表定义。
`MSCRM.SuppressDuplicateDetection`	`false`	将此标头与值 `false` 一起使用，以便在创建或更新记录时启用重复检测。详细信息：检查是否有重复记录。
`MSCRM.BypassCustomPluginExecution`	`true`	如果想要绕过自定义插件代码，并且调用方具有 `prvBypassCustomPlugins` 权限，请使用此标头。详细信息：绕过自定义业务逻辑。
`Consistency`	`Strong`	如果必须具有缓存项的最新版本，请使用此标头。缓存的项包括元数据定义、标签、用户权限和团队权限。例如，如果对某些元数据定义、标签或权限应用更改，并且代码必须在更改后的 30 秒内使用最新定义，请使用此标头来确保获得最新版本。使用此标头会产生较小的性能损失，因此不要一直使用它。

执行批处理操作时，您必须在请求中应用许多不同的标头，并在正文中发送的每个部分中应用这些标头。详细信息：使用 Web API 执行批处理作。

标识状态代码

无论 HTTP 请求是成功还是失败，响应都包含状态代码。下表描述了 Microsoft Dataverse Web API 返回的状态代码。

Code	说明	类型
`200 OK`	当操作在响应正文中返回数据时，请预期此状态码。	成功
`201 Created`	当您的实体 POST 操作成功，并且您在请求中指定了 `return=representation` 首选项时，您可以预期将收到此状态代码。	成功
`204 No Content`	当你的操作成功但没有在响应体中返回数据时，预期将收到此状态代码。	成功
`304 Not Modified`	预期在测试实体自上次检索以来是否已修改时使用此状态代码。详细信息：条件检索	重定向
`403 Forbidden`	对于以下类型的错误，预期此状态代码： - `AccessDenied` - `AttributePermissionReadIsMissing` - `AttributePermissionUpdateIsMissingDuringUpdate` - `AttributePrivilegeCreateIsMissing` - `CannotActOnBehalfOfAnotherUser` - `CannotAddOrActonBehalfAnotherUserPrivilege` - `CrmSecurityError` - `InvalidAccessRights` - `PrincipalPrivilegeDenied` - `PrivilegeCreateIsDisabledForOrganization` - `PrivilegeDenied` - `unManagedinvalidprincipal` - `unManagedinvalidprivilegeedepth`	客户端错误
`401 Unauthorized`	对于以下类型的错误，预期此状态代码： - `BadAuthTicket` - `ExpiredAuthTicket` - `InsufficientAuthTicket` - `InvalidAuthTicket` - `InvalidUserAuth` - `MissingCrmAuthenticationToken` - `MissingCrmAuthenticationTokenOrganizationName` - `RequestIsNotAuthenticated` - `TamperedAuthTicket` - `UnauthorizedAccess` - `UnManagedInvalidSecurityPrincipal`	客户端错误
`413 Payload Too Large`	当请求长度过大时，会出现此状态代码。了解请求和响应有效负载大小限制	客户端错误
`400 BadRequest`	当参数无效时，预期此状态代码。	客户端错误
`404 Not Found`	当资源不存在时，预期会收到此状态码。	客户端错误
`405 Method Not Allowed`	对于不正确的方法和资源组合，会出现此错误。例如，不能对实体集合使用 DELETE 或 PATCH。对于以下类型的错误，预期会出现这种情况： - `CannotDeleteDueToAssociation` - `InvalidOperation` - `NotSupported`	客户端错误
`412 Precondition Failed`	对于以下类型的错误，预期此状态代码： - `ConcurrencyVersionMismatch` - `DuplicateRecord`	客户端错误
`429 Too Many Requests`	当 API 限制被超出时，可以预期此状态代码。详细信息：服务保护 API 限制	客户端错误
`501 Not Implemented`	当某些请求的操作未实现时，可以预期会收到此状态代码。	服务器错误
`503 Service Unavailable`	当 Web API 服务不可用时，预期会出现此状态代码。	服务器错误

分析响应中的错误

响应中包含有关错误的详细信息，格式为 JSON 格式。

{  
 "error":{  
  "code": "<This code is not related to the http status code and is frequently empty>",  
  "message": "<A message describing the error>"  
 }  
}

包含更多有关错误的详细信息

有些错误通过批注包含更多详细信息。当请求包含 Prefer: odata.include-annotations="*" 标头时，响应将包括包含有关错误的更多详细信息的所有批注，以及一个 URL，这些批注可能会指示你针对错误的特定指南。

编写插件的开发人员可以设置其中一些详细信息。例如，假设你有一个插件，该插件使用 InvalidPluginExecutionException（OperationStatus、Int32、String）构造函数引发错误。此构造函数接受值 OperationStatus 、自定义整数错误代码和错误消息。

简单的插件可能如下所示：

namespace MyNamespace
{
    public class MyClass : IPlugin
    {
        public void Execute(IServiceProvider serviceProvider)
        {

            // Obtain the tracing service
            ITracingService tracingService =
            (ITracingService)serviceProvider.GetService(typeof(ITracingService));

            tracingService.Trace("Entering MyClass plug-in.");

             try
            {
                throw new InvalidPluginExecutionException(OperationStatus.Canceled, 12345, "Example Error Message.");
            }
            catch (InvalidPluginExecutionException ex)
            {
                tracingService.Trace("StackTrace:");
                tracingService.Trace(ex.StackTrace);
                throw ex;
            }
        }
    }
}

在帐户实体的“创建”消息中注册此插件时，创建帐户的请求包括 odata.include-annotations="*" 首选项，请求和响应如以下示例所示：

请求：

POST https://yourorg.api.crm.dynamics.com/api/data/v9.2/accounts HTTP/1.1
Content-Type: application/json;
Prefer: odata.include-annotations="*"
{
    "name":"Example Account"
}

响应：

HTTP/1.1 400 Bad Request
Content-Type: application/json; odata.metadata=minimal
{
    "error": {
        "code": "0x80040265",
        "message": "Example Error Message.",
        "@Microsoft.PowerApps.CDS.ErrorDetails.OperationStatus": "1",
        "@Microsoft.PowerApps.CDS.ErrorDetails.SubErrorCode": "12345",
        "@Microsoft.PowerApps.CDS.HelpLink": "http://go.microsoft.com/fwlink/?LinkID=398563&error=Microsoft.Crm.CrmException%3a80040265&client=platform",
        "@Microsoft.PowerApps.CDS.TraceText": "\r\n[MyNamespace: MyNamespace.MyClass ]\r\n[52e2dbb9-85d3-ea11-a812-000d3a122b89: MyNamespace.MyClass : Create of account] \r\n\r\n Entering MyClass plug-in.\r\nStackTrace:\r\n   at MyNamespace.MyClass.Execute(IServiceProvider serviceProvider)\r\n\r\n"
        "@Microsoft.PowerApps.CDS.InnerError.Message": "Example Error Message."
    }
}

下表描述了响应中的批注。

批注和说明	价值
`@Microsoft.PowerApps.CDS.ErrorDetails.OperationStatus` OperationStatus由InvalidPluginExecutionException（OperationStatus，Int32，String）构造函数设置的值。	`1`
`@Microsoft.PowerApps.CDS.ErrorDetails.SubErrorCode` 由InvalidPluginExecutionException（OperationStatus， Int32， String）构造函数设置的`SubErrorCode` 值。	`12345`
`@Microsoft.PowerApps.CDS.HelpLink` 包含有关错误的信息的 URL，可能会重定向到有关如何解决错误的指南。	`http://go.microsoft.com/fwlink/?LinkID=398563&error=Microsoft.Crm.CrmException%3a80040265&client=platform`
`@Microsoft.PowerApps.CDS.TraceText` 使用 ITracingService.Trace（String， Object[]）方法写入插件跟踪日志的内容。此批注包括插件的堆栈跟踪，因为插件作者记录了它。	`[MyNamespace: MyNamespace.MyClass ]` `[52e2dbb9-85d3-ea11-a812-000d3a122b89: MyNamespace.MyClass :Create of account]` `Entering MyClass plug-in.` `StackTrace:` `at MyNamespace.MyClass.Execute(IServiceProvider serviceProvider)`
`@Microsoft.PowerApps.CDS.InnerError.Message` 异常的 InnerError 中包含的错误消息。此消息应与错误消息相同，但某些特殊情况下仅供内部使用。	`Example Error Message.`

注释

@Microsoft.PowerApps.CDS.HelpLink不能保证为每个错误提供指导。 指导可以主动提供，但最常见的是根据链接的使用频率以被动方式提供。使用链接。如果未提供指导，您的使用此链接有助于产品团队了解用户需要更多关于错误的指导。团队可以据此优先为用户最需要的错误添加指导说明。链接可能指向的资源可能是文档、社区资源的链接或外部网站。

如果不想在响应中接收所有批注，可以指定要返回的批注。请使用以下值，而不是Prefer: odata.include-annotations="*"，以便仅在检索数据时接收格式化值，并在发生错误时获取帮助链接：Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue,Microsoft.PowerApps.CDS.HelpLink"。

详细信息：请求批注

从 Web API 添加共享变量

可以在SharedVariables集合中设置一个字符串值，该值可供ExecutionContext插件使用。有关详细信息，请参见:

另请参阅

使用 Web API 执行操作
 使用 Web API 查询数据
 使用 Web API 创建表行
 使用 Web API 检索表行
 使用 Web API 更新和删除表行
 使用 Web API 关联和取消关联表行
 使用 Web API 函数
 使用 Web API 操作
 使用 Web API 执行批处理作
 使用 Web API 模拟其他用户
 使用 Web API 执行条件操作。

反馈

此页面是否有帮助？

Last updated on 2026-03-11