开放搜索服务 OpenSearch SDK 参考手册

Transcription

1 开放搜索服务 OpenSearch SDK 参考手册

2 SDK 参考手册 JavaSDK 手册 版本说明 前言 简介 提供 java 语言对 API 接口的封装 ( 应用管理 数据处理 搜索 错误日志等 ) 版本说明 当前版本 :V2.1.2 maven 地址 : <dependency> <groupid>com.aliyun.opensearch</groupid> <artifactid>aliyun-sdk-opensearch</artifactid> <version>2.1.2</version> </dependency> 历史版本 V2.1.1 新功能 : 在 search index doc 类中调用 client.call 方法之后可以调用此接口获得本次操作发送的请求串 ; 在 client 的构造函数中添加对请求超时时间 timeout 和连接超时时间 conn_timeout 的设置 ; sdk 发送的请求支持 gzip 方式 ; 实例化 client 时可以设置 sdk 支持的最大连接数 在 sdk 发送的请求的 user-agent 中加入 sdk 的类型和版本信息 ; Search 类的 config 子句支持 rerank_size 属性 ; 兼容性 : 在实例化 client 时通过设置 debug=true 输出调试信息的方式已失效,2.1.1 版本 SDK 中默认记录上次 请求串, 可以在 CloudsearchSearch CloudsearchIndex CloudsearchDoc 类中通过调用 getdebuginfo 来获取 原 config 子句中设置 starthit hit 和 format 三个属性的方法 setstarthit() sethits() setformat() 失 效,2.1.1 版本中通过设置 configmap 来设置 config 子句的属性 1

3 使用教程 使用教程 准备工作获取用户 AccessKeyId 和秘钥 (secret) 用户可以使用阿里云的账号登录本系统, 在登录完成后, 点击 ACCESSKEY 管理 可以查看您的 Access Key ID(AccessKeyId) 和 Access Key Secret(secret) 也可以在阿里云官网, 点击 用户中心 > 我的服务 > 安全验证 即可到 ACCESSKEY 管理中心 将 SDK 添加到项目中 使用 OpenSearch SDK 有两种方式 : 1. 下载 SDK 源码包, 在下载中心下载最新版的 JAVA SDK 到本地, 并 import 到您的工作目录中 2. 引入 OpenSearch SDK 依赖, 通过 maven 二方库依赖的方式将 opensearch 的 sdk 加入到自己的项目 中 <dependencies> <dependency> <groupid>com.aliyun.opensearch</groupid> <artifactid>aliyun-sdk-opensearch</artifactid> <version>2.1.2</version> </dependency> </dependencies> 创建应用 通过控制台也可以完成创建应用的操作, 这里介绍一下如何使用 SDK 实现 这里使用 import SDK 的方式, 使 用上面获取的 AccessKey 和 Secret 实例化一个 Opensearch Client( 下面的操作里将继续使用如下的 client), 然后 通过 CloudsearchIndex 类来创建一个应用 具体代码如下 : import com.opensearch.javasdk.*; String accesskey= " 您的阿里云的 Access Key ID"; String secret = " 阿里云 Access Key ID 对应的 Access Key Secret"; String appname = " 您要创建的应用名称 "; Map<String, Object> opts = new HashMap<String, Object>(); // 这里的 host 需要根据访问应用详情页中提供的的 API 入口来确定 opts.put("host", " CloudsearchClient client = new CloudsearchClient(accesskey, secret, opts, KeyTypeEnum.ALIYUN); CloudsearchIndex app = new CloudsearchIndex(appName, client); // 您可以根据自己的需求来选择相应的模板, 根据模板名称创建应用 ; 创建自定义结构时您需要在网站中先创建好应用结构并保存成模板, 然后再通过 SDK 使用模板名称进行创建 System.out.println(app.createByTemplateName("template_name")); 2

4 如果中 status 字段为 OK 表示应用创建成功, 否则表示创建失败, 同时会提供相应的错误码和错误信息 可以通过下面的方法查看当前应用的状态 System.out.println(app.status()); 上传文档 OpenSearch 的文档是一个 json 类型的字符串, 结构如下 : [ ] { fields :{...}, cmd :"..." }... 一条文档是由 fields 字段和 cmd 字段构成的一个结构体, 其中 fields 字段内包含文档的核心数据,cmd 表示针对 此条文档所做的操作, 对文档的操作包括添加 (add), 更新 (update) 和删除 (delete) 三种 一段文档示例如下 : [ { fields : { id : "0", summary : " 广大中小企业都有各种结构化的数据需要进行检索, 目前一般采用数据库本身提供的搜索功能或者利用 open source 的搜索软件搭建, 这样的做法不但会消耗网站本身的资源, 性能也会很容易成为问题, 而且相关性通常也不够好 我们的产品的目的是要利用阿里云先进的云计算和搜索技术向广大中小企业提供低成本, 高质量, 高性能, 可定制的数据搜索解决方案 本项目和云搜索的通用解决方案目标略有不同, 主要区别为本项目主要针对用户的结构化数据进行搜索, 云搜索的通用解决方案则主要是针对网页型数据为处理对象 " }, cmd : "ADD" }, { fields : { id : "1", summary : " 云搜索 ( Cloud Search Engine), 是运用云计算 ( Cloud Computing) 技术的搜索引擎, 可以绑定多个域名, 定义搜索范围和性质, 同时, 不同域名可以有不同 UI 和流程, 这个 UI 和流程由运行在云计算服务器上的个性化程序完成 作为新型搜索引擎, 与传统搜索引擎需要输入多个关键字不同的是, 用户可以告诉搜索引擎每个搜索关键字的比重, 每个搜索关键字都被置于 搜索云 中, 并用不同大小, 粗细的字型区分 " }, cmd : "ADD" } ] 将文档上传到应用的某个表中的代码如下 : CloudsearchDoc doc = new CloudsearchDoc(indexName, client); table_name = " 要上传数据的表名 "; data = "[{"cmd":"add", "fields":{"id":"0","summary":"blabla..."}}]"; System.out.println(doc.push(data, table_name)); 另外还可以通过 CloudsearchDoc 类的提供的 add update delete 三个接口生成待上传的数据, 最后在调用 3

5 push 方法将数据上传 ; 开始搜索 OpenSearch 通过设置可以实现高度个性化的搜索需求, 但通用的基本的搜索功能只需通过非常简单的设置即 可实现 : CloudsearchSearch search = new CloudsearchSearch(client); // 添加指定搜索的应用 : search.addindex(" 您的应用名称 "); // 指定搜索的关键词, 这里要指定在哪个索引上搜索, 如果不指定的话默认在使用 default 索引 ( 索引字段名称是您在您的数据结构中的 索引到 字段 ) search.setquerystring("' 词典 '"); search.setquerystring("default:' 词典 '"); search.setquerystring("index_name:' 词典 '"); // 指定搜索返回的格式 search.setformat("json"); // 设定过滤条件 search.addfilter("price>10"); // 设定排序方式 + 表示正序 - 表示降序 search.addsort("price", "+"); // 返回搜索结果 System.out.println(search.search()); 调试 通过上面的操作我们已经可以使用基本的搜索功能了, 但是优化搜索 提高搜索结果相关性是一个漫长的的过程, 需要我们不断试错和迭代来一点点改进 在这个过程中如果遇到问题或者发现结果与预期不一致时可以通过下面的接口获得请求的详细信息, 您可以通过这些信息排查问题 特别是当遇您到问题, 在旺旺群 QQ 群中寻求帮助的时候, 根据您提供的调试信息我们可以迅速帮您定位到问题所在 // 搜索类的调试信息调用接口 System.out.println(search.getDebugInfo()); // 文档类的调试信息调用接口 System.out.println(doc.getDebugInfo()); // 应用类的调试信息调用接口 System.out.println(index.getDebugInfo()); SDK 客户端 CloudsearchClient 类接口说明 构造函数 接口描述 CloudsearchClient 类是线程安全的 accesskey String 用户的 accesskey, 从网站中可以获得此信息 4

6 secret String 用户的 secret, 从网站中可以获得此信息 opts Map<String, Object> 一些可选信息, 包含 : keytype KeyTypeEnum 指定当前的用户类型, 取值范围为 :KeyTypeEnum.OPENSEARC H,KeyTypeEnum.ALIYUN 默认值为 KeyTypeEnum.OPENSEARCH, 使用阿里云账号的用户请设置此参数值为 KeyTypeEnum.ALIYUN opts: 一些可选信息, 包含 : 参数名称 version 当前使用的 API 版本, 默认值为 v2 host timeout connect_timeout 指定请求的 host 地址, 默认为 : 指定请求超时时间, 单位为 : 微秒 用户可以根据自己的场景来设定此值, 例如如果搜索可以设定时间稍短, 如果推送文档, 可以设定稍长的时间 单位为 : 微妙, 默认值为 指定连接超时时间, 单位为 : 微秒, 默认值为 5000 CloudsearchClient(String accesskey, String secret,map<string, Object> opts, KeyTypeEnum keytype) 指定连接池的最大连接数 maxconnections int 连接池的最大连接数 void setmaxconnections(int maxconnections) 搜索操作 CloudsearchSearch 类接口说明 5

7 构造函数 接口描述 CloudsearchSearch 类是非线程安全的 建议每次请求完毕后需要调用 clear() 接口清空上次请求的设置或者重新实例化一个 CloudsearchSearch 对象 client CloudsearchClient 此对象由 CloudsearchClient 类实例化 CloudsearchSearch(CloudsearchClient client) 执行搜索请求 (1) 接口描述参见 :API 配置 config 子句 opts Map<String, Object> 此参数如果被赋值, 则会把此参数的内容分别赋给相应的变量 此参数的值可能有以下内容 : opts: 此参数如果被赋值, 则会把此参数的内容分别赋给相应的变量 此参数的值可能有以下内容 : 参数名称 query indexes fetch_fields format formula_name first_formula_name summary start hits 指定的搜索查询串, 可以为 query=>' 鲜花 ', 也可以为 query=>" 索引名 :' 鲜花 '" 指定的搜索应用, 可以为一个索引, 也可以多个索引查询 设定只返回某些字段的值 指定返回的数据格式, 有 json,xml 和 protobuf 三种格式可选 指定的精排表达式名称, 此名称需在网站中设定 指定的粗排表达式名称, 此名称需在网站中指定 指定 summary 字段一些标红 省略 截断等规则 指定搜索结果集的偏移量 取值范围 :[0,5000], 默认值 :0 指定集的数量 取值范围 :[0,500], 默认 6

8 值 :20 sort 指定排序规则 默认值 : - ( 降序 ) filter aggregate distinct kvpair 指定通过某些条件过滤结果集 指定统计类的信息 指定 distinct 排序 指定的 kvpair 内容 String 返回搜索结果 异常描述 IOException ClientProtocolException String search(map<string, Object> opts)throws ClientProtocolException, IOException, UnknownHostException 执行搜索请求 (2) String 返回搜索结果 异常描述 IOException ClientProtocolException String search() throws ClientProtocolException, IOException 添加一个应用列表来进行搜索 indexes List<String> 应用名称或应用名称列表 7

9 void addindex(list<string> indexes) 添加一个应用来进行搜索 indexname String 要搜索的应用名称 void addindex(string indexname) 在当前搜索中去掉一个应用的搜索结果 indexname String void removeindex(string indexname) 获取当前请求中所有的应用名列表 List<String> 返回当前搜索的所有应用列表 List<String> getsearchindexes() 设置精排表达式名称 接口描述此表达式名称和结构需要在网站中已经设定, 详情请浏览官网中的应用指定的表达式名称 formulaname String 表达式名称 void setformulaname(string formulaname) 8

10 获取当前设置的表达式名称 String 返回当前设定的表达式名称 String getformulaname() 设置粗排表达式名称 接口描述此表达式名称和结构需要在网站中已经设定, 详情请浏览官网中的应用指定的表达式名称 formulaname String 表达式名称 void setfirstformulaname(string formulaname) 获取当前设置的粗排表达式名称 String 返回当前设定的表达式名称 String getfirstformulaname() 添加一条动态摘要信息 (1) 接口描述增加了此内容后,fieldName 字段可能会被截断 飘红等 fieldname len element ellipsis String Integer String String 指定的生效的字段 此字段必需为可分词的 text 类型的字段 指定结果集返回的词字段的字节长度, 一个汉字为 2 个字节 指定命中的 query 的标红标签, 可以为 em 等 指定用什么符号来标注未展示完的数据, 例如... snippet Integer 指定 query 命中几段 9

11 summary 内容 boolean 返回是否添加成功 boolean addsummary(string fieldname, Integer len, String element,string ellipsis, Integer snippet) 添加一条动态摘要信息 (2) 接口描述增加了此内容后,fieldName 字段可能会被截断 飘红等 fieldname String 指定的生效的字段 此字段必需为可分词的 text 类型的字段 boolean 返回是否添加成功 boolean addsummary(string fieldname) 添加一条动态摘要信息 (3) 接口描述增加了此内容后,fieldName 字段可能会被截断 飘红等 fieldname len ellipsis snippet String Integer String Integer 指定的生效的字段 此字段必需为可分词的 text 类型的字段 指定结果集返回的词字段的字节长度, 一个汉字为 2 个字节 指定用什么符号来标注未展示完的数据, 例如... 指定 query 命中几段 summary 内容 elementprefix String 指定标签前缀 elementpostfix String 指定标签后缀 10

12 boolean 返回是否添加成功 boolean addsummary(string fieldname, Integer len, String ellipsis,integer snippet, String elementprefix, String elem entpostfix) 获取当前所有设定的摘要信息 Map<String, Map<String, Object>> 返回 summary 信息 Map<String, Map<String, Object>> getsummary() 获取指定字段的摘要信息 fieldname String 指定的字段名称 Map<String,Object> 返回指定字段的 summary 信息 Map<String, Object> getsummary(string fieldname) 把摘要信息生成字符串并返回 String 返回字符串的 summary 信息 String getsummarystring() 设置返回的数据格式名称 format String 数据格式名称, 有 xml, json 和 protobuf 三种类型 默认值为 : xml 11

13 void setformat(string format) 获取当前的数据格式名称 String 返回当前的数据格式名称 String getformat() 设置的偏移量 start int 偏移量 取值范围为 [0,5000], 默认值为 :0 void setstarthit(int start) 获取的偏移量 int 返回当前设定的偏移量 int getstarthit() 设置当前集的文档个数 hits int 指定的 doc 个数 默认值为 :20, 取值范围 :[0,500] void sethits(int hits) 获取当前设定的结果集的文档条数 12

14 int 返回当前指定的 doc 个数 int gethits() 增加一个排序字段及排序方式 接口描述详细描述请见 API 排序 sort 子句 field String 需要排序的字段名称 sortchar String 排序方式, 有升序 + 和降序 - 两种方式 默认值为 - void addsort(string field, String sortchar) 增加一个排序字段 接口描述详细描述请见 API 排序 sort 子句 field String 指定排序的字段名称 void addsort(string field) 删除指定字段的排序 field String 指定的字段名称 void removesort(string field) 获取排序信息 13

15 返回当前所有的排序字段及升降序方式 Map<String, String> getsort() 获取字符串类型的排序信息 接口描述把排序信息生成字符串并返回 String 返回字符串类型的排序规则 String getsortstring() 增加一个自定义参数 paramkey String 参数名称 paramvalue String 参数值 void addcustomparam(string paramkey, String paramvalue) 获取自定义参数 返回自定义参数 Map<String, String> getcustomparam() 增加过滤规则 (1) 接口描述详细请见 API 过滤 filter 子句 filter String 过滤规则, 例如 fieldname >= 1 14

16 operator String 操作符, 可以为 AND OR 默认为 AND void addfilter(string filter, String operator) 增加过滤规则 (2) 接口描述详细请见 API 过滤 filter 子句 filter String 过滤规则 void addfilter(string filter) 获取过滤规则 String 返回字符串类型的过滤规则 String getfilter() 添加统计信息相关参数 (1) 接口描述一个关键词通常能命中数以万计的文档, 用户不太可能浏览所有文档来获取信息 而用户感兴趣的可能是一些统计类的信息, 比如, 查询 手机 这个关键词, 想知道每个卖家所有商品中的最高价格 则可以按照卖家的 user_id 分组, 统计每个小组中最大的 price 值, 例如 : groupkey:user_id,aggfun:max(price) 详细说明请参见 :APi aggregate 子句说明 groupkey String 指定需要统计的字段名称 aggfun String 指定统计的方法 当前支持 :count max min sum 等 range String 指定统计范围 15

17 maxgroup String 最大组个数 aggfilter String 指定过滤某些统计 aggsamplerthreshold String 指定抽样的伐值 aggsamplerstep String 指定抽样的步长 boolean 返回添加成功或失败 boolean addaggregate(string groupkey, String aggfun, String range,string maxgroup, String aggfilter, String aggs amplerthreshold,string aggsamplerstep) 添加统计信息相关参数 (2) groupkey String 指定需要统计的字段名称 aggfun String 指定统计的方法 当前支持 :count max min sum 等 boolean 返回添加成功或失败 boolean addaggregate(string groupkey, String aggfun) 获取用户设定的统计相关信息 List<Map<String, Object>> 返回用户设定的统计信息 List<Map<String, Object>> getaggregate() 返回字符串类型的统计信息 String 返回字符串类型的统计信息 16

18 String getaggregatestring() 添加一条排序信息 (1) 接口描述例如 : 检索关键词 手机 共获得 10 个结果, 分别为 :doc1,doc2,doc3,doc4,doc5,doc6, doc7,doc8,doc9,doc10 其中前三个属于用户 A,doc4-doc6 属于用户 B, 剩余四个属于用户 C 如果前端每页仅展示 5 个商品, 则用户 C 将没有展示的机会 但是如果按照 user_id 进行抽取, 每轮抽取 1 个, 抽取 2 次, 并保留抽取剩余的结果, 则可以获得以下文档排列顺序 :doc1 doc4 doc7 doc2 doc5 doc8 doc3 doc6 doc9 doc10 可以看出, 通过 distinct 排序, 各个用户的商品都得到了展示机会, 结果排序更趋于合理 详细说明请见 :API distinct 子句 key distcount String int 为用户用于做 distinct 抽取的字段, 该字段要求为可过滤字段 为一次抽取的 document 数量, 默认值为 1 disttimes int 为抽取的次数, 默认值为 1 reserved distfilter updatetotalhit String String String 为是否保留抽取之后剩余的结果,true 为保留,false 则丢弃, 丢弃时 totalhits 的个数会减去被 distinct 而丢弃的个数, 但这个结果不一定准确, 默认为 true 为过滤条件, 被过滤的 doc 不参与 distinct, 只在后面的排序中, 这些被过滤的 doc 将和被 distinct 出来的第一组 doc 一起参与排序 默认是全部参与 distinct 当 reserved 为 false 时, 设置 update_total_hit 为 true, 则最终 total_hit 会减去被 distinct 丢弃的的数目 ( 不一定准确 ), 为 false 则不减 ; 默认为 false grade double 指定档位划分阈值 返回是否添加成功 17

19 boolean adddistinct(string key, int distcount, int disttimes,string reserved, String distfilter, String updatetotalhit,d ouble grade) 添加一条排序信息 (2) key String 为用户用于做 distinct 抽取的字段, 该字段要求为可过滤字段 返回是否添加成功 boolean adddistinct(string key) 添加一条排序信息 (3) key distcount String int 为用户用于做 distinct 抽取的字段, 该字段要求为可过滤字段 为一次抽取的 document 数量, 默认值为 1 返回是否添加成功 boolean adddistinct(string key, int distcount) 添加一条排序信息 (4) key distcount String int 为用户用于做 distinct 抽取的字段, 该字段要求为可过滤字段 为一次抽取的 document 数量, 默认值为 1 disttimes int 为抽取的次数, 默认值为 1 18

20 返回是否添加成功 boolean adddistinct(string key, int distcount, int disttimes) 添加一条排序信息 (5) key distcount String int 为用户用于做 distinct 抽取的字段, 该字段要求为可过滤字段 为一次抽取的 document 数量, 默认值为 1 disttimes int 为抽取的次数, 默认值为 1 reserved String 为是否保留抽取之后剩余的结果,true 为保留,false 则丢弃, 丢弃时 totalhits 的个数会减去被 distinct 而丢弃的个数, 但这个结果不一定准确, 默认为 true 返回是否添加成功 boolean adddistinct(string key, int distcount, int disttimes,string reserved) 添加一条排序信息 (6) key distcount String int 为用户用于做 distinct 抽取的字段, 该字段要求为可过滤字段 为一次抽取的 document 数量, 默认值为 1 disttimes int 为抽取的次数, 默认值为 1 reserved String 为是否保留抽取之后剩余的结果,true 为保留,false 则丢弃, 丢弃时 totalhits 的个数会减去被 distinct 而丢弃的个数, 但这个结果不一定准确, 默认为 true 19

21 distfilter String 为过滤条件, 被过滤的 doc 不参与 distinct, 只在后面的排序中, 这些被过滤的 doc 将和被 distinct 出来的第一组 doc 一起参与排序 默认是全部参与 distinct 返回是否添加成功 boolean adddistinct(string key, int distcount, int disttimes,string reserved, String distfilter) 添加一条排序信息 (7) key distcount String int 为用户用于做 distinct 抽取的字段, 该字段要求为可过滤字段 为一次抽取的 document 数量, 默认值为 1 disttimes int 为抽取的次数, 默认值为 1 reserved distfilter updatetotalhit String String String 为是否保留抽取之后剩余的结果,true 为保留,false 则丢弃, 丢弃时 totalhits 的个数会减去被 distinct 而丢弃的个数, 但这个结果不一定准确, 默认为 true 为过滤条件, 被过滤的 doc 不参与 distinct, 只在后面的排序中, 这些被过滤的 doc 将和被 distinct 出来的第一组 doc 一起参与排序 默认是全部参与 distinct 当 reserved 为 false 时, 设置 update_total_hit 为 true, 则最终 total_hit 会减去被 distinct 丢弃的的数目 ( 不一定准确 ), 为 false 则不减 ; 默认为 false 返回是否添加成功 boolean adddistinct(string key, int distcount, int disttimes,string reserved, String distfilter, String updatetotalhit) 20

22 删除某个字段的所有 distinct 排序信息 distinctkey String 要删除的 dist key 字段名称 void removedistinct(string distinctkey) 获取某所有的 distinct 排序信息 返回所有的 distinct 信息 Map<String, Map<String, Object>> getdistinct() 获取 类型的所有的 distinct 信息 返回字符串类型的 distinct 信息 String getdistinctstring() 设定指定索引字段范围的搜索关键词 接口描述此 query 是查询必需的一部分, 可以指定不同的索引名, 并同时可指定多个查询及之间的关系 (AND, OR, ANDNOT, RANK) 例如查询 subject 索引字段的 query: 手机, 可以设置为 query=subject:' 手机 ' 上边例子如果查询 price 在 之间的手机, 其查询语句为 : query=subject:' 手机 ' AND price:[1000,2000] NOTE: text 类型索引在建立时做了分词, 而 类型的索引则没有分词 详细说明请见 :API query 子句 query String 设定搜索的查询语法 21

23 void setquerystring(string query) 获取当前指定的查询词内容 返回当前设定的查询 query 子句内容 String getquery() 设定当前的 kvpair 接口描述详细请见 API 自定义 kvpair 子句 pair String kvpair 内容 void setpair(string pair) 获取当前的 kvpair String 返回当前设定的 kvpair String getpair() 设定 rerank_size rerank_size int 精排算分文档个数, 默认值 200 void setreranksize(int rerank_size) 获取当前 rerank_size 22

24 接口描述 reranksize 表示参与精排算分的文档个数, 一般不用修改, 使用默认值就能满足, 不用设置, 会自动使 用默认值 200 int 当前设定的 rerank_size int getreranksize() 设置搜索返回的索引字段列表 fields List<String> 结果集返回的字段 void addfetchfields(list<string> fields) 添加某个字段到搜索结果字段列表中 field String 指定的字段名称 void addfetchfield(string field) 获取搜索结果包含的字段列表 返回指定返回字段的列表 List<String> getfetchfields() 清空用户设置的所有搜索条件 void clear() 添加一条自定义配置 23

25 key String 自定义配置项 key value Object 自定义配置项 value void addcustomconfig(string key, Object value) 移除自定义配置 key String 指定配置项的 key void removecustomconfig(string key) 获取上次搜索请求的信息 String 上次搜索请求的信息 String getdebuginfo() 搜索示例 import com.opensearch.javasdk.*; String accesskey= " 您的阿里云的 Access Key ID"; String secret = " 阿里云 Access Key ID 对应的 Access Key Secret"; Map<String, Object> opts = new HashMap<String, Object>(); // 这里的 host 需要根据访问应用基本详情中的 API 入口来确定 opts.put("host", " CloudsearchClient client = new CloudsearchClient(accesskey, secret, opts, KeyTypeEnum.ALIYUN); CloudsearchSearch search = new CloudsearchSearch(client); // 添加指定搜索的应用 : search.addindex("my_demo"); // 指定搜索的关键词, 如果没有输入索引名称, 则使用 default search.setquerystring("' 词典 '"); 24

26 // 和下边等同 search.setquerystring("default:' 词典 '"); // 或者指定某索引字段进行查找 // 索引字段名称是您在您的数据结构中的 索引到 字段 search.setquerystring("index_name:' 词典 '"); // 指定搜索返回的格式 search.setformat("json"); // 设定过滤条件 字段必须设定为可过滤 search.addfilter("price>10"); // 设定排序方式 字段必须设定为可过滤 search.addsort("price", "+"); // 返回搜索结果 System.out.println(search.search()); 文档操作 CloudsearchDoc 类接口说明 构造函数 接口描述 CloudsearchDoc 类是非线程安全的, 请每次调用时单独实例化一个实例使用 indexname String 指定操作的索引名称 client CloudsearchClient CloudsearchClient 实例 CloudsearchDoc(String indexname, CloudsearchClient client) 查看文档详情 接口描述根据 doc id 获取 doc 的详细信息 docid String 指定的 doc id 返回 API 返回的结果 25

27 异常描述 IOException ClientProtocolException String detail(string docid) throws ClientProtocolException, IOException 添加文档 接口描述设置需要添加的属性名称和属性值, 用于生成符合文档格式的数据, 所有更新结束之后需要调用 push(string tablename) 方法 fields Map<String, Object> 字段名和字段值的 map 异常描述 JSONException void add(map<string, Object> fields) throws JSONException 更新文档 接口描述设置需要更新的属性名称和属性值, 用于生成符合文档格式的数据, 所有更新结束之后需要调用 push(string tablename) 方法 fields Map<String, Object> 字段名和字段值的 map 异常描述 JSONException void update(map<string, Object> fields) throws JSONException 删除文档 26

28 接口描述设置需要删除的属性名称和属性值, 用于生成符合文档格式的数据, 所有更新结束之后需要调用 push(string tablename) 方法 fields Map<String, Object> 字段名和字段值的 map 异常描述 JSONException void remove(map<string, Object> fields) throws JSONException 执行文档变更操作 (1) 接口描述针对文档的操作 add update 和 remove 会生成符合文档格式的数据, 通过调用此接口用户提交的文 档变更才会真正生效 tablename String 表名称 返回的数据 异常描述 IOException ClientProtocolException String push(string tablename) throws ClientProtocolException, IOException 执行文档变更操作 (2) 接口描述通过此接口可以直接将符合文档格式的数据直接推送到指定的表中 docs String 此 docs 为用户 push 的数据, 此 27

29 字段为 json 类型的字符串 tablename String 操作的表名 请求 API 并返回相应的结果 异常描述 IOException ClientProtocolException String push(string docs, String tablename) throws ClientProtocolException, IOException 通过文件导入数据 (1) 接口描述导入 HA3 doc 数据到指定的应用的指定表中文件编码 :UTF-8 支持 CMD: add, delete, update 如果给出的字段不是全部,add 会在未给出的字段加默认值, 覆盖原值 ;update 只会更新给出的字段, 未给出的不变 文件分隔符 : <pre> 编码 描述 显示形态 "\x1e\n" 每个 doc 的分隔符. ^^( 接换行符 ) "\x1f\n" 每个字段 key 和 value 分隔. ^_( 接换行符 ) "\x1d" 多值字段的分隔符. ^] </pre> 示例 : <pre> CMD=add^_ url= title= 开放搜索 ^_ body=xxxxxxxxx^ 28

30 multivalue_feild=123^]1234^]12345^ ^^ CMD=update^_... </pre> NOTE: 文件结尾的分隔符也必需为 "^^\n", 最后一个换行符不能省略 filepath String 指定的文件路径 tablename String 指定 push 数据的表名 返回成功或者错误信息 异常描述 JSONException String pushhadocfile(string filepath, String tablename) throws JSONException 通过文件导入数据 (2) 接口描述导入 HA3 doc 数据到指定的应用的指定表中 filepath String 指定的文件路径 tablename String 指定 push 数据的表名 offset long 文档数据的偏移量, 小于设定的 offset 行号的文档将被跳过 返回成功或者错误信息 异常描述 JSONException 29

31 String pushhadocfile(string filepath, String tablename, long offset) throws JSONException 获取上次请求的信息 String String getdebuginfo() 文档操作 应用结构 首先我们回顾一下我们之前创建的应用的结构 : 1 id 名称 含义 标示一个主键 id, 在应用中唯一的字段,primary_key 2 type_id 类型的 id 3 cat_id 分类 id, 类似于,1 标示体育,2 科技,3 军事等等 4 title 资讯的标题 5 body 资讯的内容 6 url 资讯的 url 连接 7 author 作者 8 thumbnail 缩略图 9 source 来源 10 create_timestamp 资讯的创建时间 11 update_timestamp 资讯的最后修改时间 12 hit_num 点击次数 13 focus_count 关注次数 14 grade 等级 15 comment_count 评论数 16 tag 标签 文档概念 30

32 OpenSearch 的文档是一个 json 类型的字符串, 结构如下 : [ ] { fields:{...}, cmd:"..." }... 一条文档是由 fields 字段和 cmd 字段构成的一个结构体, 其中 fields 字段内包含文档的核心数据,cmd 表示针对 此条文档所做的操作, 对文档的操作包括添加 (add), 更新 (update) 和删除 (delete) 三种 我们创建的 news 应 用的一条文档示例如下 : [ { "fields": { "id": "0", "type_id": 34, "cat_id": 10, "title": " 阿里云开放搜索助力企业搜索应用 ", "body": " 广大中小企业都有各种结构化的数据需要进行检索, 目前一般采用数据库本身提供的搜索功能或者利用 open source 的搜索软件搭建, 这样的做法不但会消耗网站本身的资源, 性能也会很容易成为问题, 而且相关性通常也不够好 我们的产品的目的是要利用阿里云先进的云计算和搜索技术向广大中小企业提供低成本, 高质量, 高性能, 可定制的数据搜索解决方案 本项目和云搜索的通用解决方案目标略有不同, 主要区别为本项目主要针对用户的结构化数据进行搜索, 云搜索的通用解决方案则主要是针对网页型数据为处理对象 ", "url": " "author": " 阿里云 ", "thumbnail": " "source": " 新浪科技 ", "create_timestamp": , "update_timestamp": , "hit_num": 700, "focus_count": 31, "grade": 96, "comment_count": 68, "tag": " 搜索 " }, "cmd": "ADD" }, ] 文档操作 在建立好应用之后, 我们需要把自己应用的数据上传到应用中, 并且在运营的过程中对文档的内容进行维护 这里涉及到的文档相关的操作包括以下四种 : 添加文档 查看文档 更新文档和删除文档 添加文档将文档添加到 OpenSearch 应用的表中对应的操作 cmd 是 ADD, 在 Java SDK 中可以使用 add 接口完成文档添加操作 : 例如上面的 fields 字段的内容是从数据库中读取的, 存放在一个 Map<String,Object> 类型的数据结构里, 可以直接使用 add 接口生成符合文档格式的 json 字符串, 再调用 push 接口完成上传 ; client.add(fields); client.push("main");//main 是上传到的表名 31

33 如果已经生成了符合文档格式的 json_ 可以直接调用 push 接口实现上传 : client.push(json_,"main"); 查看文档将文档上传至应用后可以通过文档 id 使用 detail 接口查看文档内容 : doc.detail("1"); 更新文档更新文档时文档中 cmd 字段对应的值为 update, 并且在 fields 字段中要提供待更新的文档的 id, 然后 调用 push 接口使其生效 : doc.update(fields); doc.push("main");//main 为待更新的文档所在的表名 删除文档删除文档时文档中的 cmd 字段对应的值为 delete, 需要提供待删除的文档的 id, 然后调用 push 接口 doc.remove("1"); doc.push("main");//main 为待删除文档所在的表名 使用文件来上传文档除了上面的方法还可以通过文件量, 小于设定的 offset 行号的 doc 将被跳过导入 HA3 doc 数据到指定的应用的指定表中文件编码 :UTF-8 支持 CMD: add, delete, update 如果给出的字段不是全部,add 会在未给出的字段加默认值, 覆盖原值 ;update 只会更新给出的字段, 未给出的不变 文件分隔符 : <pre> 编码 描述 显示形态 "\x1e\n" 每个 doc 的分隔符. ^^( 接换行符 ) "\x1f\n" 每个字段 key 和 value 分隔. ^_( 接换行符 ) "\x1d" 多值字段的分隔符. ^] </pre> 示例 : <pre> CMD=add^_ url= title= 开放搜索 ^_ body=xxxxxxxxx^ multivalue_feild=123^]1234^]12345^ 32

34 ^^ CMD=update^_... </pre> 注意 : 文件结尾的分隔符也必需为 "^^\n", 最后一个换行符不能省略 doc.pushhadocfile(file_path,table_name); 使用 HA 类型文件推送文档时还可以指定从文件中的某个位置开始推送, 对应的接口为 : doc.pushhadocfile(file_path,talbe_name,offset); 其中 :offset 文档数据的偏移量, 小于设定的 offset 行号的 doc 将被跳过 调试接口 CloudsearchDoc 类内置了一个调试接口, 通过调用调试接口可以获得操作发出的请求内容, 当我们 操作文档时发现与预期不符时可以通过此接口查看请求细节 debuginfo = doc.getdebuginfo(); 应用操作 CloudsearchIndex 类接口说明 构造函数 接口描述 CloudsearchIndex 类是非线程安全的, 请每次使用时单独实例化一个实例使用 indexname String 索引的名称 client CloudsearchClient 提交请求的 client CloudsearchIndex(String indexname, CloudsearchClient client) 根据模板名称创建应用 (1) templatename String 模板名称 opts Map<String, String> 包含应用的备注信息, 具体包括 :index_des- 应用的描述信息 33

35 ,package_id- 该应用选择的套餐 返回 api 返回的正确或错误的结果 异常描述 IOException ClientProtocolException String createbytemplatename(string templatename,map<string, String> opts) throws ClientProtocolException,IOE xception 根据模板名称创建应用 (2) templatename String 模板名称 返回 api 返回的正确或错误的结果 异常描述 IOException ClientProtocolException String createbytemplatename(string templatename) throws ClientProtocolException, IOException 更新应用的名称和备注信息 toindexname String 应用名称 opts Map<String, String> 相关参数 34

36 返回 api 返回的正确或错误的结果 异常描述 JSONException IOException ClientProtocolException String rename(string toindexname, Map<String, String> opts)throws JSONException, ClientProtocolException,IOEx ception 删除当前的应用 返回 API 返回的正确或错误的结果 异常描述 IOException ClientProtocolException String delete() throws ClientProtocolException, IOException 查看当前应用的状态 返回 API 返回的正确或错误的结果 异常描述 IOException ClientProtocolException 35

37 String status() throws ClientProtocolException, IOException 列出所有应用 page Integer 开始的页码 pagesize Integer 获取的记录数 返回 API 返回的正确或错误的结果 异常描述 IOException ClientProtocolException String listindexes(integer page, Integer pagesize) throws ClientProtocolException, IOException 获取当前应用的名称 应用名称 String getindexname() 获取错误信息 page int 开始页数 pagesize int 每页的记录数 36

38 异常描述 API 返回的错误信息 IOException ClientProtocolException String geterrormessage(int page, int pagesize) throws ClientProtocolException, IOException 获取上次请求的信息 String String getdebuginfo() 应用操作示例 通过 OpenSearch 控制台也可以完成应用创建 查看 修改等操作, 在 SDK 中也提供了部分操作应用的接口 下面带大家逐一看一下各个接口的使用方式 首先我们实例化一个应用类, 很简单 CloudsearchIndex app = new CloudsearchIndex("sdk_user_demo",client); 其中 client 的实例化可以在 CloudsearchClient 类的示例中查看, 这里不再重复 使用模板创建应用 OpenSearch 内置了多个应用模板 ( 当前包括 : 资讯类 小说类 应用类 社区类 文档类和电商类 ), 如果希望 使用内置模板, 则可以通过下面方式创建一个应用, 这里我们使用系统内置的资讯类应用模板 (builtin_news) 来 创建一个应用 String ret = app.createbytemplatename("builtin_news"); 您可以在控制台创建自定义结构的应用, 然后保存为应用模板, 然后也可以这种方式来创建应用 操作成功时 返回 {"result":{"index_name":" 您要创建的应用名称 "},"status":"ok","requestid":""} 创建失败时 ( 可能有多种原因 ) 返回的示例如下 : {"status":"fail","errors":[{"code":2002,"message":"app already exists"}],"requestid":""} 修改应用名称 37

39 很简单 : String ret = app.rename(" 要修改成的应用名称 "); System.out.println(ret); 这个接口还支持修改应用的描述信息, 参见接口的参数说明 删除应用 String ret = app.delete(); System.out.println(ret); 获取应用名称 System.out.println(app.getIndexName()); 查看应用详情 System.out.println(app.status()); 获取应用列表 获取您的所有的应用列表信息, 该接口可以指定页码或者每页的条数 // 获取所有的应用信息, 取第一页的数据, 每页取 10 条 System.out.println(app.listIndexes(1, 10)); 获取错误信息 错误信息一般情况下在您请求每个接口时实时返回, 但是 push 数据时如果数据已经到了后端发现错误, 则此时 这些接口已经拿不到这个数据的错误信息了 这个时候您可以 : 1 通过网站查看某个应用的 push 错误信息 2 通过 sdk 中 geterrormessage() 来获取错误信息的方式来获取某个应用在 push 的过程中出现了哪 些错误信息 // 列出当前应用的所有错误信息 System.out.println(app.getErrorMessage()); // 或者分页获取, 例如列出第一页 每页 10 条 : System.out.println(app.getErrorMessage(1, 10)); 获取调试信息 CloudsearchIndex 类内置了一个调试接口, 通过调用调试接口可以获得操作发出的请求内容, 当我们操作文档 时发现与预期不符时可以通过此接口查看请求细节 debuginfo = app.getdebuginfo(); 38

40 相关下载 相关下载 最新稳定版 v2.1.2( ) java-sdk-v2.1.2.jar maven 地址 <dependency> <groupid>com.aliyun.opensearch</groupid> <artifactid>aliyun-sdk-opensearch</artifactid> <version>2.1.2</version> </dependency> PhpSDK 手册 版本说明 前言 简介 提供 PHP 语言对 OpenSearch API 接口的封装, 实现开放搜索服务相关的应用管理 数据处理 搜索等功能 版本说明 当前版本为 2.0.4, 相对于上一版本 (2.0.3), 本次升级涉及的功能变更如下 : 修改 bug client 中取消设置默认时区, 使用 gmdate 代替原有 date 获取 gmt 时间 调试接口 client 提供类中 getrequest() 方法获取上次操作的请求信息 client 参数 添加对 API 请求超时时间和 client 连接超时时间的设置 User-Agent 在 sdk 发出的请求的 useragent 中添加 sdk 的类型和版本信息 Search 属性 39

41 添加对 config 子句的 rerank_size 属性的支持 历史版本 在 版本 SDK 中使用直接在控制台输出调试信息的方式进行调试,2.0.4 版本中改用 getrequest() 接口获取 其他接口对上一版本完全兼容 使用教程 快速开始 使用 opensearch 提供搜索功能十分简单, 下面给带大家迅速上手 准备工作 获取 AccessKey 和 Secret 登录 点击 ACCESSKEY 管理查看是否已经创建了阿里云 access key id 和 access key secret 如果没有创建, 则点击创建一套 id 和 secret 下载 php SDK 并添加到项目中 在左侧栏相关下载中下载 php SDK 包 (Github 镜像即将推出 ) 并将 SDK 添加到项目中 <?php require_once("php_v2.0.4/cloudsearchclient.php"); require_once("php_v2.0.4/cloudsearchindex.php"); require_once("php_v2.0.4/cloudsearchdoc.php"); require_once("php_v2.0.4/cloudsearchsearch.php"); 创建应用 我们先实例化一个 SDK 客户端 client, 在下面的操作中我们都会使用到它 $access_key = " 替换成自己的 accesskey"; $secret = " 替换成自己的 Secret"; // 杭州公网 API 地址 : // 北京公网 API 地址 : $host = " 根据自己的应用区域选择 API $key_type = "aliyun"; // 固定值, 不必修改 $opts = array('host'=>$host); $client = new CloudsearchClient($access_key,$secret,$opts,$key_type); 下面我们通过系统内置的小说类型的模板创建一个应用 // 指定即将创建的应用名称 $app_name = "sdk_user_demo"; $index = new CloudsearchIndex($app_name,$client); $result = $index->createbytemplatename("builtin_novel"); echo $result; 40

42 通过上面的代码, 我们使用系统内置的小说类型的模板完成了一个应用的创建 上传文档 在上面代码的基础上我们继续使用 CloudsearchDoc 类向刚创建的应用中上传一些文档, 应用名称继续使用上 面的 $app_name OpenSearch 应用中的文档是一个 json 类型的字符串, 结构如下 : [... ] { } "fields":{}, "cmd":"" cmd 字段可选的值为 :ADD DELETE UPDATE, 分别表示添加 删除以及更新一条文档 ;fields 字段内包含 文档本身的字段属性, 比如在一个小说应用的结构中可能包含以下字段 :title: 小说的名字,body: 小说主体内 容,url: 访问小说的地址等 $doc_obj = new CloudsearchDoc($app_name,$client); $docs_to_upload = array(); for ($i = 0; $i < 10; $i++){ $item = array(); // 指定文档操作类型为 : 添加 $item['cmd'] = 'ADD'; // 添加文档内容 $item["fields"] = array("id" => $i + 1, "title" => " 我是一条新文档的标题 ", "body" => " 我是一条新文档的 body", "url" => " "create_timestamp" => time()); $docs_to_upload[] = $item; } // 生成 json 格式字符串 $json = json_encode($docs_to_upload); // 将文档推送到 main 表中 echo $doc_obj->add($json,"main"); 以上我们向 sdk_user_demo 应用中上传了 10 条文档 开始搜索 下面我们继续使用 CloudsearchSearch 类搜索一下刚才上传的数据 // 实例化一个搜索类 $search_obj = new CloudsearchSearch($client); // 指定一个应用用于搜索 $search_obj->addindex($app_name); // 指定搜索关键词 $search_obj->setquerystring("default: 标题 "); // 指定返回的搜索结果的格式为 json $search_obj->setformat("json"); // 执行搜索, 获取搜索结果 41

43 $json = $search_obj->search(); // 将 json 类型字符串解码 $result = json_decode($json,true); print_r($result);?> 这样我们就完成了一个简单的搜索功能了! 完整示例代码 大家可以直接复制下面代码, 将其中的 access key 和 secret 替换成自己的, 下载 SDK 代码, 并解压到下面代码 文件的同级目录中就可以体验一下 OpenSearch 了 <?php require_once("php_v2.0.4/cloudsearchclient.php"); require_once("php_v2.0.4/cloudsearchindex.php"); require_once("php_v2.0.4/cloudsearchdoc.php"); require_once("php_v2.0.4/cloudsearchsearch.php"); $access_key = " 替换成自己的 accesskey"; $secret = " 替换成自己的 Secret"; // 杭州公网 API 地址 : // 北京公网 API 地址 : (2015 年 4 月初开放 ) $host = " $key_type = "aliyun"; // 固定值, 不必修改 $opts = array('host'=>$host); // 实例化一个 client 使用自己的 accesskey 和 Secret 替换相关变量 $client = new CloudsearchClient($access_key,$secret,$opts,$key_type); $app_name = "sdk_user_demo"; // 实例化一个应用类 index_obj $index_obj = new CloudsearchIndex($app_name,$client); $result = $index_obj->createbytemplatename("builtin_novel"); // 实例化一个文档类 doc_obj 指定应用名称 $doc_obj = new CloudsearchDoc($app_name,$client); $docs_to_upload = array(); for ($i = 0; $i < 10; $i++){ $item = array(); $item['cmd'] = 'ADD'; $item["fields"] = array("id" => $i + 1, "title" => " 我是一条新文档的标题 ", "body" => " 我是一条新文档的 body", "url" => " "create_timestamp" => time()); $docs_to_upload[] = $item; } $json = json_encode($docs_to_upload); // echo $doc_obj->add($json,"main"); // 实例化一个搜索类 search_obj 42

44 $search_obj = new CloudsearchSearch($client); // 指定一个应用用于搜索 $search_obj->addindex($app_name); // 指定搜索关键词 $search_obj->setquerystring("default: 标题 "); // 指定返回的搜索结果的格式为 json $search_obj->setformat("json"); // 执行搜索, 获取搜索结果 $json = $search_obj->search(); // 将 json 类型字符串解码 $result = json_decode($json,true); print_r($result); 调试 通过上面的操作我们已经可以使用基本的搜索功能了, 但是优化搜索 提高搜索结果相关性是一个漫长的的过程, 需要我们不断试错和迭代来一点点改进 在这个过程中如果遇到问题或者发现结果与预期不一致时可以通过下面的接口获得请求的详细信息, 可以通过这些信息排查问题 特别是当遇您到问题, 在旺旺群 QQ 群中寻求帮助的时候, 根据调试信息我们可以迅速帮您定位到问题所在 $client->getrequest(); SDK 客户端 CloudsearchClient 构造函数 与服务器交互的客户端, 支持单例方式调用 请求参数 key secret 用户的 key, 从阿里云网站中获取的 Access Key ID 用户的 secret, 对应的 Access Key Secret opts array 包含下面一些可选信息 key_type key 和 secret 类型, 在这里必须设定为 'aliyun', 表示这个是 aliyun 颁发的, 默认值 opensearch 是为了兼容老用户 默认值为 :opensearch opts: 包含下面一些可选信息 参数名称参数类型 version 使用的 API 版本 默认值为 :v2 43

45 host gzip debug signaturemethod 指定请求的 host 地址 默认值为 : 指定返回的结果用 gzip 压缩 默认值为 :false 打印 debug 信息 默认值为 :false 签名方式, 目前支持 HMAC- SHA1 默认值为 :HMAC- SHA1 signatureversion 签名算法版本 默认值为 :1.0 function construct($key, $secret, $opts = array(),$key_type = 'opensearch') $access_key = " 替换成自己的 accesskey"; $secret = " 替换成自己的 Secret"; // 杭州公网 API 地址 : // 北京公网 API 地址 : (2015 年 4 月初开放 ) $host = " 根据自己的应用区域选择 API $key_type = "aliyun"; // 固定值, 不必修改 $client = new CloudsearchClient($access_key,$secret,$host,$key_type); 调试接口 获取 SDK 调用的调试信息, 需要指定 debug=true 才能使用 类型 array\null 描述 调试开关 (debug) 打开时返回调试信息 function getrequest() $clinet->getrequest(); 搜索操作 CloudsearchSearch 构造函数 44

46 请求参数 client CloudsearchClient 此对象由 CloudsearchClient 类实例化 function construct($client) $search_obj = new CloudsearchSearch($client); 执行搜索 执行向 API 提出搜索请求 更多说明请参见 API 接口 - 搜索相关 请求参数 opts array 此参数如果被赋值, 则会把此参数的内容分别赋给相应的变量 此参数的值可能有以下内容 : opts: 此参数如果被复制, 则会把此参数的内容分别赋给相应的变量 此参数的值可能有以下内容 : 参数名称参数类型 query indexes fetch_fields format formula_name summary start hits array array array int int 指定的搜索查询串, 可以为 query=>" 索引名 :' 鲜花 '" 指定的搜索应用, 可以为一个应用, 也可以多个应用查询 设定返回的字段列表, 如果只返回 url 和 title, 则为 array('url', 'title') 指定返回的数据格式, 有 json,xml 和 protobuf 三种格式可选 默认值为 :'xml' 指定的表达式名称, 此名称需在网站中设定 指定 summary 字段一些标红 省略 截断等规则 指定搜索结果集的偏移量 默认为 0 指定集的数量 默认为 20 45

47 sort array 指定排序规则 默认值为 :'self::sort_decrease' ( 降序 ) filter 指定通过某些条件过滤结果集 aggregate array 指定统计类的信息 distinct array 指定 distinct 排序 kvpair 指定的 kvpair 类型 array 描述 返回搜索结果 function search($opts = array()) $result = $search_obj->search(); 增加新的应用来进行检索 请求参数 indexname \array 应用名称或应用名称列表. function addindex($indexname) $search_obj->addindex("my_app_1"); $search_obj->addindex("my_app_2"); $search_obj->addindex("my_app_3"); 删除待搜索的应用 在当前检索中删除此应用的检索结果 请求参数 indexname 待删除的应用名称 46

48 function removeindex($indexname) $search_obj->removeindex("my_app_3"); 获得请求应用列表 当前请求中所有的应用名列表 类型 array 描述 返回当前搜索的所有应用列表 function getsearchindexes() $result = $search_obj->getsearchindexes(); 设置表达式名称 此表达式名称和结构需要在网站中已经设定 请求参数 formulaname 表达式名称 function setformulaname($formulaname) // 例如我们在控制台已经设定了一个名称为 my_formula_name 的排序表达式 $search_obj->setformulaname("my_formula_name"); 获取表达式名称 获得当前请求中设置的表达式名称 类型 描述 47

49 返回当前设定的表达式名称 function getformulaname() $result = $search_obj->getformulaname(); 清空精排表达式名称设置 function clearformulaname() $search_obj->clearformulaname(); 设置粗排表达式名称 此表达式名称和结构需要在网站中已经设定 请求参数 FormulaName 表达式名称 function setfirstformulaname($formulaname) // 例如我们在控制台已经设定了一个名称为 my_first_formula_name 的排序表达式 $search_obj->setfirstformulaname("my_first_formula_name"); 获取粗排表达式设置 获取当前设置的粗排表达式名称 类型 描述 返回当前设定的表达式名称 function getfirstformulaname() 48

50 $result = $search_obj->getfirstformulaname(); 清空粗排表达式名称设置 function clearfirstformulaname() $search_obj->clearfirstformulaname(); 添加一条 summary 信息 请求参数 fieldname len element ellipsis snipped elementprefix elementpostfix 指定的生效的字段 此字段必需为可分词的 text 类型的字段 指定结果集返回的词字段的字节长度, 一个汉字为 2 个字节 指定命中的 query 的标红标签, 可以为 em 等 指定用什么符号来标注未展示完的数据, 例如... 指定 query 命中几段 summary 内容 如果指定了此参数, 则标红的开始标签以此为准 如果指定了此参数, 则标红的结束标签以此为准 function addsummary($fieldname, $len = 0, $element = '',$ellipsis = '', $snipped = 0, $elementprefix = '', $element Postfix = '') //title 返回的字数长度为 50, 飘红用 "<em></em>", 截取长度后用 "..." 来结束, 返回的结果在一个片段 ( 片段的概念就是在一段落中还是几段落中 ) 中 $search_obj->addsummary('title',50,'em','...', 1, $elementprefix = '', $elementpostfix = ''); //title 返回的字数长度为 250, 飘红用 "<em></em>", 截取长度后用 "..." 来结束, 返回的结果在 2 个片段中 $search_obj->addsummary("body", 250, "em", "...", 2); 获取当前的 summary 信息 49

51 可以通过指定字段名称返回指定字段的 summary 信息 请求参数 field 指定的字段, 如果此字段为空, 则返回整个 summary 信息, 否则返回指定 field 的 summary 信息 类型 array 描述 返回 summary 信息 function getsummary($field = '') $result = $search_obj->getsummary('title'); 获取 summary 字符串 把 summary 信息生成字符串并返回 类型 描述 返回字符串的 summary 信息 function getsummarystring() $result = $search_obj->getsummarystring(); 设置返回的数据格式 请求参数 format 数据格式名称, 有 xml, json 和 protobuf 三种类型 50

52 function setformat($format) $search_obj->setformat("json"); 获取当前的数据格式名称 类型 描述 返回当前的数据格式名称 function getformat() $result = $search_obj->getformat(); 设置的 offset 偏移量 请求参数 start int 偏移量 function setstarthit($start) $search_obj->setstarthit(100); 获取的 offset 偏移量 类型 int 描述 返回当前设定的偏移量 function getstarthit() 51

53 $result = $search_obj->getstarthit(); 设置结果集大小 设置当前集的 doc 个数 请求参数 hits number 指定的 doc 个数 默认值 :20 function sethits($hits = 20) // 每页获取 25 条记录 $search_obj->sethits(25); 获取结果集大小 获取当前设定的结果集的 doc 数 类型 number 描述 返回当前指定的 doc 个数 function gethits() $result = $search_obj->gethits(); 添加排序设置 增加一个排序字段及排序方式 更多说明请参见 API 排序 sort 子句 请求参数 field 字段名称 sortchar 排序方式, 有升序 + 和降序 - 两种方式 52

54 function addsort($field, $sortchar = self::sort_decrease) // 按创建时间倒序获取搜索结果 $result = $search_obj->addsort("create_timestamp", '-'); 删除指定字段的排序 请求参数 field 指定的字段名称 function removesort($field) $result = $search_obj->removesort("create_timestamp"); 获取排序信息 请求参数 sortkey 如果此字段为空, 则返回所有排序信息, 否则只返回指定字段的排序值 类型 \array 描述 返回排序值 function getsort($sortkey = '') $result = $search_obj->getsort(); 获取排序字符串 53

55 把排序信息生成字符串并返回 类型 描述 返回字符串类型的排序规则 function getsortstring() $result = $search_obj->getsortstring(); 添加过滤规则 针对指定的字段添加过滤规则 更多说明请参见 API 过滤 filter 子句 请求参数 filter operator 过滤规则, 例如 fieldname>=1 操作符, 可以为 AND OR 默认值为 :'AND' function addfilter($filter, $operator = 'AND') //cat_id 必需为可过滤或者可聚合属性 $search_obj->addfilter("cat_id=1"); 获取过滤规则 类型 filter 描述 返回字符串类型的过滤规则 function getfilter() 54

56 $result = $search_obj->getfilter(); 添加统计信息相关参数 一个关键词通常能命中数以万计的文档, 用户不太可能浏览所有文档来获取信息 而用户感兴趣的可能是一些统计类的信息, 比如, 查询 手机 这个关键词, 想知道每个卖家所有商品中的最高价格 则可以按照卖家的 user_id 分组, 统计每个小组中最大的 price 值 :groupkey:user_id, aggfun: max(price) 更多说明请参见 APi aggregate 子句说明请求参数 groupkey 指定的 group key. aggfun 指定的 function 当前支持 :count max min sum range 指定统计范围 maxgroup 最大组个数 aggfilter aggsamplerthreshold 表示仅统计满足特定条件的文档 抽样统计的阈值 表示该值之前的文档会依次统计, 该值之后的文档会进行抽样统计 aggsamplerstep 抽样统计的步长 function addaggregate($groupkey, $aggfun, $range = '', $maxgroup = '',$aggfilter = '', $aggsamplerthreshold = ' ', $aggsamplerstep = '') $search_obj- >addaggregate($groupkey, $aggfun, $range, $maxgroup,$aggfilter, $aggsamplerthreshold, $aggsamplerstep); 删除指定的统计数据 请求参数 groupkey 指定的 group key function removeaggregate($groupkey) 55

57 $search_obj->removeaggregate("cat_id"); 获取统计相关信息 请求参数 groupkey 指定 group key 获取其相关信息, 如果为空, 则返回整个信息 类型 array 描述 统计相关信息 function getaggregate($key = '') $result = $search_obj->getaggregate(); 获取字符串类型的统计信息 类型 描述 获取字符串类型的统计信息 function getaggregatestring() $result = $search_obj->getaggregatestring(); 添加 distinct 排序信息 例如 : 检索关键词 手机 共获得 10 个结果, 分别为 :doc1,doc2,doc3,doc4,doc5,doc6, doc7,doc8,doc9,doc10 其中前三个属于用户 A,doc4-doc6 属于用户 B, 剩余四个属于用户 C 如果前端每页仅展示 5 个商品, 则用户 C 将没有展示的机会 但是如果按照 user_id 进行抽取, 每轮抽取 1 个, 抽取 2 次, 并保留抽取剩余的结果, 则可以获得以下文档排列顺序 :doc1 doc4 doc7 doc2 doc5 doc8 doc3 doc6 doc9 doc10 可以看出, 通过 distinct 排序, 各个用户的商品都得到了展示机会, 结果排序更 56

58 趋于合理 更多说明请参见 API distinct 子句请求参数 key distcount int 为用户用于做 distinct 抽取的字段, 该字段要求建立 Attribute 索引 为一次抽取的 document 数量, 默认值为 1 disttimes int 为抽取的次数, 默认值为 1 reserved distfilter updatetotalhit maxitemcount int 为是否保留抽取之后剩余的结果,true 为保留,false 则丢弃, 丢弃时 totalhits 的个数会减去被 distinct 而丢弃的个数, 但这个结果不一定准确, 默认为 true 为过滤条件, 被过滤的 doc 不参与 distinct, 只在后面的排序中, 这些被过滤的 doc 将和被 distinct 出来的第一组 doc 一起参与排序 默认是全部参与 distinct 当 reserved 为 false 时, 设置 update_total_hit 为 true, 则最终 total_hit 会减去被 distinct 丢弃的的数目 ( 不一定准确 ), 为 false 则不减 ; 默认为 false 设置计算 distinct 时最多保留的 doc 数目 grade number 指定档位划分阈值 function adddistinct($key, $distcount = 0, $disttimes = 0,$reserved = '', $distfilter = '', $updatetotalhit = '',$maxit emcount = 0, $grade = '') // 每次抽取 3 条文档, 抽取 4 次, 丢掉抽取之后的结果, 并且更新搜索结果中总文档的个数 $search_obj->adddistinct($key, 3, 4, false, '', true); 删除某个字段的所有 distinct 排序信息 请求参数 57

59 distinctkey 指定的字段 function removedistinct($distinctkey) $search_obj->removedistinct($distinctkey); 获取某字段的 distinct 排序信息 请求参数 key 指定的 distinct 字段, 如果字段为空则返回所有 distinct 信息 类型 array 描述 指定字段的 distinct 排序信息 function getdistinct($key = '') $result = $search_obj->getdistinct(); 获取字符串类型的所有的 distinct 信息 类型 描述 字符串类型的所有的 distinct 信息 function getdistinctstring() $result = $search_obj->getdistinctstring(); 设定指定索引字段范围的搜索关键词 58

60 [NOTE]:$query 必须指定索引名称, 格式类似为索引名称 :' 搜索关键词 ' 此 query 是查询必需的一部分, 可以指定不同的索引名, 并同时可指定多个查询及之间的关系 (AND, OR, ANDNOT, RANK) 例如查询 subject 索引字段的 query: 手机, 可以设置为 query=subject:' 手机 ' NOTE: text 类型索引在建立时做了分词, 而 类型的索引则没有分词更多说明请参见 API query 子句请求参数 query 设定搜索的查询词 fieldname 设定的索引范围 function setquerystring($query) $search_obj->setquerystring('default: 阿里云 '); 获取当前指定的查询词内容 类型 描述 当前指定的查询词内容 function getquery() $result = $search_obj->getquery(); 添加指定结果集返回的字段 请求参数 field array\ 结果集返回的字段 59

61 function addfetchfields($field) // 希望搜索结果只返回 title,body,url 和 hit_count 四个字段时的设置 $search_obj->addfetchfields("title"); $search_obj->addfetchfields("body"); $search_obj->addfetchfields("url"); $search_obj->addfetchfields("hit_count"); 删除指定结果集的返回字段 请求参数 fieldname 指定字段名称 function removefetchfield($fieldname) $search_obj->removefetchfield("url"); 设置 kvpair 更多说明请参见 API 自定义 kvpair 子句请求参数 pair 指定的 pair 信息 function setpair($pair) // 例如我们在控制台中设计的表达式中需要根据用户的地理位置对结果进行排序 // 在搜索时需要传入用户的地理位置信息, 比如分别传入用户的经纬度信息 $search_obj->setpair("latitude: (n),longitude:4.768(e)"); 获取当前的 kvpair 类型 描述 60

62 返回当前设定的 kvpair function getpair() $result = $search_obj->getpair(); 增加自定义参数 请求参数 paramkey 参数名称 paramvalue 参数值 function addcustomparam($paramkey, $paramvalue) $search_obj->addcustomparam("xxx", "YYY"); 指定精排算分的文档个数 若不指定则使用默认值 200 请求参数 reranksize int 精排算分文档个数 function addreranksize($reranksize) $search_obj->addreranksize(200); 获取精排算分文档个数 类型 int 描述 精排算分文档个数 61

63 function getreranksize() $result = $search_obj->getreranksize(); 获取自定义参数 类型 描述 自定义参数 function getcustomparam() $result = $search_obj->getcustomparam(); 获取指定结果集返回的字段列表 类型 array 描述 指定结果集返回的字段列表 function getfetchfields() $result = $search_obj->getfetchfields(); 文档操作 CloudsearchDoc 构造函数 请求参数 indexname 指定操作的索引名称 62

64 client CloudsearchClient cloudsearch 客户端 opts array 可选参数 function construct($indexname, $client, $opts = array()) $app_name = " 你的应用名称 "; $doc_obj = new CloudsearchDoc($app_name, $client); 查看文档 根据文档 id 获取 doc 的详细信息 请求参数 docid 指定的文档 id 类型 描述 该 docid 对应的 doc 详细信息 function detail($docid) $result = $doc_obj->detail($docid); 更新文档 向指定的表中更新 doc 请求参数 docs array 指定要更新的 doc tablename 指定向哪个表中更新 doc 类型 描述 返回 API 返回的结果 63

65 function update($docs, $tablename) $doc_obj->update($docs,$table_name); 添加文档 向指定的表中增加 doc 请求参数 docs array 指定要添加的 doc tablename 指定向哪个表中增加 doc 类型 描述 返回 API 返回的结果 function add($docs, $tablename) $doc_obj->add($docs,$table_name); 删除文档 删除指定表中的 doc 请求参数 docs array 指定要删除的 doc 列表, 必须含有主键 tablename 指定要从哪个表删除记录 类型 描述 返回 API 返回的结果 64

66 function remove($docs, $tablename) $doc_obj->remove($docs,$table_name); 通过 csv 格式文件上传文档数据 NOTE: 此文件必需为 csv 格式的文件 (, 分割 ); 且第一行为数据结构字段名称, 例如 : id, title, name, date,1, " 我的测试数据 \"1\" 测试 1", test_name1, " :12:22"... 请求参数 filename 本地文件 primarykey 指定此表的主键 tablename 指定表名 multivalue offset maxsize frequence array int number int 指定此表中的多值的字段 默认值为空 指定从第 offset 条记录开始导入 默认值为 1 指定每次 push 数据的最大值, 单位为 MB 默认值为 4 指定上传数据的频率, 默认值为 4, 单位为次 / 秒 类型 描述 返回如果成功上传或上传失败的状态 function pushcsvfile($filename, $primarykey, $tablename,$multivalue = array(), $offset = 1, $maxsize = self::pus H_MAX_SIZE,$frequence = self::push_frequence) // 其他字段使用默认值 $result = $doc_obj->pushcsvfile($filename,$primarykey,$tablename); 推送 HA3 格式文档 65

67 除了上面的方法还可以通过文件将文档导入到指定的表中这里的文档需满足一定的格式, 我们称之为 HA3 文档格式 HA3 文件的要求如下 : 文件编码 :UTF-8 支持 CMD: add, delete,update 如果给出的字段不是全部,add 会在未给出的字段加默认值, 覆盖原值 ;update 只会更新给出的字段, 未给出的不变 文件分隔符 : <pre> 编码 描述 显示形态 "\x1e\n" 每个 doc 的分隔符. ^^( 接换行符 ) "\x1f\n" 每个字段 key 和 value 分隔 ^_( 接换行符 ) "\x1d" 多值字段的分隔符 ^] </pre>; 示例 : <pre>; CMD=add^_ url= title= 开放搜索 ^_ body=xxxxxxxxx^ multivalue_feild=123^]1234^]12345^ ^^ CMD=update^_... </pre> 注意 : 文件结尾的分隔符也必需为 "^^\n", 最后一个换行符不能省略 请求参数 filename 指定 HA3DOC 所有在的路径 tablename 指定要导入的表的名称 offset int 指定偏移行数, 如果非 0, 则从当前行一下的数据开始导入 默认值为 :1 66

68 maxsize frequence number int 指定每次导入到 api 接口的数据量的大小, 单位 MB, 默认值为 :4 指定每秒钟导入的频率, 单位次 / 秒, 默认值为 :4 类型 描述 返回导入成功标志 function pushhadocfile($filename, $tablename, $offset = 1,$maxSize = self::push_max_size, $frequence = self::p USH_FREQUENCE) // 其他参数使用默认值 $doc_obj->pushhadocfile($filename,$tablename); 应用操作 CloudsearchIndex 构造函数 请求参数 indexname 指定操作的应用名称 client CloudsearchClient cloudsearch 客户端 function construct($indexname, $client) $index_obj = new CloudsearchIndex($indexName,$client); 通过模板名称创建应用 用指定的模板名称创建一个新的应用 请求参数 67

69 templatename 模板名称 ( 可以使系统内置模板, 也可以是自定义模板 ) opts array 包含应用的备注信息 类型 描述 返回 api 返回的结果 function createbytemplatename($templatename, $opts = array()) // 使用内置的新闻应用模板创建一个应用 $index_obj->createbytemplatename("builtin_news"); 通过模板创建应用 用指定的模板创建一个新的应用 模版是一个格式化数组, 用于描述应用的结构, 可以在控制台中通过创建应用 - > 保存模板 -> 导出模板来获得 json 结构的模板 ; 也可以自己生成, 格式见控制台模板管理 请求参数 template 使用的模板 opts array 包含应用的备注信息 类型 描述 返回 api 返回的正确或错误的结果 function createbytemplate($template,$opts = array()) $index_obj->createbytemplate($template); 修改应用名称和备注 更新当前应用的应用名称和备注信息 请求参数 68

70 toindexname 更改后的新名字 opts array 可选参数, 包含 : desc 应用备注信息 类型 描述 API 返回的操作结果 function rename($toindexname, $opts = array()) $index_obj->rename("new_index_name"); 删除应用 类型 描述 API 返回的操作结果 function delete() $result = $index_obj->delete(); 查看应用状态 类型 描述 API 返回的操作结果 function status() $result = $index_obj->status(); 69

71 列出所有应用 请求参数 page int 页码 pagesize int 每页的记录条数 function listindexes($page = 1, $pagesize = 10) $reuslt = $index_obj->listindexes(1,10); 获取应用名称 获取当前应用的名称 类型 描述 当前应用的名称 function getindexname() $result = $index_obj->getindexname(); 获取应用的最近错误列表 请求参数 page pagesize int int 指定获取第几页的错误信息 默认值 :1 指定每页显示的错误条数 默认值 :10 类型 array 描述 返回指定页数的错误信息列表 70

72 function geterrormessage($page = 1, $pagesize = 10) $result = $index_obj->geterrormessage(2,10); 相关下载 相关下载 最新稳定版 v2.0.4 php_v2.0.4.zip github 镜像即将开放.NetSDK 手册 相关下载 相关下载 最新稳定版 AliCouldAPI_vs2010_v2.1.1.zip AliCouldAPI_vs2012_v2.1.1.zip 71