如何使用趋势科技服务器深度安全防护系统 REST API
趋势科技服务器深度安全防护系统包括 REST（具象状态传输）Web 服务 API，允许趋势科技服务器深度安全防护系统功能与其他应用程序集成。这允许使用不依赖任何语言的简单编程方法从外部访问数据和编程配置。REST API 会使用标准 HTTP 机制，例如 GET 和 PUT，以及常用的数据编码方法，例如 JSON 和 XML。
有关 REST 接口中每个可用的 API 调用，访问每个调用所需的 HTTP 语法（包括 HTTP 路径和方法（GET 和 PUT 等）），以及传入或传出 API 调用的数据结构的描述，请参阅以下文档:
此 API 文档从包含的 Java REST API 客户端生成，但并不特定于任何编程语言。
包含的 Java REST API 客户端是基于 RESTEasy 项目，并且将 Apache HttpComponents™ 用于 HTTP 传输。这些项目的文档可以在 RESTEasy 项目和 Apache HttpComponents™ 项目中找到。
REST API 包括以下功能：
- 认证 - 用户登录及注销。
- 云帐户 - 创建、列出、更新并删除趋势科技服务器深度安全防护系统管理中心同步的云帐户；强制云同步。
- 事件 - 列出防恶意软件和 Web 信誉事件。
- 状态监控 - 查看趋势科技服务器深度安全防护系统管理中心节点的状态，包括各种运行状况检查。
- 租户管理 - 创建、列出、更新并删除租户帐户；创建并列出租户使用的数据库服务器。
- 使用情况监控 - 检索与趋势科技服务器深度安全防护系统管理中心为哪些租户执行了哪些操作有关的统计信息。
入门
REST API 的入门基本步骤如下：
- 启用状态监控 API（可选）。
- 创建外部 Web 服务客户端可以利用的用户帐户。
- 获取趋势科技服务器深度安全防护系统管理中心的 SSL 证书。
- 开发 REST API 客户端，以便与趋势科技服务器深度安全防护系统管理中心通信。
启用状态监控 API（可选）
不适用于趋势科技服务器深度安全防护系统即服务
在趋势科技服务器深度安全防护系统管理中心安装并启动后，REST API 的大多数功能都可用。它们无需任何附加配置。唯一的例外是：如果要使用状态监控，则必须先将其启用。缺省情况下，API 被禁用，因为它不需要身份验证来进行访问。
- 在趋势科技服务器深度安全防护系统管理中心中，转至管理 > 系统设置 > 高级。
- 在“状态监控 API”部分，选择已启用，然后单击保存。
创建 Web 服务用户帐户
如果用户帐户可以访问 Web 服务 API 或管理中心用户界面，那么趋势科技服务器深度安全防护系统管理中心允许强大的基于角色的访问，包括控制设置。出于安全原因，我们建议您创建新的用户帐户和新的 Web 服务特定的角色。
REST 和 SOAP Web 服务 API 都可以强制所有的角色访问控制，例如计算机权限、安全配置文件权限以及用户权限。如果角色是针对 Web 服务 API 创建的，且只允许查看特定的计算机组的计算机，那么使用该用户的 Web 服务客户端只能够访问指定的计算机组。
要创建新的 Web 服务只访问角色，请完成以下步骤：
- 在趋势科技服务器深度安全防护系统管理中心中，转至管理 > 用户管理 > 角色。
- 单击新建。
- 取消选中允许访问趋势科技服务器深度安全防护系统管理中心用户界面复选框，并选中允许访问 Web 服务 API 复选框。
- 在完成所有其他配置后，请单击保存。
- 转至管理 > 用户管理 > 用户，然后单击新建。
- 创建只使用 Web 服务 API 的新用户。向此用户分配之前创建的新角色。
记下新的用户帐户用户名和密码。
获取趋势科技服务器深度安全防护系统管理中心的 SSL 证书
所有的 REST API 客户端必须与使用 HTTPS 通信的趋势科技服务器深度安全防护系统管理中心通信。除非趋势科技服务器深度安全防护系统管理中心使用著名的证书颁发机构发放的证书运行，一般情况下，这意味着趋势科技服务器深度安全防护系统管理中心 SSL 证书需要导入到 REST 客户端实施使用的可信 X.509 证书存储区。在 Java 程序中，可以使用定制信任存储区，或者证书可以导入缺省信任存储区。有关 Java 的 SSL 配置选项的更多文档，请参阅 Java™ 安全套接字扩展名 (JSSE) 参考指南。
有很多方法可以检索已安装的趋势科技服务器深度安全防护系统管理中心的公共证书。以下是使用 Firefox 的一种方法：
- 启动 Firefox 并连接到趋势科技服务器深度安全防护系统管理中心 Web 页面。
- 双击地址旁边的锁定图标。
- 单击更多信息。
- 单击查看证书。
- 单击详细信息选项卡。
- 单击导出。
- 将证书导出为“X.509 证书 (DER)”。
- 将其保存为 Manager.cer。例如，c:\work\DeepSecurityWebServices\Manager.cer
开发 REST API 客户端应用程序
任何支持 XML 或 JSON 编码的编程语言以及 HTTP 和 HTTPS 协议可以用于开发趋势科技服务器深度安全防护系统管理中心 REST API 客户端应用程序。与基于 SOAP 的 Web 服务不同，REST Web 服务不会发布描述所有操作以及这些操作的输入和输出的 WSDL 文件。相反，客户端应用程序开发人员要负责根据 API 的文档编写调用 API 的代码。
对于 Java 开发人员，lib 文件夹包含一系列 Java 分类，这些 Java 分类可以用于 Java 应用程序，使 Java 客户端应用程序开发变得更加简便。可以在 samples 文件夹中找到演示如何使用这些类的示例代码。
对于使用其他语言的开发人员，或想使用他们自己的 REST 客户端技术的 Java 开发人员而言，有关 REST 接口中每个可用的 API 调用，进行访问所需的 HTTP 语句，包括 HTTP 路径和操作（GET、PUT 等），以及传入或传出 API 调用的数据结构的描述，请参阅 API 文档。
使用 REST API
本节概述了如何使用 REST API。
基本 API 访问
对 REST API 的所有访问均通过趋势科技服务器深度安全防护系统管理中心 URL https://<host or IP>:<port>/rest。例如，如果在名为 dsm.example.com 的计算机上安装了趋势科技服务器深度安全防护系统管理中心，且管理中心在 REST API 端口号上侦听，则 URL 可以为：
由于 REST API 使用了标准 HTTP 机制，并且有些操作可以使用 HTTP GET 进行访问而无需验证，那么这些方法则可以通过在 Web 浏览器中输入正确的地址进行访问。例如：
将向浏览器返回 REST API 版本。
对于趋势科技服务器深度安全防护系统即服务，REST API 终端为 https://app.deepsecurity.trendmicro.com/rest，SOAP API 终端为 https://app.deepsecurity.trendmicro.com/webservice/Manager?WSDL。
但是，大多数 REST API 调用都需要验证。这会以会话标识符 (SID) 的形式呈现，此会话标识符将作为 GET 和 DELETE 方法的查询参数或者出现在 PUT 和 POST 方法的消息正文中而传递到调用。通过使用允许访问 API 的用户的用户名和密码来调用 /rest/authentication/login URL 可获取会话 ID。一旦应用程序完成或者不再需要会话 ID，那么会话应该通过调用 /rest/authentication/logout URL 来结束。以下示例应用程序说明了此过程。
使用提供的 Java REST API 客户端
所提供的 Java REST API 客户端是基于 RESTEasy 客户端框架。此框架会采用已使用 JAX-RS 注释标记的 Java 接口，并生成可以和趋势科技服务器深度安全防护系统管理中心通信的这些接口的实施。使用此客户端代码负责所有对象序列化和反序列化，HTTP URL 和 HTTP 方法。
要使用 Java REST API 客户端，请在应用程序的类路径中将所有 JAR 文件包含在 lib 文件夹。有些 JAR 文件，例如 commons-logging，会经常使用，而且可能已经包含在您的应用程序中，并且如果他们确实已经在您的应用程序中，则没有必要再添加一次。
所有 API 的接口都可以在 Java 软件包 com.trendmicro.ds.platform.rest.api 中找到。所有发送到或发送自 API 的对象都可以在 Java 软件包 com.trendmicro.ds.platform.rest.object 及其子软件包中找到。
示例 Java 代码
此处的示例代码表明了如何使用 Java REST API 客户端代码验证 REST API 的用户。
- 按照之前所述的方法检索服务器的证书。
- 使用 Java 的 keytool 将证书导入新的信任存储区。例如：
keytool -importcert -trustcacerts -keystore c:\work\DeepSecurityWebServices\dsm.jks -file c:\work\DeepSecurityWebServices\Manager.cer - 使用 JVM 选项
-Djavax.net.ssl.trustStore=c:\work\DeepSecurityWebServices\dsm.jks运行程序，使 Java 使用定制信任存储区。
import javax.ws.rs.core.Response.Status;
import org.jboss.resteasy.client.ClientResponse; import org.jboss.resteasy.client.ClientResponseFailure; import org.jboss.resteasy.client.ProxyFactory; import org.jboss.resteasy.client.core.executors.ApacheHttpClient4Executor; import org.jboss.resteasy.plugins.providers.RegisterBuiltin; import org.jboss.resteasy.spi.ResteasyProviderFactory;
import com.trendmicro.ds.platform.rest.api.IAuthenticationAPI; import com.trendmicro.ds.platform.rest.message.error.ErrorMessage; import com.trendmicro.ds.platform.rest.object.DSCredentials;
public class AuthenticateSample {
public static void main(String[] args) { // URL for the REST API.Change this as appropriate.String restApiUrl = "https://10.0.0.5:4119/rest";
// The user name to use for authentication.Change this as appropriate.String username = "admin";
// The user's password.Change this as appropriate.String password = "supersecretpassword";
// Variable to store the session identifier (SID).String sID = null;
// RESTEasy client framework initialization that only needs to be done once per VM RegisterBuiltin.register(ResteasyProviderFactory.getInstance());
// An object that will execute HTTP requests ApacheHttpClient4Executor executor = new ApacheHttpClient4Executor();
// Create the object that will communicate with the authentication API.IAuthenticationAPI authClient = ProxyFactory.create(IAuthenticationAPI.class, restApiUrl, executor);
// Create the object to pass to the authentication call.DSCredentials credentials = new DSCredentials(); credentials.setUserName(username); credentials.setPassword(password);
try { System.out.println("Attempting to authenticate to Deep Security Manager REST API..."); sID = authClient.login(credentials);
System.out.println("Authentication successful."); System.out.println("Authentication session ID string received:" + sID);
} catch (ClientResponseFailure e) { // This is a special type of exception that means the server threw // an exception because there was a problem with the credentials.// It's important to handle these exceptions explicitly or the // connection to the server won't be released back in to the // underlying connection pool, meaning any subsequent API calls would fail.// See the RESTEasy Client Framework documentation for more details.ClientResponse<?> clientResponse = e.getResponse();
// Try to parse the error response in to an instance of the special // ErrorMessage class and display the result.Status status = clientResponse.getResponseStatus(); System.out.println("Server returned error status code " + status.getStatusCode() + " (" + status + ")"); ErrorMessage errorMessage = clientResponse.getEntity(ErrorMessage.class); System.out.println("Returned error message:" + errorMessage.getMessage());
} catch (Exception e) { // Some other error happened, most likely related to network communication problems.System.out.println("There was an error during authentication."); e.printStackTrace();
} finally { if (sID != null) { // Make sure to always log out.System.out.println(""); System.out.println("Ending session..."); authClient.endSession(sID); System.out.println("End session successful."); // make sure the session ID isn't accidentally re-used. sID = null; } }
// Cleanup:force the HTTP Client to close any open sockets executor.close();
}
}
使用 Java 示例代码
有些 Java 示例代码包含在示例文件夹中。这些示例是 Eclipse 项目的一部分，可以通过以下过程导入到您的 Eclipse 工作区。
- 在 Eclipse 中打开“文件”菜单并选择导入。
- 为导入源选择常规 > 工作区中的现有项目
- 单击浏览，然后选择
restapi\samples文件夹作为根目录 - 确保选择了 REST API 示例项目，并单击完成。
可以通过以下方法在 Eclipse 中运行示例文件：打开该文件并选择运行 > 以下列身份运行 > Java 应用程序。示例需要命令行参数，这些参数需要通过“运行配置”窗口进行设置。
API 文档
有关 REST API 中可用的每种方法的描述，请参阅趋势科技服务器深度安全防护系统 API 文档或趋势科技服务器深度安全防护系统即服务 API 文档。此文档的编程不依赖任何语言。
还为 Java REST API 客户端的用户提供了 javadoc 格式的文档。
响应处理
HTTP 状态代码
REST API 使用了标准 HTTP 状态代码来返回请求状态。下表显示了可以使用的响应代码以及在什么情况下它们可以被返回。
| HTTP 状态代码 | 返回的条件 |
|---|---|
| 200 正常 | 请求已成功完成。 |
| 400 错误的请求 | 调用方没有提供调用所需的全部数据。 |
| 401 未经授权 | 由于不活动，调用方的 SID 已经超时。认证过程必须重复。 |
| 403 禁止访问 |
|
| 404 未找到 |
|
| 405 找不到方法 | 调用方指定了给定 URL 不允许的 HTTP 方法。例如，使用 HTTP POST 访问指定为需要 GET 访问的 API。 |
| 500 服务器内部错误 |
|
错误响应
当 API 调用返回 200 OK 以外的状态代码时，响应正文将包含类似于以下的 XML 结构：
<error> <message>错误消息字符串</message> </error>
包含的错误消息可能对于调试问题很有帮助，但是不适合呈现给应用程序的最终用户。
返回 javax.ws.rs.core.Response 的 API 调用
有些 API 调用会记录为返回类型 javax.ws.rs.core.Response 的对象。这些调用会被视为只返回 HTTP 状态代码。
当使用提供的 Java REST API 客户端时，要检索此类调用的结果而不是忽略它们，这一点非常重要。如果您拥有响应对象，与服务器的潜在连接必须手动释放回连接池，如 RESTEasy 客户端框架所述。例如：
org.jboss.resteasy.client.ClientResponse<?> clientResponse = (ClientResponse<?>)apiObject.methodThatReturnsResponse(methodParameters);
clientResponse.releaseConnection();
其他注意事项
在查询参数中指定日期
在搜索查询中指定日期时，它们会使用 RFC 822 第 5 部分中规定的日期编码规则进行编码，除非年份要根据 RFC 1123 第 5.2.14 部分按 4 位数编码而不是按 2 位数编码。例如，美国东部时间 2012 年 11 月 31 日下午 3:45 分将被编码为 31 Nov 2012 15:45:00 -0500。
在 Java 中，这些日期应该使用日期格式特征码为 "dd MMM yyyy HH:mm:ss zzz" 的 java.text.SimpleDateFormat 进行编码。
示例：如果您的会话 ID 是 DC5A4AA79326DF3E149A26EA2DA6B0C7，您可以使用以下 URL 查询从美国东部时间 2012 年 11 月 31 日下午 3:45 起的所有主机防护信息，其中日期编码中的空格都是使用 '%20' 进行编码的 URL：https://dsm.example.com:4119/rest/monitoring/usages/hosts/protection?sID=DC5A4AA79326DF3E149A26EA2DA6B0C7&from=31%20Nov%202012%2015:45:00%20-0500
多租户权限
许多 REST API 都与管理多租户环境相关。在所需的正常角色权限之外，这些 API 还需要进行 API 调用的用户成为主租户帐户中的用户。如果租户的用户尝试调用这些 API，则会返回状态代码为 403 Forbidden 的响应。仅能由主租户用户调用的 API 包括：
- /monitoring - 监控 API
- /multitenantconfiguration - 多租户配置 API
- /tenants - 租户 API
- /tenantdatabaseservers - 租户数据库服务器 API
- /tenants - 租户模板 API
