Aleph : X-Server 接口简介及应用实例

周磊2014-6

2

内容

X-server 简介• 入门• 权限控制• 转换机制（ Translate ）

常用 X-Services 应用实例 :

• 书目相关接口 • 读者相关接口• 馆员认证接口• 更新读者接口

3

内容

X-server 简介• 入门• 权限控制• 转换机制（ Translate ）

常用 X-Services 样例 :

• 书目相关接口 • 读者相关接口• 馆员认证接口• 更新读者接口

4

X-server 简介 – 1 • 基于 URL/XML 的 API 接口

• 应用于 Exlibris 产品之间及与 Exlibris 产品与外部应用系统之间进行互操作 • Ex Libris 产品例如 Metalib , Verde, PDS, Web ILL 都

会用到 Aleph 的 X-Server• 第三方应用系统如一卡通系统、门禁系统、电子阅览室系统、

自助办证、移动服务、短信服务等• Aleph 本地开发模块：

APSM 、 APSS 、 AOMS 、 AIMS 、 APMS 、 WebCIR 等

5

X-server 简介 – 2• 接口返回有层级关系的结构化 XML 格式数据

• 易于理解• 有大量商用解析器可直接使用

Aleph

GUI Client

BrowserHTML

Proprietary format

XMLClient

XML

6

X-Server 简介 – 3调用语法

http://<server>:<port>/X?op=<servicename>&<param_name>=<param_value>

• Port 就是 OPAC 的端口。

• 通常使用 GET 机制发送请求

• 但对于 update-bor ， update-doc 等接口使用 POST 机制发送请求

7

样例 1 – 查找 输入：http://202.198.141.86:8992/X?op=find&request=wti=oracle&base=whu01

基地址： IP ： Port/X? 接口名： op=find 参数： &request=wti=oracle 参数： &base=whu01

输出：

8

样例 2 – 读者认证

http://202.198.141.86:8992/X?op=bor-auth&id=ID51&verification=1234

9

ALEPH 500 系统 X-service 接口 查询、排序、显示 书目记录创建、更新 联编异构系统上载书目、馆藏 馆藏信息查询、更新 读者认证、读者查询、读者记录创建、更新、删除 借、还、续借、预约、现金事务处理 订单修改、订单转移、订单删除 图书封面、热门信息推送 短信通知服务接口

9

10

常用 X-services 列表 1

• bor-auth• bor-by-key• bor-course• bor-info• circ-status• find• find-doc• get-holding• get-sort-codes• hold-req• hold-req-cancel• item-data• present• renew• sort-set

• update-bor• update-doc• explain• login• user-auth• ill-arrive-copy• ill-arrive-loan• ill-bor-auth• ill-bor-info• ill-build-loan• ill-create-pat• ill-get-doc• ill-get-doc-short• ill-get-set

• ill-loan-return• ill-print-holdings• ill-print-items• ill-holds-delete• ill-in-loc• ill-in-loc-preview• ill-item-by-bc• ill-item-delete• ill-item-due-date• ill-item-info• ill-loan-info• ill-loan-lost• ill-loan-recall• ill-loan-renew

11

常用 X-services 列表 2

• bor_auth_valid• bor_info_nlc• item_data_nlc• loan_history• hold_list• overdue_list• return_date

• bor_status• bor_farewell• hold_req_nlc• update_bor_nlc • update_bor_id• update_item_nlc • update_cash• update_user_pwd• update_order

• lcl_loan• lcl_return• lcl_find• lcl_doc_short• get_bor_idp• get_hol_ucs• update_doc_ucs• update_hol_ucs

12

内容

X-server 简介• 入门• 权限控制• 转换机制（ Translate ）

常用 X-Services 样例 :

• 书目相关接口 • 读者相关接口• 馆员认证接口• 更新读者接口

13

X-server 权限控制 IP 控制

$alephe_tab/server_ip_allowed

账号控制 user_name user_password

14

权限控制 – 账号控制 – 1• 每个接口都对应一项工作人员权限

• 系统设置缺省账号 WWW-X/WWW-X 。该账号的权限就是匿名 X-server 用户的权限。

• find, find-doc 和 present 接口完全开放

• 注意 : 如果修改了 WWW-X 用户的密码，就取消了匿名访问。同时，可以通过增减 WWW-X 用户的账号权限来调整匿名用户的权限。

15

权限控制 – 账户控制 -2 可以为不同的用户配置不同的权限

16

权限控制 – 账户控制 – 3• 可以有两种方式调用先前创建的用户 :

方法 1:

在提交 url 接口里，增加 user_name 和 user_password 两个参数。•

例如 :• 测试账户： WWW-TEST/TEST

http://202.198.141.86:8992/X?op=bor-auth_valid&id=ID51&verification=1234&user_name=WWW-TEST&user_password=TEST

17

权限控制 – 账户控制 – 4• 不带 user_name,user_password 的话就校验 WWW-X 用户的权限 :

http://202.198.141.86:8992/X?op=bor-auth_valid&id=ID51&verification=1234

18

权限控制 – 账户控制 – 5• 方法 2:

1) 先带” user_name”,”user_password” 参数调用“ login” 接口2) 如果账户验证通过， X-server 会返回一串 session-ID 3) 在之后调用 X-server 的时候都加上 “ session” 参数，它的值就是这串 session-ID 值。

样例 :1) http://202.198.141.86:8992/X?op=login&user_name=www-test&user_password=test&library=whu50

2) http://202.198.141.86:8992/X?op=bor-auth_valid&id=ID51&verification=1234&session=UU3H9FRDJJUXER7DJCALEU1285HALFKLL7ENIGU9QD28XU2KKE

• 推荐采用第二种方法，因为第一种方法每次调用会产生不同的session-id ，占用 license 资源。

19

内容

X-server 简介• 入门• 权限控制• 转换机制（ Translate ）

常用 X-Services 样例 :

• 书目相关接口 • 读者相关接口• 馆员认证接口• 更新读者接口

20

转换机制 Translate• 每个输出都会经过转换

• 转换机制可以针对 tag 或数据。可以屏蔽或改变一些 tag ，或者调整数据显示格式及内容。

• 有两种不同的转换机制 :1) 在 $alephe_root/www_x_lng/ 目录下有一系列的 *trn 文件。这个可以处理数据的显示格式及内容

2) 在 $alephe_root/www_x_lng/ 目录下有一系列的 *tag 文件。可以屏蔽一些字段，或转换字段名

• 特别的，对于 bor-info 接口，还有一个过滤机制 filter-mechanism

21

转换机制 – trn – 1 • 对于所有接口，都会调用 global.trn 和 <service-name>.trn

• DATE 把数字转换为日期格式• SUB-LIB 把分馆代码转换为分馆名称• PC-TAB-EXP 根据 pc_tab_exp_field.lng 参数表，把代码转换为描述• TEXT 直接根据第 4 列参数的内容做转换• DECIMAL 增加小数点• NONE 不做转换

22

转换机制 – trn – 2• 以 bor-info 为例

http://202.198.141.86:8992/X?op=bor-info&id=6666&session=UU3H9FRDJJUXER7DJCALEU1285HALFKLL7ENIGU9QD28XU2KKE

返回 :<bor-info>+ <z303> […] <z303-home-library> 武大馆 </z303-home-library> <z303-birth-date>08/11/1973</z303-birth-date> </z303> <z304> […] </z304> <z305> <z305-bor-status> 教职工 </z305-bor-status> </z305> <z31> <z31-sum>(10.00)</z31-sum> </z31></bor-info>

23

转换机制 – tag – 1 • 对于所有接口，都会调用 global.tag 和 <service-

name>.tag

• Tag 转换机制主要用于三个目的 :• 改变标签（ tag ）的标题• 屏蔽指定 tags• 屏蔽数据字段

• 说明 : 屏蔽数据能够提高 X-server 输出的响应时间。

24

转换机制 – tag – 2 • 例如 :在 $alephe_root/www_x_eng/bor-info.tag中设置

z304 DELETEz305-id DELETEz305-sub-library TRANSLATE sublib

http://202.198.141.86:8992/X?op=bor-info&id=6666&session=UU3H9FRDJJUXER7DJCALEU1285HALFKLL7ENIGU9QD28XU2KKE

返回信息中就没有 z304节点，而 z305-sub-library标签也变更为 sublib<bor-info>...<z305><sublib> 武大馆 </sublib><z305-open-date>26/01/2007</z305-open-date>…

25

转换机制 - filter – 1 • 特别的，对于 bor-info 接口，有一个 filter 过滤机制，可以定义那些字段需要显示• 可以在 $alephe_root/www_x_eng 中增加一个文件，比如tab_bor_info_filter ，在这个文件中列出来需要显示的字段：

样例： tab_bor_info_filter:Z303-NAMEZ304-TELEPHONE

26

转换机制 - filter– 2 • 在 bor-info 接口里增加参数 &filter_data=<file_name> :

• http://202.198.141.86:8992/X?op=bor-info&id=ID51&cash=O&filter_data=tab_bor_info_filter&session=UU3H9FRDJJUXER7DJCALEU1285HALFKLL7ENIGU9QD28XU2KKE

这样只有读者姓名、电话会显示了：

27

内容

X-server 简介• 入门• 权限控制• 转换机制（ Translate ）

常用 X-Services 样例 :

• 书目相关接口 • 读者相关接口• 馆员认证接口• 更新读者接口

28

书目检索、排序与显示 - 1• 查找 find

• http://202.198.141.86:8992/X?op=find&request=wti=oracle&base=whu01&session=UU3H9FRDJJUXER7DJCALEU1285HALFKLL7ENIGU9QD28XU2KKE

• Request 参数：检索式• Base 参数：检索库

• 返回• Set_number 结果集名称• No_records 命中记录数• No_entries 可显示记录数

29

书目检索、排序与显示 - 2 排序 sort-set

http://202.198.141.86:8992/X?op=sort_set&library=whu01&set_number=000081&sort_code_1=01&sort_order_1=D&sort_code_2=04&sort_order_2=A&session=UU3H9FRDJJUXER7DJCALEU1285HALFKLL7ENIGU9QD28XU2KKE

sort_code 来自书目库的 tab_sort 参数表，通常是01 年份02 著者03 题名04 索书号 /分类号

30

书目检索、排序与显示 - 3 显示 present

http://202.198.141.86:8992/X?op=present&base=whu01&set_number=000081&set_entry=000000001&session=UU3H9FRDJJUXER7DJCALEU1285HALFKLL7ENIGU9QD28XU2KKE

显示一条 http://

202.198.141.86:8992/X?op=present&base=whu01&set_number=000081&set_entry=000000001-00000010&session=UU3H9FRDJJUXER7DJCALEU1285HALFKLL7ENIGU9QD28XU2KKE

显示多条

31

书目检索、排序与显示 - 4

32

显示书目的馆藏状态 馆藏状态 circ_status

http://202.198.141.86:8992/X?op=circ_status&sys_no=000610238&library=WHU01&session=UU3H9FRDJJUXER7DJCALEU1285HALFKLL7ENIGU9QD28XU2KKE

33

读者相关接口 - 1• 读者认证 bor-auth:

• http://202.198.141.86:8992/X?op=bor-auth&id=ID51&verification=1234&library=WHU50&session=UU3H9FRDJJUXER7DJCALEU1285HALFKLL7ENIGU9QD28XU2KKE

• 如果密码正确，返回读者的 z303 ， z304 ， z305 信息• 否则返回 <error>Error in Verification</error>

34

读者相关接口 - 1• 读者认证 bor-auth-valid:

• http://202.198.141.86:8992/X?op=bor-auth_valid&id=ID51&verification=1234&library=WHU50&session=UU3H9FRDJJUXER7DJCALEU1285HALFKLL7ENIGU9QD28XU2KKE

• 比 bor-auth 接口增加了检查读者有效性，在 tab_check_circ中定义：

• BOR-AUTH check_circ_1_a• BOR-AUTH check_circ_1_c_a

• 如果密码正确，且读者证卡有效，返回读者的z303 ， z304 ， z305 信息

• 否则返回 • <error> 验证错误 </error> 或• <error> 不是有效读者 </error>

35

读者相关接口 - 2• 读者信息 bor-info:

• http://202.198.141.86:8992/X?op=bor-info&id=ID51&library=WHU50&session=UU3H9FRDJJUXER7DJCALEU1285HALFKLL7ENIGU9QD28XU2KKE

• 可以不用密码，返回读者的 z303 ， z304 ， z305 以及外借、预约、现金事务等信息

• 可以通过参数过滤是否显示相关信息• Loan=N 不显示外借• Hold=N 不显示预约• Cash=O 只显示未完成的现金事务• Format=1 显示详细读者信息，包括多个地址信息和多个 ID 信息

36

馆员认证 • 馆员认证 user-auth

• http://202.198.141.86:8992/X?op=user-auth&staff_user=TEST&staff_pass=TEST&library=WHU50&session=UU3H9FRDJJUXER7DJCALEU1285HALFKLL7ENIGU9QD28XU2KKE

• 如果认证成功，返回账户基本信息

37

更新读者记录 - 1 更新读者记录 update-bor

可以新建、更新、删除读者记录 采用 POST 方式，需要做一些脚本

<input type="hidden" name="op" value="update-bor"><input type="hidden" name=“SESSION" value="UU3H9FRDJJUXER7DJCALEU1285HALFKLL7ENIGU9QD28XU2KKE"><input type="hidden" name="library" value=“WHU50"><input type="hidden" name="update_flag" value="Y"><textarea name="xml_full_req" cols="50" rows="10"></textarea>

同时准备一个 xml_full_req 文件，里面存放的 xml格式的详细读者信息

38

更新读者记录 - 2 Xml_full_req 文件内容：

39

参考文档 ALEPH 18[1].01 X-Services.pdf Aleph 500 X-Services -- LOCALIZATION.doc Aleph 500 常用 X-Services 列表 .doc 文档中心

Thank you!Lei.zhou@exlibrisgroup.com