转载

在 API Connect 组合件中通过针对 IBM DataPower 的自定义策略增加日志记录功能

简介

API Connect 版本：

本教程需要使用具有 IBM DataPower Gateway 的 IBM API Connect 5.0.2.0 或其更高版本。

在设计和开发自定义集成策略时，需要警惕策略中的任何问题。通过定义一个自定义日志策略来记录上下文变量的值，您可以快速获知何处的策略可能存在故障，以便更正所有错误。

本教程将描述一个用户定义的策略，该策略可有助于在 API Connect 组合件工具中记录日志和诊断错误。在此策略中，可在运行 API 的过程中的任何时刻将自定义字符串或上下文变量直接写入 IBM® DataPower® 日志。通过定义该策略，可写入任何优先级别的消息。此外，如果将 API Connect 与 DataPower 选择性监听不同优先级的能力相结合，您在设计 API 时就会获得简单且强大的日志记录和诊断功能。

API Connect 中的策略

借助 API Connect 组合件工具，您可以向 API 的运行时行为添加转换和逻辑。您可以使用组合件创建包含逻辑结构（比如 if 和 switch 语句）的复杂流。也可以创建数据操作机制，比如字段编辑、JSON 向 XML 转换和输入输出映射。这些操作被称为策略。您可以将磁贴拖到组合件中来连接和组织它们。

在 API Connect 组合件中通过针对 IBM DataPower 的自定义策略增加日志记录功能

writeToDatapowerLog 策略

为了解决在使用组合件时发现的记录错误诊断日志的难题，可以使用用户定义的策略。在本文中，我们将使用并介绍 writeToDatapowerLog 策略。（您可以从本文末尾的 “可下载资源” 部分下载此策略。）

请将该策略以压缩 (.zip) 文件形式导入 API Connect。压缩文件包含 DataPower 在运行时运行策略所需的所有文件，以及一个描述策略参数和元数据的 YAML 文件。不需要解压和处理该存档文件。

要使用该策略，可将该压缩文件导入 API Connect 中。导入该文件后，策略会显示在组合件中（如下图中的底部所示）并供您使用。

现在，可以将策略拖到组合件中，您可以根据需要拖动任意多次。该磁贴的每个实例都包含自己的不同配置。该策略使用了以下两个参数：

logLevel 。此参数表示记录的消息的优先级。DataPower 拥有从 info 到 critical 的一系列优先级。可从策略配置中的下拉列表中找到这些级别。
Message 。此参数指的是要写入 DataPower 日志的消息。Message 参数完全支持 DataPower 运行时上下文变量。

下图给出了一个示例组合件，它使用了 writeToDatapowerLog 策略的两个不同实例。

在 API Connect 组合件中通过针对 IBM DataPower 的自定义策略增加日志记录功能

下图给出了API Connect 组合件中针对两个实例的配置。第一个实例（参见下图）显示了针对某个关键情形的消息。

在 API Connect 组合件中通过针对 IBM DataPower 的自定义策略增加日志记录功能

第二个实例（参见下图）使用上下文变量支持在日志错误消息中记录 API 名称。

在 API Connect 组合件中通过针对 IBM DataPower 的自定义策略增加日志记录功能

API 调用中来自这些实例的结果显示在 DataPower 日志中，如下图所示。此图中显示的两条消息都是依据我们之前描述的策略配置来创建的。顶部的第一条消息显示了 API 的名称 (writetodatapowerlog-api)，它是从上下文变量引用 $(api.name) 扩展而得到的。底部的第二条消息记录为第一个实例中指定的 critical 级别。

在 API Connect 组合件中通过针对 IBM DataPower 的自定义策略增加日志记录功能

两条消息都属于 gatewayscript-user 类别，因为主要规则逻辑是使用 DataPower 中的 gatewayscript 描述的。下一节将介绍该策略的规则编码的扩展版本。

gatewayscript 代码

策略的主要执行过程是围绕以下 gatewayscript 构建的。

function writeToDatapowerLog()
                {

    var apic = require('local://isp/policy/apim.custom.js');
    var props = apic.getPolicyProperty(),
        apiName = apic.getContext('api.name'),
        m = props.message;

    if (props === undefined) {
        console.error('The policy properties were not retrieved for policy: writeToDatapowerLog.');
        return;
    }

    if  (apiName === undefined || apiName === '') {
        console.error('The name of the API for this call could not be determined.');
    }

    switch(props.logLevel) {
        case 'info':
            console.info('The API: /"' + apiName + '/" has logged the following message: ' + m); break;
        case
                'notice':
            console.notice('The API: /"' + apiName + '/" has logged the following message: ' + m); break;
        case
                'warn':
            console.warn('The API: /"' + apiName + '/" has logged the following message: ' + m); break;
        case
                'error':
            console.error('The API: /"' + apiName + '/" has logged the following message: ' + m); break;
        case
                'critical':
            console.critical('The API: /"' + apiName + '/" has logged the following message: ' + m); break;
        case
                'alert':
            console.alert('The API: /"' + apiName + '/" has logged the following message: ' + m); break;
        case
                'emerg':
            console.emerg('The API: /"' + apiName + '/" has logged the following message: ' + m); break;
        case
                'log':
            console.log('The API: /"' + apiName + '/" has logged the following message: ' + m); break;
        case
                'trace':
            console.trace('The API: /"' + apiName + '/" has logged the following message: ' + m); break;
        default:
            console.error('The logLevel chosen: ' + props.logLevel + ' was not recognised');
    }
    return;
}

writeToDatapowerLog();

有关更多信息，请参阅 IBM 知识中心中的实现策略和gatewayscript 主题。

结束语

本教程介绍了一个通用的解决方案，在组合使用 DataPower 运行时和 API Connect 时，它可以帮助您解决日志记录灵活性方面的难题。通过使用所描述的用户定义策略，可以将特定优先级的自定义消息直接记录到 DataPower 日志中，并实现对运行时上下文变量的全面支持。此解决方案非常强大，可以在开发期间为错误检测和诊断提供参考性的有用消息，也可用作运行时监视设备。