API RESTful

API RESTful использует модель запрос-ответ протокола передачи гипертекста (HTTP) для связи с MATLAB ® Production Server™. Эта модель включает методы запросов, коды ответов, заголовки сообщений и тела сообщений. API RESTful имеет следующие характеристики :

Методы HTTP - POST, GET и DELETE - образуют основной режим связи между клиентом и сервером.
Уникальные универсальные идентификаторы ресурсов (URI) идентифицируют ресурсы, создаваемые сервером.
Заголовки сообщений передают метаданные, такие как Content-Type запроса.
- API поддерживает application/json как HTTP Content-Type заголовок.
- API RESTful для выполнения функций MATLAB также поддерживает application/x-google-protobuf как HTTP Content-Type только через API клиента Java ® и .NET.
Текст сообщения запроса содержит информацию, подлежащую отправке на сервер.
- При использовании JSON в качестве формата сериализации данных входные данные функции MATLAB, содержащиеся в развернутом архиве, представляются в JSON и инкапсулируются в тело сообщения.
- При использовании буферов протокола (protobuf) для сериализации данных клиентские библиотеки Java и .NET предоставляют вспомогательные классы для внутреннего создания сообщений protobuf на основе формата proto и возвращают соответствующий массив байтов. Используйте этот массив байтов в теле сообщения запроса.
Текст сообщения ответа содержит информацию о запросе, такую как состояние или результаты.
Если для сериализации данных используется protobuf, клиентские библиотеки Java и .NET предоставляют методы и классы для десериализации ответов protobuf.
API поддерживает синхронный и асинхронный режимы сервера.

Примечание

Приведенные ниже примеры и графика используют JSON в качестве формата сериализации данных.

RESTful API для выполнения функции MATLAB

Напечатать	Цель
Синхронное выполнение (производственный сервер MATLAB)	Выполнение синхронных запросов к серверу
Асинхронное выполнение (производственный сервер MATLAB)	Выполнение асинхронных запросов к серверу

API RESTful для обнаружения и диагностики серверов

Напечатать	Цель
Служба обнаружения (производственный сервер MATLAB)	Обнаружение функций MATLAB, развернутых на сервере
Проверка работоспособности (производственный сервер MATLAB)	Проверка работоспособности сервера

Синхронное выполнение

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

Вызовы API RESTful для синхронного режима

Звонить	Цель
Синхронный запрос POST (производственный сервер MATLAB)	Выполнение синхронного запроса на сервер и ожидание ответа

На следующем рисунке показано, как API RESTful работает в синхронном режиме.

When the server receives a request in synchronous mode, it blocks all other requests till it finishes processing the current request.

Пример: Синхронное выполнение магического квадрата с использованием RESTful API и JSON

В этом примере показано, как использовать API RESTful и JSON, предоставляя две отдельные реализации - одну с использованием ^JavaScript ®, а другую с использованием Python ®. При ^{выполнении} этого примера сервер возвращает список из 25 разделенных запятыми значений. Эти значения являются выходными данными развернутой функции MATLAB mymagic, представленный в формате «основной столбец». Код MATLAB для mymagic следует функция.

function out = mymagic(in)
out = magic(in);

В этом примере выполняется экземпляр производственного сервера MATLAB, содержащий развернутую функцию MATLAB. mymagic должен быть запущен. Дополнительные сведения о создании развертываемого архива см. в разделе Создание развертываемого архива для производственного сервера MATLAB. Дополнительные сведения о настройке сервера см. в разделе Создание экземпляра сервера (MATLAB Production Server).

Реализация JavaScript

При реализации JavaScript API RESTful сценарий включается в <script> </script> теги HTML-страницы. При открытии этой HTML-страницы в веб-браузере сервер возвращает значения mymagic функция. Обратите внимание, что сервер должен иметь CORS включен для работы кода JavaScript. Дополнительные сведения о включении CORS, см. cors-allowed-origins(Производственный сервер MATLAB).

Код:

restApiSyncMagicJavaScript.html

Реализация Python

В этом примере используется Python 2.x. При использовании Python 3.x необходимо изменить некоторые части кода.

Код:

restApiSyncMagicPython.py

Сведения о том, как развернуть функцию MATLAB на производственном сервере MATLAB и вызвать ее с помощью RESTful API и JSON, см. в разделе Веб-инструмент с использованием RESTful API, JSON и JavaScript.

Асинхронное выполнение

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

Вызовы API RESTful для асинхронного режима

Звонить	Цель
Асинхронный запрос POST (производственный сервер MATLAB)	Сделать асинхронный запрос на сервер
Представление асинхронного запроса GET (производственный сервер MATLAB)	Просмотр представления асинхронного запроса к серверу
Сбор запросов GET (производственный сервер MATLAB)	Просмотр коллекции запросов
Информация о состоянии GET (производственный сервер MATLAB)	Получение информации о состоянии запроса
Результат запроса GET (производственный сервер MATLAB)	Получение результатов запроса
Запрос на отмену POST (производственный сервер MATLAB)	Отменить запрос
Запрос DELETE (производственный сервер MATLAB)	Удалить запрос

На следующем рисунке показано, как API RESTful работает в асинхронном режиме. Рисунок не охватывает все вызовы API RESTful. Полный список вызовов см. в предыдущей таблице.

Asynchronous request processing.

Пример: Асинхронное выполнение магического квадрата с использованием RESTful API и JSON

В этом примере показано, как использовать API RESTful и JSON для асинхронного выполнения с использованием JavaScript. При выполнении этого примера сервер возвращает список из 100 разделенных запятыми значений. Эти значения являются выходными данными развернутой функции MATLAB mymagic, представленный в формате «основной столбец». Код MATLAB для mymagic следует функция.

function out = mymagic(in)
out = magic(in);

Код:

restApiAsyncMagicJavaScript.html

<!DOCTYPE html>
<html>

    <head>
        <title>Magic Square</title>
        <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.11.0/jquery.min.js"></script>
        <script>
            // MPS RESTful API (Asynchronous): Specify URL
            var hostname = "http://localhost:9910";
            var mode = "async";
            var clientID = "client100";
            var ctfName = "mymagic";
            var matlabFuncName = "mymagic"
            var url = hostname + "/" + ctfName + "/" + matlabFuncName + "?mode=" + mode + "&client=" + clientID;
            // Specify arguments
            var params = {
                "nargout": 1,
                "rhs": [100],
                "outputFormat": {"mode": "small"}
            };
            $.ajax(url, {
                data: JSON.stringify(params),
                //MPS RESTful API (Asynchronous): Specify Content-Type to application/json and Specify HTTP POST method
                contentType: 'application/json',
                method: 'POST',
                dataType: 'json',
                success: function(response) {
                    // Print Request URI to webpage
                    $("#requestURI").html('<strong>Request URI: </strong>' + hostname + response.self);
                    pollUsingUp(response);
                }
            });
            // Polling Server using UP
            function pollUsingUp(request) {
                setTimeout(function() {
                    var newSeq = parseInt(request.lastModifiedSeq) + 1;
                    var queryURI = hostname + request.up + "?since=" + newSeq + "&ids=" + request.id;
                    $.ajax({
                        url: queryURI,
                        method: 'GET',
                        dataType: 'json',
                        success: function(response) {
                            //Poll again if no data about the request was received.
                            if (response.data.length == 0) {
                                pollUsingUp(request);
                                return;
                            }

                            var requestResource = response.data[0];
                            // Print "state" of request
                            $("#state").html('<strong>State: </strong>' + requestResource.state);


                            if (requestResource.state != "READY" && requestResource.state != "ERROR") {
                                //Keep polling if the request is not done yet.
                                pollUsingUp(requestResource);
                            } else {
                                var requestURI = hostname + requestResource.self;
                                var responseURI = hostname + requestResource.self + "/result";
                                // Get result.
                                $.ajax({
                                    url: responseURI,
                                    // MPS RESTful API (Asynchronous): Specify HTTP GET method
                                    method: 'GET',
                                    dataType: 'json',
                                    success: function(response) {
                                        if (response.hasOwnProperty("lhs")) {
                                            $("#demo").html('<p>' +
                                                response.lhs[0] + '</p>');
                                            //Uncomment the next line if using JSON large representation
                                            //response.lhs[0].mwdata + '</p>');

                                        } else if (response.hasOwnProperty("error")) {
                                            alert("Error: " + response.error.message);
                                        }
                                        // MPS RESTful API (Asynchronous): Specify HTTP DELETE method
                                        $.ajax({
                                            url: requestURI,
                                            method: 'DELETE'
                                        });
                                    }
                                });
                            }
                        }
                    });
                }, 200);
            }
        </script>
    </head>

    <body>
        <p><strong>MPS RESTful API and JSON EXAMPLE</strong></p>
        <p> >> mymagic(5)</p>
        <p id="requestURI"></p>
        <p id="state"></p>
        <p id="demo"></p>
        <p> # output from server returned in column-major format </p>
    </body>

</html>

Управление HTTP-файлами cookie

Развертывание сервера MATLAB Production Server на Azure ® предоставляет URL-адрес конечной точки HTTPS для вызова функций MATLAB, развернутых на сервере. Шлюз приложений Azure обеспечивает сходство сеансов на основе файлов cookie, где он использует файлы cookie для сохранения сеанса пользователя на том же сервере. При получении запроса от клиентской программы шлюз приложений устанавливает Set-Cookie Заголовок ответа HTTP с информацией о виртуальной машине сервера, обрабатывающей запрос.

Асинхронное выполнение запроса

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

Синхронное выполнение запроса

Клиентская программа, использующая синхронные запросы для выполнения функции MATLAB, развернутой на сервере, не должна устанавливать Cookie Заголовок запроса HTTP со значением Set-Cookie заголовок, и должен очистить значение Cookie если он был установлен ранее. Это обеспечивает балансировку нагрузки синхронных запросов и их обработку одной и той же виртуальной машиной сервера.

Дополнительные сведения об архитектуре и ресурсах для производственного сервера MATLAB на Azure см. в разделах Архитектура и ресурсы на Azure (производственный сервер MATLAB) и Архитектура и ресурсы на Azure (производственный сервер MATLAB).

Служба обнаружения

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

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

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

Вызовите службу обнаружения с помощью метода HTTP GET.

Вызовы API RESTful для службы обнаружения

Звонить	Цель
Информация об обнаружении GET	Обнаружение функций MATLAB, развернутых на сервере

Ответ от сервера является объектом JSON.

Example of a response to the GET discovery information request.

Объект ответа JSON

Object {;}

Имя	Описание
`discoverySchemaVersion`	Номер версии схемы обнаружения. Примерное значение: `1.0.0`
► `archives`	Список развернутых архивов. См. раздел Архивы.

Архивы

archives

Имя	Описание
`archiveSchemaVersion`	Номер версии схемы архива. Примерное значение: `1.1.0`
`archiveUuid`	Уникальный идентификатор.
`name`	Имя архива CTF.
`matlabRuntimeVersion`	Версия среды выполнения MATLAB. Примерное значение: `9.5.0`
`typedefs`	При развертывании функций MATLAB, для которых в качестве входных данных требуются массивы или структуры ячеек, необходимо определить их как `typedefs`. Дополнительные сведения см. в разделе Typedefs.
`► functions`	Объект функции для каждой развертываемой функции. Дополнительные сведения см. в разделе Функции.

Typedefs

typedefs

Функции

functions

Проверка работоспособности

Используйте API проверки работоспособности, чтобы определить, имеет ли сервер действительную лицензию и может ли он обрабатывать HTTP-запросы. Проверка работоспособности классифицирует сервер как исправный или нездоровый в зависимости от того, имеет ли сервер действительную лицензию и может ли он взаимодействовать с менеджером сетевых лицензий. Дополнительные сведения о лицензировании см. в разделе Управление лицензиями для производственного сервера MATLAB (MATLAB Production Server).

Работоспособность сервера	Код состояния ответа HTTP	Описание
Здоровый	200 OK	Сервер исправен, если он находится в одном из следующих состояний: Сервер работает с действительной лицензией. Сервер связывается с менеджером сетевых лицензий, и необходимое количество ключей лицензий извлекается. Сервер потерял связь с менеджером сетевых лицензий, но сервер по-прежнему полностью работоспособен и будет работать до конца льготного периода, как указано в `license-grace-period`(Производственный сервер MATLAB).
Вредный для здоровья	503 Health Check Failed	Сервер потерял связь с менеджером сетевых лицензий на период времени, превышающий льготный период. Обработка запросов приостановлена, но сервер активно пытается восстановить связь с менеджером сетевых лицензий. Обработка запроса возобновляется, если сервер может восстановить связь с менеджером лицензий.

Если проверка работоспособности выполнена успешно, ответ от сервера является объектом JSON, указывающим на работоспособность сервера.

{
  "status": "ok"
}

Сбой проверки работоспособности указывает на то, что сервер недоступен для обработки HTTP-запросов, но не предоставляет дополнительных сведений о причине сбоя в теле ответа. Администраторы сервера могут использовать mps-status(Производственный сервер MATLAB) для получения подробной информации о состоянии сервера. Вы должны находиться в той же системе, что и сервер для запуска mps-status.

Вызов API RESTful для проверки работоспособности

Звонить	Цель
Работоспособность сервера GET (производственный сервер MATLAB)	Получение информации об общем состоянии сервера

См. также

mps-status(Производственный сервер MATLAB)

Связанные темы

Создание экземпляра сервера (производственный сервер MATLAB)
Проверка состояния сервера (производственный сервер MATLAB)

Документация

API RESTful

Синхронное выполнение

Пример: Синхронное выполнение магического квадрата с использованием RESTful API и JSON

Реализация JavaScript

Реализация Python

Асинхронное выполнение

Пример: Асинхронное выполнение магического квадрата с использованием RESTful API и JSON

Управление HTTP-файлами cookie

Асинхронное выполнение запроса

Синхронное выполнение запроса

Служба обнаружения

Объект ответа JSON

Архивы

Typedefs

Функции

Проверка работоспособности

См. также

Связанные темы

Документация по SDK компилятора MATLAB

Поддержка