Dataverse Web API 客户端错误的故障排除

总结

本文介绍使用 Dataverse Web API 时可能会遇到的常见客户端错误，以及如何避免这些错误。 这些错误包括找不到资源、属性名称无效、HTTP 方法不正确、有效负载错误和标头值无效 Prefer 。 每个部分提供有关如何避免错误的症状、原因和指导。

找不到段的资源

现象

Request

GET [Organization URI]/api/data/v9.2/Account HTTP/1.1

响应

HTTP/1.1 404 Not Found

{
 "error": {
  "code": "0x8006088a",
  "message": "Resource not found for the segment 'Account'."
 }
}

原因

使用资源的名称不正确时，会发生此错误。 该资源可能是实体集、函数或操作的名称。 这些资源名称区分大小写。 在前面的示例中，有一个称为 accounts实体集，但没有一个命名 Account的实体集。

如果资源是定义为 自定义进程操作的操作，则如果自定义进程操作处于非活动状态，也可能发生此错误。

如何避免

• 如果资源是实体类型，请查询 Web API 服务文档，该文档 提供所有已知实体集名称的列表。
• 如果资源是函数或操作，请验证你使用的名称是否存在于 CSDL $metadata 文档中。
• 如果 CSDL $metadata 文档中不存在该操作，则可能是非活动自定义进程操作。 应验证它是否处于活动状态。

在类型“Microsoft.Dynamics.CRM”上找不到名为“{property name}”的属性。{entity name}'

现象

Request

GET [Organization URI]/api/data/v9.2/accounts?$select=Name HTTP/1.1

响应

HTTP/1.1 400 Bad Request

{
 "error": {
  "code": "0x0",
  "message": "Could not find a property named 'Name' on type 'Microsoft.Dynamics.CRM.account'."
 }
}

原因

当您使用了不正确的属性名称时，会发生这个错误。 属性名称区分大小写。

在前面的示例中，有一个名为name的属性，但没有名为Name的属性。

如何避免

验证你使用的名称是否存在于 CSDL $metadata 文档中。 有关详细信息，请参阅 Web API 属性。

找不到与请求 URI 匹配的 HTTP 资源

现象

Request

POST [Organization URI]/api/data/v9.2/WhoAmI

响应

HTTP/1.1 404 Not Found

{
 "error": {
  "code": "",
  "message": "No HTTP resource was found that matches the request URI '[Organization URI]/api/data/v9.2/WhoAmI'."
 }
}

原因

当将不正确的 HTTP 方法应用于函数或操作时，会发生此错误。 在这种情况下，WhoAmI 函数 需要使用 GET，然而却使用了 POST。

如何避免

请注意所使用的 OData 操作类型以及要使用的正确 HTTP 方法。 有关详细信息，请参阅：

• Web API 操作
• 使用 Web API 操作
• Web API 函数
• 使用 Web API 函数

在实体 'Microsoft.Dynamics.CRM.{entity name}' 中找到的属性 {property name} 是无效的。

现象

Request

POST [Organization URI]/api/data/v9.2/accounts HTTP/1.1

{
 "Name": "Account name"
}

响应

HTTP/1.1 400 Bad Request

{
 "error": {
  "code": "0x0",
  "message": "An error occurred while validating input parameters: 
    Microsoft.Crm.CrmException: Invalid property 'Name' was found in entity 'Microsoft.Dynamics.CRM.account'. 
    ---> Microsoft.OData.ODataException: Does not support untyped value in non-open type.<truncated for brevity>"
 }
}

原因

发生此错误的原因是使用了属性的名称不正确。 属性名称是区分大小写的，Name 被使用而不是 name。

如何避免

验证所使用的属性名称是否存在于 CSDL $metadata 文档中。 有关详细信息，请参阅 Web API 属性。

用户为实体“{实体名称}”提供的有效负载中标识的错误

出现此错误时可能会出现两个单独的问题。 区别在于 InnerException。

• InnerException ： Microsoft.OData.ODataException： 在有效负载中发现了未声明的属性 } 。
• InnerException ： System.ArgumentException： Stream 不可读。

InnerException ： Microsoft.OData.ODataException： 在数据负载中找到未声明的属性 ...

当请求中包含无效的导航属性名称时，会发生此错误。

现象

Request

POST [Organization URI]/api/data/v9.2/contacts HTTP/1.1

{
  "firstname":"test",
  "lastname":"contact",
  "parentcustomerid@odata.bind": "accounts(a779956b-d748-ed11-bb44-6045bd01152a)"
}

响应

HTTP/1.1 400 Bad Request

{
    "error": {
        "code": "0x80048d19",
        "message": "Error identified in Payload provided by the user for Entity :'contacts'  ---->  
        InnerException : Microsoft.OData.ODataException: An undeclared property 'parentcustomerid' 
        which only has property annotations in the payload but no property value was found in the payload. 
        In OData, only declared navigation properties and declared named streams can be represented as 
        properties without values <truncated for brevity>".
    }
}

原因

发生此错误的原因是联系人实体类型中没有名为 parentcustomerid 的单值导航属性。 有关详细信息，请参阅 单值导航属性。

parentcustomerid 是联系人表中查找列的逻辑名称。 所有查找在 OData 中都有一个或多个单值导航属性。 查找属性的名称并不总是与相应的单值导航属性名称匹配。

在这种情况下， parentcustomerid 该列是客户查找类型，它是一种 多表查找 ，可能链接到帐户表或联系人表。 为了支持此客户信息查询，存在两个独立的关系，每个关系具有不同的单一值导航属性。 在这种情况下，正确的单值导航属性为 parentcustomerid_account。

如何避免

验证使用的导航属性名称是否存在于 CSDL $metadata 文档中。 有关详细信息，请参阅 Web API 导航属性，尤其是 多表查找 部分。

InnerException ： System.ArgumentException： Stream 不可读

执行批处理操作时会出现此错误。

现象

发送 $batch 请求时收到以下错误。

响应

HTTP/1.1 400 Bad Request

--batchresponse_5bd81edb-2ef9-4269-85c3-4623981e6c6e
Content-Type: application/http
Content-Transfer-Encoding: binary

HTTP/1.1 400 Bad Request
REQ_ID: 4c8c75eb-10bf-47f9-9998-c119146d511f
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0

{"error":{"code":"0x80048d19","message":"Error identified in Payload provided by the user for Entity :'accounts',
For more information on this error please follow this help link https://go.microsoft.com/fwlink/?linkid=2195293
---->  InnerException : System.ArgumentException: Stream was not readable.\r\n
at System.IO.StreamReader..ctor(Stream stream, Encoding encoding, Boolean detectEncodingFromByteOrderMarks, Int32 bufferSize, Boolean leaveOpen)\r\n
at System.IO.StreamReader..ctor(Stream stream, Encoding encoding)\r\n
at Microsoft.OData.JsonLight.ODataJsonLightInputContext.CreateTextReader(Stream messageStream, Encoding encoding)\r\n
at Microsoft.OData.JsonLight.ODataJsonLightInputContext..ctor(ODataMessageInfo messageInfo, ODataMessageReaderSettings messageReaderSettings)\r\n
at Microsoft.OData.Json.ODataJsonFormat.CreateInputContext(ODataMessageInfo messageInfo, ODataMessageReaderSettings messageReaderSettings)\r\n
at Microsoft.OData.ODataMessageReader.ReadFromInput[T](Func`2 readFunc, ODataPayloadKind[] payloadKinds)\r\n
at System.Web.OData.Formatter.Deserialization.ODataResourceDeserializer.Read(ODataMessageReader messageReader, Type type, ODataDeserializerContext readContext)\r\n
at System.Web.OData.Formatter.ODataMediaTypeFormatter.ReadFromStream(Type type, Stream readStream, HttpContent content, IFormatterLogger formatterLogger)."}}
--batchresponse_5bd81edb-2ef9-4269-85c3-4623981e6c6e--

原因

在批处理请求正文中使用非CRLF的行结束符会导致出现这种反序列化错误。

根据所使用的编辑器，这些非打印字符可能很难看到。 如果使用 记事本++，可以使用“ 显示所有字符 ”选项来显示这些字符。

此有效负载可以正常运行。

此有效负载失败，因为最后一行没有以CRLF结尾。

在这种情况下，只需在最后一行末尾添加换行符就足以使操作成功。

如何避免

确保请求正文中的所有行结束符为CRLF。 如果无法使用CRLF，请在批处理请求正文末尾添加两个非CRLF行结束符，以解决此反序列化错误。 有关详细信息，请参阅 Batch 请求。

在“Prefer”标头中，标识为“odata.include-annotations”的值存在错误。

现象

当 Dataverse Web API 接收到请求，在请求头中包含无效的odata.include-annotations值时，会发生此错误。 当使用POST、PATCH、PUT或GET这些HTTP方法发送请求，并且请求头Prefer中包含无效或格式不正确的值时，会出现此问题。

在下面的示例中， odata.include-annotations 值错误地包括反斜杠（\）以转义引号字符。

Request

POST [Organization URI]/api/data/v9.2/contacts HTTP/1.1

Prefer: odata.include-annotations=\"*\"

{
  "firstname":"test",
  "lastname":"contact"
}

响应

HTTP/1.1 400 Bad Request

{
  "Message": "Error identified on the 'odata.include-annotations' value inside the 'Prefer' header. 
  Refer to the following link for more details: https://go.microsoft.com/fwlink/?linkid=2300109. 
  See exception message for more details 'An error occurred when parsing the HTTP header 'Prefer'. The header value 'odata.include-annotations=\\\"*\\\"' is incorrect at position '26' because the escape character '\\' is not inside a quoted-string.'.",
  "ErrorCode": "0x80097303"
}

原因

为了提供更安全的服务，我们修复了一个问题：在使用POST、PATCH或PUT HTTP 方法时，处理无效Prefer请求标头值未经过验证。 现在，对所有 HTTP 方法强制实施验证。 此错误从 Dataverse 版本 9.2.2412.3 开始于 2025 年 1 月开始部署，到 2025 年 2 月将部署到所有区域。

如何避免

请查看关于如何在 Dataverse Web API 中正确设置 Prefer 标头的指南。

另请参阅

• Web API 类型和操作
• 编写 HTTP 请求并处理错误