通过

撰写 HTTP 请求并处理错误

  • 项目

 

发布日期： 2017年1月

适用于： Dynamics 365 (online),Dynamics 365 (on-premises),Dynamics CRM 2016,Dynamics CRM Online

您通过撰写并发送 HTTP 请求与 Web API 交互。 您需要知道如何设置相应的 HTTP 标头并处理响应中的任何错误。

本主题内容

Web API URL 和版本

HTTP 方法

HTTP 标头

识别状态代码

解析响应错误

Web API URL 和版本

若要访问 Web API，必须使用下表中的组件编制 URL。

项

说明

协议

相应的协议（https:// 或 http://）。

基 URL

这是通常用于打开 Web 应用程序的 URL。

  • 对于 Microsoft Dynamics 365 (online)：使用 <tenant name>.crm.dynamics.com。

  • 对于 面向 Internet 的部署 (IFD)：使用适合您的实例的 URL。 即：<organization name>.<domain name>。

  • 对于 Dynamics 365（本地）：使用 <server name>/<organization name>

Web API 路径

此 Web API 的路径为 /api/data/。

版本

版本表示为：v[Major_version].[Minor_version][PatchVersion]/。 此发行版的有效版本为：

  • v8.0/ 对于 Microsoft Dynamics CRM Online 2016 更新 0.1 和 Microsoft Dynamics CRM 2016 更新 0.1

  • v8.1/ 对于 Microsoft Dynamics CRM Online 2016 更新 1 和 Microsoft Dynamics CRM 2016 Service Pack 1

  • 适用于 Dynamics 365 的 2016 年 12 月更新（联机和本地） 的 v8.2/

只要您已应用了相应的更新或服务包，所用具体值对此版本不重要。 更多信息：版本兼容性

资源

要使用的实体、功能或操作的名称。

将使用的 URL 由以下部分组成：协议 + 基 URL + Web API 路径 + 版本 + 资源。

版本兼容性

在此版本中，已通过各更新或服务包应用了一些累加更改。 应用这些更新时，已将相同功能添加到了后续小版本中。 因此，如果可以使用版本 8.2，则版本 8.1 和 8.0 将具有相同功能。 这是因为，所有更改都已是累加的或是针对Microsoft Dynamics 365Web API 限制中列出的项的错误修复。 未引入重大更改。

备注

下一个主版本 (v9) 引入该版本独有的功能。 后续小版本可能提供更多功能，这些功能不向后移植到早期的小版本。 在所用 URL 中引用 v8.2 时，您为 v8.x 编写的代码在 v9.x 中继续有效。

对于 v8.x 版本，请尽量使用您知道在此主版本内的更新或服务包将不引入重大更改的最新版本。 但是这在将来的版本中则不然，到时需要更注意您面对的服务版本。

HTTP 方法

HTTP 请求可应用各种不同方法。 使用 Web API 时，您将只使用下表列出的方法。

方法

使用情况

GET

在检索数据（包括调用函数）时使用。 确保成功检索的预期状态代码为 200 OK。

POST

在创建实体或调用操作时使用。

PATCH

在更新实体或执行 upsert 操作时使用。

DELETE

在删除实体或实体的各个属性时使用。

PUT

在某些情况下用于更新实体的各个属性。 更新大多数实体时，不建议使用此方法。 您将在更新模型实体时使用此方法。

HTTP 标头

尽管 OData 协议支持 JSON 和 ATOM 两种格式，但 Web API 只支持 JSON。 因此，可应用以下标头。

即使预计没有响应正文，每个请求也都应包含值为 application/json 的 Accept 标头。 响应中返回的任何错误都将作为 JSON 返回。 虽然即使不包含此标头，您的代码也可用，但建议您最好包含此标头

当前 OData 版本为 4.0，但以后的版本可能会推出新功能。 为确保将在未来该时刻应用于代码的 OData 版本没有任何不明确之处，应始终包含应用于代码的当前 OData 版本以及最高版本的明确声明。 使用值设置为 4.0 的 OData-Version 和 OData-MaxVersion 标头。

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

Accept: application/json OData-MaxVersion: 4.0 OData-Version: 4.0

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

Content-Type: application/json

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

  • 要在实体的创建 (POST) 或更新 (PATCH) 操作中返回数据，请加入 return=representation 首选项。 如果将此首选项应用于 POST 请求，则成功响应的状态为 201 (Created)。 对于 PATCH 请求，成功响应的状态为 200 (OK)。 如果不应用该首选项，则两项操作都将返回状态 204 (No Content) 以表明响应正文中默认不返回任何数据。

    备注

    此功能是使用 适用于 Dynamics 365 的 2016 年 12 月更新（联机和本地） 添加的。

  • 若要通过查询返回格式化值，则使用首选标头包含设置为 Microsoft.Dynamics.CRM.formattedvalue 的 odata.include-annotations 首选项。详细信息：包含格式化值

  • 您也可以使用具有 odata.maxpagesize 选项的 Prefer 标头指定您要返回的页数。详细信息：指定在一个页面中返回的实体数

  • 若要在调用方拥有操作权限时模拟其他用户，请添加具有要模拟的用户的 systemuserid 值的 MSCRMCallerID 标头。详细信息：使用 Web API 模拟其他用户。

  • 若要应用乐观并发，您可以应用具有 Etag 值的 If-Match 标头。详细信息：应用乐观并发。

  • 若要为 POST 请求启用重复项检测，可使用 MSCRM.SuppressDuplicateDetection: false 标头。详细信息：244259ca-2fbc-4fd4-9a74-6166e6683355#bkmk_SuppressDuplicateDetection

  • 若要控制 upsert 操作实际应创建或更新实体，您还可以使用 If-Match 和 If-None-Match 标头。详细信息：Upsert 实体。

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

识别状态代码

无论 http 请求成功与否，响应都将包含一个状态代码。Microsoft Dynamics 365 Web API 返回的状态代码包含以下内容。

代码

说明

类型

200 OK

当您的操作将在响应正文中返回数据时，出现此结果。

成功

201 Created

实体 POST 操作成功且您已在请求中指定了 return-representation 首选项时应该返回此结果。

备注

此功能是使用 适用于 Dynamics 365 的 2016 年 12 月更新（联机和本地） 添加的。

成功

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

客户端错误

500 Internal Server Error

有关创建实体的 POST 请求启用重复项检测，并且要创建的实体为重复项时，将发生此错误。详细信息：244259ca-2fbc-4fd4-9a74-6166e6683355#bkmk_SuppressDuplicateDetection

服务器错误

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>", "innererror": { "message": "
            <A message describing the error, this is frequently the same as the outer message>", "type": "Microsoft.Crm.CrmHttpException", "stacktrace": "
            <Details from the server about where the error occurred>" } } }

另请参阅

使用 Web API 执行操作
使用 Web API 查询数据
使用 Web API 创建实体
使用 Web API 检索实体
使用 Web API 更新和删除实体
使用 Web API 关联和解除关联实体
使用 Web API 功能
使用 Web API 操作
使用 Web API 执行批处理操作
使用 Web API 模拟其他用户
使用 Web API 执行条件操作

Microsoft Dynamics 365

© 2017 Microsoft。 保留所有权利。 版权