RESTful API

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

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

Примечание

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

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

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

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

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

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

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

RESTful API вызывает синхронный режим

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

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

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

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

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

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

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

Реализация JavaScript

С реализацией JavaScript RESTful API, вы включаете скрипт в <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 Production Server и вызвать ее с помощью RESTful API и JSON, смотрите веб- Инструмент с использованием RESTful API, JSON и JavaScript.

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

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

RESTful API вызывает асинхронный режим

Звонить	Цель
POST асинхронный запрос (MATLAB Production Server)	Сделайте асинхронный запрос к серверу
GET-представление асинхронного запроса (MATLAB Production Server)	Просмотр представления асинхронного запроса на сервер
Сбор запросов GET (MATLAB Production Server)	Просмотр набора запросов
Информация о состоянии GET (MATLAB Production Server)	Получите информацию о состоянии запроса
GET результат запроса (MATLAB Production Server)	Получение результатов запроса
Запрос на отмену POST (MATLAB Production Server)	Отменить запрос
Запрос на УДАЛЕНИЕ ( MATLAB Production Server)	Удалить запрос

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

Asynchronous request processing.

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

В этом примере показано, как использовать RESTful API и 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>

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

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

Выполнение асинхронного запроса

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

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

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

Для получения дополнительной информации об архитектуре и ресурсах для MATLAB Production Server на Azure, смотрите Architecture and Resources on Azure (MATLAB Production Server) и Architecture and Resources on Azure (MATLAB Production Server).

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

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

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

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

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

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

Звонить	Цель
ПОЛУЧЕНИЕ информации об обнаружении	Обнаружение функций 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 Runtime. Пример значения: 9.5.0
`typedefs`	Если вы развертываете функции MATLAB, которые требуют массивов ячеек или структур в качестве входов, вы должны задать их как `typedefs`. Для получения дополнительной информации смотрите Typedefs.
`► functions`	Объект функции для каждой функции, которую вы развертываете. Для получения дополнительной информации смотрите Функции.

Typedefs

typedefs

Функции

functions

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

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

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

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

{
  "status": "ok"
}

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

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

Звонить	Цель
Состояние сервера GET (MATLAB Production Server)	Получите информацию об общем состоянии сервера

См. также

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

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

RESTful API

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

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

Реализация JavaScript

Реализация Python

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

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

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

Выполнение асинхронного запроса

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

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

Объект отклика JSON

Архивы

Typedefs

Функции

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

См. также

Похожие темы

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

Поддержка