Интеграция с внешними системами > Запросы к сервису интеграции > Получение сущностей

При чтении сущности сервис интеграции в ответе не передает значения свойств с типом «Коллекция». Это экономит трафик. Чтобы получить свойства-коллекции, используйте в запросе параметр $expand.

Формат GET-запроса такой же, как для получения значений свойств-ссылок. Пример:

GET /Integration/odata/ISupAgreements?$expand=Versions HTTP/1.1
Host: DirectumRXServer.com
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json
Accept: application/json

В ответе придут сущности с развернутой информацией для свойства-коллекции Версии (Versions).

{
    "@odata.context": "https://DirectumRXServer.com/odata/$metadata#ISupAgreements(Versions())",
    "value": [
        {
            "Name": "Доп. соглашение №1 от 12.05.2021 к договор аренды №001-2021 с Рим \"График технического обслуживания\"",
            "Created": "2021-05-12T09:24:57Z",
            "Modified": "2021-05-12T10:08:18Z",
            "HasRelations": true,
            "LastVersionSignatureType": null,
            "LastVersionApproved": false,
            "HasVersions": true,
            "HasPublicBody": false,
            "VersionsLocked": false,
            "Id": 83,
            ...
            "Versions": [
                {
                    "Number": 1,
                    "Note": "Первоначальная версия",
                    "Created": "2021-05-12T09:24:41Z",
                    "Modified": "2021-05-12T09:24:57Z",
                    "Id": 49
                },
                {
                    "Number": 2,
                    "Note": "Версия 2",
                    "Created": "2021-05-12T10:07:40Z",
                    "Modified": "2021-05-12T10:07:40Z",
                    "Id": 50
                },
                {
                    "Number": 3,
                    "Note": "Итоговый вариант",
                    "Created": "2021-05-12T10:07:53Z",
                    "Modified": "2021-05-12T10:07:53Z",
                    "Id": 51
                }
            ]
        }
    ]
}

Если после наследования или перекрытия в потомке в свойство-коллекцию добавить новое дочернее свойство, то у потомка в метаданных OData появится новое свойство-коллекция с именем: <Имя типа сущности потомка><Имя свойства-коллекции>. Например, у типа сущности «Служебная записка» (Memo) есть свойство-коллекция Выдача (Tracking). Тип сущности перекрыли и в коллекцию добавили новое дочернее свойство. В метаданных появилось новой свойство-коллекция с именем:

В этом случае при запросе к Memo можно обратиться и к свойству Tracking, и к свойству MemoTracking:

GET /Integration/odata/IMemos?$expand=Tracking,MemoTracking HTTP/1.1
Host: DirectumRXServer.com
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json
Accept: application/json

В ответе придут обе коллекции, но в коллекции MemoTracking будет новое добавленное свойство ChildPropertyDEV.

{
    "@odata.context": "https://DirectumRXServer.com/odata/$metadata#IMemos(Tracking(),MemoTracking())",
    "value": [
        {
            "Name": "Служебная записка №1 от 12.05.2021 \"О выдаче рабочей бригаде временного пропуска в офис\"",
            "Created": "2021-05-12T12:51:23Z",
            "Modified": "2021-05-12T12:54:12Z",
            "HasRelations": false,
            "LastVersionSignatureType": null,
            "LastVersionApproved": false,
            "HasVersions": true,
            "HasPublicBody": false,
            "VersionsLocked": false,
            "Id": 88,
            ...
            "Tracking": [
                {
                    "IsOriginal": true,
                    "ReturnDeadline": "2021-05-26T00:00:00Z",
                    "ReturnDate": "2021-05-12T00:00:00Z",
                    "DeliveryDate": "2021-05-12T00:00:00Z",
                    "Note": null,
                    "Iteration": null,
                    "ExternalLinkId": null,
                    "Action": "Delivery",
                    "ReturnResult": "AtControl",
                    "Id": 6
                }
            ],
            "MemoTracking": [
                {
                    "IsOriginal": true,
                    "ReturnDeadline": "2021-05-26T00:00:00Z",
                    "ReturnDate": "2021-05-12T00:00:00Z",
                    "DeliveryDate": "2021-05-12T00:00:00Z",
                    "Note": null,
                    "Iteration": null,
                    "ExternalLinkId": null,
                    "Action": "Delivery",
                    "ReturnResult": "AtControl",
                    "Id": 6,
                    "ChildPropertyDEV": null
                }
            ]
        }
    ]
}

Рекомендуется в параметре $expand указывать только одно однотипное свойство-коллекцию в зависимости от нужного вам состава дочерних свойств. Иными словами, в примере выше рекомендуется в запросе указывать только свойство Tracking или MemoTracking.

Чтение дочерних свойств «Бинарные данные в хранилище», «Бинарные данные», «Картинка» и «Ссылка»

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

•Бинарные данные в хранилище;

•Бинарные данные;

•Картинка;

•Ссылка.

Чтобы получить их в виде строки, закодированной в формате Base64, используйте в запросе параметр $expand.

Дочерние свойства с типом Бинарные данные, Бинарные данные в хранилище и Картинка также можно получить в виде потока данных – последовательности байтов без кодирования.

Чтение дочерних свойств в виде строки

Чтобы получить дочернее бинарное свойство в виде строки, закодированной в формат Base64, используйте GET-запрос с параметром $expand и укажите имя дочернего свойства.

Формат URL:

{Протокол https или http}://{имя сервера, на котором установлен сервис интеграции}/{имя сервиса интеграции}/odata/{Интерфейс типа сущности во множественном числе}?$expand={Имя свойства-коллекции}($expand={Имя дочернего свойства с типом Бинарные данные в хранилище, Бинарные данные, Картинка или Ссылка})

Учитывайте ограничения при написании запроса.

Пример

У типа документа «Дополнительное соглашение» (SupAgreement) в свойстве-коллекции Версии (Versions) добавлено дочернее свойство Текст (Body). Дочернее свойство имеет тип Бинарные данные в хранилище. Чтобы получить все документы типа SupAgreement со свойством-коллекцией Versions и дочерним бинарным свойством Body, напишите запрос:

GET /Integration/odata/ISupAgreements?$expand=Versions($expand=Body) HTTP/1.1
Host: DirectumRXServer.com
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json
Accept: application/json

Для получения документа типа SupAgreement с идентификатором 83, со свойством-коллекцией Versions и дочерним бинарным свойством Body используйте запрос:

GET /Integration/odata/ISupAgreements(83)?$expand=Versions($expand=Body) HTTP/1.1
Host: DirectumRXServer.com
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json
Accept: application/json

В последнем запросе в ответе придет дополнительное соглашение с развернутой информацией для свойства-коллекции Versions. В каждой записи свойства-коллекции будет раскрыта информация для свойства Body с типом Бинарные данные в хранилище.

{
    "@odata.context": "https://DirectumRXServer.com/odata/$metadata#ISupAgreements(Versions(Body()))/$entity",
    "Name": "Доп. соглашение №1 от 12.05.2021 к договор аренды №001-2021 с Рим \"График технического обслуживания\"",
    "Created": "2021-05-12T09:24:57Z",
    "Modified": "2021-05-12T10:08:18Z",
    "HasRelations": true,
    "LastVersionSignatureType": null,
    "LastVersionApproved": false,
    "HasVersions": true,
    "HasPublicBody": false,
    "VersionsLocked": false,
    "Id": 83,
    ...
    "Versions": [
        {
            "Number": 1,
            "Note": "Первоначальная версия",
            "Created": "2021-05-12T09:24:41Z",
            "Modified": "2021-05-12T09:24:57Z",
            "Id": 49,
            "Body": {
                "Id": "00000000-0000-0000-0000-000000000000",
                "Value": "UEsDBBQABAAIAGJivkClq/f+WgEAADMEAAATAAAAW0NvbnRlbnRfVHlwZXNdLnht7DMx4EhcgUkCSEFVaV8/...
            }
        },
        {
            "Number": 2,
            "Note": "Версия 2",
            "Created": "2021-05-12T10:07:40Z",
            "Modified": "2021-05-12T10:07:40Z",
            "Id": 50,
            "Body": {
                "Id": "00000000-0000-0000-0000-000000000000",
                "Value": "UEsDBBQABAAIAGJivkClq/f+WgEAADMEAAATAAAAW0NvbnRlbnRfVHlwZXNdLnhtbKyXtgp8ldFEOYOxJY9Wx/...
            }
        },
        {
            "Number": 3,
            "Note": "Итоговый вариант",
            "Created": "2021-05-12T10:07:53Z",
            "Modified": "2021-05-12T10:07:53Z",
            "Id": 51,
            "Body": {
                "Id": "00000000-0000-0000-0000-000000000000",
                "Value": "UEsDBBQABAAIAGJivkClq/f+WgEAADMEAAATAAAAW0NvbnRlbnRfVHlwZXK3LJACCXtgp8ldFEOYOxJBRy8+S/...
            }
        }
    ]
}

Если у документа много версий, а нужно получить тело только одной версии, используйте запрос формата:

GET /Integration/odata/ISupAgreements(83)/Versions(51)?$expand=Body HTTP/1.1
Host: DirectumRXServer.com
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json
Accept: application/json

Где 83 – идентификатор документа, а 51 – идентификатор версии документа, у которой нужно получить содержимое.

Запрос дочерних свойств Бинарные данные, Картинка и Ссылка с помощью параметра $expand выполняются аналогично.

Чтение дочерних бинарных свойств в виде потока данных

Чтобы получить дочерние свойства коллекции с типом Бинарные данные, Бинарные данные в хранилище и Картинка в виде последовательности байтов без кодирования, напишите GET-запрос c параметром $value. В обязательном заголовке Content-Type укажите значение application/octet-stream.

Формат URL:

{Протокол https или http}://{имя сервера, на котором установлен сервис интеграции}/{имя сервиса интеграции}/odata/{Интерфейс типа сущности во множественном числе}(ИД)/{Имя свойства-коллекции}(ИД записи свойства-коллекции)/{Имя свойства с типом Бинарные данные в хранилище, Бинарные данные или Картинка}/$value

Учитывайте ограничения при написании запроса.

Пример

Чтобы получить содержимое свойства-коллекции Версии (Versions) для простого документа (SimpleDocument), напишите запрос:

GET /Integration/odata/ISimpleDocuments(1013)/Versions(5)/Body/$value HTTP/1.1
Host: DirectumRXServer.com
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/octet-stream
Accept: application/json

Где 1013 – идентификатор документа, а 5 – идентификатор версии документа, у которой нужно получить содержимое.

В теле ответа будет последовательность байтов без кодировки:

ceXQ3dnPCeerjWh0vr1123RA5ztaL8bsPvrBe2ZCqrvAlJbhfFnOs2HGQrk…

Чтение свойства-коллекции

Чтение свойства-коллекции