排查 Dataverse Web API 客户端错误

项目
01/30/2025

本文介绍使用 Dataverse Web API 时可能会遇到的常见客户端错误，以及如何避免这些错误。

找不到段的资源

现象

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 方法。有关详细信息，请参阅：

在实体“Microsoft.Dynamics.CRM”中找到属性 {property name} 无效。{entity 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 的批处理请求正文的屏幕截图。

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

如何避免

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

在“Prefer”标头内的“odata.include-annotations”值上标识的错误

现象

当 Dataverse Web API 在请求标头值中Prefer收到具有无效odata.include-annotations值的请求时，会发生此错误。当使用包含无效或格式不正确的值的请求标头发送POSTGETPATCHPUT请求或 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"
}

原因

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

如何避免

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

通过

排查 Dataverse Web API 客户端错误

找不到段的资源

现象

原因

如何避免

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

现象

原因

如何避免

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

现象

原因

如何避免

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

现象

原因

如何避免

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

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

现象

原因

如何避免

InnerException ： System.ArgumentException： Stream 不可读

现象

原因

如何避免

在“Prefer”标头内的“odata.include-annotations”值上标识的错误

现象

原因

如何避免

另请参阅

反馈

其他资源

通过

排查 Dataverse Web API 客户端错误

找不到段的资源

现象

原因

如何避免

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

现象

原因

如何避免

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

现象

原因

如何避免

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

现象

原因

如何避免

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

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

现象

原因

如何避免

InnerException ： System.ArgumentException： Stream 不可读

现象

原因

如何避免

在“Prefer”标头内的“odata.include-annotations”值上标识的错误

现象

原因

如何避免

另请参阅

反馈

其他资源

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