Oracle APEX 系列文章16：AOP - PDF报表打印新选择

英文原文链接：Configuring AOP as Print Server in Oracle APEX 20.1

在 Oracle APEX 20.1 中将 AOP 配置为打印服务器

Oracle Application Express（APEX）20.1 的新功能之一，就是与 APEX Office Print（AOP）的集成。

在这篇文章中，将介绍这种集成的含义以及如何在 APEX 20.1 中设置和使用 AOP。

Oracle APEX 中的后台打印/报表导出

Oracle APEX 3.0 引入了将报告区域导出为PDF的功能 - 本质上是打印报告。它是声明式定义的，并且可用于所有报告区域。您可以查看和打印带有在每个页面上重复的页面标题和页脚，以及与各种页面大小正确匹配的内容的报告。为此，可使用外部定义的报告服务器将报告数据转换为PDF格式。在早期，此外部报表服务器是 Oracle BI Publisher 或外部 Apache FOP 服务器。后来，当 ORDS 出现时，FOP服务器作为选件包括在内。

我相信外部 Apache FOP 并没有被广泛使用，因为它太复杂，无法简单地设置。有能力支付（巨大的）许可证或已经在公司中拥有许可证的人使用 Oracle BI Publisher。以我的经验，ORDS是使用最多的打印服务器。但是，在ORDS 18.4发行说明中，宣布将弃用内置FOP服务器，而在ORDS 19.4中，FOP更是被完全放弃。

这意味着人们需要使用旧版本的ORDS或使用其他版本…

关于 APEX Office Print（AOP）

APEX Office Print（AOP）已有5年多历史了，它使从 Oracle APEX 导出和打印报告变得更加容易且成本可控。根据您在Word，Excel，Powerpoint，HTML和Text中创建的模板，AOP会将来自APEX区域的数据，数据库中的数据甚至外部数据与已定义输出格式的模板（例如PDF或任何模板格式）合并。在过去的几年中，AOP广受欢迎，并已成为 Oracle APEX 项目的首选打印引擎。

去年，Oracle宣布他们将直接在 Oracle APEX 中集成 APEX Office Print (AOP) ，而现在已在 APEX 20.1 版本中正式实现。在这一次版本迭代中，AOP 替代了 FOP 服务器，在将来的 Oracle APEX 版本中，则计划支持更多的 AOP 特性。

在 Oracle APEX 20.1 中配置 AOP

要将 AOP 配置为打印服务器，请登录到 INTERNAL 工作区并转到 Instance Settings：

单击 Report Printing，然后选择 APEX Office Print 作为打印服务器：

填写运行 AOP Server 的主机地址。AOP支持运行在AOP云中，或者本地部署AOP Server。您可以在 www.apexofficeprint.com 上免费订阅AOP打印服务，也可以下载后进行本地部署。

在APEX 20.1中，只能在实例级别上配置打印服务器。在未来的APEX 20.2版本中，将能够在工作空间（Workspace）级别上覆盖这些设置。这意味着您将有能力为不同的项目使用不同的AOP服务器或云帐户，增加更多的灵活性。

在 Oracle APEX 20.1 中使用 AOP

要查看实际运行中的AOP集成，可以转到任何经典报表（Classic Report）或交互式报表（Interactive Report），然后单击“打印”或“下载到PDF”链接。

经典报表（Classic Report）中的“打印”链接：

输出将如下所示：

您可以在“区域”的“打印属性”中自定义输出：

单击交互式报告（Interactive Report）中的“操作”>“下载”>“PDF”时，您具有相同的功能

这是 AOP 在 Oracle APEX 中的最基本功能，它模仿了提供的 ORDS、BI Publisher 或外部FOP服务器。

实际上，APEX Office Print 可以做得更多。AOP 可以完全按照您在屏幕上看到的方式打印一个或多个 Interactive Reports，包括突出显示、分段显示、过滤器等。它还可以将 IR、IG 和 Classic Reports 结合在一起，甚至在您提供的自定义模板中将图表全部组合在一起。

如果需要此功能，则需要使用 AOP插件 或 AOP PL/SQL API，就像在 APEX 20.1 之前一样,您可以从 www.apexofficeprint.com 网站下载该文件。

强烈建议您安装AOP Sample App，它展示了 AOP 在过去5年中获得的所有功能。在每个页面上，您都可以查看示例的构建方式以及使用的模板。

第1步：下载 AOP 安装包

访问 AOP 官网，点击Downloads链接，根据实际情况下载安装包。

下载并解压后，目录结构如下：

第2步：安装 AOP

安装 AOP PL/SQL API：

登录到您希望使用 AOP 的 APEX 工作空间（Workspace），待安装的组件如下：

AOP PL/SQL API
AOP 插件（3个）
AOP 示例应用

这里假设您已安装了 APEX 自带的示例应用 Sample Database packaged application，希望在这个应用里使用 AOP 的打印功能。

导航到 SQL Workshop -> SQL Scripts -> Upload，选择 aop_db_pkg.sql 进行上传（您可以在db目录下找到它）.

aop_db_pkg.sql 文件会安装 AOP 所需的数据库表、PL/SQL包、同义词等。

别忘了点击运行按钮以便执行刚刚上传的sql文件。

确保选择了正确的数据库schema。

运行完毕后，效果如下图所示：

如果您在创建同义词时遇到了 ORA-01031 insufficient privileges 错误，联系DBA让他授予您的数据库schema相应权限（CREATE SYNONYM）。

安装 AOP 插件：

AOP 包含了3个插件，您可以选择只用 AOP 的 PL/SQL API 来与 AOP 进行交互，但因为您需要与 APEX 配合使用，所以您还会用到 动态行为插件、过程处理插件和内容转换插件，这些插件可以处理所有的 PL/SQL 调用，您只需告诉 AOP 到哪里找到合适的模板和数据即可。

AOP 动态行为插件：这个插件应该用得是最多的，也是最简单和最稳定的。
AOP 过程处理插件：这个插件仅用在特定的场景，比如：在页面加载前用模式窗口显示 PDF 内容，或者您需要在调用 AOP 打印功能之前提交并保存数据。
AOP 内容转换插件：这个插件被用来将任意类型的文件转换成 PDF 格式，而无需依赖模板，这也是它唯一的用处。

导航到 Shared Components -> Plug-ins，点击 Import 按钮.

选择 dynamic_action_plugin_be_apexrnd_aop_da.sql 文件（位于安装包的apex目录下），文件类型 选项选择 Plug-in，字符集 选择 Unicode UTF-8，点击若干次 下一步 按钮完成插件导入。

一旦安装完毕，您将来到 Component Settings 页面，以便对当前插件做进一步设置。

重复上述步骤，完成另外两个插件（process_type_plugin_be_apexrnd_aop.sql，dynamic_action_plugin_be_apexrnd_aop_convert_da.sql）的导入。

第3步：AOP 插件设置

首先配置 APEX Office Print (AOP) - DA [Plug-in] 插件。

这里唯一需要修改的就是 API Key。如果您采用本地化部署（On Premises），则无需设置 API Key。您可以登陆 AOP 官网后，在 AOP Dashboard 中找到属于您的 API Key。

对于另外两个插件，同样设置 API Key。

好了，如果您采用 AOP Free Cloud 的方式使用 AOP，以上设置就足够了。

以下是更多有关插件的设置：

AOP URL: 这个 url 指向 AOP 服务器。如果您选择使用 AOP Cloud，保留默认值（http://api.apexofficeprint.com/）即可。如果您选择了本地化部署（On-Premises），请确保提供了正确的您的服务器地址。当使用 HTTPS 时，请确保您已经往数据库wallet中添加了必要的证书。有关这部分介绍，可以查看我们官网的相关文档。
AOP Failover URL (仅适用于本地化部署): 可选配置，可以指向您的备用 AOP 服务器，一旦主实例出现故障，备用服务器将提供服务。如果您选择的是 AOP Cloud 的方式，无需设置此项。
AOP Mode (仅适用于AOP Cloud): AOP 可以运行在生产模式（Production Mode），生产模式下，打印报表时会相应地扣减您账户中的信用点；您也可以使用开发模式（Development Mode），开发模式下不会扣减任何信用点，唯一的差别是打印的报告中会带有水印。您可以利用一个名为AOP_MODE的内置 item 动态设置 AOP 的运行模式。
Debug: 启用这一选项将强制 AOP 捕获发送到 AOP 服务器端的 JSON 内容，这一选项对您分析问题时将会特别有用。
- 当该选项被设置为 Local 时：您的报表将下载为 JSON 格式，这将让您有机会分析具体问题所在。你也可以将问题描述及 JSON 文件发送给 support@apexofficeprint.com 以便获得进一步的支持。
- 当该选项被设置为 Remote 时：将适用于 AOP Cloud 方式。您可以从 AOP Dashboard 中找到对应的 JSON 文件，进而进行进一步分析。
- 您可以使用一个名为 AOP_DEBUG 的内置 item 来动态设置 Debug 模式。
Converter: 为了能够将文档转换成 PDF 格式，AOP 需要使用外部转换器（Converter），AOP 使用 LibreOffice 作为默认转换器。如果您选择本地化部署，可以添加其他第三方转换器，比如：AbiWord, Aspose, 或者其他转换器。
Use settings defined in package: 您可以编写 PL/SQL 包来设置 AOP 插件，这也让您可以很方便地在多个环境（开发、测试、生产）中安装部署 AOP 插件。
Log Package: AOP 内置支持日志功能。为了启用日志，您需要执行 ALTER PACKAGE aop_api19_pkg COMPILE PLSQL_CCFLAGS = 'logger_on:TRUE';。一旦编译成功，您可以通过指定全局变量 g_logger_enabled 来启用/关闭 debug 信息。您可以指定您自己的 debug 存储过程，所有的日志请求将被发送给 aop_api_pkg.plsql_call_to_aop。

AOP做的第一件事就是调用 start_request，最后一件事是调用 stop_request. 您可以在AOP Sample APP中找到更多关于 aop_log_pkg 的例子。

第4步：AOP 使用

这里以APEX自带的Sample Database Application为例，假设我们已经完成了上述设置。打开page 4，这个页面包含一个互动报表（Interactive Report）。

切换到页面编辑模式

在 Order Region 下创建一个叫 PRINT 的按钮。

按钮属性配置如下：

Button Name: PRINT
Label: Print
Button Position: Right of Interactive Report Search Bar
Button Template: Icon
Icon: fa-print
Action: Defined by Dynamic Action

在按钮上添加动态行为。

选择 APEX Office Print (AOP) - DA [Plug-in] 插件作为展示选项。

Template Type 选项选择 AOP Template，这样 AOP 将生成一个通用模板，以便后续您可以进一步编辑。

将 Data Type 选项设置为 Region(s): Classic Report, Interactive Report/Grid, SVG, Canvas, HTML, Other，并且将 Region Static Id(s) 设置成 orders_ir（这个 static id 将被AOP用来获取该region的元数据，以便生成需要在屏幕上显示的数据）。