ГОСТ Р ИСО/МЭК 17963-2016 Спецификация веб-служб для управления (WS-management)

ГОСТ Р ИСО/МЭК 17963-2016

НАЦИОНАЛЬНЫЙ СТАНДАРТ РОССИЙСКОЙ ФЕДЕРАЦИИ

Спецификация веб-служб для управления (WS-management)

Web services for management (WS-Management) specification

ОКС 35.020

Дата введения 2017-06-01

Предисловие

1 ПОДГОТОВЛЕН Обществом с ограниченной ответственностью "Информационно-аналитический вычислительный центр" (ООО "ИАВЦ") на основе собственного перевода на русский язык англоязычной версии стандарта, указанного в пункте 4

2 ВНЕСЕН Техническим комитетом по стандартизации ТК 22 "Информационные технологии"

3 УТВЕРЖДЕН И ВВЕДЕН В ДЕЙСТВИЕ Приказом Федерального агентства по техническому регулированию и метрологии от 18 мая 2016 г. N 335-ст

4 Настоящий стандарт идентичен международному стандарту ИСО/МЭК 17963:2013* "Спецификация веб-служб для управления (WS-management)" (ISO/IEC 17963:2013 "Web Services for Management (WS-Management) Specification", IDT).
________________
* Доступ к международным и зарубежным документам, упомянутым здесь и далее по тексту, можно получить, перейдя по ссылке на сайт . - .


ИСО/МЭК 17963:2013 разработан подкомитетом ПК 38 "Платформы и сервисы для распределенных приложений" совместного технического комитета по стандартизации СТК 1 "Информационные технологии" Международной организации по стандартизации (ИСО) и Международной электротехнической комиссии (МЭК).

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

5 ВВЕДЕН ВПЕРВЫЕ


Правила применения настоящего стандарта установлены в ГОСТ Р 1.0-2012 (раздел 8). Информация об изменениях к настоящему стандарту публикуется в ежегодном информационном указателе "Национальные стандарты", а текст изменений и поправок - в ежемесячном информационном указателе "Национальные стандарты". В случае пересмотра (замены) или отмены настоящего стандарта соответствующее уведомление будет опубликовано в ежемесячном информационном указателе "Национальные стандарты". Соответствующая информация, уведомление и тексты размещаются также в информационной системе общего пользования - на официальном сайте Федерального агентства по техническому регулированию и метрологии в сети Интернет (www.gost.ru)

Введение

Введение

Настоящий стандарт использует функциональность, подобную следующим Рекомендациям W3C:

- обработка событий веб-служб (WS-Eventing);

- передача данных веб-служб (WS-Transfer);

- перечисление веб-служб (WS-Enumeration).

Когда был определен WS-Management, данные Рекомендации W3C еще не существовали, и подобная функциональность была включена непосредственно в условия спецификации WS-Management. При последующих пересмотрах WS-Management эти функции могут быть включены посредством внешних ссылок на указанные Рекомендации W3C.

1 Область применения

Спецификация веб-служб для управления (WS-management) описывает протокол Веб-служб, основанный на SOAP, для использования в предметных областях, связанных с управлением. Данные предметные области включают управление объектами такими, как персональные компьютеры, серверы, устройства, Веб-службы и другие приложения, а также другие объекты управления. Службы могут предоставлять отдельный интерфейс WS-Management или составной интерфейс, в котором интерфейс службы WS-Management объединен с некоторыми из многих других спецификаций Веб-служб.

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

- получить, обновить, создать и удалить отдельные экземпляры ресурсов, такие как параметры настройки и динамические значения;

- перечислить содержимое контейнеров и коллекций, таких как большие таблицы и журналы событий;

- подписаться на события, порождаемые управляемыми ресурсами;

- выполнять определенные методы управления со строго типизированными параметрами ввода и вывода.

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

Настоящий стандарт предназначен для того, чтобы отвечать следующим требованиям:

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

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

- гарантировать обратную совместимость и функциональную совместимость (интероперабельность) с версией 1.0 WS-Management;

- гарантировать компонуемость с другими спецификациями Веб-служб.

2 Нормативные ссылки

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


IETF RFC 2616, Р.Филдинг и др., Протокол передачи гипертекста (HTTP 1.1) (R.Fielding et al, Hypertext Transfer Protocol (HTTP 1.1)), Июнь 1999, //www.ietf.org/rfc/rfc2616.txt

IETF RFC 2818, Э.Рескорла, HTTP поверх TLS (HTTPS) (E.Rescorla, HTTP over TLS (HTTPS)), Май 2000, //www.ietf.org/rfc/rfc2818.txt

IETF RFC 3986, Т.Бернерс-Ли и др., Унифицированные идентификаторы ресурсов (URI): Общий синтаксис (T.Berners-Lee et al, Uniform Resource Identifiers (URI): Generic Syntax), Август 1998, //www.ietf.org/rfc/rfc3986.txt

IETF RFC 4122, П.Лич и др., Пространство имен URN для универсальных уникальных идентификаторов (UUID) (P.Leach et al, A Universally Unique Identifier (UUID) URN Namespace), Июль 2005, //www.ietf.org/rfc/rfc4122.txt

IETF RFC 4178, Л.Жу и др., Простой и защищенный механизм согласования программного интерфейса общего сервиса безопасности (L.Zhu et al, The Simple and Protected Generic Security Service Application Program Interface (GSS-API) Negotiation Mechanism), Октябрь 2005, //www.ietf.org/rfc/rfc4178.txt

IETF RFC 4559, К.Яганатан и др., Применение механизмов аутентификации Kerberos и NTLM, основанных на SPNEGO, для HTTP в Microsoft Windows (K.Jaganathan et al, SPNEGO-based Kerberos and NTLM HTTP Authentication in Microsoft Windows), Июнь 2006, //www.ietf.org/rfc/rfc4559.txt

IETF RFC 5646, А.Филипс и др., Метки для идентификации языков (A.Phillips et al, Tags for Identifying Languages), Сентябрь 2009, //tools.ietf.org/rfc/rfc5646.txt

Директивы ISO/IEC, Часть 2. Правила, относящиеся к структуре и проектированию Международных стандартов (ISO/IEC Directives, Part 2: Rules for the structure and drafting of International Standards)

OASIS, А.Надалин и др., Профиль безопасности "Usertname Token" для Веб-служб 1.0 (A.Nadalin et al, Web Services Security Username Token Profile 1.0), Март 2004, //docs.oasis-open.org/wss/2004/01/ oasis-200401-wss-username-token-profile-1.0.pdf

OASIS, А.Надалин и др., Безопасность Веб-служб: безопасность сообщений SOAP 1.0 (A.Nadalin et al, Web Services Security: SOAP Message Security 1.0) (WS-Security 2004), Март 2004, //docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0.pdf

OASIS, С.Андресон* и др., Нотация для доверия в Веб-службах (WS-Trust) (S.Anderson* et al, Web Services Trust Language (WS-Trust)), Декабрь 2005, //schemas.xmlsoap.org/ws/2005/02/trust
________________
* Текст документа соответствует оригиналу. - .


Стандарт Unicode версии 3.0 (The Unicode Consortium, The Unicode Standard Version 3.0), Январь 2000, //www.unicode.org/book/u2.html

Консорциум "Юникод" Часто задаваемые вопросы по отметке порядка байтов (BOM) (The Unicode Consortium, Byte Order Mark (BOM) FAQ), //www.unicode.org/faq/utf_bom.html#BOM

W3C, М.Гаджин и др., SOAP - Версия 1.2. Часть 1 - Основы обмена сообщениями (M.Gudgin, et al, SOAP Version 1.2 Part 1: Messaging Framework), Июнь 2003, https://www.w3.org/TR/soap12-part1/

W3C, М.Гаджин и др., SOAP - Версия 1.2. Часть 2 - Дополнения (M.Gudgin, et al, SOAP Version 1.2 Part 2: Adjuncts), Июнь 2003, https://www.w3.org/TR/2003/REC-soap12-part2-20030624

W3C, М.Гаджин и др., Механизм оптимизации передачи сообщений SOAP (MTOM) (M.Gudgin, et al, SOAP Message Transmission Optimization Mechanism (MTOM)), Ноябрь 2004, https://www.w3.org/TR/2004/PR-soap12-mtom-20041116/

W3C, Дж.Кларк и др., Язык путей в XML - Версия 1.0 (XPath 1.0) (J.Clark et al, XML Path Language Version 1.0 (XPath 1.0)), Ноябрь 1999, https://www.w3.org/TR/1999/REC-xpath-19991116

W3C, Дж.Кован и др., Информационный набор XML - Вторая редакция (Инфонабор XML) (J.Cowan et al, XML Information Set Second Edition (XML Infoset)), Февраль 2004, https://www.w3.org/ TR/2004/REC-xml-infoset-20040204/

W3C, Г.Томпсон и др., XMLСхема - Часть 1. Структуры (XMLСхема 1) (H.Thompson et al, XML Schema Part 1: Structures (XML Schema 1)), Май 2001, https://www.w3.org/TR/xmlschema-1/

W3C, П.Бирон и др., XML Схема - Часть 2. Типы данных (XML Схема 2) (P.Biron et al, XML Schema Part 2: Data types (XML Schema 2)), Май 2001, https://www.w3.org/TR/xmlschema-2/

W3C, Адресация Веб-служб 1.0 - Базовая спецификация, Рекомендация W3C (Web Services Addressing 1.0 - Core, W3C Recommendation), Май 2006, https://www.w3.org/TR/2006/REC-ws-addr-core-20060509/

W3C, Адресация Веб-служб 1.0 - Привязка SOAP, Рекомендация W3C (Web Services Addressing 1.0 - SOAP Binding, W3C Recommendation), Май 2006, https://www.w3.org/TR/2006/REC-ws-addr-soap-20060509/

W3C, Адресация Веб-служб 1.0 - Метаданные, Рекомендация W3C (Web Services Addressing 1.0 - Metadata, W3C Recommendation), Сентябрь 2007, https://www.w3.org/TR/2007/REC-ws-addr-metadata-20070904/

W3C, Расширяемый язык разметки (XML) 1.0, Рекомендация W3C (Extensible Markup Language (XML) 1.0, W3C Recommendation), Октябрь 2000, https://www.w3.org/TR/2000/REC-xml-20001006

W3C, Пространства имен в XML, Рекомендация W3C (Namespaces in XML, W3C Recommendation), Январь 1999, https://www.w3.org/TR/1999/REC-xml-names-19990114/

W3C, Э.Кристинсен и др., Язык описания Веб-служб, версия 1.1 (WSDL/1.1) (E.Christensen et al, Web Services Description Language Version 1.1 (WSDL/1.1)), Март 2001, https://www.w3.org/TR/wsdl

W3C, С.Боаг и др., XQuery 1.0: язык запросов XML (XQuery 1.0) (S.Boag et al, XQuery 1.0: An XML Query Language (XQuery 1.0)), Январь 2007, https://www.w3.org/TR/2007/REC-xquery-20070123/

3 Термины и определения

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

3.1 может (can): Используется для утверждений о возможности и возможности, будь то материальная, физическая или причинная.

3.2 не может (cannot): Используется для утверждений о возможности и возможности, будь то материальная, физическая или причинная.

3.3 обусловлен (conditional): Отмечает требования, которые следует строго соблюдать, чтобы соответствовать документу, когда указанные условия выполнены.

3.4 обязательный (mandatory): Отмечает требования, которые необходимо строго выполнять, чтобы соответствовать документу, и от которых не допускаются никакие отклонения.

3.5 может (may): Указывает на образ действия, допустимый в рамках конкретного документа.

3.6 не требуется (need not): Указывает на образ действия, допустимый в рамках конкретного документа.

3.7 необязательный (optional): Указывает на образ действия, допустимый в рамках конкретного документа.

3.8 должен (shall): Указывает на требования, которые необходимо строго соблюдать, чтобы соответствовать документу, и от которых не допускаются никакие отклонения.

3.9 не должен (shall not): Указывает на требования, которые необходимо строго соблюдать, чтобы соответствовать документу, и от которых не допускаются никакие отклонения.

3.10 следует (should): Указывает, что среди нескольких возможностей одна рекомендуется как особенно подходящая, не упоминая или исключая другие, либо подразумевая, что предпочитается, но не обязательно требуется определенный образ действия.

3.11 не следует (should not): Указывает, что определенная возможность или образ действия не поощряются, но не запрещаются.

3.12 клиент (client): Приложение, которое использует Веб-службы, определенные в данном документе, чтобы получить доступ к службе управления.

3.13 потребитель (customer): Веб-служба, которая запрашивает перечисление данных у источника данных.

3.14 источник данных (data sourse): Веб-служба, которая поддерживает перебор с использованием контекстов перечисления посредством операции Enumerate, определенной в настоящем стандарте.

3.15 режим доставки (delivery mode): Механизм, с помощью которого сообщения уведомления передаются от источника до приемника.

3.16 контекст перечисления (enumeration context): Контекст сессии, который представляет собой определенный перебор логической последовательности информационных элементов XML с использованием операции Pull, определенной в настоящем стандарте.

3.17 приемник событий (event sink): Веб-служба, которая получает уведомления.

3.18 источник событий (event source): Веб-служба, которая отправляет уведомления и принимает запросы о создании подписки.

3.19 управляемый ресурс (managed resource): Сущность, которая может представлять интерес для администратора. Это может быть физический объект, такой как портативный компьютер или принтер, либо абстрактный объект, такой как служба.

3.20 уведомление (notification): Сообщение, отправленное для указания того, что событие имело место.

3.21 режим без запроса (push mode): Механизм доставки, в котором источник отправляет приемнику сообщения о событиях как отдельные незапрашиваемые сообщения SOAP.

3.22 ресурс (resource): Веб-служба, адресуемая ссылкой оконечной точки, доступ к которой осуществляется посредством операций, определенных в настоящем стандарте. Такой ресурс может быть представлен XML-документом. XML-документ может являться представлением управляемого ресурса.

3.23 класс ресурса (resourse* class): Абстрактное представление (тип) управляемого ресурса. Класс ресурса определяет представление связанных с управлением операций и свойств. Пример класса ресурса - описание операций и свойств для некоторого множества портативных компьютеров.
________________
* Текст документа соответствует оригиналу. - .

3.24 фабрика ресурса (resourse factory): Веб-служба, способная создавать новые ресурсы, используя операцию Create, определенную в настоящем стандарте.

3.25 экземпляр ресурса (resourse instance): Экземпляр класса ресурса.

Пример:

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

3.26 селектор (selector): Связанная с ресурсом пара имя-значение, которая действует как дискриминант экземпляров, когда используется с моделью адресации WS-Management по умолчанию.

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

Отношения служб к классам и экземплярам ресурсов:

- служба состоит из одного или более классов ресурса;

- класс ресурса может содержать ноль или более экземпляров.

Если существует более одного экземпляра для класса ресурса, они изолируются или идентифицируются посредством частей адреса SOAP для ресурса, таких как поля ResourceURI и SelectorSet в модели адресации по умолчанию.

3.27 служба (service): Приложение, которое предоставляет клиентам услуги управления, предоставляя доступ к Веб-службам, определенным в данном документе.

Как правило, служба эквивалентна сетевому "слушателю", связана с физическим транспортным адресом и является по существу типом точки доступа управляемости (manageability access point).

3.28 подписчик (subscriber): Веб-служба, которая отправляет запросы, чтобы создавать, возобновлять и/или удалять подписки.

3.29 менеджер подписки (subscribtion manager): Веб-служба, которая принимает запросы на управление, получение статуса, возобновление и/или удаление подписки от имени источника события.

4 Сокращения и обозначения

В настоящем стандарте применены следующие обозначения и сокращения.

4.1 BNF - форма Бэкуса-Наура.

4.2 BOM - отметка порядка байтов.

4.3 CQL - язык запросов CIM.

4.4 EPR - ссылка на оконечную точку.

4.5 GSSAPI - универсальный прикладной программный интерфейс служб безопасности.

4.6 SOAP - простой протокол доступа к объектам.

4.7 SPNEGO - простой и защищенный механизм переговоров GSSAPI.

4.8 SQL - язык структурированных запросов.

4.9 URI - универсальный идентификатор ресурса.

4.10 URL - унифицированный указатель ресурсов.

4.11 UTF - формат преобразования UCS.

4.12 UUID - универсально уникальный идентификатор.

4.13 WSDL - язык описания веб-служб.

4.14 WS-Man - веб-служба для управления.

5 Адресация

WS-Management опирается на механизм адресации, основанный на SOAP (например, определенный в 5.1), для определения ссылок на оконечные точки на других Веб-служб и определения некоторых заголовков, используемых в сообщениях SOAP. Данный механизм адресации семантически эквивалентен и полностью бинарно совместим с версией WS-Addressing, на которую ссылаются в WS-Management 1.0, поэтому данное изменение для WS-Management полностью обратно совместимо с существующими реализациями WS-Management.

5.2 определяет, как можно использовать более одной версии адресации с WS-Management, таких как версия, определенная в 5.1, или версия адресации из Рекомендации W3C. В настоящем стандарте, если конкретная версия не указана явно, термин "Адресация" относится в целом к любой версии адресации, как определено в 5.2.

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

- базовая адресация, как определено в 5.1;

- модель адресации по умолчанию, как определено в 5.4.2;

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

5.1 Адресация для управления

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

5.1.1 Введение

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

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

- ссылки оконечной точки подходят для передачи информации, необходимой для получения доступа к оконечной точке Веб-службы;

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

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

Пример:

Следующий пример иллюстрирует использование этих механизмов в сообщении SOAP 1.2, посланном от //business456.example/client1 к //fabrikam123.example/Purchasing.

Строки с (002) по (014) представляют заголовок сообщения SOAP, в котором используются механизмы, опреденные* в данном пункте. Тело представлено строками от (015) до (017).
________________
* Текст документа соответствует оригиналу. - .


Строки с (003) по (013) содержат блоки информационных заголовков сообщения. Именно, строки с (003) по (005) определяют идентификатор для этого сообщения, строки с (006) по (008) определяют оконечную точку, в которой сообщение порождено, и строки с (009) по (011) определяют оконечную точку, в которую следует отправить ответ на данное сообщение, как ссылку оконечной точки. Строка (012) задает URI адреса окончательного приемника данного сообщения. Строка (013) задает ActionURI, определяющий ожидаемую семантику.

5.1.2 Ссылки оконечной точки

Данный пункт определяет синтаксис ссылки оконечной точки (EPR).

5.1.2.1 Формат ссылок оконечной точки

Данный пункт определяет представление XML для ссылки оконечной точки как тип XML (wsa:EndpointReferenceType) и как элемент XML (<wsa:EndpointReference>).

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

<wsa:EndpointReference>

<wsa:Address>xs:anyURI</wsa:Address>

<wsa:ReferenceProperties>... </wsa:ReferenceProperties>?

<wsa:ReferenceParameters>... </wsa:ReferenceParameters>?

<wsa:PortType>xs:QName</wsa:PortType> ?

<wsa:ServiceName PortName="xs:NCName"?>xs:QName</wsa:ServiceName>?

<wsp:Policy> ... </wsp:Policy>*

</wsa:EndpointReference>

Ниже описаны атрибуты и элементы, перечисленные в этой схеме сообщения:

wsa:EndpointReference

Представляет собой некоторый элемент типа wsa:EndpointReferenceType. Данный пример использует предварительно определенный элемент <wsa:EndpointReference>, однако может использоваться любой элемент типа wsa:EndpointReferenceType.

wsa:EndpointReference/wsa:Address

Данный обязательный элемент (типа xs:anyURI) определяет URI адреса, задающего оконечную точку. Данный адрес может быть логическим адресом или идентификатором оконечной точки службы.

wsa:EndpointReference/wsa:ReferenceProperties/

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

Примечание - Использование свойств ссылки устарело; вместо них следует использовать параметры ссылки.

wsa:EndpointReference/wsa:ReferenceProperties/ {любой}

Каждый дочерний элемент элемента ReferenceProperties представляет отдельное свойство ссылки.

wsa:EndpointReference/wsa:ReferenceParameters/

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

см. в 5.4 некоторые параметры ссылки, специфичные для WS-Management.

wsa:EndpointReference/wsa:ReferenceParameters/ {любой}

Каждый дочерний элемент элемента ReferenceParameters представляет отдельный параметр ссылки.

wsa:EndpointReference/wsa:PortType

Данный необязательный элемент (типа xs:QName) определяет значение основного portType передаваемой оконечной точки.

Примечание - Использование wsa:PortType устарело.


wsa:EndpointReference/wsa:ServiceName

Данный необязательный элемент (типа xs:QName) задает определение <wsdl:service>, содержащее описание WSDL оконечной точки, на которую указывает ссылка. Имя службы обеспечивает связь с полным описанием оконечной точки службы. Необязательное неквалифицированное имя определяет конкретный порт в службе, которая соответствует оконечной точке.

Примечание - Использование wsa:ServiceName устарело.


wsa:EndpointReference/wsa:ServiceName/@PortName

Данный необязательный атрибут (типа xs:NCName) задает название определения <wsdl:port>, соответствующее оконечной точке, на которую указывает ссылка.

wsa:EndpointReference/wsp:Policy

Данный необязательный элемент определяет политику, которая относится к взаимодействию с оконечной точкой.

Примечание - Использование wsp:Policy устарело.

wsa:EndpointReference/{любой}

Механизм расширения, позволяющий определять дополнительные элементы.

wsa:EndpointReference /@ {любой}

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

Пример:

Следующий пример иллюстрирует ссылку оконечной точки. Данный элемент дает ссылку на URI "//www.fabrikam123.example/acct":

<wsa:EndpointReference xmlns:wsa="..." xmlns:fabrikam="...">

<wsa:Address>//www.fabrikam123.example/acct</wsa:Address>

</wsa:EndpointReference>

5.1.2.2 Привязка ссылок оконечной точки

Когда необходимо адресовать сообщение к оконечной точке, информация, содержащаяся в ссылке оконечной точки, отображается на сообщение согласно преобразованию, которое зависит от протокола и представления данных, используемых для отправки сообщения. Определенные для протокола отображения (или привязки) определяют, как информация из ссылки оконечной точки копируется в поля сообщения и протокола. Данный пункт определяет привязку SOAP для ссылок оконечной точки. Это отображение может быть явным образом заменено другими привязками (определенными как привязки WSDL или как политики); однако в отсутствие применимой политики, определяющей, что должно использоваться иное отображение, должна применяться привязка SOAP, определенная в данном пункте. Чтобы обеспечить функциональную совместимость для широкого диапазона устройств, все реализации, соответствующие настоящему стандарту, должны поддерживать привязку SOAP.

Привязка SOAP для ссылок оконечной точки определяется следующими двумя правилами:

R5.1.2.2-1 Элемент wsa:Address в ссылке оконечной точки должен быть скопирован в поле заголовка wsa:To сообщения SOAP.

R5.1.2.2-2 Каждый элемент ReferenceProperty и ReferenceParameter становится блоком заголовка в сообщении SOAP. Каждый элемент ReferenceProperty или ReferenceParameter (включая все его дочерние элементы, атрибуты и пространства имен в области видимости) должны быть добавлены как блок заголовка в новом сообщении.

Пример:

Следующий пример показывает, как используется привязка SOAP по умолчанию для ссылок оконечной точки для конструирования сообщения, адресованное к оконечной точке:

<wsa:EndpointReference xmlns:wsa="..." xmlns:fabrikam="...">

<wsa:Address>//www.fabrikam123.example/acct</wsa:Address>

<wsa:ReferenceParameters>

<fabrikam:CustomerKey>123456789</fabrikam:CustomerKey>

<fabrikam:ShoppingCart>ABCDEFG</fabrikam:ShoppingCart>

</wsa:ReferenceParameters>

</wsa:EndpointReference>

Согласно правилам отображения, сформулированным выше, значение адреса скопировано в заголовок "To", и элемент "CustomerKey" должен быть скопирован посимвольно как заголовок в сообщение SOAP, адресованное этой оконечной точке. Сообщение SOAP будет выглядеть следующим образом:

<S:Envelopexmlns:S="https://www.w3.org/2003/05/soap-envelope"

xmlns:wsa="..." xmlns:fabrikam="...">

<S:Header>

…

<wsa:To>//www.fabrikam123.example/acct</wsa:To>

<fabrikam:CustomerKey>123456789</fabrikam:CustomerKey>

<fabrikam:ShoppingCart>ABCDEFG</fabrikam:ShoppingCart>

…

</S:Header>

<S:Body>

…

</S:Body></S:Envelope>

5.1.3 Информационные заголовки сообщения

Данный пункт определяет синтаксис информационного заголовка сообщения.

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

"Запрос-ответ" является общим шаблоном взаимодействия, который состоит из первоначального сообщения, отправленного исходной оконечной точкой (запрос), и последующего сообщения, отправленного из места назначения запроса назад к источнику (ответ). Ответ может быть сообщением приложения, отказом или любым другим сообщением.

Блоки информационного заголовка сообщения обеспечивают характеристики сообщения, не изменяющиеся в ходе доставки сообщения и представимые как целостные единицы. Информация в этих заголовках неизменна и не предназначена для изменения по пути следования сообщения.

Рисунок 1 показывает содержимое блоков информационных заголовков сообщения:

Рисунок 1 - блоки информационных заголовков сообщения

<wsa:MessageID> xs:anyURI </wsa:MessageID>

<wsa:RelatesTo RelationshipType="..."?>xs:anyURI</wsa:RelatesTo>

<wsa:To>xs:anyURI</wsa:To>

<wsa:Action>xs:anyURI</wsa:Action>

<wsa:From>ссылка-на-оконечную-точку</wsa:From>

<wsa:ReplyTo>ссылка-на-оконечную-точку</wsa:ReplyTo>

<wsa:FaultTo>ссылка-на-оконечную-точку</wsa:FaultTo>

Рисунок 1 - блоки информационных заголовков сообщения

Далее описаны атрибуты и элементы, перечисленные на рисунке 1:

wsa:MessageID

Данный необязательный элемент (типа xs:anyURI) однозначно определяет сообщение во времени и пространстве. Данный элемент должен присутствовать, если присутствовуют wsa:ReplyTo или wsa:FaultTo. Никакие два сообщения с определенным намерением приложения не могут иметь общее значение wsa:MessageID. Сообщение может быть передано далее для любой цели (включая отказ соединения) и может использовать то же самое значение wsa:MessageID. Значение данного заголовка - непрозрачный URI; для значения в настоящем стандарте не определена интерпретация помимо эквивалентности. Если ожидается ответ, это свойство должно присутствовать.

wsa:RelatesTo

Данный необязательный (повторяющийся) элемент указывает, как сообщение относится к другому сообщению в форме пары URI-QName. Дочерний элемент данного элемента (который имеет типа xs:anyURI) содержит wsa:MessageID связанного с ним сообщения или следующий известный URI, который означает "неуказанное сообщение":

//schemas.xmlsoap.org/ws/2004/08/addressing/id/unspecified

Ответное сообщение должно содержать заголовок wsa:RelatesTo, состоящий из wsa:Reply и значения wsa:MessageIDсообщения-запроса.

wsa:RelatesTo / @RelationshipType

Данный необязательный атрибут (типа xs:QName) передает тип связи как QName. В случае, если он отсутствует, подразумеваемое значение этого атрибута - wsa:Reply.

В настоящем стандарте определен один тип связи, как показано в таблице 1.


Таблица 1 - Тип связи

wsa:ReplyTo

Данный необязательный элемент (типа wsa:EndpointReferenceType) предоставляет ссылку оконечной точки, которая определяет приемник, предназначенный для ответов на сообщение. Данный элемент должен присутствовать, если ожидается ответ. Если присутствует данный элемент, то должен присутствовать wsa:MessageID. Если ответ ожидается, то сообщение должно содержать заголовок wsa:ReplyTo. Отправитель должен использовать содержимое wsa:ReplyTo, чтобы сформулировать ответное сообщение, как определено в 5.1.3.1. Если заголовок wsa:ReplyTo отсутствует, то содержимое заголовка wsa:From может использоваться для того, чтобы сформулировать сообщение к источнику. Данный заголовок может отсутствовать, если у сообщения нет содержательного ответа.

wsa:From

Данный необязательный элемент (типа wsa:EndpointReferenceType) предоставляет ссылку на оконечную точку, где возникло сообщение.

wsa:FaultTo

Данный необязательный элемент (типа wsa:EndpointReferenceType) предоставляет ссылку оконечной точки, которая определяет приемник, предназначенный для отказов, связанных с сообщением. Если присутствует данный элемент, то должен присутствовать wsa:MessageID. При формулировании сообщения об отказе, как определено в 5.1.3.1, отправитель должен использовать содержимое данного заголовка, чтобы сформулировать сообщение отказа. Если данный заголовок отсутствует, отправителю следует использовать содержимое заголовка wsa:ReplyTo, чтобы сформулировать сообщение-отказ. Если отсутствуют оба заголовка wsa:FaultTo и wsa:ReplyTo, отправитель может использовать содержимое заголовка wsa:From для формулирования сообщения об отказе.

wsa:To

Данный обязательный элемент (типа xs:anyURI) обеспечивает адрес приемника, предназначенного для этого сообщения.

wsa:Action

Данный обязательный элемент (типа xs:anyURI) однозначно определяет семантику, подразумеваемую сообщением. Рекомендуется, чтобы значение этого заголовка было URI, определяющий входные данные, результаты, или сообщение-отказ в рамках типа порта WSDL. Действие может быть явно или неявно связано с соответствующим определением WSDL. Наконец, если в дополнение к заголовку wsa:Action в запросе будет закодирован URI действия SOAP, то URI действия SOAP должен либо совпадать с значением, определенным в заголовке wsa:Action, либо быть установленными.

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

Посколько в настоящее время широко используется ряд сетевых технологий (например, NAT, DHCP и брандмауэры), многие реализации не могут назначать значимый глобальный URI для заданной оконечной точки. Чтобы позволить этим "анонимным" конечным точкам начинать шаблоны обмена сообщениями и получать ответы, адресация определяет следующий известный URI для использования конечными точками, у которых не может быть стабильного, разрешимого URI:

//schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous

Запросы, у которых заголовки wsa:ReplyTo, wsa:From и/или wsa:FaultTo используют данный адрес, должны обеспечивать некоторый механизм, находящийся вне настоящего стандарта, для доставки ответов или отказов (например, путем возврата ответа через то же самое транспортное соединение). Таким механизмом может быть простой транспортный протокол запроса/ответа (например, HTTP GET или POST). Данный URI может использоваться в качестве заголовка wsa:To для ответных сообщений и не должен использоваться в качестве заголовка wsa:To при других обстоятельствах.

5.1.3.1 Формулировка ответного сообщения

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

Примеры:

1 Следующий пример иллюстрирует сообщение-запрос, использующий блоки информационных заголовков сообщения в сообщении SOAP 1.2:

<S:Envelope xmlns:S="https://www.w3.org/2003/05/soap-envelope"

xmlns:wsa="//schemas.xmlsoap.org/ws/2004/08/addressing"

xmlns:f123="//www.fabrikam123.example/svc53">

<S:Header>

<wsa:MessageID>uuid:aaaabbbb-cccc-dddd-eeee-ffffffffffff

</wsa:MessageID>

<wsa:ReplyTo>

<wsa:Address>//business456.example/client1</wsa:Address>

</wsa:ReplyTo>

<wsa:To S:mustUnderstand="1">mailto:[email protected]</wsa:To>

<wsa:Action>//fabrikam123.example/mail/Delete</wsa:Action>

</S:Header>

<S:Body>

<f123:Delete>

<maxCount>42</maxCount>

</f123:Delete>

</S:Body>

</S:Envelope>

2 Следующий пример иллюстрирует ответное сообщение, использующее блоки информационных заголовков сообщения в сообщении SOAP 1.2:

<S:Envelope

xmlns:S="https://www.w3.org/2003/05/soap-envelope"

xmlns:wsa="//schemas.xmlsoap.org/ws/2004/08/addressing"

xmlns:f123="//www.fabrikam123.example/svc53">

<S:Header>

<wsa:MessageID>

uuid:aaaabbbb-cccc-dddd-eeee-wwwwwwwwwww

</wsa:MessageID>

<wsa:RelatesTo>

uuid:aaaabbbb-cccc-dddd-eeee-ffffffffffff

</wsa:RelatesTo>

<wsa:To>

//business456.example/client1

</wsa:To>

<wsa:Action>//fabrikam123.example/mail/DeleteAck</wsa:Action>

</S:Header>

<S:Body>

<f123:DeleteAck/>

</S:Body>

</S:Envelope>

5.1.3.2.1 Связывание действий с операциями WSDL

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

5.1.3.2.2 Явная ассоциация

Действие может быть ассоциировано явным образом посредством атрибут wsa:Action.

Пример:

Рассмотрим следующий фрагмент WSDL:

<definitions targetNamespace="//example.com/stockquote" ……

<portType name="StockQuotePortType">

<operation name="GetLastTradePrice">

<input message="tns:GetTradePricesInput"

wsa:Action="//example.com/GetQuote"/>

<output message="tns:GetTradePricesOutput"

wsa:Action="//example.com/Quote"/>

</operation>

</portType>

...

</definitions>

Действие над входными данными операции GetLastTradePrice в StockQuotePortType явно определено как //example.com/GetQuote. Действие для выходных данных этой той же самой операции - //example.com/Quote.

5.1.3.2.3 Шаблон действия по умолчанию

В отсутствие атрибута wsa:Action следующий шаблон используется для конструирования действия по умолчанию для входных и выходных данных. Общая форма URI следующая:

targetNamespace/portTypeName/(inputName|outputNname)

"/" литеральный символ, который будет включен в действие. Значения свойств следующие:

- targetNamespace целевое пространство имен (/definition/@targetNamespace). Если target namespace заканчивается на "/", то дополнительный "/" не добавляется;

- portTypeName название типа порта (/definition/portType/@name);

- (inputName|outputName) название элемента, как определено в Разделе 2.4.5 спецификации WSDL 1.1.

Для сообщений отказа данный образец не применяется. Вместо этого следующий URI является URI действия по умолчанию для сообщения об отказе:

//schemas.xmlsoap.org/ws/2004/08/addressing/fault

Пример:

Рассмотрим следующий фрагмент WSDL:

<definitions targetNamespace="//example.com/stockquote" ...>

...

<portType name="StockQuotePortType">

<operation name="GetLastTradePrice">

<input message="tns:GetTradePricesInput" name="GetQuote"/>

<output message="tns:GetTradePricesOutput" name="Quote"/>

</operation>

</portType>

...

</definitions>

targetNamespace = //example.com/stockquote

portTypeName = StockQuotePortType

inputName = GetQuote

outputName = Quote

Применяя предыдущий шаблон с этими значениями, получаем следующее:

- действие для входных данных =

//example.com/stockquote/StockQuotePortType/GetQuote;

- действие для выходных данных =

//example.com/stockquote/StockQuotePortType/Quote.

WSDL определяет правила для имени по умолчанию для входных или выходных данных, если атрибут имени не присутствует. Рассмотрим следующий пример:

Пример:

Ниже приведен фрагмент WSDL:

<definitions targetNamespace="//example.com/stockquote" ...>

...

<portType name="StockQuotePortType">

<operation name="GetLastTradePrice">

<input message="tns:GetTradePricesInput"/>

<output message="tns:GetTradePricesOutput"/>

</operation>

</portType>

...

</definitions>

targetNamespace = //example.com/stockquote

portTypeName = StockQuotePortType

Согласно правилам, определенным в подпункте 2.4.5 спецификации WSDL, если атрибут имени отсутствует для сообщения с входными данными операции вида запрос - ответ, значение по умолчанию - имя операции с добавленной к нему строкой "Request"

inputName = GetLastTradePriceRequest

Аналогично по умолчанию имя для выходных данных состоит из имени операции с добавленной строкой "Response".

outputName = GetLastTradePriceResponse

Применяя предыдущий пример с этими значениями, получаем следующее:

- действие для входных данных =

//example.com/stockquote/StockQuotePortType/GetLastTradePriceRequest;

- действие для выходных данных =

//example.com/stockquote/StockQuotePortType/GetLastTradePriceResponse.

5.2 Версии адресации

Для поддержания совместимости с реализациями предыдущих версий WS-Management, данный протокол поддерживает обработку сообщений, сформированных в соответствии с предыдущими версиями. Однако WS-Management 1.1 также допускает опциональное использование рекомендации W3C WS-Addressing.

Для ясности и краткости используются следующие сокращения:

- "WSMA" обозначает версию Management Addressing, определенную в 5.1;

- "WSA-Rec" обозначает рекомендацию W3C WS-Addressing;

- "WS-Man 1.0" обозначает спецификацию WS-Management 1.0 и реализации, совместимые с указанной спецификацией;

- "WS-Man 1.1" обозначает данную спецификацию и реализации, совместимым* с данной спецификацией;

________________

* Текст документа соответствует оригиналу. - .


"Анонимный URI адресации" относится к анонимному URI, который определен версией Адресации, использующейся в настоящее время. В WSA-Rec определен анонимный URI

//schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous.

В WSMA определен анонимный URI https://www.w3.org/2005/08/addressing/anonymous.

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

5.2.1 Технические различия

Спецификации WSMA и WSA-Rec ссылаются на различные пространства имен XML. Оконечная точка, посылающая сообщения Веб-службы, должна использовать для заголовков адресации SOAP одно пространство имен или другое; конечная точка получения может распознать одно пространство имен или оба пространства имен. Существующие реализации WS-Man 1.0 распознают только пространства имен WSMA. Взаимодействия между реализациями WS-Man 1.0 и WS-Man 1.1 должны будут допускать эти ограничения.

5.3 Требования к совместимости

Чтобы максимизировать функциональную совместимость реализаций WS-Management, клиенты и службы WS-Man 1.0 и WS-Man 1.1 должны быть в состоянии обмениваться сообщениями. Эти требования сведены в таблицу 2.


Таблица 2 - Требования функциональной совместимости (интероперабельность)

Однородные соединения клиентов и служб, соответствующих стандарту (то есть клиента версии 1.0 со службой версии 1.0 или клиента версии 1.1 со службой версии 1.1) могут обмениваться сообщениями в соответствии со своим версиями спецификации. Чтобы гарантировать надежную связь, разнородные соединения должны отвечать определенным требованиям и осуществлять определенные упорядочивающие стратегии.

В частности клиенты и службы, которые реализуют WS-Man 1.0, могут использовать только WSMA в любых обменах; поэтому все обмены с оконечными точками версии 1.0 используют только WSMA. Это заключение отражено в таблице 3.


Таблица 3 - Версии WSA в обменах

5.3.1 Обнаружение или согласование

Если можно определить возможности обслуживания для клиента относительно WSA, такое обнаружение более эффективно, чем согласование версии WSA. Например, если служба поддерживает Indentify, то клиент может определить заранее протокол WS-Man, а также версию или версии адресации, поддерживаемые службой. Поэтому поддержка Identify является обязательной в настоящем стандарте в случае, когда используется WSA-Rec.

Identify может использоваться следующим образом:

- клиент отправляет службе сообщение Identify;

- если служба не поддерживает Identify, клиент может прийти к заключению, что служба является реализацией WS-Man 1.0 и поддерживает только WSMA;

- если служба успешно обрабатывает сообщение Identify, клиент определяет версии Адресации по элементу AddressingVersionURI (как определено в разделе 11) и может выбрать соответствующую версию;

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

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

5.3.2 Стратегии согласования клиента

Клиент WS-Man 1.0 будет использовать в обменах сообщениями только WSMA. Клиент WS-Man 1.1, однако, может использовать в обменах сообщениями либо WSMA, либо WSA-Rec. Если клиент WS-Man 1.1 не знает версию WSA службы, он может использовать различные стратегии при первом установлении связи со службами. Клиент может начать обмен сообщениями с любой версии WSA, используя WSA-Rec или WSMA в сообщении запроса. Обмен сообщениями может продолжиться следующим образом:

- тип стратегии 1: клиент отправляет запрос, используя WSA-Rec. Заголовки SOAP WSA-Rec должны быть отмечены атрибутом mustUnderstand ="1", чтобы гарантировать, что если приемник не поддерживает версию адресации WSA-Rec, будет сгенерирован отказ. Тогда клиент может повторить операцию, используя WSMA;

- тип стратегии 2: клиент отправляет запрос, используя WSMA, и службы WS-Man 1.0 и службы WS-Man 1.1 отвечают на запрос, используя WSMA.

5.3.3 Инициирование обменов сообщениями

Исходящие сообщения, инициированные реализацией WS-Man, должны использовать ту же самую версию адресации, которая использовалась в ссылке оконечной точки, в которую отправляют эти сообщения, например, если сообщение-запрос Subscribe использует WSA-Rec в заголовках SOAP (например, для wsa:To и wsa:ReplyTo), но если использует WSMA для NotifyTo, то ответ на Subscribe отправят, используя WSA-Rec, но события отправят, используя WSMA.

5.3.4 Нормативные правила

R5.3.4-1 Если служба WS-Man 1.1 поддерживает WSA-Rec, то она должна также поддерживать операцию Identify.

R5.3.4-2 Служба WS-Man 1.1 должна поддерживать WSMA и должна поддерживать WSA-Rec.

R5.3.4-3 Реализация WS-Man 1.1 должна отправлять сообщения в оконечные точки, используя ту же самую версию Адресации, которая используется в ссылке оконечной точки (Endpoint Reference) оконечной точки назначения (см. 5.2).

R5.3.4-4 В рамках единственного сообщения SOAP реализация WS-Man 1.1 должна использовать одну и ту же самую версию адресации для всех заголовков адресации SOAP.

Поскольку WS-Man 1.1 допускает использование любой версии Адресации, R5.3.4-4 устраняет возможность смешивания этих двух версий для заголовков SOAP WSA, но не запрещает, чтобы ссылки оконечной точки, которые могут присутствовать в других местах сообщения, имели другую версию.

Для обеспечения пути миграции от WSMA до WSA-Rec схема некоторых сообщений допускает EndpointReferenceType любой используемой версии. В то время как сама схема написана очень общим способом (то есть, используя xs:any), что позволяет включать любой произвольный XML, реализации должны ограничивать содержимое этого элемента до одного из типов ссылки оконечной точки.

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

5.4 Использование адресации в WS-Management

Данный пункт описывает использование ссылок оконечной точки независимо от того, использует ли реализация адресацию WS-Management (см. 5.1) или версию рекомендации W3C WS-Addressing.

Адресация (при любом типе адресации) ссылки оконечной точки (EPR) используется для передачи информации, необходимой, чтобы адресовать оконечную точку Веб-службы. WS-Management определяет модель адресации по умолчанию, которая может использоваться в EPR.

5.4.1 Использование ссылок оконечной точки

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

R5.4.1-1 Все сообщения, адресованные к классу или экземпляру ресурса, на который ссылается EPR, должны выполнять правила адресации для предоставления содержания EPR (адрес и параметры ссылки) в сообщении SOAP. Это правило также относится к сообщениям, таким как Pull или Release, которые продолжают операцию, начатую в предыдущем сообщении. Несмотря на то, что такие сообщения содержат контекстную информацию, которая связывает их с предыдущей операцией, информация EPR должна присутствовать в сообщении для маршрутизации к правильному обработчику.

Правило R5.4.1-1 разъясняет, что для сообщений таких, как Pull или Renew, требуется полный EPR. Для Pull, например, данный EPR должен совпадать с ERP исходной операции Enumerate, несмотря на то, что EnumerateResponse возвращает объект контекста, который, казалось бы, устранил потребность в EPR. EPR все еще требуется, чтобы маршрутизировать сообщения должным образом. Точно также запрос Renew использует SubscriptionManager EPR, полученный в SubscribeResponse.

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

R5.4.1-2 EPR, возвращенный службой, должен быть приемлемым для данной службы, чтобы обращаться к тому же самому управляемому ресурсу.

R5.4.1-3 Все EPR, возвращенные службой, выраженные с использованием модели адресации WS-Management по умолчанию (см. 5.4.2) или с помощью какой-либо другой модели адресации, должны быть действительными, пока существует управляемый ресурс.

5.4.2 Модель адресации WS-Management по умолчанию

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

Настоящий стандарт использует примеры этой модели адресации, содержащие составные части - заголовки SOAP ResourceURI и SelectorSet. Данная спецификация не зависит от фактической модели данных и не определяет структуру ResourceURI или набор значений селекторов для заданного ресурса. Они могут быть определены поставщиком или другими спецификациями.

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

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

Модель адресации по умолчанию использует представление EPR, которое является последовательностью следующих заголовков SOAP:

- wsa:To (обязательный заголовок): транспортный адрес службы;

- wsman:ResourceURI (обязательный заголовок, если используется модель адресации по умолчанию): URI представления класса ресурса или представления экземпляра;

- wsman:SelectorSet (необязательный заголовок): заголовок, который определяет или "выбирает" экземпляр ресурса, к которому необходимо получить доступ, если существует более одного экземпляра класса ресурса.

Во всех сообщениях, использующих модель адресации по умолчанию, значение wsman:Resource URI должно быть отмечено атрибутом s:mustUnderstand, установленным в значение "true". В противном случае служба, которая не понимает данную модель адресации, может непреднамеренно возвратить ресурс, не запрашиваемый клиентом.

Модель адресации WS-Management по умолчанию определена в следующей схеме XML для EPR:

Следующие определения накладывают дополнительные нормативные ограничения на приведенную выше схему сообщения:

wsa:Address

URI транспортного адреса

wsa:ReferenceParameters/wsman:ResourceURI

URI класса ресурса или экземпляра, к которому запрашивается доступ.

Как правило, данный URI представляет класс ресурса, но может представлять и экземпляр. Комбинация этого URI и wsa:ToURI составляет полный адрес класса ресурса или экземпляра.

wsa:ReferenceParameters/wsman:SelectorSet:

необязательное множество селекторов, как описано в 5.4.2.2.

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

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

Пример:

Ниже приведен пример определения EPR:

Это определение адреса при использовании в сообщении SOAP преобразуется следующим образом: wsa:Address становится wsa:To, и разворачиваются и сочетаются параметры ссылки. Следующий пример показывает типовое сообщение SOAP, использующее WSMA:

Следующее сообщение показывает типовое сообщение SOAP, использующее WS-Rec:

В обоих случаях элементы wsa:To, wsman:ResourceURI и wsman:SelectorSet работают вместе для ссылки на экземпляр ресурса, которым будут управлять, но фактический метод или операция, которые должны быть выполнены с данным ресурсом, обозначены в заголовке wsa:Action.

Пример:

Ниже приведен пример заголовков адресации, основанных на модели адресации по умолчанию, в фактическом сообщении:

В этом примере используются следующие определения:

wsa:To

адрес сети (или транспортного уровня) службы

wsman:ResourceURI

ResourceURI класса ресурса или экземпляра ресурса, к которому будет осуществлен доступ

wsman:SelectorSet

обертка для селекторов

wsman:SelectorSet/wsman:Selector определяет или выбирает экземпляр ресурса, к которому будет осуществляться доступ, если существует более одного экземпляра ресурса.

В этом случае селектором является "LUN" (Logical Unit Number, номер логической единицы) и выбранное устройство - блок (unit) номер "2".

wsa:Action определяет, какая операция должна быть выполнена с ресурсом (в этом случае, "Get").

wsa:MessageID

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

5.4.2.1 ResourceURI

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

R5.4.2.1-1 На формат wsman:ResourceURI не накладываются ограничения, за исключением требований RFC 3986.

Формат и синтаксис ResourceURI могут быть любыми URI, корректными согласно RFC 3986. Хотя по умолчанию схема URI не задана, http: и urn: широко используются по умолчанию. Если используется http:, пользователи могут ожидать, что по этому адресу будет находиться Веб-ресурс документации. Элементы wsa:To и wsman:ResourceURI работают вместе для фактического определения целевого ресурса.

R5.4.2.1-2 URI, специфичный для поставщика или для организации, должен содержать доменное имя Интернета в первой последовательности символов после схемы, такое как "example.org" в ResourceURI в следующем примере.

Пример:

R5.4.2.1-3 При использовании модели адресации по умолчанию требуется параметр ссылки wsman:ResourceURI в сообщениях со следующими wsa:ActionURI:

//schemas.xmlsoap.org/ws/2004/09/transfer/Get

//schemas.xmlsoap.org/ws/2004/09/transfer/Put

//schemas.xmlsoap.org/ws/2004/09/transfer/Create

//schemas.xmlsoap.org/ws/2004/09/transfer/Delete

//schemas.xmlsoap.org/ws/2004/09/enumeration/Enumerate

//schemas.xmlsoap.org/ws/2004/09/enumeration/Pull

//schemas.xmlsoap.org/ws/2004/09/enumeration/Renew

//schemas.xmlsoap.org/ws/2004/09/enumeration/GetStatus

//schemas.xmlsoap.org/ws/2004/09/enumeration/Release

//schemas.xmlsoap.org/ws/2004/08/eventing/Subscribe

В следующих сообщениях требуется, чтобы EPR был возвращен в элементе SubscriptionManager сообщения SubscribeResponse. Формат EPR определяется службой и может включать или не включать ResourceURI:

//schemas.xmlsoap.org/ws/2004/08/eventing/Renew

//schemas.xmlsoap.org/ws/2004/08/eventing/GetStatus

Несмотря на то, что модель адресации WS-Management по умолчанию требует наличие заголовка SOAP ResourceURI, он может быть короткой и очень простой формы, такой как //example.com/* или //example.com/resource.

R5.4.2.1-4 Для сообщения - запроса специализированных действий (методов) в сообщении может присутствовать заголовок ResourceURI, чтобы помочь маршрутизировать сообщение к правильному обработчику.

R5.4.2.1-5 Элемент ResourceURI не следует включать в другие сообщения, такие как ответы или события, если связанный элемент EPR не включает его в свой элемент ReferenceParameters.

На практике элемент wsman:ResourceURI требуется только в тех запросах, в которых идет ссылка на целевой класс ресурса. Ответы не адресованы к ресурсу управления, таким образом, wsman:ResourceURI в этом контексте не имеет смысла.

R5.4.2.1-6 Когда используется модель адресации по умолчанию и элемент wsman:ResourceURI отсутствует или выражен в неправильной форме, служба должна вернуть сообщение-отказ wsa:DestinationUnreachable со следующим кодом детализации

//schemas.dmtf.org/wbem/wsman/1/wsman/faultDetail/InvalidResourceURI

R5.4.2.1-7 Элемент wsman:ResourceURI должен использоваться только для того, чтобы указывать на идентификацию ресурса, он не может использоваться для указания на действие, применяемое к тому ресурсу, что выражается должным образом посредством wsa:Action URI.

В специализированных методах, основанных на WSDL, присутствует как идентичность ResourceURI для адресации, так и wsa:ActionURI для выполнения. Во многих случаях ResourceURI - просто псевдоним для идентичности WSDL и порта, и wsa:Action URI - конкретный метод этого порта (или интерфейса).

Теоретически для определения экземпляра ресурса в случае множественных экземплярах может быть достаточно единственного URI, тем не менее рекомендуется для определения местонахождения службы WS-Management использовать элемент wsa:To, для определения класса ресурса использовать элемент wsman:ResourceURI, а для ссылки на экземпляр ресурса использовать элемент wsman:SelectorSet. Если ресурс состоит из единственного экземпляра, то элемент wsman:ResourceURI указывает на единственный экземпляр.

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

См. рекомендации по унификации адресации в 7.2.

У специализированных действий есть две различные идентичности: ResourceURI, которое может идентифицировать WSDL и порт (или интерфейс), и wsa:Action URI, который идентифицирует конкретный метод. Если в интерфейсе существует только один метод, в некотором смысле ResourceURI и wsa:Action URI идентичны.

Не является ошибкой использовать wsa:Action URI для ResourceURI специализированного метода, однако оба они требуются в сообщении для унификации обработки клиентами и службами.

Пример:

Следующее действие для перезагрузки сетевой платы может использовать следующее EPR:

Во многих случаях ResourceURI эквивалентен имени и порту WSDL, и wsa:Action URI содержит необязательный символ как суффикс, что показано в следующем примере.

Пример:

Наконец, ResourceURI может быть абсолютно не связан с wsa:Action URI, как в следующем примере.

Пример:

Все эти варианты правомерны.

При использовании с подписками EPR, описанные элементами wsa:Address и wsman:ResourceURI (и дополнительно значениями wsman:SelectorSet), определяют источник события, к которому направлена подписка. Во многих случаях ResourceURI определяет реальный или виртуальный журнал событий, и подписка предназначена для того, чтобы предоставить уведомления в реальном времени о любых новых записях, добавленных в журнал. Во многих случаях элемент wsman:SelectorSet не может использоваться в качестве части EPR.

5.4.2.2 Селекторы

В модели адресации WS-Management по умолчанию селекторы - это необязательные элементы, используемые для определения экземпляров в пределах класса ресурса. Для таких операций, как Get или Put, селекторы используются для определения единственного экземпляра класса ресурса, на который ссылается ResourceURI.

На практике, поскольку ResourceURI часто выступает как таблица или "класс", элемент SelectorSet используется для различения, определения конкретного "ряда" или "экземпляра". Если ResourceURI подразумевает только один экземпляр класса ресурса, то SelectorSet может быть пропущен, так как ResourceURI выступает как полный идентификатор ресурса. Если требуется более одного значения селектора, вся группа селекторов интерпретируется службой для обращения к определенному экземпляру. Селекторы интерпретируются, как будто они объединены подразумеваемыми логическими операторами И.

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

R5.4.2.2-1 Если ресурс имеет более одного экземпляра, может использоваться элемент wsman:SelectorSet, чтобы различать, какой экземпляр является целевым при использовании модели адресации WS-Management по умолчанию. C элементом wsman:SelectorSet может появиться любое число значений wsman:Selector, необходимых для точного определения экземпляра класса ресурса. Служба может учитывать регистр имен селектора и значений (см. 13.6), как требуется в нижележащей среде выполнения.

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

R5.4.2.2-2 Все содержимое в рамках элемента SelectorSet нужно рассматривать как единственный параметр ссылки с областью применения, относящейся к ResourceURI.

R5.4.2.2-3 Служба, использующая модель адресации WS-Management по умолчанию, должна исследовать все селекторы в сообщении и обработать их, как если бы они были логически связаны оператором И. Если множество селекторов оказывается некорректным для целевого экземпляра ресурса, следует вернуть клиенту отказ wsman:InvalidSelectors со следующими кодами детализации:

если селекторы отсутствуют:

- //schemas.dmtf.org/wbem/wsman/1/wsman/faultDetail/InsufficientSelectors

если значения селектора некорректного типа:

- //schemas.dmtf.org/wbem/wsman/1/wsman/faultDetail/TypeMismatch.

если тип значения селектора правилен с точки зрения типов XML, но значение находится вне диапазона или иным образом неправомерно в определенном информационном домене:

- //schemas.dmtf.org/wbem/wsman/1/wsman/faultDetail/InvalidValue.

если имя не является известным именем селектора:

- //schemas.dmtf.org/wbem/wsman/1/wsman/faultDetail/UnexpectedSelectors.

R5.4.2.2-4 Атрибут SelectorName не должен повторяться на том же самом уровне вложения. Если это происходит, службе следует вернуть отказ wsman:InvalidSelectors со следующим кодом детализации:

//schemas.dmtf.org/wbem/wsman/1/wsman/faultDetail/DuplicateSelectors

Данная спецификация не налагает требования на использование селекторов. Некоторые реализации могут решить использовать сложные схемы URI, в которых сам ResourceURI неявно определяет конкретный экземпляр.

Формат элемента SelectorSet следующий:

Следующие определения накладывают дополнительные нормативные ограничения на схему сообщения, представленную выше:

wsman:SelectorSet

оболочка для одного или более элементов Selector, которые требуются для ссылки на экземпляр

wsman:SelectorSet/wsman:Selector

используется для описания селектора и его значения.

Если требуется более одного селектора, то для каждой части полного селектора существует свой элемент Selector. Значение этого элемента является значением Selector.

wsman:SelectorSet/wsman:Selector/@Name

имя селектора (должно обрабатываться нечувствительно к регистру)

Значение селектора может быть вложенная ссылка оконечной точки (EPR).

Пример:

В следующем примере селектор в строке 9 является частью SelectorSet, который содержит вложенную EPR (строки 10-18) со своим собственным адресом, ResourceURI и элементами SelectorSet: