使用 IBM InfoSphere Guardium Data Redaction 在您的业务工作流中集成文档数据编校流程

Redaction 客户端 API 编程技巧

IBM® InfoSphere® Guardium® Data Redaction 提供了一个 Java® API,支持您的自定义应用程序使用编校 (redaction) 服务器。本文将介绍如何在 3 种典型的文档编校场景中使用该 API。

Yasutomo Nakayama, 软件开发实验室(YSL), IBM

Yasutomo Nakayama 是 IBM 日本 Yamato 软件开发实验室(YSL)企业内容管理开发团队的成员。



Eisuke Kanzaki, 软件开发实验室(YSL), IBM

Eisuke Kanzaki 是 IBM 日本 Yamato 软件开发实验室(YSL)企业内容管理开发团队的成员。



2011 年 12 月 05 日

简介

IBM InfoSphere Guardium Data Redaction 支持选择性地公开文档中的信息。编校服务器会自动删除自由文本文档和表单中的私有信息,如图 1 中所示。

这些功能有助于处理可能分散在各种位置的大量文档。当因为制度和业务而需要在文档中维护某些信息的隐私,同时专门向授权的人员显示相关信息时,编校系统可帮助实现这两个目标。

此产品包括基于浏览器的应用程序,它们具有直观的界面,允许您编校文档或查看编校的文档。它还提供了多个自动化访问选项。这些功能在企业内容管理 (ECM) 工作流中可能特别有用,其中受控的编校是文档管理的重要部分。

图 1. IBM InfoSphere Guardium Data Redaction 概述
此图概述了 InfoSphere Guardium Data Redaction,包括编校管理器、安全查看器和连接到编校服务器,然后连接到 ECM 系统的自定义应用程序。

有 3 种使用这些编校服务的方法:

  • 通过文档存储库或文件系统 —— 将原始文档复制到一个输入文件夹,在输出文件夹中接收编校的文件。
  • 通过 SOAP API —— 建议将此方法用于非 Java 应用程序。
  • 通过 Java 编校客户端 API —— 这是本文的讨论重点。

IBM InfoSphere Guardium Data Redaction 提供了一个编校客户端 API,以便您的自定义应用程序可通过 API 直接控制编校服务。本文将介绍编校客户端 API 的功能,以及如何在自定义应用程序中使用该 API。本文中以示例的形式描述了 3 种典型的场景。

注意:本文基于 IBM InfoSphere Guardium Data Redaction V2.1。


编校客户端 API

编校客户端 API 是一个 Java 类库,用于从程序访问编校服务器的服务。API 工具包包含在 IBM InfoSphere Guardium Data Redaction 中。

为 API 提供了开箱即用的示例代码和文档。当安装产品时,会将 API 库和示例程序复制到 <IBM_REDACTION_HOME>\client 文件夹中,其中 <IBM_REDACTION_HOME> 是安装文件夹。API 的 Java 文档也将复制到 <IBM_REDACTION_HOME>\docs\apidocs 文件夹中。

使用该 API,可通过两种模式从自定义应用程序使用编校服务:远程客户端模式和进程内客户端模式。在远程客户端模式中,远程(或本地)客户端机器上的程序通过 SOAP 连接调用编校服务器。在进程内客户端模式中,整个编校服务器作为客户端应用程序的一部分运行。程序的实现在两种模式下几乎相同。在这些示例中,首先介绍在远程客户端模式下,该 API 在每种典型场景中的使用。最后,将介绍两种模式之间的区别。

第一个场景是最基本的场景。一个客户端程序连接到服务器并编校文档。在第二个场景中,将许多文档发送到服务器,使用一个批处理存储库编校它们。第三个场景是一种高级情形,展示了应用程序对一组文档的编校的高级控制。


场景 1:本地文件系统编校

这是最简单的场景,演示了该 API 的基本用法。在此场景中,远程客户端机器上的一个程序向编校服务器发送了一个编校请求,如图 2 所示。

图 2. 发送到编校服务器的编校请求
此图显示了客户端机器向编校服务器发送编校请求

该场景包含以下步骤:

  1. 建立编校服务器连接
  2. 以二进制数据形式加载目标文档
  3. 提交编校请求
  4. 将结果保存为文档

建立编校服务器连接

要连接编校服务器,首先创建一个 RedactionToolkitClient 类对象。可以使用 createRemoteClient() 方法在远程客户端模式下创建对象。清单 1 展示了如何使用 createRemoteClient() 方法。

清单 1. 使用 createRemoteClient() 方法
User user = new User("CustomApp01", "userid", "password");
RedactionToolkitClient client = RedactionToolkitClient.createRemoteClient("foo.bar.com", 
8097, user);

当调用 createRemoteClient() 方法时,会在远程客户端机器和编校服务器之间建立一个 SOAP 连接。因此,该方法需要编校服务器的 IP 地址和端口号。它还需要编校服务器的有效用户 ID 和密码。连接编校服务器和客户端之后,您的应用程序可通过 SOAP 引擎调用服务器的服务。该 API 提供了几个方法来调用编校服务。

以二进制数据形式加载目标文档

编校服务器支持多种文档格式,比如 PDF、Microsoft Word、tiff 图像和纯文本。对于所有格式,文档内容应该以二进制数组形式传递给服务器。因此,在文件系统中编校文档时,该文档必须在二进制模式下打开。

提交编校请求

redactDocumentByRules() 方法向服务器发送一个编校请求。此方法需要一些参数来指定请求的选项。表 1 列出了用于指定请求参数的类。

表 1. 用于 redactDocumentByRules() 方法的类
要设置的参数
RedactionAttributes 输出格式、屏蔽规则、颜色模式、时间戳和其他编校选项
RedactionStamp 时间戳标签和位置
DocumentAttributes 文档名称、文档的语言等
Document 文档数据(二进制)、DocumentAttributes 类对象

RedactionAttributes 类对象指定如何编校文档。清单 2 显示了如何设置这个类对象的编校属性。在此示例中,“image/png” 指定输出内容类型,GRAY 指定为输出颜色模式,“Classified” 指定为文档页面左上角的时间戳。RedactionAttributes.ColorMode.GRAY 是指定颜色模式的静态常量。

清单 2. 设置编校特性
// Set Redaction Attributes
// Set output format
RedactionAttributes redactionAttributes = new RedactionAttributes("image/png");
// Set color mode
redactionAttributes.addAttribute(RedactionAttributes.ColorMode.COLOR_MODE , 
new AttributeValue(RedactionAttributes.ColorMode.GRAY.toString()));
// Set stamp
RedactionStamp stamp = new RedactionStamp(Boolean.TRUE, "Classified", 
RedactionStamp.StampPosition.UPPER_LEFT) ;
redactionAttributes.addRedactionStamp(stamp);

Document 类对象用于设置与输入文档相关的信息,获取已编校文档中的信息。DocumentAttributes 类用于保存 Document 类元数据,比如文档名称、内容类型、语言等。

在清单 3 中,输入文档的名称和内容类型由构造函数指定。当用 "" 指定为内容类型时,编校服务器会检查文档数据并识别类型。可以使用 addAttribute() 方法设置对象的文档语言(英语)。如果未指定语言,系统会在编校过程中自动识别它。文档的二进制数据、documentAttributes 实例和文档状态是在 Document 类对象中设置的。在此示例代码中,文档的二进制数据存储在 inputDocBytes 变量中。

清单 3. 使用 Document 类对象
byte[] inputDocBytes; //  binary document data 
...
// set file name and language   
DocumentAttributes documentAttributes = new DocumentAttributes("sales_results.pdf", "", 
null);
documentAttributes.addAttribute(DocumentAttributes.LANGUAGE, new AttributeValue("en"));
// set binary data, attributes and status 
Document document = new Document(inputDocBytes, documentAttributes, 
DOCUMENT_STATE.NOT_REDACTED);

IBM InfoSphere Guardium Data Redaction 有 13 种预定义的主要语义类别,如表 2 所示,您可以使用它们指定应该编校文档中的哪些词。也可以根据需要创建其他类别。

表 2. 预定义的语义类别
类别 ID语义类别
2 电话号码
3 组织
4 日期
5 时间
6 SSN(社会安全号码)
7 电子邮件地址
8 URL
9 位置
10 人员
11 地址
100 USD(美国美元)
101 民族
102 银行卡编号

当使用 redactDocumentByRules() 方法将编校请求发送到服务器时,需要指定编校的目标数据类型。清单 4 给出了一个准备编校规则和调用该方法的示例。此示例指定必须编校电话号码、人员姓名和地址。

清单 4. 准备编校规则
RedactionRules rules = new RedactionRules();
rules.add(new RedactionRule( 2, RedactionRule.PERMISSION_TYPE.REDACT)); // ID  2:
Phone Number
rules.add(new RedactionRule(10, RedactionRule.PERMISSION_TYPE.REDACT)); // ID 10: 
Person name
rules.add(new RedactionRule(11, RedactionRule.PERMISSION_TYPE.REDACT)); // ID 11: Address
Document outDocument = client.redactDocumentByRules(redactionAttributes, document, rules);

使用角色可以更容易地指定编校的数据类型。为每种角色指定各种语义类别的权限(即是否编校)。规则和角色相结合,称为一种策略模型,它应该在编校服务器上 <IBM_REDACTION_HOME>\server\conf 文件夹中的 XmlPolicyModel.xml 文件中定义。

redactDocumentForRole() 方法用于将角色指定为编校选项。清单 5 给出了一个使用 redactDocumentForRole() 方法的示例。RESTRICTED 角色 (ID 1000) 是一个产品的示例角色。通常,您应该使用预定义的语义类别定义适合您的业务逻辑的角色。

清单 5. 使用 redactDocumentForRole() 方法
int ROLE_RESTRICTED = 1000; // RESTRICTED role in the sample policy model
// redact a document
Document outDocument = client.redactDocumentForRole(redactionAttributes, document, 
ROLE_RESTRICTED);

将结果保存为文档

redactDocumentByRules() 方法和 redactDocumentForRole() 方法都返回一个 Document 类对象作为编校的结果。来自此对象的二进制数据和文档名称用于将文档保存到一个本地文件。

此场景最适合需要同步处理的客户端。在编校结束之前,编校服务器的连接会一直处于活动状态。这允许客户端跟踪进度和控制编校的执行。编校参数随各个文档一起传递。要实现更高的吞吐量,客户端可从多个线程提交编校请求。第二个场景适合在不应阻止客户端应用程序时对大量文档进行编校。


场景 2:在批处理存储库中编校文档

存储库是文件系统或 ECM 系统中某个指定的文件夹,包含子文件夹。它用于输入和输出文档,以及编校中使用的其他工件。有两种存储库类型:批处理和按需处理。第二个场景中使用批处理存储库。将编校服务器设置为监控批处理存储库的输入文件夹中传入的文档,当文档复制到输入文件夹时,服务器会自动使用提前为存储库定义的选项对文档进行编校,并将结果放在输出文件夹中。

在此场景中,自定义应用程序分解为两部分,如图 3 所示。第一部分(自定义应用程序 A)将文档发送到批处理存储库。服务器处理文档之后,第二部分(自定义应用程序 B)连接到服务器并下载编校的文档。

图 3. 自定义应用程序可分解为两部分
此图演示了进入服务器机器的自定义应用程序 A 和 B

表 3 显示了 RedactionToolkitClient 类的存储库相关方法。此场景使用其中一些方法实现。

表 3. 操作存储库的方法
方法操作
queryDocumentRepository() 获取存储库中的文档列表
addDocumentToRepository() 将文档添加到存储库
getRepositoryDocument() 从存储库获取文档
deleteRepositoryDocument() 删除存储库中的文档
redactRepositoryDocumentByRules() 依据指定的规则编校存储库中的文档
redactRepositoryDocumentForRole() 依据指定的接收者角色的权限编校存储库中的文档

发送文档

自定义应用程序 A 连接服务器并加载目标文档。这些操作类似于场景 1 中的前两步。

addDocumentToRepository() 方法将一个文档放在指定存储库的输入文件夹中。清单 6 显示了一个使用 addDocumentToRepository() 方法的示例。“batch” 是在安装产品时创建的一个示例批处理存储库。

清单 6. 使用 addDocumentToRepository() 方法
DocumentAttributes documentAttributes = new DocumentAttributes("sales_results.pdf", "", 
null);
Document document = new Document(inputDocBytes, documentAttributes, 
DOCUMENT_STATE.NOT_REDACTED);
client.addDocumentToRepository(document, "batch");

应用程序继续上传,直到所有文档都已发送到存储库。在上传完最后一个文档后,程序终止。

服务器监控输入文件夹并自动开始处理文档。这使得在处理期间必须维护服务器的连接。使用存储在存储库的编校服务器上的配置文件中定义的选项来处理文档。

下载文档并清理存储库

随后,自定义应用程序 B 连接编校服务器并检查存储库的输出文件夹。queryDocumentRepository() 方法获得指定的存储库中的文档的引用。清单 7 显示了一个使用 queryDocumentRepository() 方法的示例。

清单 7. 使用 queryDocumentRepository() 方法
String repositoryFolderName = "batch";
DocumentReference[] docRefs = null;
...
docRefs = client.queryDocumentRepository(new DocumentRepositorySearchCriteria
(repositoryFolderName, DocumentRepositorySearchCriteria.SEARCH_WITHIN.REDACTED));

要找到已编校的文档,应该将 DocumentRepositorySearchCriteria.SEARCH_WITHIN.REDACTED 指定为要搜索的文档类型,这表示该文档是已编校过的文档,而不是原始文档。查询的结果在一个 DocumentReference 类数组中返回。引用用于指定存储库文件夹中要下载或删除的文档。getRepositoryDocument() 方法可以获取实际的文档数据,即 Document 类对象。甚至在下载数据后,原始数据仍然保留在存储库中。您可以调用 deleteRepositoryDocument() 方法来清理存储库。清单 8 显示了一个使用 getRepositoryDocument()deleteRepositoryDocument() 方法的示例。

清单 8. 使用 getRepositoryDocument() and deleteRepositoryDocument() 方法
for (int i = 0; i < docRefs.length; i++) {
    Document doc = client.getRepositoryDocument(docRefs[i]);
    ...
    // save the binary data to a local file
    ...
    // delete the document to ensure next query doesn't return it
    client.deleteRepositoryDocument(docRefs[i]);
}

批处理存储库用于通过可配置数量的线程一次编校许多文档。可为每个存储库指定一组编校选项,例如输出格式、颜色模式、角色等。如果不同的文档有不同的编校选项,那么必须为每组选项准备一个批处理存储库。相反,在使用按需存储库时,您可以控制服务器编校存储库中的每个文档的方式。


场景 3:使用按需存储库编校文档

在第三个场景中,自定义应用程序分解为 3 部分。上传和下载部分几乎与第二个场景中相同,但会将文档上传到某个按需存储库中。与批处理存储库不同,按需存储库不会自动开始编校输入文档。因此,必须在服务器机器上运行一个新部件(自定义应用程序 C)来请求服务器处理文档,如图 4 所示。

图 4. 在服务器机器上运行自定义应用程序 C 来处理编校流程
此图显示了在服务器机器上运行的自定义应用程序 C

自定义应用程序 A 将文档上传到按需存储库。这可以重复和根据需要完成。服务器机器上的自定义应用程序 C 定期运行,比如一天一次,或者在它通过检查存储库来查找文档时。

应用程序 C 在服务器机器上运行,但是,它仍然通过 SOAP 连接连接到服务器进程,因为它像在其他自定义应用程序中一样使用了 createRemoteClient()。对存储库输入文件夹中的文档的引用使用 queryDocumentRepository() 方法和 DocumentRepositorySearchCriteria.SEARCH_WITHIN.NOT_REDACTED 选项来实现。redactRepositoryDocumentByRules()redactRepositoryDocumentForRole() 方法用于编校按需存储库文件夹中的文档。

应用程序可使用 RedactionAttributes 类和业务逻辑所需要的角色或规则为每个文档指定不同的选项。例如,可通过引用每个文档名称为每个文档指定不同的角色。

清单 9 显示了一个使用 redactRepositoryDocumentForRole() 的示例。在此代码中,文件名前缀为 “ClassA” 的文档使用 RESTRICED 角色进行编校,将 “Classified” 时间戳添加到页面中。

清单 9. 使用 redactRepositoryDocumentForRole() 方法
for (int i = 0; i < docRefs.length; i++) {
    // Set output format
    int role = 1001; //  GENERAL role in the sample policy model
    RedactionAttributes redactionAttributes = new RedactionAttributes("image/tiff"); // 
set output format to tiff image

    if(docRefs[i].getDocumentName().startsWith("ClassA")){
        //add stamp and use RESTRICTED role
        RedactionStamp stamp = new RedactionStamp(Boolean.TRUE, "Classified", 
RedactionStamp.StampPosition.UPPER_LEFT) ;
        redactionAttributes.addRedactionStamp(stamp);
        role = 1000; //  RESTRICTED role in the sample policy model
    }
    client.redactRepositoryDocumentForRole(redactionAttributes, docRefs[i], role);
}

可扩展此场景,根据需要将文档编校流程集成到文档工作流中。编校服务器可访问一个 ECM 系统,并使用它的数据存储作为存储库。因此,自定义应用程序可以使用所需的业务逻辑监控和处理 ECM 系统上的文档。


使用进程内客户端模式

对于现场编校服务,要避免继续运行编校服务器(进而保留资源)或减少进程间通信开销,可使用进程内客户端模式编校文档。此模式为客户端应用程序提供了对编校服务器生命周期的控制。该服务器与客户端一起初始化。这意味着,自定义应用程序和编校服务器在相同的 JVM 进程中运行,如图 5 中所示。

图 5. 在进程内客户端模式下编校文档
此图显示了在相同 JVM 进程中运行的自定义应用程序和编校服务器

要在进程内客户端模式下使用编校客户端 API。可以使用 createInProcessClient() 方法创建一个 RedactionToolkitClient 类对象,而不使用 createRemoteClient() 方法。与远程客户端不同,进程内客户端不使用 SOAP 连接。它以一个 JVM 进程的形式启动编校服务器。获取对象后,您的程序可与在远程客户端模式下相同的方式使用它的方法。唯一的区别是,必须在程序结束时调用 cleanup() 方法来释放不需要的资源,然后再停止 JVM 进程。

我们修改了第一个场景中的程序来使用进程内客户端,替换 createRemoteClient() 方法并添加 cleanup() 方法。

清单 10 显示了一个使用进程内客户端的示例。

清单 10. 使用进程内客户端
User user = new User("CustomApplication04", "userid", "password");
RedactionToolkitClient client = RedactionToolkitClient.createInProcessClient(user);
// redact the documents with the client object here
client.cleanup();

进程内客户端比远程客户端更加高效,因为它减少了进程间通信开销。但是,远程客户端在客户端与服务器进程之间具有更紧密的耦合。进程间客户端还有其他一些问题。

编校服务器组件

程序必须在拥有编校服务器组件的相同机器上运行,它必须在与服务器组件相同的 JVM 上运行 (<IBM_REDACTION_HOME>\ibm-java2-jre-60\jre\bin\java.exe)。

示例配置文件同时用于编校服务器和进程内客户端。但是,Web 服务(编校管理器和安全查看器)、SOAP 服务和批处理器不能在进程内客户端模式中使用。

与编校服务器共存

进程内客户端甚至可在编校服务器运行时使用,除非编校服务器连接到 ECM 服务器。当编校服务器连接到 ECM 服务器上的存储库(数据存储)时,它会锁定存储库。因此,如果进程内客户端启动,并且也尝试连接 ECM 服务器,将发生冲突。

类路径

表 4 中列出的所有 jar 文件都必须添加到类路径中。

表 4. 进程内客户端的类路径中需要的 jar 文件
<IBM_REDACTION_HOME>\server\lib 中的所有 jar 文件
<IBM_REDACTION_HOME>\server\plugins 下的所有 jar 文件

此外,如果 Content Manager 8 对象存储用作存储库,类路径中也需要表 5 中的 jar 文件和目录,其中 <IBMCMROOT> 是 IBM DB2 Information Integrator for Content 的安装文件夹。如果 InfoSphere Guardium Data Redaction 打算连接 IBM Content Manager 8,此产品是唯一的前提条件。

表 5. CM8 连接需要的 jar 文件和目录
<IBMCMROOT>\lib\cmbcm81.jar
<IBMCMROOT>\lib\cmbicm81.jar
<IBMCMROOT>\lib\db2jcc_license_cisuz.jar
<IBMCMROOT>\lib\db2jcc_license_cu.jar
<IBMCMROOT>\lib\db2jcc.jar
<IBMCMROOT>\cmgmt

Java 启动选项需求

自定义应用程序必须使用这些选项来运行。可能还必须使用它们来修改内存池大小。

-Xms256m -Xmx1536m -Djava.security.auth.login.config="%IBM_REDACTION_HOME%/server/conf/login.conf"


结束语

编校客户端 API 的基本用法已在 3 种典型编校场景和 2 种模式(远程客户端和进程内客户端)中介绍。在自定义应用程序中通过此 API 来使用 InfoSphere Guardium Data Redaction,系统中的文档工作流可得以改进,业务流程可更加高效。


致谢

作者感谢 InfoSphere Guardium Data Redaction 开发团队的 thank Joshua Fox 和 Michael Pelts 的细心评审和宝贵建议。

参考资料

学习

获得产品和技术

讨论

  • 查阅 developerWorks 博客 并加入 developerWorks 中文社区,developerWorks 社区是一个面向全球 IT 专业人员,可以提供博客、书签、wiki、群组、联系、共享和协作等社区功能的专业社交网络社区。

条评论

developerWorks: 登录

标有星(*)号的字段是必填字段。


需要一个 IBM ID?
忘记 IBM ID?


忘记密码?
更改您的密码

单击提交则表示您同意developerWorks 的条款和条件。 查看条款和条件

 


在您首次登录 developerWorks 时,会为您创建一份个人概要。您的个人概要中的信息(您的姓名、国家/地区,以及公司名称)是公开显示的,而且会随着您发布的任何内容一起显示,除非您选择隐藏您的公司名称。您可以随时更新您的 IBM 帐户。

所有提交的信息确保安全。

选择您的昵称



当您初次登录到 developerWorks 时,将会为您创建一份概要信息,您需要指定一个昵称。您的昵称将和您在 developerWorks 发布的内容显示在一起。

昵称长度在 3 至 31 个字符之间。 您的昵称在 developerWorks 社区中必须是唯一的,并且出于隐私保护的原因,不能是您的电子邮件地址。

标有星(*)号的字段是必填字段。

(昵称长度在 3 至 31 个字符之间)

单击提交则表示您同意developerWorks 的条款和条件。 查看条款和条件.

 


所有提交的信息确保安全。


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=10
Zone=Information Management
ArticleID=778791
ArticleTitle=使用 IBM InfoSphere Guardium Data Redaction 在您的业务工作流中集成文档数据编校流程
publish-date=12052011