Руководство по использованию протоколов обмена 22 Система адресации 22

Скачать 468.04 Kb.

Название	Руководство по использованию протоколов обмена 22 Система адресации 22
страница	7/8
Тип	Руководство

filling-form.ru > бланк заявлений > Руководство

1 2 3 4 5 6 7 8

4Руководство по использованию протоколов обмена

В данном разделе собрана информация о том, как следует использовать различные протоколы обмена данными с веб-сервисом. В подразделах приведены пошаговые инструкции по формированию и разбору сообщений веб-сервиса. Для сообщений описаны только ключевые структуры и поля данных, содержание которых критично для обмена данными. Полное описание структур данных приведено в документе «Альбом форматов данных веб-сервера ФССП России».

Система адресации

Система адресации, принятая в системе, обеспечивает:

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

Адрес участника обмена данными состоит из двух полей: «Код организации» и «Код подразделения организации». Содержание полей задаётся специальными справочниками. Конкретные значения полей, которые должны использовать клиенты веб-сервиса, описано в документе «Спецификации обмена данными с контрагентами».

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

Типом всех полей является строковый. Структура полного адреса участника обмена данными приведена в таблице 4.1.1.

Таблица 4.1.1: Структура полного адреса стороны обмена данными

Наименование поля	Описание	Максимальная длина
Код организации	Код организации из справочника организаций	10
Код подразделения	Код подразделения организации из справочника подразделений. Не заполняется при отсутствии у участника обмена подразделений, ведущих независимый друг от друга обмен данными.	20
Код соглашения	Код соглашения по справочнику соглашений.	50

Протокол обмена данными версии 1.0.

Данный протокол был разработан для передачи данных в рамках реализации требований по обмену данными СМЭВ версии 2.3.4. Данный протокол работает только через СМЭВ.

В протоколе используются следующие пространства имен XML-сообщений:

http://www.red-soft.biz/schemas/dx/1.0 для служебных сообщений протокола.
http://smev.gosuslugi.ru/rev110801 для служебных данных СМЭВ версии 2.3.
http://www.red-soft.biz/schemas/fssp/common/1.0 служебные структуры протокола.
http://www.red-soft.biz/schemas/fssp/common/2011/0.5 документы ФССП России.

4.1.1Структура сообщения веб-сервиса

При передаче данных через СМЭВ используется единственная операция веб-сервиса — DxSmev. Входным и выходным параметром данной операции является сообщение SmevMessage.

На рисунке 4.2.1.1 показано, каким образом обеспечивается работа протокола через СМЭВ (показано сообщение, которое отправляет клиент в СМЭВ).

При обращении к веб-сервису, служебные блоки сообщения веб-сервиса размещаются внутри элемента AppData (в том месте, где в схеме данных СМЭВ находится тег xs:any). Заполнение всех остальных полей структуры данных SmevMessage производится так, как это описано в текущих методических рекомендациях СМЭВ.

Наличие и содержание служебных блоков протокола зависят от сценария использования веб-сервиса, которые описаны далее.
С

Рис.4.2.1.1: Общий вид сообщения веб-сервиса протокола обмена данными версии 1.0

ообщение состоит из следующих компонентов:

Сообщение SOAP — стандартный тег «Envelope» протокола SOAP
Заголовок SOAP — стандартный тег «Header» протокола SOAP
Заголовок подсистемы безопасности веб-сервиса.
Тело сообщения SOAP — стандартный тег «Body» протокола SOAP
Стандартная служебная структура СМЭВ SmevMessage.
Служебные блоки протокола в элементе AppData сообщения СМЭВ.

4.1.2Аутентификация и контроль целостности сообщения

Для контроля целостности SOAP-сообщения применяется цифровая подпись по ГОСТ Р 34.10-2001. Для аутентификации клиента веб-сервиса используются данные ЭП сообщения и сертификата открытого ключа в формате X.509.

Обращение клиента к веб-сервису с проверкой прав доступа включает следующие этапы:

Клиент веб-сервиса подготавливает сообщение для передачи веб-сервису.
Клиент веб-сервиса производит вычисление хэш-функции и вычисляет электронную подпись значения хэш-функции сообщения.
Клиент добавляет в сообщение следующие данные: заголовок SOAP, заголовок подсистемы безопасности веб-сервиса в формате «Web Service Security», данные сертификата открытого ключа, соответствующие закрытому ключу, с помошью которого формировалась электронная подпись сообщения в формате «Binary Security Token», данные электронной подписи сообщения в формате, описанном в документе «XML Signature Syntax and Processing».
Клиент передает сообщение веб-сервису.
Сервер вычисляет значение хэш-функции сообщения и сравнивает его с переданным в заголовке безопасности сообщения.
Сервер выполняет верификацию значения электронной подписи значения хэш-функции с использованием сертификата открытого ключа, переданного в заголовке безопасности сообщения.
Сервер проверяет данные сертификата открытого ключа на соответствие настройкам доступа к веб-сервису. В частности, проверяется отсутствие сертификата отправителя в списке отозванных сертификатов, срок действия сертификата, электронную подпись удостоверяющего центра сертификата, наличие УЦ или сертификата в списке доверенных сертификатов сервера.
В случае, если какой-либо из этапов проверки сообщения на сервере завершился неудачно, происходит отказ в доступе к функциям веб-сервиса с формированием и передачей клиенту веб-сервиса сообщения об ошибке доступа.
Сервером выполняется обработка сообщения, формирование ответа и передача его клиенту.

При автоматическом формировании SOAP-заголовка, он должен соответствовать следующим политикам профиля безопасности веб-сервиса:

xmlns:wsp="http://www.w3.org/ns/ws-policy"

xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702"

xmlns:cpxmlsec="urn:ietf:params:xml:ns:cpxmlsec"

>

Процесс формирования SOAP-заголовка в формате «Web Service Security» подробно описан в документе «Методические рекомендации по разработке электронных сервисов и применению технологии электронной подписи при межведомственном электронном взаимодействии» начиная с версии 2.3.4.

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

4.1.3Функция (операция) веб-сервиса DxSmev и её аргументы

Для выполнения всех операций передачи данных у веб-сервиса имеется функция под названием DxSmev. В качестве входных и выходных параметров вызова функции используется тип данных SmevMessage.

Значение типа SmevMessage используется исключительно для объединения служебных блоков сообщений веб-сервиса, все передаваемые данные находятся внутри служебных блоков.

Структура значения этого типа приведена на рисунке 4.2.1.1.

4.1.4Служебные блоки сообщений веб-сервиса

Служебными блоками сообщений веб-сервиса являются части сообщения, включаемые в корневое сообщений протокола. В настоящий момент такими блоками являются:

Управляющий блок протокола.
Пакет документов.
Квитанция.
Запрос информации о системе.
Информация о системе.

Все служебные блоки расширяют один базовый XML-тип DXPart. Это значит, что все поля, присутствующие в типе DXPart, также присутствуют во всех типах, для который DXPart является базовым. Порядок заполнения полей, общий для всех служебных блоков описан в таблице 4.2.4.1.

Таблица 4.2.4.1: Порядок заполнения атрибутов служебных блоков протокола 1.0

Наименование поля	Значение, которым заполняется атрибут
Direction/Sender/Org	Коды организации и подразделений отправителя и получателя. заполняется из справочника организаций обмена данными значением и справочника подразделений организаций обмена данными значениями, указанным в документе «Спецификации обмена данными с контрагентами».
Direction/Sender/Dept
Direction/Receiver/Org
Direction/Receiver/Dept
Direction/Protocol	Код соглашения заполняется в соответствии со значением, указанным в документе «Спецификации обмена данными с контрагентами».
@id	Атрибут. Уникальный идентификатор блока. Заполняется любым уникальным значением, например, GUID.
@session	Атрибут. Номер сессии. При первом обращении к серверу в рамках сессии не заполняется. При последующих обращениях (например, при подтверждении пакета квитанцией) заполняется значением, возвращённым в ответе сервера при первом обращении. Номера сессии должны быть одинаковы для всех блоков, передаваемых общим сообщением.
@phase	Атрибут. Последовательный номер сообщения в сессии. При первом обращении к серверу заполняется значением 1. При повторном обращении к серверу заполняется значением, возвращённым сервером в последнем ответе в управляющем блоке, увеличенном на 1.
@replyTo	Атрибут. При формировании блока в ответ на ранее полученный блок протокола, указывается идентификатор блока, на который возвращается ответ.
@time_sent	Атрибут. Заполняется датой и временем включения блока в корневое сообщение протокола.

4.1.5Отправка служебного блока веб-сервису и получение ответа

В дальнейшем, при описании обращения к серверу будет использоваться термин «сформировать и отправить служебный блок на сервер». Этот термин обозначает, что надо сформировать служебный блок, заполнить общие реквизиты блока, заполнить реквизиты в зависимости от типа блока, включить блок в служебное сообщение веб-сервиса. Затем следует сформировать SOAP-сообщение и передать его на сервер.

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

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

При отсутствии управляющего блока считается, что все его поля равны значениям по умолчанию, установленным для соответствующего сценария использования.

4.1.6Получение информации о системе (выполнение контрольного примера)

Для получения информации о системе следует передать на сервер блок DXSysInfoRequest. Общие поля, заполнение которые требуется, описаны в таблице 4.2.4.1. Помимо общих, значения полей, которыми требуется заполнить блок, описаны в таблице 4.2.6.1.

В качестве ответа, веб-сервис возвращает блок DXSystemInfo.

Таблица 4.2.6.1: Поля служебного блока DXSysInfoRequest

Наименование поля	Значение, которым заполняется поле
Asker	Наименование внешнего контрагента, производящего запрос

4.1.7Передача документов от клиента к серверу

Для передачи документов от внешнего контрагента, необходимо сформировать пакет документов блок DXPack и передать его на сервер.

Общие поля, заполнение которые требуется, описаны в таблице 4.2.4.1. Помимо общих, значения полей, которыми требуется заполнить блок, описаны в таблице 4.2.7.1.

Документы помещаются внутрь тега Documents пакета документов. При этом каждый документ должен быть отдельным XML-элементом (один элемент внутри элемента Documents один документ).

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

Таблица 4.2.7.1: Поля служебного блока DXPack

Наименование поля	Значение, которым заполняется поле
DocDate	Дата создания пакета документов.
DocNumber	Номер пакета документов в системе документооборота. Необязательно к заполнению.
Generation	При отправке документов на сервер не заполняется.
Signed	ФИО должностного лица, подписавшего пакет документов. Необязательно к заполнению.
Documents	Документы
@time_created	Атрибут. Дата и время формирования пакета. Необязателен к заполнению.
@time_queued	Атрибут. Дата и время, когда пакет был включён в очередь отправки, т. е. когда он стал доступен получателю. Необязателен к заполнению.

4.1.8Передача документов от сервера к клиенту

Для получения документов от сервера, клиенту необходимо включить в запрос к серверу служебный управляющий блок протокола DXControl и заполнить в нем структуру Pack. В данной структуре передаётся информация о готовности стороны обмена (клиента веб-сервиса) принять пакет(ы) документов.

Передача пакета документов сервером возможна в двух режимах, использование которых оговаривается с внешним контрагентом:

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

4.1.8.1Порядок заполнения управляющего блока протокола

Общие поля, заполнение которые требуется, описаны в таблице 12. Помимо общих, значения полей, которыми требуется заполнить структуру Pack управляющего блока, описаны в таблице 4.2.8.1.1.

Результатом вызова веб-сервиса будет являться, при наличии пакетов в очереди, один или несколько пакетов документов — блоков DXPack. На каждый пакет документов, принятый от веб-сервиса, клиент должен сформировать квитанцию.

Таблица 4.2.8.1.1: Поля структуры Pack управляющего блока протокола DXControl.

Наименование поля	Значение, которым заполняется поле
MaxCount	Максимальное количество пакетов документов, которые может вернуть веб-сервис одним сообщением.
GenerationId	Максимальный номер поколения пакета, имеющегося у клиента. Обязательно к заполнению при использовании режима передачи пакетов по номерам поколений, иначе не заполняется.

4.1.8.2Порядок заполнения квитанции на пакет документов

Квитанция на пакет документов передаётся в служебном блоке веб-сервиса DXReceipt. В квитанции указывается то, как был принят пакет документов в целом и то, как был принят каждый документ пакета.

Общий статус приёма пакета может иметь три значения:

SUCCESS — обозначает, что пакет принят и все документы в пакете также приняты успешно.
PARTIALLY — обозначает, что пакет принят, но есть документы, приём которых по определенным причинам не удался.
FAIL — обозначает, что пакет документов не может быть принят клиентом, по причинам, исключающим повторную передачу пакета.
Статус приёма документа может иметь два значения:
SUCCESS — обозначает, что приём документа произведён успешно.
FAIL — обозначает, что приём документа не произведён.

При возврате в квитанции статуса FAIL для пакета, в квитанцию должен быть включён элемент ErrorInfo, в котором должна содержаться информация о причинах неприёма пакета документов.

При возврате в квитанции статуса FAIL для документа, в квитанции формируется элемент Notes. В этот элемент для каждого ошибочного документа включается структура DocNote с указанием причин неприёма документа.

Формирование отдельной квитанции об успешном приёме документа в возможно и в случае удачного приёма документа для информирования отправителя документа о том, что документ был передан из одной системы в другую.

Общие поля, заполнение которые требуется, описаны в таблице 4.2.4.1. Помимо общих, значения полей, которыми требуется заполнить блок, описаны в таблице 4.2.8.2.1.

Таблица 4.2.8.2.1: Поля служебного блока квитанции на пакет документов DXReceipt.

Наименование поля	Значение, которым заполняется поле
Reference	Ссылка на пакет документов
Reference@type	Атрибут. Тип ссылки. Заполняется значением DXPack.
Reference@id	Атрибут. Внутренний идентификатор пакета. Необязателен.
Reference@ext_id	Атрибут. Идентификатор пакета.
Status	Результат приёма пакета. Заполняется значением SUCCESS, PARTIALLY или FAIL.
ErrorInfo	Информация о причинах неприёма пакета. Обязательно для заполнения, если значение поля Status — FAIL.
ErrorInfo@Code	Атрибут. Код ошибки. Значение берётся из справочника кодов ошибок клиента веб-сервиса.
Notes	Технологические сообщения о приёме документов. Для всех непринятых документов пакета необходимо сформировать технологическое сообщение в виде элемента Note.
Notes/Note	Технологическое сообщение о приёме документа. Порядок заполнения описан в таблице 4.2.8.2.2.

Таблица 4.2.8.2.2: Поля квитанции на документ DocNote.

Наименование поля	Значение, которым заполняется поле
Message@code	Атрибут. Код ошибки. Значение берётся из справочника кодов ошибок клиента веб-сервиса.
Message	Текст сообщения об ошибке приёма документа.
DocRef	Ссылка на документ
DocRef/DocNumber	Номер документа. Необязателен для заполнения.
DocRef/DocDate	Дата документа. Необязательно для заполнения.
DocRef@docType	Атрибут. Код типа документа. Необязательно для заполнения.
DocRef@id	Атрибут. Заполняется значением внутреннего идентификатора документа в АИС получателя пакета.
DocRef@ext_id	Атрибут. Идентификатор принятого документа. Значение идентификатора документа должно быть взято из реквизитов документа.
Status	Результат приёма документа — SUCCESS или FAIL.
@timestamp	Атрибут. Дата и время формирования квитанции на документ.
@id	Атрибут. Идентификатор квитанции в АИС получателя документа. Может не заполняться в случае, если учёт таких сообщений в системе не ведётся.