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

Взаимодействие с PIX Master через 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.

          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)

                  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
                                                          
                                                          
                                                          API-запрос можно осуществить в приложении Postman (надо установить программу на компьютере).
                                                          Для этого надо авторизоваться по токену (API запроса токена), выбрать команду POST и вставить сформированную в Swagger ссылку (URL).
                                                                Для получения списка планировщиков с расписанием запуска задач и процессов воспользуйтесь 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 передается значение имени шаблона.