使用 IBM Lotus Sametime Unified Telephony API

本文描述了 IBM® Lotus® Sametime® Unified Telephony API 以及相关的部署、配置和调用步骤。Lotus Sametime Unified Telephony API 是一个 REST (Representation State Transfer) API,提供了点击通话(click-to-call)和点击会议(click-to-conference)语义。

Mark Wallace, 软件架构师, EMC

Mark Wallace 是位于爱尔兰的 IBM Dublin 软件实验室的一名软件架构师。他与 1993 年加入 IBM Lotus,从那时起一直从事各种主题的项目,包括 IBM Lotus Sametime Translation Services、Lotus Sametime Everyplace、IBM 数据访问工具和 Lotus Component Designer。他目前是实验室中从事 IBM Lotus Sametime Unified Telephony 项目的团队的技术主管。



John Crawley, 软件开发人员, EMC

John Crawley 是一名软件开发人员,并且自 2006 年起就成为了 IBM 的员工。他目前从事 IBM Lotus Sametime Unified Telephony 项目,此前是 IBM Learning 团队的一名成员。



2009 年 11 月 24 日

编辑注:您很精通这个主题吗?希望分享您的经验吗?请马上加入到 IBM Lotus 软件 wiki 项目。

简介

Lotus 软件试用下载

立即下载最新版本的 IBM Lotus 试用软件,轻松体验产品的最新特性!

IBM Lotus Sametime Unified Telephony 软件是在异构电话环境中提供一致通信特性的中间件。该项目提供了使用一个或多个联系人或外部号码拨打电话的功能、显示某个联系人当前是否在通话中的电话在线提示功能以及首选项配置,后者允许用户使用多种方式配置传入呼叫的路线。

本文假设您熟悉 Lotus Sametime、IBM WebSphere® Application Server、Java™ Server Pages 和 Web 技术。本文将首先介绍如何安装和配置 REST API,接着描述如何调用 API。此外,还讨论了一些高级部署选项。

REST API 提供了点击通话和点击会议语义,允许在注册用户和一个或多个 Lotus Sametime 联系人或外部电话号码之间建立通话。这个 REST API 与 Lotus Sametime Connect Web Kit 电话 API 共享了相同的签名,这允许您编写能够根据可用性在使用本地 API 或远程 API 之间切换的应用程序。

图 1. 最小 Lotus Sametime Unified Telephony 部署
最小 Lotus Sametime Unified Telephony 部署

在 Lotus Sametime Unified Telephony 部署中包含两种服务器类型:

  • Lotus Sametime Unified Telephony 核心服务器。这种服务器类型管理呼叫模型、聚集电话在线提示、跟踪用户和设备、执行呼叫工作流、管理 Lotus Sametime 软件电话的注册和路径选择,并提供铃声和通知以及特定会议支持。另一个可选特性是可以托管 REST API。
  • Lotus Sametime Unified Telephony 连接服务器。这个服务器类型为接口提供了现有电话环境。它负责在呼叫期间在端点之间编排会话初始化协议(session initiation protocol,SIP)、处理相同的号码,维护通向多个专用分组交换机(PBX)、网关(或两者兼有)的 SIP 中继线。

安装和配置

Lotus Sametime Unified Telephony API 被作为一个 Java Platform, Enterprise Edition (Java EE) 企业应用程序提供,并且可以作为 Lotus Sametime Unified Telephony Core 服务器的一部分提供。完成企业应用程序配置后,还需要执行一些配置步骤,以允许将其连接到 Lotus Sametime 服务器并选择性地支持发布有关 Lotus Sametime Unified Telephony API 的信息。安装和配置步骤由 Lotus Sametime Unified Telephony Core 服务器安装程序自动完成;这是安装企业应用程序的最简单方式。

遵循以下步骤,使用 Lotus Sametime Unified Telephony Core 服务器安装程序安装 Lotus Sametime Unified Telephony API:

  1. 在 Lotus Sametime Unified Telephony Core 服务器中打开 SSH 会话并作为根用户进行身份验证。
  2. 转到 /software/IBM 文件夹。
  3. 使用以下命令启动安装程序,安装 REST API:

    ./install.sh rest
  4. 在出现提示时输入 YES,阅读许可协议并选择接受。REST API 企业应用程序完成安装。
  5. 使用如下命令安装 WebSphere Application Server:

    /opt/IBM/WebSphere/AppServer/bin/startServer.sh server1
  6. 使用如下命令重启 OSGI 容器:

    /etc/init.d/symphoniad restart

遵循以下步骤,使用 WebSphere Application Server 集成解决方案控制台安装 REST API:

  1. 将以下文件从 Lotus Sametime Unified Telephony Core 服务器复制到计划在其中运行集成解决方案控制台的机器:

    /software/IBM/SUT/Admin/webApps/sutapi-app-8.0.ear
  2. 为您的 Lotus Sametime Unified Telephony Core 服务器打开 WebSphere Application Server 集成解决方案控制台;例如:

    https://<your server>:9043/ibm/console/logon.jsp
  3. 导航到 Applications - Enterprise Applications,单击 Install 按钮。
  4. 选择 Remote 文件系统选项,然后单击 Browse 按钮。
  5. 浏览到以下位置:

    /software/IBM/SUT/Admin/webApps
  6. 选择文件 sutapi-app-8.0.ear 并单击 OK。
  7. 只有在需要额外信息的情况下保持默认选项 Prompt me,然后单击 Next 按钮。
  8. 单击 Next 接受默认安装选项。
  9. 单击 Next 接受默认服务器模块映射。
  10. 单击 Finish 按钮完成安装,然后单击 Save 更新配置。
  11. 选择 Sametime Unified Telephony API 选项,然后选择 Environment entries for web modules 选项。
  12. 在 serviceAddress 字段中输入 Lotus Sametime Unified Telephony Core 服务器的 IP 地址。
  13. 在 sametimeServer 字段中输入 Lotus Sametime 服务器的主机名。
  14. 在 sametimePort 字段中输入连接到 Lotus Sametime 服务器时将使用的端口号(通常为 1516)。
  15. 该步骤是可选的;只用于 Lotus Sametime 8.5 互操作性。在 baseUrlAttr 字段中输入属性编号(通常为 40002)。
  16. 该步骤是可选的;只用于 Lotus Sametime 8.5 互操作性。在 baseURL 字段中输入 REST API 的基 URL。例如:

    http://<server>:<port>/sutapi MW
  17. 单击 OK,然后单击 Save 来更新配置。

安装好 Lotus Sametime Unified Telephony API 后,您需要完成一些配置步骤来为应用程序配置安全性。这个过程是必须的,因为 REST API 将只针对在 Lotus Sametime Unified Telephony Core 服务器上拥有权限的用户工作。如果无权使用 Lotus Sametime Unified Telephony 的未经身份验证的用户调用 REST API,那么他们的请求将被忽略。

注意:Lotus Sametime Unified Telephony Core 服务器安装程序并不会自动执行安全设置的配置过程,因此必须始终执行以下步骤。

遵循以下步骤为 Lotus Sametime Unified Telephony API 配置安全性:

  1. 为您的 Sametime Unified Telephony Core 服务器打开 WebSphere Application Server 集成解决方案控制台:

    https://>your server>:9043/ibm/console/logon.jsp
  2. 导航到 Security - Secure administration, applications, and infrastructure。
  3. 选择 Enable application security 选项,然后单击 Apply。
  4. 单击 Save 以更新配置。
  5. 导航到 Applications - Enterprise Applications。
  6. 选择 Sametime Unified Telephony API 选项,然后选择 Security role to user/group mapping 选项。
  7. 对于 AllAuthenticateUsers 角色,选择 All authenticate 并单击 OK。
  8. 单击 Save 以更新配置。
  9. 选择 Sametime Unified Telephony SIP Registrar,然后选择 Security role to user/group mapping 选项。
  10. 对于 secureRole 和 admins 角色,选择 Everyone 选项并单击 OK。
  11. 单击 Save 以更新配置。
  12. 重启 Sametime Unified Telephony Core 服务器,让更改生效。

接下来,必须对 WebSphere Application Server 进行配置,以便它可以使用与 Lotus Sametime 服务器相同的企业目录来对用户执行身份验证。WebSphere Application Server 被配置为对默认的管理用户使用基于文件的库。对库执行联合后可以实现与企业目录的共存。有关为 WebSphere Application Server 配置联合库的更多信息,请参见 WebSphere Application Server Version 6.1 Information Center

要检验 Lotus Sametime Unified Telephony API 是否正常工作,请执行以下步骤:

  1. 使用启用了 Lotus Sametime Unified Telephony 的客户机登录。
  2. 打开一个浏览器,输入如下所示的 URL:

    http://sutd-tas03.mul.ie.ibm.com:9080/sutapi/stwebapi/call?device=<preferred device>&userId=<user ID or phone number>
  3. 得到提示后,执行身份验证并对您的 Sametime Unified Telephony Core 服务器使用一个有效的用户名。

指定的设备发出铃声;应答该设备时,将呼叫指定的电话号码或用户。


调用 REST API

现在,已经安装并配置好了 Lotus Sametime Unified Telephony API,您可以开始进行测试了。可以实现的最简单的呼叫类型是在用户的可靠设备和一个外部电话号码之间展开的呼叫。下面是调用 REST API 以发出这类呼叫的语法:

http://<your server>/sutapi/stwebapi/call?userId=<external phone number>

当将这个 URL 输入到浏览器中后,将提示您输入您的凭证。成功完成身份验证后,您的可信任设备将响起铃声;当应答时,将拨出一个外部电话号码。需要注意的一点是,在使用 E.164 格式指定外部号码时,必须将前面的 + 编码为 %2B。这个参数名是用于在 Lotus Sametime Connect Web Kit 中维护与 Telephony API 的兼容性的 userId,Lotus Sametime Connect Web Kit 是 Lotus Sametime 8.0.2 Software Developer Kit 的一部分。

下一个选项是指定由呼叫方使用的电话。下面是调用 REST API 以发出此类呼叫的语法:

http://<your server>/sutapi/stwebapi/call?device=<your phone number>&userId=<external phone number>

使用设备参数将允许使用当前首选设备替换呼叫方的可信设备。注意,在第一版 Lotus Sametime Unified Telephony 中,将您的统一号码指定为首选设备是无效的。

下一个选项是使用用户 ID 呼叫用户。以下是调用 REST API 以发出此类呼叫的语法:

http://<your server>/sutapi/stwebapi/call?device=<your phone number>&userId=<user id>

使用这个选项后,个人的电话号码将在服务器上通过 User Information Service 解析。

下一个选项是呼叫多名用户。以下是调用 REST API 以发出此类呼叫的语法:

http://>your server>/sutapi/stwebapi/call?userId=<phone1,phone2,...>

使用这个选项后,将发起一个会议呼叫。首先对调用方拨号,当用户加入后,再将其他参与者拨入到会议中。注意,在开始会议呼叫时使用这个设备参数是无效的。


高级配置

本节将介绍以下高级配置选项:

  • 在一个独立服务器上安装 Lotus Sametime Unified Telephony API
  • 集群化
  • 单点登录
图 2. 在独立服务器上安装 Lotus Sametime Unified Telephony API
在独立服务器上安装 Lotus Sametime Unified Telephony API

图 2 展示了安装在一个独立 WebSphere Application Server 上的 Lotus Sametime Unified Telephony API,并且被连接到一个 Lotus Sametime Unified Telephony 核心服务器集群。通过遵循使用 WebSphere Application Server 集成解决方案控制台安装 REST API 的步骤,可以将 Sametime Unified Telephony API 部署到一台专用服务器上。必须确保服务器使用与 Lotus Sametime 服务器相同的企业目录来对用户执行身份验证。Lotus Sametime Unified Telephony API 和 Lotus Sametime Unified Telephony 核心服务器之间的通信通过 Lotus Sametime 服务器发生。Lotus Sametime Unified Telephony API 作为服务器应用程序连接到 Lotus Sametime 服务器;要开始工作,安装所在的服务器的 IP 地址必须列出在 Lotus Sametime 服务器上的可信 IP 列表中(Lotus Sametime Unified Telephony 核心服务器在部署时也被添加到这个列表中)。

如果您的环境包含一个 Lotus Sametime Unified Telephony 核心服务器集群,那么可以使用单个 Sametime Unified Telephony API 实例来处理对这个集群的所有请求。要使这个办法奏效,必须在 Sametime Unified Telephony API 所连接到的 Lotus Sametime Unified Telephony 核心服务器上修改通信服务配置。遵循以下步骤修改配置,从而为集群提供支持:

  1. 在 Lotus Sametime Unified Telephony 核心服务器上打开 Secure Shell (SSH) 会话,并以根用户的身份进行验证。
  2. 转到 /enterprise/ibm 文件夹。
  3. 编辑 sutbcomadapter.properties 文件。
  4. 添加(或编辑)属性 STIBroadcastMakeCall,使其值为 true。
  5. 使用如下命令重启 OSGI 容器:

    /etc/init.d/symphoniad restart

完成这些修改后,服务器接收到的任何代表 Lotus Sametime Unified Telephony API 发出呼叫的请求,以及不是针对该服务器的请求,都被传播到集群中。

图 3 演示了来自其他供应商的应用程序如何使用 Lotus Sametime Unified Telephony API。调用 Lotus Sametime Unified Telephony API 的方法有许多种。来自其他供应商的应用程序可以执行以下步骤:

  • 向直接引用 Lotus Sametime Unified Telephony API 的客户机发送标记
  • 通过向托管 Lotus Sametime Unified Telephony API 的服务器发出一个 HTTP 请求,直接调用 Lotus Sametime Unified Telephony API
图 3. 来自其他供应商的应用程序使用 Lotus Sametime Unified Telephony API
来自其他供应商的应用程序使用 Lotus Sametime Unified Telephony API

要使这些选项正常工作,必须在托管应用程序(来自其他供应商)的服务器和托管 Lotus Sametime Unified Telephony API 的服务器之间配置单点登录。有关在 WebSphere Application Server 和 IBM Lotus Domino® 或其他 WebSphere Application Server 之间配置单点登录的信息,请参考 WebSphere Application Server Version 6.1 Information Center。注意,要使用第二个选项,在发出请求时必须显式地传递 LTPA 令牌。

来自其他供应商的应用程序需要发现 Lotus Sametime Unified Telephony API 的基 URL。完成这个任务有两种方法:在应用程序中使用一种配置设置,或者使用 Lotus Sametime API 从服务器属性(由 Lotus Sametime Unified Telephony API 发布)检索基 URL。要是第二个选项工作,需要用到上面列出的 Lotus Sametime Unified Telephony API 的可选配置步骤。在配置好基 URL 属性和值后,Lotus Sametime Unified Telephony API 应用程序将使用指定的属性值(推荐的默认值为 40002)发布基 URL,作为它所连接到的 Lotus Sametime 服务器的属性。通过读取这个服务器属性,任何应用程序现在都可以检索这个值(参考 Lotus Sametime SDK 获得有关读取服务器属性的更多信息)。通过读取服务器属性(用于实现 Lotus Sametime Unified Telephony 和 Lotus Sametime 8.5 及更高版本之间的互操作性)检索基 URL。


样例应用程序

本文下载小节附带了一个样例应用程序,演示了从定制应用程序调用 Lotus Sametime Unified Telephony API 的过程。这个应用程序显示了一组人名和电话号码列表并提供了下列特性:

  • 单击呼叫一个电话号码
  • 单击呼叫一个用户 ID
  • 单击呼叫多个电话号码

样例应用程序包含了硬编码的名称和电话号码,您必须对这些内容进行修改。您应当使用 IBM Rational® Application Developer 编辑该项目,并修改这些值以符合您自己的部署。

要编辑样例应用程序,遵循以下步骤:

  1. 打开 PeopleBean.java 类。在该文件的顶部,有一个数组中包含了样例所使用的名称、用户 ID 和电话号码,如清单 1 所示。
清单 1. Person Bean 对象的数组
private PersonBean[] people = new PersonBean[] {
  new PersonBean("Mark Wallace", "mark_wallace@ie.ibm.com", "+18004264968"),
  new PersonBean("John Crawley", "crawleyj@ie.ibm.com", "+18887467426")
};
  1. 编辑这个数组,添加适合您自己的部署的值。

随后,可以将项目作为 Web Application Archive (WAR) 文件导出,此文件可以安装到您的 Lotus Sametime Unified Telephony 核心服务器。参考 WebSphere Application Server, Version 6.1 Information Center 中的 “Installing application files with the console” 部分,了解有关安装 WAR 文件的更多信息。

该应用程序必须修改其中一个环境条目:

  • 例如,REST API 的基 URL,http://<server>:<port>/sutapi

参见图 4。

图 4. 配置样例应用程序的环境条目
配置样例应用程序的环境条目

应用程序用户安全角色必须映射到 All authenticated,如图 5 所示。

图 5. 将用户安全角色映射到 All authenticated 选项
将用户安全角色映射到 All authenticated 选项

要访问应用程序,使用如下所示的 URL:

http://9.45.89.226:9080/sutapisample/People.jsp

将提示您进行身份验证以访问这个页面。

图 6 展示了一个样例应用程序。

图 6. Lotus Sametime Unified Telephony API 样例应用程序
Lotus Sametime Unified Telephony API 样例应用程序

注意:样例中指定的电话号码为 IBM 的号码:

综合查询

800-IBM-4YOU (800-426-4968)

购买帮助

888-SHOP-IBM (888-7467-426)

要发起呼叫,可以单击用户名或电话号码。然后提示您指定一个首选设备来执行呼叫,如图 7 所示。

图 7. 提示您选择一个首选设备
提示您选择一个首选设备

输入电话号码并单击 OK 后,Lotus Sametime Unified Telephony API 将被调用,而您所单击的用户 ID 或电话号码将被作为呼叫目标发送。

要发起一个会议呼叫,必须选择多个用户并单击 Call selected 按钮。

JSP 页面在一个 HTML 表中显示了一个名称和电话号码列表。每个名称和电话号码对都以超链接的方式显示。当单击这些链接后,将调用一个 JavaScript 方法来调用 Lotus Sametime Unified Telephony API。

本文下载小节提供的样例包含了一个 JavaScript 文件,该文件负责调用 Lotus Sametime Unified Telephony API。它使用 XMLHttpRequest JavaScript 对象针对 API 发出一个 Ajax 风格的请求。清单 2 展示了调用 API 以发起双方呼叫的代码。

清单 2. 发送呼叫请求的 JavaScript 方法
/*
 * Send a call request to the Sametime Unified Telephony API
 * baseUrl - Base URL of the SUT REST API
 * userId = user(s) or telephone number(s) to call
 */
function sendCallRequest(baseUrl, userId) {
	userId = escapeParam(userId);
	var device = promptPreferredDevice();
	if (device == null || device.length == 0) {
		alert("You must specify your preferred device.");
		return;
	}
	device = escapeParam(device);
	var url = baseUrl + "/stwebapi/call?device=" + device + "&userId=" + userId;
	alert(url);
	httpRequest.onreadystatechange = stateChange;
	httpRequest.open("GET", url, true);
	httpRequest.send(null);	
}

JavaScript 通过完成以下操作构建合适的 URL,以发起调用:

  • 在安装样例应用程序时,使用上文配置的基 URL
  • 将 userId 编码为将被包含到 URL 中的参数
  • 提述用户输入他们的首选设备,用于双方通话
  • 将设备编码为将被包含到 URL 中的参数
  • 使用基 URL 和参数构建将被调用的 URL
  • 使用 XMLHttpRequest 对象,通过 URL 执行一个 HTTP GET 操作

结束语

本文解释了如何部署和使用 Lotus Sametime Unified Telephony API。它展示了如何将 API 作为 Lotus Sametime Unified Telephony 核心服务器的一部分进行部署,还解释了其他一些部署选项。Lotus Sametime Unified Telephony API 基于 REST,并且可以与使用不同技术构建的应用程序集成在一起。本文附带的样例应用程序展示了将这个 API 与一个定制 Java EE 应用程序集成的例子。该样例应用程序使用的技术允许您从自己的应用程序中调用这个 API。


下载

描述名字大小
SUTAPISample.zip14KB

参考资料

学习

获得产品和技术

讨论

条评论

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=Lotus
ArticleID=449343
ArticleTitle=使用 IBM Lotus Sametime Unified Telephony API
publish-date=11242009