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

                                                  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

                                                  API очередей (QueuesApi)
                                                  Работа с очередями данных.

                                                  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).

                                                        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