Формирование API для внешних взаимодействий#
Базовые параметры API#
Согласно описанию схемы API, доступ к API осуществляется по пути, соответствующему шаблону:
http://{HOST}/{BASE}/hs/synapse/{PATH}/{CODE}?expand={EXPAND}
где:
HOST - адрес веб-сервера, на котором опубликовано Прикладное решение 1С;
BASE - путь на веб-сервере к опубликованному Прикладному решению 1С;
PATH - путь к сервису OCPL. Доступны сервисы получения изменений changes и отправки данных data;
CODE - код узла обмена;
EXPAND - параметр, отражающий необходимость дополнения ответа подробным описанием объекта. Необязательный параметр, по умолчанию - false.
Настройка сервиса получения изменений changes#
Сервис получения изменений changes доступен по пути
http://{HOST}/{BASE}/hs/synapse/changes/{CODE}?expand={EXPAND}
Запрос получения изменений#
При создании, изменении или удалении объектов типов, включенных в состав обмена узла обмена, OCPL регистрирует событие в базе данных и использует эту регистрацию для формирования ответа на запрос получения изменений.
При неверном указании CODE в ответ будет получен код 404 и описание ошибки в формате JSON:
{
"error": "Not found",
"message": "Не найден узел обмена с кодом 000000002"
}
При успешном выполнении запроса в заголовках ответа будет доступен заголовок RequestID, содержащий идентификатор запроса в виде строкового представления GUID. Этот GUID используется для привязки отправленных данных к конкретному запросу и последующих запросов подтверждения получения. Заголовок RequestID можно так же установить в запросе изменений - тогда данные, полученные в ответе, будут привязаны к указанному идентификатору и этот идентификатор должен использоваться для последующих запросов подтверждения получения. Заголовок RequestID имеет ограничение длины в 36 символов, но не накладывает иных ограничений - может использоваться любая строка длиной до 36 символов включительно, что позволяет внешним системам использовать идентификаторы, отличные от GUID.
При отсутствии или значении false параметра expand в тело ответа будет включено только базовое описание измененных объектов. Состав базового описания зависит от типа объекта и настроенных для него параметров кода, нумерации, периодичности и прочих. Например, для справочника базовое описание будет иметь вид:
{
"Catalog_FizicheskieLitsa": [
{
"type": "Справочник.ФизическиеЛица",
"version": 63875980439214,
"guid": "87433449-7cc0-11e2-9368-001b11b25590",
"path": "/odata/standard.odata/Catalog_ФизическиеЛица(guid'87433449-7cc0-11e2-9368-001b11b25590')?$format=json",
"presentation": "<Представление данных>",
"deletion": false
}
]
}
При значении true параметра expand в тело ответа будет включено полное описание измененных объектов. Состав базового описания зависит от типа объекта и настроенных для него параметров кода, нумерации, периодичности и прочих, а так же функциональных опций, настроенных в конкретном Прикладном решении 1С. Например, для справочника полное описание будет иметь вид:
{
"Catalog_FizicheskieLitsa": [
{
"type": "Справочник.ФизическиеЛица",
"version": 63875980439214,
"guid": "87433449-7cc0-11e2-9368-001b11b25590",
"path": "/odata/standard.odata/Catalog_ФизическиеЛица(guid'87433449-7cc0-11e2-9368-001b11b25590')?$format=json",
"presentation": "<Представление данных>",
"data": {
"#value": {
"Инициалы": "И. О.",
"Отчество": "<Отчество>",
"Имя": "<Имя>",
"НаименованиеСлужебное": "<Представление данных>",
"Пол": "Женский",
"ДатаРождения": "1986-01-02T00:00:00",
"Description": "<Представление данных>",
"Code": "0000000033",
"Фамилия": "<Фамилия>",
"Parent": "00000000-0000-0000-0000-000000000000",
"DeletionMark": false,
"Ref": "87433449-7cc0-11e2-9368-001b11b25590",
"ФИО": "<Представление данных>",
"IsFolder": false
},
"#type": "jcfg:CatalogObject.ФизическиеЛица"
},
"deletion": false
}
]
}
В таком ответе поле «data» содержит полные данные объекта, сериализованные в JSON стандартным сериализатором 1С (СериализаторXDTO), что позволяет использовать эти данные напрямую в 1С без необходимости предварительной конвертации.
Если целевой сервис не подразумевает работу с данными в виде массивов, то в параметрах узла обмена в Прикладном решении 1С следует установить флаг «Отправлять каждый объект отдельным запросом». В таком случае ответом на отдельный HTTP-запрос будет описание одного объекта. Например:
{
"type": "Справочник.ФизическиеЛица",
"version": 63875980439214,
"guid": "87433449-7cc0-11e2-9368-001b11b25590",
"path": "/odata/standard.odata/Catalog_ФизическиеЛица(guid'87433449-7cc0-11e2-9368-001b11b25590')?$format=json",
"presentation": "<Представление данных>",
"data": {
"#value": {
"Инициалы": "И. О.",
"Отчество": "<Отчество>",
"Имя": "<Имя>",
"НаименованиеСлужебное": "<Представление данных>",
"Пол": "Женский",
"ДатаРождения": "1986-01-02T00:00:00",
"Description": "<Представление данных>",
"Code": "0000000033",
"Фамилия": "<Фамилия>",
"Parent": "00000000-0000-0000-0000-000000000000",
"DeletionMark": false,
"Ref": "87433449-7cc0-11e2-9368-001b11b25590",
"ФИО": "<Представление данных>",
"IsFolder": false
},
"#type": "jcfg:CatalogObject.ФизическиеЛица"
},
"deletion": false
}
Параметр запроса expand так же выполняет роль выключателя отображения полного описания объекта.
Запрос подтверждения обработки изменений#
При успешной обработке данных, полученных запросом получения изменений, необходимо исключить их повторное получение. Этой цели служит запрос подтверждения обработки изменений. В общем виде, он имеет тот же вид, что и запрос получения изменений, но выполняется методом POST.
http://{HOST}/{BASE}/hs/synapse/changes/{CODE}
Параметр expand не используется и при указании будет проигнорирован.
Поддерживается два варианта подтверждения обработки изменений:
Подтверждение сразу всего массива данных по RequestID.
В заголовке POST-запроса указывается то же значение RequestID, которое было получено (или ранее установлено) при выполнении GET-запроса получения изменений. В таком случает будет удалена регистрация изменений всех объектов, которые были получены ответом на предыдущий запрос. Оптимальный вариант в сочетании с параметром «Отправлять каждый объект отдельным запросом».
Выборочное подтверждение обработанных изменений.
Если внешний сервис подразумевает обработку массива объектов и поддерживает обработку ошибок в потоке загрузки, то подтверждение загрузки выполняется на основании тела запроса подтверждения. В теле передается краткое описание успешно обработанных изменений, при этом заголовок RequestID должен отсутствовать. Например:
POST http://{HOST}/{BASE}/hs/synapse/changes/{CODE} [ { "type": "Справочник.ФизическиеЛица", "guid": "66b457e4-7c02-11e2-9362-001b11b25590" }, { "type": "Справочник.ФизическиеЛица", "guid": "87433448-7cc0-11e2-9368-001b11b25590" } ]
Настройка сервиса отправки изменений data#
Сервис отправки изменений data доступен по пути
http://{HOST}/{BASE}/hs/synapse/data/{CODE}
Принимает только POST-запросы. Запрос содержит в теле описание данных в формате, аналогичном ответу на запрос получения изменений. Параметр «Отправлять каждый объект отдельным запросом» узла обмена так же влияет на формат описания данных. Пример запроса:
POST http://{HOST}/{BASE}/hs/synapse/data/{CODE}
{
"Catalog_FizicheskieLitsa": [
{
"type": "Справочник.ФизическиеЛица",
"version": 63875980439214,
"guid": "87433449-7cc0-11e2-9368-001b11b25590",
"path": "/odata/standard.odata/Catalog_ФизическиеЛица(guid'87433449-7cc0-11e2-9368-001b11b25590')?$format=json",
"presentation": "<Представление данных>",
"data": {
"#value": {
"Инициалы": "С. Н.",
"Отчество": "Нурисламовна",
"Имя": "Светлана",
"НаименованиеСлужебное": "<Представление данных>",
"Пол": "Женский",
"ДатаРождения": "1986-01-02T00:00:00",
"Description": "<Представление данных>",
"Code": "0000000033",
"Фамилия": "Бажова",
"Parent": "00000000-0000-0000-0000-000000000000",
"DeletionMark": false,
"Ref": "87433449-7cc0-11e2-9368-001b11b25590",
"ФИО": "<Представление данных>",
"IsFolder": false
},
"#type": "jcfg:CatalogObject.ФизическиеЛица"
},
"deletion": false
}
]
}
В случае успешной обработки данных запроса, будет сформирован ответ, содержащий массив успешно обработанных изменений. Формат ответа аналогичен формату запроса подтверждения обработки изменений:
[
{
"type": "Справочник.ФизическиеЛица",
"guid": "66b457e4-7c02-11e2-9362-001b11b25590"
},
{
"type": "Справочник.ФизическиеЛица",
"guid": "87433448-7cc0-11e2-9368-001b11b25590"
}
]