Подробную информацию о триггерах в целом см. в разделе Описание триггеров.
Событие триггера веб-службы возникает при поступлении данных на отслеживаемый сокет (IP-адрес и номер порта). Данные должны использовать форму записи SOAP: она кодируют данные XML в сообщение HTTP. Интерфейс веб-службы описан в документе WSDL. Такой документ доступен для каждого настроенного триггера веб-службы.
Триггер веб-службы предоставляет обратную связь о состоянии задания печати, но для этого необходимо включить синхронный режим обработки. Дополнительные сведения см. в разделе Обратная связь по состоянию задания печати.
Обычно программисты используют веб-службу для интеграции печати этикеток в свои приложения. Существующая бизнес-система выполняет транзакцию, которая отправляет данные на определенный сокет сервера NiceLabel Automation. Отправляемые данные форматируются как сообщение SOAP. Данные могут быть представлены в формате CSV, XML и других структурированных форматах, а также устаревших форматах. В обоих случаях NiceLabel Automation считывает данные, обрабатывает значения с помощью фильтров и печатает их на этикетках. Дополнительную информацию об обработке и извлечении данных см. в разделе Описание фильтров.
Подсказка
Для помощи в создании конфигураций с триггером веб-службы см. образец файла Automation: Web Service. Образцы файлов доступны в меню Справка > Образцы файлов.
Общие
Этот раздел позволяет настроить общие параметры триггера веб-службы.
Связь
Этот раздел позволяет настроить обязательный номер порта и необязательные параметры обратной связи.
-
Порт. Номер порта, на котором будут приниматься входящие данные. Используйте порт, который не используется никаким другим приложением. Если выбранный порт используется, невозможно будет запустить триггер в Automation Manager. Дополнительную информацию о вопросах безопасности см. в разделе Защита доступа к триггерам.
Примечание
Если на сервере включена множественная адресация (несколько IP-адресов на одной или нескольких сетевых картах), NiceLabel Automation отвечает через заданный порт на всех IP-адресах.
-
Безопасное соединение (HTTPS). Включает безопасный транспортный уровень для передачи сообщений HTTP и предотвращает прослушивание. Дополнительную информацию о настройке безопасного соединения см. в разделе Использование безопасного транспортного уровня (HTTPS).
-
Максимальное количество одновременных вызовов. Задает максимальное количество принимаемых соединений. Такое количество клиентов могут одновременно отправлять данные триггеру.
-
Данные ответа. Собственный ответ, который можно использовать с методами
ExecuteTriggerWithResponseиExecuteTriggerAndSetVariablesWithResponse. Данные ответа настраиваются в текстовой области. Можно комбинировать фиксированные значения, значения переменных и специальные символы. Чтобы вставить (или создать) переменные и специальные символы, нажмите кнопку со стрелкой справа от текстовой области. Ответ может содержать двоичные данные, например изображение для предварительного просмотра этикетки и файл печати (* .PRN).
Отправка состояния по каналу обратной связи
Триггер веб-службы по умолчанию предоставляет обратную связь о состоянии созданного задания печати. Триггер принимает отправленные данные и использует их для выполнения определенных действий. Вы можете контролировать выполнение действий, так как триггер может сообщать об успешной обработке каждого события, которое происходит во время выполнения. Чтобы получать отчеты о состоянии в процессе печати, активируйте Синхронный режим печати.
Триггер веб-службы открывает доступ к следующим методам (функциям):
-
ExecuteTrigger: Этот метод получает данные для обработки и при необходимости предоставляет обратную связь о состоянии. Один из входных параметров включает или отключает обратную связь. Если включено предоставление отчетов о состоянии, информация о состоянии содержит идентификатор ошибки и подробное описание ошибки. Если идентификатор ошибки равен 0, значит, при печати файла не произошло никаких ошибок. Если идентификатор больше 0, значит, в процессе печати произошла какая-то ошибка. Ответ веб-службы при использовании этого метода не настраивается: он всегда содержит идентификатор ошибки и описание ошибки.
-
ExecuteTriggerWithResponse: Этот метод получает данные для обработки и предоставляет требуемую обратную связь о состоянии. Ответ веб-службы можно настроить. Для ответа можно использовать любой тип данных, имеющих любую доступную структуру. В ответе можно использовать двоичные данные.
-
ExecuteTriggerAndSetVariables: Аналогично описанному выше методу ExecuteTrigger, эта веб-служба предоставляет дополнительный входящий параметр, который принимает отформатированный список пар имя-значение. Триггер автоматически обрабатывает список, извлекает значения и сохраняет их в переменных с теми же именами, поэтому вам не нужно самостоятельно создавать какой-либо фильтр для извлечения данных.
-
ExecuteTriggerAndSetVariablesWithResponse: Аналогично описанному выше методу ExecuteTriggerWithResponse, эта веб-служба предоставляет дополнительный входящий параметр, который принимает отформатированный список пар имя-значение. Триггер автоматически обрабатывает список, извлекает значения и сохраняет их в переменных с теми же именами, поэтому вам не нужно самостоятельно создавать какой-либо фильтр для извлечения данных.
Дополнительную информацию о структуре сообщений, которые можно отправлять с помощью одного из перечисленных выше методов, см. в разделе WSDL ниже.
WSDL
Язык описания веб-служб (WSDL) определяет стиль сообщений SOAP. Поддерживаемые стили: Удаленный вызов процедур (RPC) и Документ. Выберите стиль, поддерживаемый приложением, которое предоставляет данные.
Документ WSDL задает входные и выходные параметры веб-службы.
После настройки триггера веб-службы на порту 12345 разверните его в Automation Manager и запустите. WSDL становится доступен по адресу:
http://localhost:12345
WSDL открывает доступ к нескольким методам, которые предоставляют данные триггеру. Выберите наиболее подходящий метод для решения поставленной задачи.
-
Если в имени метода содержится фраза WithResponse, он позволяет отправлять настраиваемые ответы, например собственные сообщения об ошибках, изображения для предварительного просмотра этикетки, файлы PDF, файлы печати (*.PRN) и т. д. Если в имени метода нет фразы WithResponse, он также предоставляет обратную связь, но его ответ нельзя настроить. Обратная связь содержит стандартные сообщения об ошибках.
-
Если в имени метода содержится фраза SetVariables, он позволяет предоставлять список переменных в двух заранее определенных форматах. Automation автоматически извлекает значения и сопоставляет их с соответствующими переменными. Это экономит ваше время, поскольку вам не нужно настраивать какие-либо фильтры для извлечения и сопоставления. Если в имени метода нет фразы SetVariables, вам необходимо настроить фильтр самостоятельно.
Интерфейс веб-службы определяет описанные ниже методы.
Метод ExecuteTrigger
Основная часть определения:
<wsdl:message name="WebSrviTrg_ExecuteTrigger_InputMessage">
<wsdl:part name="text" type="xsd:string"/>
<wsdl:part name="wait" type="xsd:boolean"/>
</wsdl:message>
<wsdl:message name="WebSrviTrg_ExecuteTrigger_OutputMessage"
<wsdl:part name="ExecuteTriggerResult" type="xsd:int"/
<wsdl:part name="errorText" type="xsd:string"/>
</wsdl:message>
Определение включает две входные переменные (вы предоставляете их значения):
-
text. Фильтр в конфигурации анализирует эту входную строку. Обычно входная строка структурирована как файл CSV или XML, что облегчает анализ. Но можно использовать и любой другой текстовый формат файла.
-
wait. Это логическое поле, которое отвечает за две настройки:
-
Хотите ли вы дождаться ответа о состоянии задания печати.
-
Должна ли веб-служба предоставить обратную связь.
Если да (True), используйте
1. Если нет (False), используйте0. В зависимости от выбранного метода можно отправить либо заранее определенный ответ, либо настроенный вами ответ. -
Далее перечислены необязательные выходные переменные (вы получаете их значения, если запрашиваете их, установив wait в 1):
-
ExecuteTriggerResult: Целочисленный ответ содержит значение 0, если при обработке данных не было выдано никаких ошибок. При наличии ошибок он содержит целое число больше 0. Приложение, которое вызывает веб-службу NiceLabel Automation, может использовать ответ в качестве индикатора ошибки.
-
errorText: Если во время обработки триггера произошла ошибка, это строковое значение содержит ответ о состоянии задания печати.
Примечание
Если во время обработки триггера происходит ошибка, этот элемент включается в ответное сообщение XML, а его значение содержит описание ошибки. Если же ошибка отсутствует, этот элемент не включается в ответ XML.
Метод ExecuteTriggerWithResponse
Этот метод следует использовать, если после завершения выполнения триггер отправляет настроенный ответ.
Некоторые примеры данных, которые можно отправить обратно в виде настроенного ответа: собственные сообщения об ошибках, изображение этикетки для предварительного просмотра, сгенерированные файлы PDF, файл потока печати (файл очереди), файл XML с информацией от механизма печати и изображением этикетки для предварительного просмотра (закодированный в виде строки Base64). Возможности безграничны.
Основная часть определения:
<wsdl:message name="WebSrviTrg_ExecuteTriggerWithResponse_InputMessage">
<wsdl:part name="text" type="xsd:string"/>
<wsdl:part name="wait" type="xsd:boolean"/>
</wsdl:message>
<wsdl:message name="WebSrviTrg_ExecuteTriggerWithResponse_OutputMessage">
<wsdl:part name="ExecuteTriggerWithResponseResult" type="xsd:int"/>
<wsdl:part name="responseData" type="xsd:base64Binary"/>
<wsdl:part name="errorText" type="xsd:string"/>
</wsdl:message>
В приведенном выше примере две входные переменные (вы предоставляете их значения):
-
text. Фильтр в конфигурации анализирует эту входную строку. Обычно входная строка структурирована как файл CSV или XML, что облегчает анализ. Но можно использовать и любой другой текстовый формат файла.
-
wait. Это логическое поле, которое отвечает за две настройки:
-
Хотите ли вы дождаться ответа о состоянии задания печати.
-
Должна ли веб-служба предоставить обратную связь.
Если да (True), используйте
1. Если нет (False), используйте0. В зависимости от выбранного метода можно отправить либо заранее определенный ответ, либо настроенный вами ответ. -
Кроме того, в приведенном выше примере используются следующие необязательные выходные переменные.
Примечание
Вы получаете значения необязательных выходных переменных, если запрашиваете их, установив для поля wait значение 1.
-
ExecuteTriggerWithResponseResult: Целочисленный ответ содержит значение 0, если при обработке данных не возникло никаких проблем. При наличии ошибок ответ содержит целое число больше 0. Приложение, которое вызывает веб-службу NiceLabel Automation, может использовать ответ в качестве индикатора ошибки.
-
responseData: Собственный ответ, который вы можете задать в конфигурации триггера веб-службы. Данные ответа кодируются по стандарту base64.
-
errorText: Если при выполнении триггера возникает ошибка, эта строка содержит значение ответа о состоянии задания печати.
Примечание
Если во время обработки триггера была выдана ошибка, ответное сообщение XML содержит элемент errorText. Значение этого элемента содержит описание ошибки. Если же ошибка отсутствует, этот элемент не включается в ответ XML.
Метод ExecuteTriggerAndSetVariables
Основная часть определения:
<wsdl:message name="WebSrviTrg_ExecuteTriggerAndSetVariables_InputMessage">
<wsdl:part name="text" type="xsd:string"/>
<wsdl:part name="variableData" type="xsd:string"/>
<wsdl:part name="wait" type="xsd:boolean"/>
</wsdl:message>
<wsdl:message name="WebSrviTrg_ExecuteTriggerAndSetVariables_OutputMessage">
<wsdl:part name="ExecuteTriggerAndSetVariablesResult" type="xsd:int"/>
<wsdl:part name="errorText" type="xsd:string"/>
</wsdl:message>
В приведенном выше примере три входные переменные (вы предоставляете их значения):
-
text. Фильтр в конфигурации анализирует эту входную строку. Обычно входная строка структурирована как файл CSV или XML, что облегчает анализ. Но можно использовать и любой другой текстовый формат файла.
-
wait. Это логическое поле, которое отвечает за две настройки:
-
Хотите ли вы дождаться ответа о состоянии задания печати.
-
Должна ли веб-служба предоставить обратную связь.
Если да (True), используйте
1. Если нет (False), используйте0. В зависимости от выбранного метода можно отправить либо заранее определенный ответ, либо настроенный вами ответ. -
-
variableData. Это строка, которая содержит пары имя:значение. Триггер считывает все пары и присваивает предоставленные значения переменным триггера с тем же именем. Если в триггере нет соответствующей переменной, он отбрасывает эту пару имя:значение. При предоставлении списка переменных и их значений с помощью этого метода не нужно настраивать извлечение данных с помощью фильтров. Триггер автоматически выполняет всю обработку.
Содержимое variableData может быть структурировано одним из двух способов.
Структура XML
Триггер предоставляет переменные в корневом элементе
<Variables />файла XML. Имя переменной содержит имя атрибута, а значение переменной содержит значение элемента.<?xml version="1.0" encoding="utf-8"?> <Variables> <variable name="Variable1">Value 1</variable> <variable name="Variable2">Value 2</variable> <variable name="Variable3">Value 3</variable> </Variables>Примечание
Вставьте данные XML в раздел CDATA. CDATA (сокращение от символьные данные) представляет собой раздел содержимого элемента, помеченный для средства синтаксического анализа, чтобы тот интерпретировал данные XML как символьные данные, а не как разметку. В результате триггер обрабатывает все содержимое как символьные данные. Например,
<element>ABC</element>интерпретируется как<element>ABC</element>. Каждый раздел CDATA начинается с последовательности<![CDATA[и заканчивается последовательностью]]>. Итак, просто вставьте данные XML между этими двумя последовательностями.Пары имя:значение
Триггер предоставляет переменные с помощью текстового потока. Каждая пара имя:значение располагается на отдельной строке. Имя переменной находится слева от знака равенства (=), а значение переменной — справа.
Variable1="Value 1" Variable2="Value 2" Variable3="Value 3"
Далее перечислены необязательные выходные переменные.
Примечание
Вы получаете значения необязательных переменных, если запрашиваете их, установив wait в 1:
-
ExecuteTriggerAndSetVariablesResult: Целочисленный ответ содержит значение 0, если при обработке данных не возникло никаких проблем. Если были выданы ошибки, он содержит целое число больше 0. Приложение, которое вызывает веб-службу NiceLabel Automation, может использовать ответ в качестве индикатора ошибки.
-
errorText: Если во время обработки триггера произошла ошибка, это строковое значение содержит ответ о состоянии задания печати.
Примечание
В случае ошибки обработки триггера этот элемент включается в ответное сообщение XML. Его значение содержит описание ошибки. Если же ошибка отсутствует, этот элемент не включается в ответ XML.
Метод ExecuteTriggerAndSetVariablesWithResponse
Этот метод следует использовать, если после завершения выполнения триггер должен отправлять настроенный ответ.
Некоторые примеры данных, которые можно отправить обратно в виде настроенного ответа: собственные сообщения об ошибках, изображение этикетки для предварительного просмотра, сгенерированные файлы PDF, файл потока печати (файл очереди), файл XML с информацией от механизма печати и изображением этикетки для предварительного просмотра (закодированный в виде строки Base64). Возможности безграничны.
Основная часть определения:
<wsdl:message name="WebSrviTrg_ExecuteTriggerAndSetVariablesWithResponse_
InputMessage">
<wsdl:part name="text" type="xsd:string"/>
<wsdl:part name="variableData" type="xsd:string"/>
<wsdl:part name="wait" type="xsd:boolean"/>
</wsdl:message>
<wsdl:message name="WebSrviTrg_ExecuteTriggerAndSetVariablesWithResponse_
OutputMessage">
<wsdl:part name="ExecuteTriggerAndSetVariablesWithResponseResult"
type="xsd:int"/>
<wsdl:part name="responseData" type="xsd:base64Binary"/>
<wsdl:part name="errorText" type="xsd:string"/>
</wsdl:message>
Здесь три входные переменные (вы предоставляете их значения):
-
text. Фильтр в конфигурации анализирует эту входную строку. Обычно входная строка структурирована как файл CSV или XML, что облегчает анализ. Но можно использовать и любой другой текстовый формат файла.
-
wait. Это логическое поле, которое отвечает за две настройки:
-
Хотите ли вы дождаться ответа о состоянии задания печати.
-
Должна ли веб-служба предоставить обратную связь.
Если да (True), используйте
1. Если нет (False), используйте0. В зависимости от выбранного метода можно отправить либо заранее определенный ответ, либо настроенный вами ответ. -
-
variableData. Это строка, которая содержит пары имя:значение. Триггер считывает все пары и присваивает предоставленные значения переменным триггера с тем же именем. Если в триггере нет соответствующей переменной, он отбрасывает эту пару имя:значение. При предоставлении списка переменных и их значений с помощью этого метода не нужно настраивать извлечение данных с помощью фильтров. Триггер автоматически выполняет всю обработку.
Содержимое variableData может быть структурировано одним из двух способов.
Структура XML
Триггер предоставляет переменные в корневом элементе
<Variables />файла XML. Имя переменной содержит имя атрибута, а значение переменной содержит значение элемента.<?xml version="1.0" encoding="utf-8"?> <Variables> <variable name="Variable1">Value 1</variable> <variable name="Variable2">Value 2</variable> <variable name="Variable3">Value 3</variable> </Variables>Примечание
Вставьте данные XML в раздел CDATA. CDATA (сокращение от символьные данные) представляет собой раздел содержимого элемента, помеченный для средства синтаксического анализа, чтобы тот интерпретировал данные XML как символьные данные, а не как разметку. В результате триггер обрабатывает все содержимое как символьные данные. Например,
<element>ABC</element>интерпретируется как<element>ABC</element>. Каждый раздел CDATA начинается с последовательности<![CDATA[и заканчивается последовательностью]]>. Итак, просто вставьте данные XML между этими двумя последовательностями.Пары имя:значение
Триггер предоставляет переменные с помощью текстового потока. Каждая пара имя:значение располагается на отдельной строке. Имя переменной находится слева от знака равенства (=), а значение переменной — справа.
Variable1="Value 1" Variable2="Value 2" Variable3="Value 3"
Далее перечислены необязательные выходные переменные.
Примечание
Вы получаете их значения, если запрашиваете их, установив wait в 1:
-
ExecuteTriggerAndSetVariablesWithResponseResult: Целочисленный ответ содержит значение 0, если при обработке данных не возникло никаких проблем. Если были выданы ошибки, он содержит целое число больше 0. Приложение, которое вызывает веб-службу NiceLabel Automation, может использовать ответ в качестве индикатора ошибки.
-
responseData: Собственный ответ, который вы можете задать в конфигурации триггера веб-службы. Данные ответа кодируются по стандарту base64.
-
errorText: Если во время обработки триггера произошла ошибка, это строковое значение содержит ответ о состоянии задания печати.
Примечание
В случае ошибки обработки триггера этот элемент включается в ответное сообщение XML. Его значение содержит описание ошибки. Если же ошибка отсутствует, этот элемент не включается в ответ XML.
Прочее
Раздел Обратная связь от печатающего устройства позволяет настроить параметры связи, чтобы получать обратную связь от механизма печати.
-
Контролируемая печать. Включение режима синхронной печати. Используйте этот параметр, если хотите отправлять состояние задания печати обратно в стороннее приложение. Дополнительные сведения см. в разделе Синхронный режим печати.
Параметры в разделе Обработка данных позволяют указать, нужно ли обрезать данные, чтобы они поместились в переменную, или игнорировать отсутствующие переменные этикетки. По умолчанию сообщает об ошибках и прерывает процесс печати, если вы пытаетесь сохранить в переменных этикетки слишком длинные значения или пытаетесь установить значения для несуществующих переменных этикетки.
-
Игнорировать избыточное содержание переменной. обрезает значения данных, длина которых превышает длину переменной, заданную в конструкторе этикеток, по длине переменной. Этот параметр применяется при установке значений переменных в фильтрах, из командных файлов, а также при назначении значений переменных триггера переменным этикетки с тем же именем.
Пример 25. Пример
Переменная этикетки вмещает максимум 5 символов. Если включить этот параметр, любое значение длиннее 5 символов будет обрезано до первых 5 символов. Если значение равно 1234567, будет игнорировать цифры 6 и 7.
-
Игнорировать отсутствующие переменные ярлыка. При печати с использованием командных файлов (таких как файл JOB) процесс печати игнорирует переменные, которые отвечают следующим условиям:
-
заданы в командном файле (с помощью команды SET);
-
не заданы на этикетке.
Подобное происходит, если область задания в фильтре должна извлекать все пары «имя-значение», но этикетка содержит меньше переменных.
При попытке установить значения несуществующих переменных этикетки сообщает об ошибке. Если включен этот параметр, печать продолжается.
-
Раздел Сценарии предназначен для настройки возможностей сценариев.
-
Язык сценариев. Выберите язык сценариев для триггера. Все действия Выполнить сценарий, используемые в этом триггере, будут использовать выбранный язык сценариев.
В разделе Сохранить полученные данные задайте доступные команды для данных, получаемых триггером.
-
Сохранить данные, полученные триггером, в файл. Включите этот параметр, чтобы сохранить полученные триггером данные. Параметр Переменная позволяет использовать переменное имя файла. Выберите переменную, которая содержит путь и имя файла.
-
При ошибке сохранять данные, полученные триггером, в файл. Включите этот параметр, чтобы сохранять данные в триггере только в случае возникновения ошибки при выполнении действия. Например, это позволяет сохранить данные, которые вызвали проблему, для последующего устранения неполадки.
Примечание
Обязательно включите поддержку контролируемой печати. Если этого не сделать, Automation не сможет распознавать ошибки во время выполнения. Дополнительные сведения см. в разделе Синхронный режим печати.
Примечание
Automation сохраняет полученные данные во временном файле. Этот временный файл удаляется сразу после завершения выполнения триггера. Имя этого файла хранится во внутренней переменной
DataFileName. Дополнительные сведения см. в разделе Внутренние переменные.