12 Vending Manager API

可以使用 Vending Manager API 访问由 Content Delivery Server 维护的 Vending Manager 数据。可以使用该 API 创建和管理包、活动、订户群和订户计划，而无需通过 Vending Manager 管理控制台界面来实现。

可以通过 XML-RPC（Remote Procedure Call, 远程过程调用）实现来访问 Vending Manager API。通过 XML-RPC，应用程序可以在进行传输和数据编码时分别使用 HTTP 和 XML 进行远程过程调用。通过使用 Internet 上提供的绑定，可以将 XML-RPC 与许多不同编程语言一起使用。

注 - 有关 XML-RPC 的教程不在本文档的范围之内。您可以从 Internet 的多个不同 Web 站点中获取有关编写使用 XML-RPC 的应用程序方面的信息。

Vending Manager API 包含以下类：

AuthenticationHandler - 验证用户是否有权访问 Vending Manager 以及处理登录和注销请求。

BundleHandler - 可以用其访问包以及创建、删除和修改包。

CampaignHandler - 可以用其访问活动以及创建、删除和修改活动。

CategoryHandler - 可以用其访问有关类别或类别树的信息。

ContentHandler - 提供类别中的所有内容的列表。

DeviceHandler - 提供 Vending Manager 支持的所有设备的列表。

PlanHandler - 可以用其访问订户计划以及创建、删除和修改订户计划。

SubscriberSegmentHandler - 可以用其访问订户群以及创建、删除和修改订户群。

TemplateHandler - 提供 Vending Manager 中的所有活动模板的列表。

UserHandler - 提供 Vending Manager 已知的所有订户的列表。

有关这些类及其方法和参数的信息，请参见 $CDS_HOME/javadoc/vendingapi/index.html 中的 Javadoc 工具的 HTML 输出。

12.1 一般处理流程

可以使用 Vending Manager API 访问 Vending Manager 数据，因此，使用该 API 的任何应用程序必须先通过 AuthenticationHandler.logUserIn 方法登录到 Vending Manager。用于登录的用户名必须是有效的 Vending Manager 管理员帐户，而不是客户服务代理。

注 - 所使用的帐户密码不能是默认密码 admin。否则，在运行应用程序之前，您必须登录到 Vending Manager 管理控制台并更改该密码。

如果登录成功，则会返回授权密钥。可以在所有后续调用中使用此授权密钥以访问 Vending Manager 数据。在应用程序完成所有任务后，最后一步是使用 AuthenticationHandler.logUserOut 方法注销 Vending Manager。

注 - 如果在指定时间（几分钟）内未使用授权密钥，该密钥将会失效，并且此后的调用将会失败。应用程序必须重新登录以接收新的授权密钥。默认时间为 10 分钟。要更改此时间，请设置 $CDS_HOME/deployment/deployment-name/conf/VSAdminConsole.properties 文件中的 vendingApi.authkey.timeout.minutes。

12.2 XML-RPC 方法调用的指导

XML-RPC 调用遵循特定的约定。本节中的样例代码说明了如何进行调用，以及如何处理用户验证结果。该样例代码是使用 Java 编程语言编写的，并使用 Apache XML-RPC 客户机库。如果使用不同的语言或库，需要编写的代码可能会有所不同。

提示 - 有关每种处理程序的方法和参数键的名称，请参见 $CDS_HOME/javadoc/vendingapi/index.html 中的 Javadoc 工具的输出。

请按以下指导原则编写处理程序调用代码：

将调用的方法参数置于一个散列表中。将散列表置于向量中。

...
// Create a vector to hold the request parameters
Vector<Hashtable> request = new Vector<Hashtable>();
 
// Create a Hashtable to hold the method specific parameters and add them.
Hashtable<String,Object> methodParams = new Hashtable<String,Object>();
methodParams.put("username", "user1");
methodParams.put("password", "cryptic1");
 
// Add the method specific parameters to the request.
request.addElement(methodParams);
...

要调用某种方法，请传递该方法的名称以及包含参数的向量。将返回一个散列表。方法调用必须包含处理程序的名称，例如：AuthenticationHandler.logUserIn。

...
// Generate the full method name. ( handlerName.methodName )
String methodName = "AuthenticationHandler.logUserIn";
// Send the request and get the response.
Hashtable response; 
response = (Hashtable) client.execute(methodName, request);
...

通过检查返回的散列表中包含的响应代码，验证方法是否成功执行。如果发生错误，散列表中还包含响应消息。

...
// Process the results: check to see if there was an error.
String responseCode = (String)response.get("responseCode");
if(!responseCode.equals(“success”)) {
   // There was an error. Find out the 'real cause'.
   String realCause = (String)response.get("responseErrorCode");
 
   System.out.println("Error: Operation failed with: " +realCause);
}
...

如果方法已成功执行，则提取散列表中返回的值。如果方法未返回任何值，则散列表只包含响应代码。

...
// Get the authKey from the request.
String authKey = (String)response.get("authKey");
...

下面提供了一个用于处理 Vending Manager 登录请求的完整示例，这是通过 Open Content Delivery Server 项目提供的：https://opencds.dev.java.net/source/browse/opencds/trunk/modules/contrib/vendingjavaclient/src/example/com/sun/content/server/vendingjavaclient/xmlrpc/LoginExample.java。该示例仅用于说明目的，本产品并不支持该示例。

12.3 访问 Content Delivery Server

要从 Content Delivery Server 获取数据，应用程序必须能够与 Content Delivery Server 进行通信。请要求网络管理员确保应用程序可以访问 Content Delivery Server，并且任何所需的代理或防火墙均已配置为允许该访问。

此外，Content Delivery Server 还必须认可客户机已授权执行数据请求。$CDS_HOME/deployment/deployment-name/conf/VSAdminConsole.properties 文件中的 vendingApi.xml-rpc.trustedHosts 属性包含请求将被接受的主机列表。

将 vendingApi.xml-rpc.trustedHosts 属性设置为应用程序所在主机的主机名和 IP 地址，而不管是否与 Content Delivery Server 位于同一主机。要接受任何主机的请求，请保留此值为空。要接受多个主机的请求，请使用逗号分隔主机名或 IP 地址，例如：

vendingApi.xml-rpc.trustedHosts=127.0.0.1,localhost