网络服务

SmartEDB 使用流行的 REST（表述性状态转移）协议提供 Web 服务。REST 服务器可以通过支持 HTTP 和 JSON 的任何语言访问，包括但不限于 C/C++、Python、Java 和 C#。请注意，REST 服务器只是一个提供 JSON 内容的 HTTP 服务器，因此符合 HTTP 和 JSON 标准。 RESTful Web 服务支持基本 HTTP 身份验证和使用 SSL 的加密通信。基本 HTTP 身份验证机制根据 RFC 2617 实现用户名和密码的身份验证。根据 RFC，用户名和密码未加密，这意味着在没有 SSL（或替代加密方法）的情况下使用此身份验证方法不能被视为安全。 SmartEDB 中 RESTful Web 服务的 SSL 实现方式与 SmartEDB 的其他网络组件类似（详情请参阅网络通信页面）。

概述

SmartEDB 通过实现 RESTful 网络服务来发布内部状态及其他信息，包括

数据库统计信息、
架构定义、
性能指标、
数据库内容（即将推出）。

SmartEDB 的 REST API 可通过以下方式之一启用：

如果数据库由 xSQL 启动，则通过 xSQL 配置参数；
或者如果数据库嵌入到应用程序中，mcorest 库会使用 mcoews 嵌入式 Web 服务库提供 REST C API 函数。

请注意，SmartEDB 支持任意深度的嵌套数据类型，例如，一个类可能包含一个结构，该结构可能包含其他结构的数组，而这些结构又可能包含其他字段等等。但是，实现单个数组、序列或结构元素访问的 RESTful API 方法仅适用于顶级字段（即类的字段）。此外，还可以使用 api/db/<dbname>/classes/<struct_no>/byindex/<index_no>/eq/<key>/field/<field_no>/at/<elem_index> 资源访问顶级对象中包含的结构的各个字段。

mcorest 库中实现的 C API 在“Web 服务 C API 参考”页面中有描述。以下部分演示了如何使用 xSQL 来公开 REST 服务器。

xSQL REST API 演示

要在 xSQL 中启动 REST 服务器，请在 SmartEDB/target/bin 目录中创建一个类似以下内容的配置文件 xsql.cfg：

    database_name : xsqldb,
    database_size : 100m, 
     
    rest : {
        addr : 127.0.0.1,
        port : 8083
    }

请注意，IP 地址参数 addr 明确设置为本地回环地址 127.0.0.1，仅用于演示目的。如果省略此参数，则默认为 0.0.0.0，这将允许 REST 服务器接受所有可用网络接口（局域网、WiFi 等）上的传入连接。请注意，这种默认行为可能不理想，甚至存在危险。若要限制网络访问，可以指定任何有效的 IP 地址；例如“addr : 192.168.0.5”。

使用此配置文件，您可以在 Unix-Linux 系统上通过如下命令启动 xSQL 并请求 REST 资源：

    ~/mcobject/SmartEDB_8.0$ ./SmartEDB/target/bin/xsql -c xsql.cfg &  
    [1] 11721
    ~/mcobject/SmartEDB_8.0$ NOTICE:  Starting XSQL
    NOTICE:  xsql started
    NOTICE:  mcorest started at port 8083
    Ctrl-C to stop SQL server
 
    ~/mcobject/SmartEDB_8.0$ curl http://localhost:8083/api/db
    {
        "databases":
        [
            "xsqldb",
            "eXDB_perf"
        ]
    }

或者在 Windows 系统上，从 SmartEDB/target/bin 目录使用以下命令启动 xSQL：

    xsql -c xsql.cfg  
    NOTICE:  Starting XSQL
    NOTICE:  xsql started
    NOTICE:  mcorest started at port 8083
     
    press Enter to stop SQL server

现在在您的浏览器中输入网址 http://localhost:8083/api/db ，随后浏览器将显示以下资源：

    {
        "databases":
        [
            "xsqldb"
        ]
    }

db 资源只是以 JSON 格式列出可用数据库的名称。有关 REST 服务器提供的资源的描述，请参阅 SmartEDB Web 服务资源页面。

使用 mcorest 库 API

mcorest 库既可以在手动多线程模式下使用，也可以在自动多线程模式下使用。后者配置起来更简单，因为 mcorest 库会内部管理接口和连接。然而，在某些情况下需要单线程模型，或者更倾向于对 API 进行更高程度的控制；在这种情况下应使用手动模式。下面将对这两种模式进行描述。本描述旨在对库进行概述。

初始化

在调用任何其他 mcorest 函数之前，通过调用 mcorest_initialize() 来初始化 mcorest 库。接下来，应用程序通过调用 mcorest_create() 创建一个 mcorest 服务器实例。应用程序通过 mcorest_h *rest 输出参数接收服务器的句柄。对于每个要服务的数据库，都应创建一个服务器实例。

然后，应用程序调用 mcorest_add_interface() 函数，告知 REST 服务器要监听的地址和端口。可以通过连续调用此函数来指定多个接口。

如果应用程序希望使用所提供的网络服务数据库、性能和 SQL，那么它必须调用相应的函数（mcorest_svc_db_init()、mcorest_svc_perf_init() 或 mcorest_svc_sql_init()）来显式地初始化这些服务。

基本 HTTP 身份验证

要启用基本 HTTP 身份验证，请使用 mcorest_set_basic_auth() C API 函数。使用 xSQL 时，请设置 rest 部分的 http_realm、http_username 和 http_password 参数。

要启用 SSL，请将指向 SSL 参数结构的指针传递给 mcorest_add_interface() C API 函数。使用 xSQL 时，可在全局 ssl_params 部分设置全局设置，或者在 rest 部分的 ssl_params 子部分设置特定于 REST 的设置。

执行

如上所述，服务器可以在自动多线程模式下运行。或者，应用程序也可以手动控制其执行。下面将对这两种模式进行讨论。

自动多线程模式

要启动服务器，应用程序需调用 mcorest_start()。在服务器以自动模式运行期间，应用程序不允许调用任何 mcorest_*() 方法，但当应用程序需要停止 REST 服务器（例如在关闭时）时，可以调用 mcorest_stop()。

手动模式

此模式可能更受那些需要对 Web 服务器进行更精细控制的应用程序的青睐。当目标平台不支持多线程时，这也是唯一的选择。

在单线程环境中，应用程序通常会在其运行循环中以方便之处插入以下步骤：

调用函数 mcorest_interface_check() 来等待并接受新的连接。（传入 0 可以轮询接口而不阻塞。）如果接受到新的连接，此调用将返回 MCO_S_REST_CONN_ACCEPTED，并通过 mcorest_conn_h *conn 参数将连接句柄传递给调用者。应用程序应保存此句柄，直到连接完成或取消。
对于一些或所有活动连接，调用函数 mcorest_conn_execute() 以使它们与对等方交换数据。如果连接正常执行并关闭，此函数将返回 MCO_S_REST_CONN_FINISHED 状态码。或者，如果连接仍然存活，则返回 MCO_S_OK 代码。应用程序可以选择使用函数 mcorest_conn_cancel() 关闭不需要的活动连接。

当应用程序不再需要 REST 服务器时，应使用函数 mcorest_conn_cancel() 取消所有活动连接。

在多线程模式下，应谨慎避免在各线程之间共享 REST 服务器实例、接口和连接。