用于安全管理可部署存档的 RESTful API

用于安全上传可部署存档的 MATLAB^® Production Server™ RESTful API 可让您安全地将存档上传、管理和部署到服务器。您可以使用 API 来：

将存档部署到服务器。
检查存档是否已部署到服务器。
列出部署到服务器上的所有存档。
更新服务器上的存档。
从服务器上删除存档。

所有这些服务都以 JSON 格式返回响应。

RESTful API 的特点

用于安全管理可部署存档的 RESTful API 使用 HTTP 请求-响应模型与 MATLAB Production Server 进行通信。该模型包括请求方法、响应码、消息头、消息体。用于安全管理可部署存档的 RESTful API 具有这些特点：

HTTP 方法 POST、GET、PUT 和 DELETE 构成了客户端和服务器之间的主要通信模式。
使用 GET 和 DELETE 方法向服务器发出的请求没有消息体，因此无需在请求中设置 Content-Type 标头。
响应的消息体包含请求的特定信息，如部署到服务器的存档信息。
唯一的统一资源标识符 (URI) 标识服务器创建的资源。

启用 RESTful API，安全管理可部署存档

要启用 RESTful API 以安全管理可部署存档，请取消注释 main_config 文件中的这些条目：

--enable-archive-management - 此条目可启用 API
--request-size-limit - 此条目设置请求正文的最大大小，默认值为 64MB，最大允许值为 1GB。API 不支持用于上传可部署存档的分块传输编码。

为可部署存档配置安全性

访问控制是可选项，默认情况下不启用。其目的是限制在开放访问系统中上传和执行可部署存档的访问权限，因为这样做会带来安全风险。在 main_config 文件中取消注释以下条目即可启用该功能：

--access-control-provider OAuth2
--access-control-config ./config/jwt_idp.json
--access-control-policy ./config/ac_policy.json

有关访问控制的更多信息，请参阅应用程序访问控制。启用访问控制后，上传、更新和删除存档需要在访问控制策略文件中执行“修改”操作，而列出存档则不需要。

上传可部署存档

您可以使用可部署存档上传服务，通过 HTTP 请求将可部署存档上传到 MATLAB Production Server。有关为 MATLAB Production Server 创建可部署存档的更多信息，请参阅针对 MATLAB Production Server 创建可部署存档。要上传您的存档，请使用此请求格式。

POST /api/archives?ctf=<filename> HTTP/1.1
Host: <hostname>:<port>
User-Agent: curl/7.88.1
Accept: */*
Content-Type: application/octet-stream
Authorization: Bearer <JSON Web Token>
Content-Length: <content-length>

filename - 可部署存档的名称，不含 .ctf 文件扩展名。API 一次只接受一个文件名查询参数和一个值。

JSON Web Token - 授权令牌

content-length - 内容长度，以字节为单位

hostname - 服务器实例的主机名

port - 服务器实例的端口名称

上传存档后，MATLAB Production Server 会返回一个 JSON 对象，其正文如下：

{
  "action": "Upload",
  "archive": <filename>,
  "result": true
  "size": Size in bytes (if known)
}

如果上传的文件不是有效的可部署存档，该文件将出现在自动部署目录中。但是，它不会执行。

要使用 POST 请求上传可部署存档，请求必须使用服务器上不存在的存档名称。如果尝试上传服务器上已存在的可部署存档，MATLAB Production Server 将返回错误。要更新现有可部署存档，请参阅更新可部署存档。

有授权令牌的 MATLAB 示例

如果配置了安全性，可使用以下 MATLAB 函数上传可部署存档。该函数接收扩展名为 .ctf 的可部署存档、主机名、端口号和 JSON 网络令牌。然后，函数会显示 MATLAB Production Server 返回的 JSON 对象，并使用 matlab.net.http.RequestMessage (MATLAB) 类格式化 HTTP 请求消息并将其发送到服务器。

function upload_authz(ctf, host, port, token)
    % ctf: Name of archive without .ctf extension, specified as string
    % host: host name, specified as string
    % port: port number, specified as int
    % token: JSON Web Token, specified as string

    [~,ctfName,~] = fileparts(ctf);
    url = sprintf("http://%s:%d/api/archives?ctf=%s",host,port,ctfName);

    % List
    list_response = webread(url);
    disp(list_response.archive);
    fp = fopen(ctf);
    closeFP = onCleanup(@()fclose(fp));
    data = fread(fp,'*uint8');

    % Create the Content-Type and Authorization HTTP Header fields:
    contentTypeField = matlab.net.http.field.ContentTypeField('application/octet-stream');
    authzField = matlab.net.http.field.AuthorizationField('Authorization',['Bearer ',token]);

    % Create the request type
    requestMethod = matlab.net.http.RequestMethod.POST;
    alreadyThere = ismember(ctfName, list_response.archive) && list_response.result;
    if (alreadyThere) % update if already exists
        requestMethod = matlab.net.http.RequestMethod.PUT;
    end
    % Create the request message with POST method and binary data
    request = matlab.net.http.RequestMessage(requestMethod, ...
        [contentTypeField,authzField],data);

    % Create the URI with query parameters:
    mpsURI = matlab.net.URI(url);
    params = struct('ctf',ctfName);
    mpsURI.Query = params;

    % Send upload request
    upload_response = request.send(mpsURI);
    disp(upload_response);
    upload_result = upload_response.Body.Data;
    disp(upload_result);
end

无授权令牌的 MATLAB 示例

如果未配置安全性，可使用以下 MATLAB 函数上传可部署存档。该函数接收扩展名为 .ctf 的可部署存档、主机名和端口号。然后，函数会显示 MATLAB Production Server 返回的 JSON 对象，并使用 matlab.net.http.RequestMessage (MATLAB) 类格式化 HTTP 请求消息并将其发送到服务器。

function upload(ctf, host, port)
    % ctf: Name of archive without .ctf extension, specified as string
    % host: host name, specified as string
    % port: port number, specified as int

    [~,ctfName,~] = fileparts(ctf);
    url = sprintf("http://%s:%d/api/archives?ctf=%s",host,port,ctfName);

    % List
    list_response = webread(url);
    disp(list_response.archive);
    fp = fopen(ctf);
    closeFP = onCleanup(@()fclose(fp));
    data = fread(fp,'*uint8');

    % Create the Content-Type and Authorization HTTP Header fields:
    contentTypeField = matlab.net.http.field.ContentTypeField('application/octet-stream');

    % Create the request type
    requestMethod = matlab.net.http.RequestMethod.POST;
    alreadyThere = ismember(ctfName, list_response.archive) && list_response.result;
    if (alreadyThere) % update if already exists
        requestMethod = matlab.net.http.RequestMethod.PUT;
    end
    % Create the request message with POST method and binary data
    request = matlab.net.http.RequestMessage(requestMethod, ...
        contentTypeField,data);

    % Create the URI with query parameters:
    mpsURI = matlab.net.URI(url);
    params = struct('ctf',ctfName);
    mpsURI.Query = params;

    % Send upload request
    upload_response = request.send(mpsURI);
    disp(upload_response);
    upload_result = upload_response.Body.Data;
    disp(upload_result);
end

cURL 示例

curl -v -X POST  -H "Content-Type: application/octet-stream" -H "Authorization: Bearer <JSON Web Token>" \
--data-binary @<filename>.ctf http://<hostname>:<port>/api/archives?ctf=<filename>

在此 cURL 示例中，--data-binary @<filename>.ctf name 选项定义了要上传的可部署存档的文件名，而 URL 查询参数定义了服务器上使用的存档名称，两者可能不同。

列出可部署的存档

您可以使用可部署存档列表服务来检查特定可部署存档是否已部署到 MATLAB Production Server 实例，或列出 MATLAB Production Server 实例上的所有已部署存档。

搜索特定存档：

GET /api/archives?ctf=<filename> HTTP/1.1
Host: <hostname>:<port>
User-Agent: curl/7.88.1
Accept: */*
Authorization: Bearer <JSON Web Token>
Content-Length: <content-length>

列出服务器上的所有存档：

GET /api/archives HTTP/1.1
Host: <hostname>:<port>
User-Agent: curl/7.88.1
Accept: */*
Authorization: Bearer <JSON Web Token>
Content-Length: <content-length>

filename（可选）- 可部署存档的名称，不含 .ctf 文件扩展名。API 一次只接受一个文件名查询参数和一个值。

JSON Web Token - 授权令牌

content-length - 内容长度，以字节为单位

hostname - 服务器实例的主机名

port - 服务器实例的端口名称

如果包含 ctf 查询参数并在其中填入可部署存档的名称，JSON 响应就会包含一个 result 字段，用于指定存档是否已部署。回复正文的格式如下

{
  "action": "List",
  "archive": <filename>,
  "result": true
  "size": Size in bytes (if known)
}

如果不包含 ctf 查询参数，服务将列出部署到服务器上的所有存档。在这种情况下，响应体包括部署到服务器的所有存档的列表：

{
  "version": "1.0.0",
  "archives": [
    {
      "archive": "filename1"
    },
    {
      "archive": "filename2"
    },
    {
      "archive": "filename3"
    }
  ]
}

cURL 示例

列出服务器上的所有存档：

curl <hostname>:<port>/api/archives

搜索特定存档：

curl <hostname>:<port>/api/archives?ctf=<filename>

更新可部署存档

您可以使用更新可部署存档服务来更新 MATLAB Production Server 实例上的可部署存档。端点要求提供要更新的可部署存档的文件名和授权令牌。

PUT /api/archives?ctf=<filename> HTTP/1.1
Host: <hostname>:<port>
User-Agent: curl/7.88.1
Accept: */*
Content-Type: application/octet-stream
Authorization: Bearer <JSON Web Token>
Content-Length: <content-length>

filename - 可部署存档的名称，不含 .ctf 文件扩展名。API 一次只接受一个文件名查询参数和一个值。

JSON Web Token - 授权令牌

content-length - 内容长度，以字节为单位

hostname - 服务器实例的主机名

port - 服务器实例的端口名称

可部署存档更新服务会返回一个 JSON 对象，确认已更新文件的名称。回复正文的格式如下

{
  "action": "Update",
  "archive": <filename>,
  "result": true
  "size": Size in bytes (if known)
}

要使用 PUT 请求更新可部署存档，请求必须使用服务器上已存在的存档名称。如果尝试更新服务器上不存在的可部署存档，MATLAB Production Server 将返回错误。要上传新的可部署存档，请参阅上传可部署存档。

cURL 示例

curl -v -X PUT  -H "Content-Type: application/octet-stream" -H "Authorization: Bearer <JSON Web Token>" \
--data-binary @<filename>.ctf http://<hostname>:<port>/api/archives?ctf=<filename>

删除可部署存档

您可以使用可部署存档删除服务从服务器实例中删除可部署存档。端点要求提供要删除的可部署存档的文件名和授权令牌。

DELETE /api/archives?ctf=<filename> HTTP/1.1
Host: <hostname>:<port>
User-Agent: curl/7.88.1
Accept: */*
Authorization: Bearer <JSON Web Token>

filename - 可部署存档的名称，不含 .ctf 文件扩展名。应用程序接口一次只接受 1 个文件名查询参数和 1 个值

JSON Web Token - 授权令牌

hostname - 服务器实例的主机名

port - 服务器实例的端口名称

可部署存档删除服务会返回一个 JSON 对象，确认已删除文件的名称。如果存档不存在，则会产生 403 错误。回复正文的格式如下

{
  "action": "Delete",
  "archive": <filename>,
  "result": true
}

cURL 示例

% curl -v -X DELETE -H "Authorization: Bearer <JSON Web Token>" \
 http://<hostname>:<port>/api/archives?ctf=<filename>

另请参阅

mps-status | license-grace-period | prodserver.metrics.setGauge (MATLAB Compiler SDK) | prodserver.metrics.incrementCounter (MATLAB Compiler SDK)