Устранение ошибок клиента веб-API Dataverse

В этой статье описываются распространенные ошибки клиента, которые могут возникнуть при использовании веб-API Dataverse и способах их предотвращения.

Ресурс не найден для сегмента

Симптомы

Запросить

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

Response

HTTP/1.1 404 Not Found

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

Причина

Эта ошибка возникает при использовании неправильного имени ресурса. Этот ресурс может быть именем набора сущностей, функции или действия. Эти имена ресурсов чувствительны к регистру. В предыдущем примере существует набор сущностей, который называется accounts, но не один с именем Account.

Если ресурс является действием, определенным как настраиваемое действие процесса, эта ошибка также может произойти, если настраиваемое действие процесса неактивно.

Как избежать

• Если ресурс является типом сущности, запросите документ службы веб-API, который предоставляет список всех известных имен наборов сущностей.
• Если ресурс является функцией или действием, убедитесь, что используемое имя существует в документе CSDL $metadata.
• Если действие не существует в документе CSDL $metadata, это может быть неактивное пользовательское действие процесса. Убедитесь, что он активен.

Не удалось найти свойство "{property name}" в типе Microsoft.Dynamics.CRM. {имя сущности}'

Симптомы

Запросить

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

Response

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. Дополнительные сведения см. в свойствах веб-API.

Ресурс HTTP не найден, соответствующий универсальному коду ресурса (URI) запроса

Симптомы

Запросить

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

Response

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 для использования. Дополнительные сведения см. в разделе:

• Действия веб-API
• Использование действий веб-API
• Функции веб-API
• Использование функций веб-API

Недопустимое свойство {имя свойства} найдено в сущности Microsoft.Dynamics.CRM. {имя сущности}'

Симптомы

Запросить

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

{
 "Name": "Account name"
}

Response

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. Дополнительные сведения см. в свойствах веб-API.

Ошибка, обнаруженная в полезных данных, предоставленных пользователем для сущности "{имя сущности}"

Существует два отдельных проблемы, которые могут возникнуть с этой ошибкой. Разница в InnerException.

• InnerException: Microsoft.OData.ODataException: необъявленное свойство [...] было найдено в полезных данных.
• InnerException: System.ArgumentException: Stream не был читаемым.

InnerException : Microsoft.OData.ODataException: необъявленное свойство [...] было найдено в полезных данных

Эта ошибка возникает при отправке недопустимого имени свойства навигации с запросом.

Симптомы

Запросить

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

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

Response

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. Дополнительные сведения см. в разделе "Свойства навигации веб-API", особенно в разделе поиска с несколькими таблицами .

InnerException: System.ArgumentException: Stream не был удобочитаемым

Эта ошибка возникает при выполнении пакетных операций.

Симптомы

При отправке $batch запроса возникает следующая ошибка.

Response

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.

В этом случае просто добавление возврата каретки в конце последней строки достаточно, чтобы сделать его успешным.

Как избежать

Убедитесь, что все конец строки в тексте $batchCRLFзапроса. Если не удается использоватьCRLF, добавьте две не конец строкиCRLF в конце текста пакетного запроса, чтобы устранить эту ошибку десериализации. Дополнительные сведения см. в разделе "Пакетные запросы".

Ошибка, обнаруженная в значении "odata.include-annotations" внутри заголовка "Prefer"

Симптомы

Ошибка возникает, когда веб-API Dataverse получает запрос с недопустимым odata.include-annotations значением в значении заголовка Prefer запроса. Эта проблема возникает, когда запрос отправляется с помощью методов , PATCHPUTили GET HTTP с POSTзаголовком Prefer запроса, содержащим недопустимое или неправильно отформатированное значение.

В следующем примере odata.include-annotations значение неправильно включает обратные очки (\), чтобы избежать символов кавычки.

Запросить

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

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

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

Response

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"
}

Причина

Чтобы обеспечить более безопасную службу, мы исправим проблему, из-за которой недопустимые Prefer значения заголовков запросов обрабатываются без проверки при использовании POSTметодов HTTP или PUT , PATCH Теперь проверка применяется для всех методов HTTP. Эта ошибка возникает начиная с Dataverse версии 9.2.2412.3, которая начинает развертывание в январе 2025 года и будет развернута во всех регионах к февралю 2025 года.

Как избежать

Ознакомьтесь с рекомендациями по правильному настройке заголовков Prefer в веб-API Dataverse.

См. также

• Типы и операции веб-API
• Создание HTTP-запросов и обработка ошибок