База знаний PIX - Мастер

МЕНЮ

Переходите на новый сайт Базы знаний. Актуализация контента происходит теперь там.

Взаимодействие с PIX Master через API

Подключение к Swagger
API запроса токена
API задач
API процессов

API проектов
API данных
API очередей
API планировщика
API шаблона расписания

Подключение к Swagger

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

Подключение Swagger
В файле appsettings.json (C:\Master\appsettings.json) для ключа UseSwagger поставить значение true:

В Linux помимо этого нужно открыть /etc/systemd/system/Master.service и в строке Environment заменить слово Production на Development.

После этого необходимо перезапустить сервер:

Запуск Swagger
Открываем Мастер и в URL в конце прописываем /swagger:

Для написания запроса достаточно выбрать нужную функцию и нажать на Try it out.

Теперь можно (1) указать параметры и (2) сформировать запрос:

Наверх

API запроса токена (TokenApi)

Генерирует уникальный токен для взаимодействия с PIX Master.

Важно! Токен действителен в течение 2 часов.

API-запросы удобно формировать в Swagger (инструкция, как подключиться).
Надо нажать Try it out в правом верхнем углу, появятся поля для ввода логина и пароля от PIX Master.

После подтверждения (Execute) появится сформированный API-запрос (1, 2) и
ответ на запрос "access_token" (3).

Пример запроса:


//Заменить username и password
//CURL
curl -X 'POST' \
  'https://nb063319.int.bit.ru:44300/api/Token?username=admin&password=Admin1Default%40' \
  -H 'accept: */*' \
  -d ''

//Request URL
"https://nb063319.int.bit.ru:44300/api/Token?username=admin&password=Admin1Default%40"

Токен можно получить без авторизации, поэтому в Swagger сразу выдается результат запроса (3).

Например, для API-запросов можно использовать приложение Postman (надо установить программу на компьютере).
Для получения токена выбираем команду POST и вставляем сформированную в Swagger ссылку (URL).
Если после отправки запроса возникает ошибка (1), надо отключить проверку сертификата (2).

В результате получаем access_token, который необходимо будет указывать при выполнении других запросов.

Наверх

API задач (TasksApi)

Получение списка задач
/
Запуск задачи по ID
/
Запуск задачи по наименованию
/
Остановка задачи

API-запросы удобно формировать в Swagger (инструкция, как подключиться).

Получение списка задач. Работает в версиях мастера после 1.18.
Для получения списка всех задач, надо прописать в следующей ссылке URL для подключения к мастеру:


// Указать ссылку для запуска мастера

// URL
'Ссылка для работы с мастером/api/Tasks/GetTaskList'

API-запрос можно осуществить в приложении Postman (надо установить программу на компьютере).
Для этого (1) выбираем функцию (GET), вставляем сформированную ссылку и авторизуемся по токену (API запроса токена).

В ответе получаем JSON со всей информацией о задачах.

Запуск задачи по ID. Для формирования запроса в Swagger надо нажать Try it out в правом верхнем углу, появится поле для ввода идентификатора задачи. Идентификатор задачи можно посмотреть в мастере или воспользоваться ранее описанным запросом получения списка задач.

После подтверждения (Execute) появится сформированный API-запрос.

Можно использовать шаблон запроса, прописав там нужные параметры:


// Указать ссылку для запуска мастера и ID задачи (без кавычек)
// CURL
curl -X 'POST' \
  'Ссылка для работы с мастером"/api/Tasks/StartTask?taskId=ID задачи' \
  -H 'accept: */*' \
  -d ''

// URL
'Ссылка для работы с мастером/api/Tasks/StartTask?taskId=ID задачи'

Для осуществления запроса в Postman (1) выбираем функцию (POST), вставляем сформированную ссылку и авторизуемся по токену (API запроса токена).

В результате выполнения API-запроса получим закодированный ответ:

Запуск задачи по наименованию. Работает в версиях мастера после 1.18.
Для запуска задачи надо в ссылке прописать наименование:


// Указать ссылку для запуска мастера и наименование задачи 

// URL
'Ссылка для работы с мастером/api/Tasks/StartTask?taskName=name'

Запуск задачи в Postman выглядит следующим образом:

Остановка задачи. Вводится ID задачи.

После подтверждения (Execute) появится сформированный API-запрос.


// Указать ссылку для запуска мастера и ID задачи (без кавычек)
// CURL
curl -X 'POST' \
  'Ссылка для работы с мастером/api/Tasks/StopTask?taskId=ID задачи' \
  -H 'accept: */*' \
  -d ''

// URL
'Ссылка для работы с мастером/api/Tasks/StopTask?taskId=ID задачи'

Наверх

API процессов (ProcessesApi)

Запуск процесса в PIX Master.

API-запросы удобно формировать в Swagger (инструкция, как подключиться).
Запуск процесса. Надо нажать Try it out в правом верхнем углу, появится поле для ввода идентификатора процесса. Идентификатор процесса можно посмотреть в используемой базе данных, например, PostgreSQL.

После подтверждения (Execute) появится сформированный API-запрос:

Swagger автоматически формирует ссылку.
Можно использовать этот код, указав ссылку для запуска мастера и ID процесса (без кавычек):


// CURL
curl -X 'POST' \
  '"Ссылка для работы с мастером"/api/Processes/StartProcess?processId="ID процесса"' \
  -H 'accept: */*' \
  -d ''

// URL
'"Ссылка для работы с мастером"/api/Processes/StartProcess?processId="ID процесса"'

API-запрос можно осуществить в приложении Postman (надо установить программу на компьютере).
Для этого надо авторизоваться по токену (API запроса токена), выбрать команду POST и вставить сформированную в Swagger ссылку (URL).

Метод для остановки процесса в Master
POST - метод API:


/api/Processes/StopProcess?processId={processId}.

В обязательном параметре processId передается значение идентификатора процесса.
Результатом выполнения метода является остановка запущенного процесса с заданным processId - статус процесса меняется с InProgress на Canceled.

Это метод API может использоваться, например,:

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

Наверх

API данных (DataApi)

Получение/установка значения данных.

API-запросы удобно формировать в Swagger (инструкция, как подключиться).
Доступны 4 опции:

Получение данных по их идентификатору.

Для формирования запроса в Swagger надо указать ID данных.
Можно подставить нужные значения в сформированном запросе:


//Curl
curl -X 'GET' \
  '"Ссылка для работы с мастером"/api/Data/GetValueById?dataId=7' \
  -H 'accept: text/plain'

//Request URL
"Ссылка для работы с мастером"/api/Data/GetValueById?dataId=7

API-запрос можно осуществить в приложении Postman (надо установить программу на компьютере).
Для этого надо выбрать команду (1) GET, вставить сформированную в Swagger ссылку (URL) и (2-3) авторизоваться по токену (API запроса токена).

В результате получаем значение.

Получение данных по их ключу.

Для формирования запроса в Swagger надо указать ключ данных.
Можно подставить нужные значения (ссылку для работы с мастером и ключ) в сформированном запросе:


//Curl
  '"Ссылка для работы с мастером"/api/Data/GetValueByKey?key=Key' \
  -H 'accept: text/plain'

//Request URL
"Ссылка для работы с мастером"/api/Data/GetValueByKey?key=Key

Установка значения данных по их идентификатору.

Для формирования запроса в Swagger надо указать ID данных и устанавливаемое значение.

Можно подставить нужные значения (ссылку для работы с мастером, ID и значение) в сформированном запросе:


//Curl
  '"Ссылка для работы с мастером"/api/Data/SetValueById?dataId=1&value=Value' \
  -H 'accept: */*' \
  -d ''

//Request URL
"Ссылка для работы с мастером"/api/Data/SetValueById?dataId=1&value=Value

Установка значения данных по их ключу.

Для формирования запроса в Swagger надо указать ключ и устанавливаемое значение.

Можно подставить нужные значения (ссылку для работы с мастером, ключ и значение) в сформированном запросе:


//Curl
  '"Ссылка для работы с мастером"/api/Data/SetValueByKey?key=Key&value=Value' \
  -H 'accept: */*' \
  -d ''

//Request URL
"Ссылка для работы с мастером"/api/Data/SetValueByKey?key=Key&value=Value

Для получения списка Данных воспользуйтесь GET методом:


/api/Data/GetDataList

Предусмотрена опциональная возможность отбора Данных по Группе, задавая поле groupName.

Наверх

API очередей (QueuesApi)

Работа с очередями данных.

Расшифровка статусов:

0 - New;
1 - Processing;
2 - Processed;
3 - Failed;
4 - Canceled;
5 - TimedOut;
6 - Retried.

API-запросы удобно формировать в Swagger (инструкция, как подключиться).
Доступны 7 способов взаимодействия с очередями:

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

Можно использовать шаблон запроса, прописав там нужные параметры:


//CURL
curl -X 'POST' \
  '"Ссылка для работы с мастером"/api/Queues/PushElementToQueue?queueName=queueName&data=data&priority=1&postponeDate=2022-09-21T17%3A32%3A28Z&deadlineDate=2022-09-22T17%3A32%3A28Z&comment=comment&reference=reference&isReferenceUnique=false' \
  -H 'accept: text/plain' \
  -d ''

//URL
"Ссылка для работы с мастером"/api/Queues/PushElementToQueue?queueName=queueName&data=data&priority=1&postponeDate=2022-09-21T17%3A32%3A28Z&deadlineDate=2022-09-22T17%3A32%3A28Z&comment=comment&reference=reference&isReferenceUnique=false

API-запрос можно осуществить в приложении Postman (надо установить программу на компьютере).
Для этого (1) выбираем команду POST, вставляем сформированную в Swagger ссылку (URL) и (2-3) авторизуемся по токену (API запроса токена).
Мы получим ответ в виде ключа и присвоенного значения.

Добавить элемент в очередь. (POST)
Этот запрос отличается от предыдущего тем, что записываемое значение указывается в Body.

Можно использовать шаблон запроса, прописав там нужные параметры:


//CURL
curl -X 'POST' \
  '"Ссылка для работы с мастером"/api/Queues/PushElementToQueueFromBodyData?priority=1&isReferenceUnique=false' \
  -H 'accept: text/plain' \
  -H 'Content-Type: application/json' \
  -d '"data"'

//URL
"Ссылка для работы с мастером"/api/Queues/PushElementToQueueFromBodyData?priority=1&isReferenceUnique=false

В Postman необходимо дополнительно указать значение в Body:

Получаем Json с полями: key – идентификатор элемента очереди, value – значение элемента очереди.

Получить элемент из очереди. (GET)

Сформировать запрос можно в Swagger, указав следующие параметры:

Можно задать необходимые параметры в шаблоне:


//CURL
curl -X 'GET' \
  '"Ссылка для работы с мастером"/api/Queues/GetElementFromQueue?queueName=%D0%9E%D1%87%D0%B5%D1%80%D0%B5%D0%B4%D1%8C1&reference=reference&priority=1&comment=comment' \
  -H 'accept: text/plain'

//URL
"Ссылка для работы с мастером"/api/Queues/GetElementFromQueue?queueName=%D0%9E%D1%87%D0%B5%D1%80%D0%B5%D0%B4%D1%8C1&reference=reference&priority=1&comment=comment

В результате выполнения запроса получаем Json с полями: key – идентификатор элемента очереди, value – значение элемента очереди.

Подтвердить обработку элемента. (POST)

Сформировать запрос можно в Swagger, указав следующие параметры:

Можно использовать шаблон запроса, прописав там нужные параметры:


//CURL
curl -X 'POST' \
  '"Ссылка для работы с мастером"/api/Queues/ConfirmQueueItemProcessFinish?id=1&isSuccess=true&errorComment=%D0%BD%D0%B5%20%D0%BE%D0%B1%D1%80%D0%B0%D0%B1%D0%BE%D1%82%D0%B0%D0%BD&errorType=1' \
  -H 'accept: */*' \
  -d ''

//URL
"Ссылка для работы с мастером"/api/Queues/ConfirmQueueItemProcessFinish?id=1&isSuccess=true&errorComment=%D0%BD%D0%B5%20%D0%BE%D0%B1%D1%80%D0%B0%D0%B1%D0%BE%D1%82%D0%B0%D0%BD&errorType=1

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

Отменить элемент очереди. (POST)

Чтобы сформировать запрос в Swagger, надо указать следующие параметры:

Можно использовать шаблон запроса, прописав там нужные параметры:


//CURL
curl -X 'POST' \
  '"Ссылка для работы с мастером"/api/Queues/CancelQueueItem?id=1&comment=comment' \
  -H 'accept: */*' \
  -d ''

//URL
"Ссылка для работы с мастером"/api/Queues/CancelQueueItem?id=1&comment=comment

Получить статус элемента. (GET)

Для осуществления запроса надо указать ID элемента:


//CURL
curl -X 'GET' \
  '"Ссылка для работы с мастером"/api/Queues/GetQueueItemStatus?id=1' \
  -H 'accept: text/plain'

//URL
"Ссылка для работы с мастером"/api/Queues/GetQueueItemStatus?id=1

Получить элементы очереди по фильтру. (GET)

Чтобы сформировать запрос в Swagger, надо указать следующие параметры:

Можно использовать шаблон запроса, прописав там нужные параметры:


//CURL
curl -X 'GET' \
  '"Ссылка для работы с мастером"/api/Queues/GetQueueItemsByFilters?queueName=%D0%9E%D1%87%D0%B5%D1%80%D0%B5%D0%B4%D1%8C1&maxItems=100&statuses=new' \
  -H 'accept: text/plain'

//URL
"Ссылка для работы с мастером"/api/Queues/GetQueueItemsByFilters?queueName=%D0%9E%D1%87%D0%B5%D1%80%D0%B5%D0%B4%D1%8C1&maxItems=100&statuses=new

В результате получим JSON с элементами, соответствующими условиям фильтрации.

Наверх

API планировщика (SchedulersApi)

Включение/отключение планировщика.

API-запросы удобно формировать в Swagger (инструкция, как подключиться).
Надо нажать Try it out в правом верхнем углу, поля для настройки параметров станут активными.
Необходимо указать ID и статус (true - включить, false - отключить) планировщика.

Можно использовать этот код, указав ссылку для запуска мастера (без кавычек), ID и статус планировщика:


// CURL
curl -X 'POST' \
  '"Ссылка для работы с мастером"/api/Schedulers/UpdateSchedulerStatus?id=1&isActive=true' \
  -H 'accept: */*' \
  -d ''

// URL
'"Ссылка для работы с мастером"/api/Schedulers/UpdateSchedulerStatus?id=1&isActive=true

Для получения списка планировщиков с расписанием запуска задач и процессов воспользуйтесь GET запросом:


/api/GetSchedulersList

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

Для получения текущего статуса (true/false = активен/неактивен) планировщика с определенным id существует GET метод:


/api/Schedulers/GetSchedulersActivityStatus

Наверх

API проектов (ProjectsApi)

API проектов позволяет получить список проектов, загрузить новую версию проекта/новый проект и получить архив проекта без использования веб-интерфейса Мастера.

API-запросы удобно формировать в Swagger (инструкция, как подключиться).
Доступны 4 способа взаимодействия с проектами:

Получение списка проектов.

Для формирования запроса в Swagger надо нажать на Try it out в правом верхнем углу, тогда поля с параметрами станут активными.
Для получения списка проектов параметры не задаются.
Можно использовать этот код, указав ссылку для запуска мастера:


// CURL
curl -X 'GET' \
  '"Ссылка для работы с мастером"/api/Projects/GetProjectList' \
  -H 'accept: */*'

// URL
"Ссылка для работы с мастером"/api/Projects/GetProjectList

API-запрос можно осуществить в приложении Postman (надо установить программу на компьютере).
Для этого надо (1) авторизоваться по токену (API запроса токена), (2) выбрать команду GET и вставить сформированную в Swagger ссылку (URL).

В результате получим список проектов.

Загрузка новой версии проекта

Для формирования запроса в Swagger необходимо заполнить следующие поля:

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


// CURL
curl -X 'POST' \
  '"Ссылка для работы с мастером"/api/Projects/UploadProjectVersion?projectId=1&entryPoint=entryPoint&version=version&description=description&isActual=false' \
  -H 'accept: */*' \
  -d ''
// URL
"Ссылка для работы с мастером"/api/Projects/UploadProjectVersion?projectId=1&entryPoint=entryPoint&version=version&description=description&isActual=false

Получить архив проекта

Для формирования запроса в Swagger необходимо заполнить следующие поля:

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


// CURL
curl -X 'POST' \
  '"Ссылка для работы с мастером"/api/Projects/DownloadProject?projectId=1&version=version' \
  -H 'accept: text/plain' \
  -d ''

// URL
"Ссылка для работы с мастером"/api/Projects/DownloadProject?projectId=1&version=version

Загрузка нового проекта.

Для формирования запроса в Swagger необходимо заполнить следующие поля:

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


// CURL
curl -X 'POST' \
  '"Ссылка для работы с мастером"/api/Projects/UploadProject?entryPoint=entryPoint&name=name&description=description' \
  -H 'accept: */*' \
  -d ''

// URL
"Ссылка для работы с мастером"/api/Projects/UploadProject?entryPoint=entryPoint&name=name&description=description

Метод для получения атрибутов и данных проекта
GET - метод API:


/api/Projects/GetProject?projectId={projectId}.

В обязательном параметре projectId передается значение идентификатора проекта.
Возвращается IProjectInfo - проект с соответствующим идентификатором, активной и последней версиями проекта (возвращается одна версия - если она одновременно является активной и последней).

Метод для проверки существования проекта
GET - метод API:


/api/Projects/ProjectExists?projectId={projectId}

В обязательном параметре projectId передается значение идентификатора проекта.
Возвращается true, если проект с соответствующим идентификатором существует или false, если такого проекта нет или пользователь не состоит в группе, имеющей доступ к данному проекту.

Наверх

API шаблонов расписания (ScheduleTypes)

Получение списка названий шаблонов расписаний
GET-медод


/api/ScheduleTypes/GetList?scheduleMode=Calendar

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

Получение списка дат для шаблона расписания с видом Calendar
GET-метод


/api/ScheduleTypes/GetCalendar?name=test

В обязательном параметре name передается значение имени шаблона.

Наверх