APIP1V1_OpenAPI(zh-CN)



  • APIP1: OpenAPI
    Version: 1
    Language: zh-CN
    Author: C_armX, Write_cash
    Status: draft
    Created date: 2021-10-30
    Update:2022-12-01
    PID: ""
    TXID: 
    

    APIP1V1_OpenAPI(zh-CN)

    目录

    关于APIP

    APIP的发布

    接口标识

    接口url的构成

    时间戳格式

    密码算法

    示例身份信息

    API服务流程

    谁是API的请求方

    如何购买API服务

    connect接口

    数据请求接口

    APIP简易查询语法


    Type: APIP
    SerialNumber: 1
    ProtocolName: OpenAPI
    Version: 1
    Description : 定义在Freecash主链上发布开放API协议的一般方式.
    Author: C_armX,Write_cash
    Language: zh-CN
    PID:""
    

    关于APIP

    APIP(Application Programming Interface Protocols)是自由共识生态协议的一种类型,用于创建和发布开放的API文档,供API服务方开发部署通用API服务,以实现数据服务的去中心化。API需求方可以按照APIP协议从遵循该协议的任何一个API服务方那里获取数据服务。


    APIP协议的发布

    APIP协议与自由共识生态的其他自由协议一样,由协议作者按照《FEIP1_FreeProtocol》协议在链上发布注册,注册交易的OP_RETURN内容为:

    {
        "type": "FEIP"
        "sn": 1,
        "ver": 7,
        "name": "FreeProtocol",
        "pid": [string, FEIP1V7 协议文本的双sha256哈希值,该协议正式发布前暂时留空],
        "data": {
            "op": "register",
            "type": "APIP",
            "sn": [int,协议编号,必填],
            "ver": [int,协议版本号,必填],
            "name": [string,协议名称,必填],
            "desc": [string,对协议的描述],
            "authors": [string array, 作者们的fch地址],
            "pid": [string, 协议id,即协议文本的双sha256哈希值,留空为测试中协议],
            "lang": [string,语言,基于i18n编码],
            "prePid": [string,前一版本协议文本的pid],
            "fileUrl": [string array, 协议文本存放位置]
        }
    }
    

    自由协议的更新、注销和评价参见《FEIP1_FreeProtocol》。


    接口标识

    1. 通用标识

    接口名称@PID#[所属APIP协议的PID]

    1. 简化标识

    接口名称@协议类型+协议编号

    简化标识不一定唯一,主要便于人类记忆和识别,重要场景或机器识别应采用唯一标识。

    1. 示例:

    APIP1的balance接口的通用标识为:balance@PID#[APIP1协议文本的哈希值,待确认]

    简化标识为:balance@APIP1


    接口url的构成

    接口的url分为两部分:urlHeadurlTail

    1. urlHead

    urlHead为某API服务方提供的所有接口url的共同部分,由服务方依据《FEIP29_Service》在data.params.urlHead字段中发布在链上。格式为:

    scheme://domain or IP:port/subdirectory/

    所需信息 必填 说明
    scheme Y 协议类型,http、https、ws等
    domainOrIP Y 域名或IP
    port N 端口
    subdirectory N 接口子目录

    示例

    https://www.sign.cash/api/

    1. urlTail

    urlTail是该API服务方按照APIP协议,在链上发布API服务时声明的具体接口的具体位置。格式为:

    apip[协议编号]/v[版本号]/[接口名称]

    示例:

    apip1/v1/connect

    1. url

    接口的完整url = urlHead + urlTail

    示例:

    https://www.sign.cash/api/apip1/v1/connect


    时间戳格式

    APIP协议涉及的时间戳,若无特定说明,默认为13位,精确到毫秒
    Freecash区块数据的时间戳为10位,应转换为13位。


    密码算法

    哈希算法

    无特殊说明,哈希算法采用两次sha256算法,即:sha256(sha256(byte[] message_bytes)),哈希值为Hex,字母为小写.

    加密算法

    无特殊说明,文本和文件加解密采用ECC256k1-AESCBC算法,协议PID为[待开发完成后发布]。

    签名算法

    1. 对称密码签名:无特殊说明,对称密码签名验证采用数据加入symKey后序列化,做两次sha256哈希算法得到签名。

    2. 非对称密码签名:无特殊说明,非对称密码签名验证采用椭圆曲线算法(ECDSA)算法,以签发者私钥对数据进行签名,协议PID为[待开发完成后发布]。


    示例身份信息

    APIP协议默认采用以下请求方身份信息:

    requester:FEk41Kqjar45fLDriztUDTUkdki7mmcjWK

    requester的公钥pubKey:030be1d7e633feb2338a74a860e76d893bac525f35a5813cb7b21e27ba1bc8312a

    requester的私钥priKey:L2bHRej6Fxxipvb4TiR5bu1rkT3tRp8yWEsUy4R1Zb8VMm2x7sd8

    requester获得的对称密钥symKey:d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09


    API服务流程

    按照APIP协议,服务方(API服务的提供者,简称APISP)为请求方(API服务的使用者,APP或用户个人)提供API服务的一般流程为:

    1. 服务方 开发部署API服务

    服务方选择一个或多个链上注册的APIP协议,开发和部署相应的API服务。

    1. 服务方 链上注册API服务

    服务方依据《FEIP29_Service》协议,在链上发布自己的API服务,并给出订购方式、API的urlHead。

    发布者FCH地址为交易的第一个输入,发布交易的OP_RETURN内容为:

    {
        "type": "FEIP",
        "sn": 29,
        "ver": 2,
        "name": "Service",
        "pid": [string, FEIP29V1 协议文本的双sha256哈希值,该协议正式发布前暂时留空],
        "data":{
            "op": "start",
            "stdName": [string,服务的英文名],
            "localName": [string array,服务的其他语言名称],
            "desc": [string, 对服务的描述,包括:url共用部分,付费方式,服务价格等],
            "type": [string array, 服务的分类,可多个。应包含“APIP”]
            "prot": [string array, 所遵循的协议]
            "urlHead": [string, API的url的首部]
            "pubKeyAdmin": "02966dc682850550b1df046f2a03cfe546c4e4cf83f739d1497f6c292fabdad1b4",
            "params":{
    	        "urlHead": [string, API访问位置的共同部分,如http://sign.cash/api/],
    	        "receivingAccount":[string,收款账号,缺省为发布者FCH'地址],
    	        "pricePerRequest": [int, 每次请求的服务收费,采用最小单位],
    	        "minPayment": [int64, 最低单次购买金额,采用最小单位],
    	        "currency": [string,支付的币种,缺省为FCH,法币则遵循ISO4217,如'CNY']
        }
    }
    
    1. 请求方 链上查询API服务

    请求方在链上查询自己所需要的API服务方,获得订购方式(receivingAccount,pricePerRequest,minPayment,currency)和API路径的共同部分(urlHead)。

    1. 请求方 链下订购API服务

    请求方按照订购方式,向服务方订购API服务。服务方记录请求方的身份(FCH地址)和充值余额,开始服务。

    1. 请求方 发出连接服务请求

    请求方通过connect接口,向服务方发起包含自身pubKey的连接请求和私钥签名,以获得后续数据请求使用的对称密钥symKey,详情参见[##connect接口](##connect接口)。

    1. 服务方 验证请求分配密钥

    服务方对请求进行安全验证后,发放用请求方pubKey加密的对称密钥symKey。具有相同urlHead的接口共用同一个symKey。

    1. 请求方 解密保存symKey

    请求方用自己的私钥priKey解密密文,获得symKey,保存用于后续数据请求。

    1-7步骤的流程图:

    APIP1_OpenAPI插图 连接.png

    1. 请求方 发出数据服务请求

    请求方根据自身数据需求,选择服务方的对应接口,构造API的url和请求参数并签名后,向服务方发出数据请求。详情参见[##数据服务接口](##数据服务接口)

    1. 服务方 验证请求返回数据

    服务方收到请求后,进行安全验证无误后,返回响应数据和签名给请求方。

    1. 请求方 验证签名接受数据

    请求方收到响应数据后,验证签名是否无误则接受数据,服务完成。

    8-10的流程图:

    APIP1_OpenAPI插图 数据.png

    谁是API的请求方

    APP有两种请求方设定逻辑:

    1.用户作为请求方

    • 1)用户通过APP或其他途径用自己的FCH地址购买服务。

    • 2)用户进入APP需要获取数据时,用自己的私钥签名发起connect连接请求。

    • 3)APP为用户在本地保存symKey,用于向API服务方发起数据请求。

    • 4)特点:符合密码经济中“用户掌握数据”的安全准则,减少对APP的依赖,更加安全、开放、去中心化。

    2.APP作为请求方

    • 1)APP发布者用自己的地址向API服务方购买服务,获得symKey。

    • 2)用户使用APP时,所需要的数据由APP向API服务方提出请求。

    • 3)特点:符合传统开发习惯,便于APP运营者掌控数据,有中心化风险。


    如何购买API服务

    请求方购买API服务的方式由服务方在链上注册服务时,在data.desc字段描述,在data.params字段给出相关参数。服务方未特殊声明,则默认采用以下方式:

    1. 服务方链上注册服务时在data.params中声明收费信息
    {
        "receivingAccount":[string,收款账号,缺省为发布者FCH'地址],
        "pricePerRequest": [int, 每次请求的服务收费,采用最小单位],
        "minPayment": [int64, 最低单次购买金额,采用最小单位],
        "currency": [string,支付的币种,缺省为FCH,法币则遵循ISO4217,如'CNY']
    }
    
    1. 请求方链上获取收费信息的两种方式

      • 1)通过APP获取。APP提供API服务方及价格列表,供请求方选择购买服务。

      • 2)请求方自行查找链上API服务方,获取API服务的收费信息。

    2. 请求方链上购买服务的两种方式

      • 1)通过APP购买。APP在请求方同意购买,并填写或选择支付金额后,为请求方构造包含购买标记的交易,由请求方确认后发送交易。

        1. 请求方自行构造包含购买标记的交易完成支付。
    3. 请求方的购买标记,即购买交易的OP_RETURN内容,如下:

    {
        "type": "APIP"
        "sn": 1,
        "ver": 1,
        "name": "OpenAPI",
        "pid": [string, FEIP1V7 协议文本的双sha256哈希值,该协议正式发布前暂时留空],
        "data": {
            "op":"buy",
            "sid":[string,所购买服务的sid,必填]
        }
    }
    
    
    1. API服务方启动服务

      • API服务方收到有购买标记的交易后,自动登记第一个输入的FCH地址为用户ID,并登记余额,开始服务。

      • 请求方的每次请求按pricePerRequest计减余额。

      • 余额一旦小于pricePerRequest则服务终止,删除该用户信息,以防止用户信息累计过多,并防止与此相关的攻击。


    connect接口

    connect接口用来向服务方申请获得symKey,symKey用于后续数据请求的签名和验证。

    1. 接口名称

    connect


    2. 请求方法

    POST


    3. URL

    url = urlHead + urlTail

    = [服务方链上注册服务时的data.params.urlHead值] + "apip1/v1/connect"

    示例:

    data.params.urlHead = "https://www.sign.cash/api/"
    
    url: "https://www.sign.cash/api/apip1/v1/connect"
    
    

    4. 请求参数

    参数 类型 说明 必填
    pubKey hex 请求方的公钥,用于验证身份和授权 Y
    url string 当前connect的url,防止重放攻击 Y
    timestamp time stamp 精确到毫秒的时间戳,防止重放攻击 Y
    sign string 用请求方私钥priKey对序列化后的其他参数的签名,防止身份伪造 Y
    • 签名

    请求方用自己的私钥priKey对除sign之外的请求参数序列化后,进行签名,得到sign,加入请求json。

    • 示例

    请求参数

    {
    	"pubKey": "030be1d7e633feb2338a74a860e76d893bac525f35a5813cb7b21e27ba1bc8312a",
    	"url": "https://www.sign.cash/api/apip1/v1/connect",
    	"timestamp": 1635513688254,
        "sign": "H6d+wvrsj5Bgh4Y2GeOFujYvXijMK1FG97bSDd7zaX8VY78X3a2Ey2Success.wpyo5ASiwWA8cW6gP1rejWjZMbPcS3k\u003d"
    }
    

    其中,sign为私钥priKey(L2bHRej6Fxxipvb4TiR5bu1rkT3tRp8yWEsUy4R1Zb8VMm2x7sd8)对序列化后的其他请求参数({"pubKey":"030be1d7e633feb2338a74a860e76d893bac525f35a5813cb7b21e27ba1bc8312a","timestamp":"1635513688254","url":"https://www.sign.cash/api/apip1/v1/connect"})所做的签名。

    请求方保存API服务信息

    请求方为其使用的每个APIP协议,分别保存以下信息:

    信息名称 类型 说明 必填
    sid string 接口服务的SID,即服务方在链上注册服务时的txid N
    pid string APIP协议的PID N
    title string APIP协议的标题,如:APIP1V1_OpenAPI(zh-CN) N
    sn int APIP协议编号 Y
    ver int APIP协议版本号 Y
    sid string 当前接口服务的SID,即服务方在链上注册服务时的txid N
    stdName string 接口服务链上注册的英文标准名称 N
    urlHead string connect的urlHead,相同sid的urlHead值相同 Y
    pubKeyAdmin string 发布者为api服务指定的管理员pubKey,用于加密和验证签名,缺省为服务发布者公钥 N
    addressAdmin string 发布者为api服务指定的管理员,即pubKeyAdmin计算的FCH地址,缺省为服务发布者地址 N
    receivingAccount string 服务方链上发布的充值收款账号,缺省为发布者FCH地址 N
    pricePerRequst string 每次请求的服务收费,采用最小单位 N
    minPayment string 最低单次购买金额,采用最小单位 N
    currency string 支付的币种,缺省为FCH,法币则遵循ISO4217,如'CNY' N
    symKey string 当前生效的symKey,相同urlHead的各接口使用同一个symKey N
    timestamp time stamp 当前生效的symKey获得的时间戳 N
    days int 当前生效的symKey的有效天数 N
    apiBalance int64 请求方当前服务余额 all

    5. 响应

    • 验证请求。服务方对请求依次验证:

      • 1)验证用户。验证requester是否在用户列表中,用户列表由余额大于pricePerRequest的FCH地址构成。不在列表返回1000.

      • 2)验证请求对象。验证签名内容中的“url”值是否与服务方当前接口的url相同,防止重放攻击。不同则返回1001

      • 3)验证时间戳。验证当前时间戳减timestamp的绝对值是否小于服务方设定的windowTime。过期返回1002.

      • 4)验证签名:用pubKey验证签名sign是否正确,防止身份伪造。失败返回1003。

    • 响应状态

    code message 说明 响应参数
    0 Success. 请求成功.返回数据和签名 data,apiBalance
    1000 Please purchase the service. 请购买该服务。返回购买信息 receivingAccount, pricePerRequst, minPayment, currency
    1001 The URL you requested is wrong. 请求中的url与服务方接口url不符,返回服务方接口url url
    1002 Request expired, 请求已过期。返回服务方设定的时间窗口长度。 windowTime
    1003 Failed to verify signature. 验证签名失败
    1006 Other error,please contact the service provider. 其他错误,请联系服务方.
    1020~1099 API服务商自定义响应码、响应信息和响应参数
    • 响应参数
    参数 类型 说明 适用状态
    code int 响应状态码 all
    message string 响应状态描述 all
    data.symKeyEncrypted string symKey的密文 0
    data.days int symKey的有效天数 0
    data.receivingAccount string 服务方链上发布的充值收款地址,缺省为服务发布者地址 1000
    data.pricePerRequst string 服务方每次请求价格 1000
    data.minPayment string 服务方最低充值金额 1000
    data.currency string 充值币种,缺省为"FCH",法币则遵循ISO4217 1000
    data.url string 服务方当前接口的url 1001
    data.windowTime timestamp 服务方设置的时间窗口长度,精确到毫秒 1002
    apiBalance int64 请求方当前服务余额 all
    • 示例

    设服务方验证请求无误后,为该请求方分配symKey为:"d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09"。

    请求方公钥pubKey为:"030be1d7e633feb2338a74a860e76d893bac525f35a5813cb7b21e27ba1bc8312a"。

    则响应参数为:

    {
    	"code": "0",
    	"message": "Success.",
    	"data": {
    		"symKeyEncrypted": "A+wCC1gjAoWiF+it5xnE668eoJHHMnF5UpjI2fxKQeuJyOWAiFsl5RPX0HEIEPm5ygmOifwBpZ2Yh3e5NyH2BlDEPaYPFoUZqdedBTRWoVHR48hKFN088dZYX+/6f0w+jhOsjxylXlxdwe6p/kwXNIuQ3iEVPz9cyVGNdFm8vVMQkHtbZlIdDjj0L13CCOuIJnByjNBMsPbP4qCnNSunuAIV91z2XAGlofGrIozGA3AY",
    		"days": 365
    	},
    	"apiBalance": 2000
    }
    
    

    服务方应保存的用户信息

    名称 类型 说明
    address string 用户的FCH地址,即ID,应与充值FCH地址、connect请求参数中pubKey计算的FCH地址相同。
    apiBalance int64 用户余额,余额小于pricePerRequest值,则删除该用户所有信息,充值后重建用户信息
    pubKey string 用户的公钥,connect请求时获取,用于验证connect请求的签名。若对应FCH地址未保存,则视为新用户。
    symKey string 该用户最新的symKey,过期保留直至用户重置
    timestamp int 当前symKey发放时间,用于控制连接的有效期
    days int N

    数据请求接口

    1. 接口名称

    接口名称在相应APIP协议中定义。

    示例:

    在协议APIP99V1中定义接口 interface1


    2. 请求方法

    POST


    3. URL

    url = urlHead + urlTail

    urlHead为 [服务方链上注册服务时的data.params.urlHead值],如:"https://www.sign.cash/api/"

    urlTail在具体的APIP协议的具体接口处定义,格式为:apip[协议编号]/v[协议版本号]/[接口名称]。如:"apip99/v1/interface1"

    示例:

    urlHead = "https://www.sign.cash/api/"
    
    urlTail = "apip99/v1/interface1"
    
    url: "https://www.sign.cash/api/apip99/v1/interface1"
    
    

    4. 请求参数

    请求应包含以下通用参数:

    name type description requested
    requester string 请求方的fch地址 Y
    url string 当前所请求api的url Y
    timestamp timestamp 发起请求的时间戳,精确到毫秒 Y
    query object 请求数据的查询语句,参见APIP简易查询语法 N
    sort object 请求数据的排序语句,参见APIP简易查询语法 N
    from int 请求列表数据时的起始位置,从0开始 N
    size int 请求列表数据时的每页条目数 N
    sign string 用symkey对其他参数所做的签名 Y

    query、sort、from和size由具体APIP协议规定。

    • 签名

    symKey加入除sign以外的其他请求参数并序列化后,做两次sha256计算,获得sign

    • 示例:

    查询address包含“armX”,且1000<amount<=2000的条目,按amount升序排列,取前20条。

    请求参数parameters

    {
    	"requester": "FEk41Kqjar45fLDriztUDTUkdki7mmcjWK",
    	"timestamp": 1635513688254,
    	"url": "https://www.sign.cash/api/interface1",
    	"query": {
    		"bool": {
    			"must": {
    				"match": {
    					"address": "armX"
    				},
    				"range": {
    					"amount": {
    						"gt": 1000,
    						"lte": 2000
    					}
    				}
    			}
    		}
    	},
    	"sort": [{
    		"amount": {
    			"order": "asc"
    		}
    	}],
    	"from": 0,
    	"size": 20,
    	"sign": "814b7ab051e0d4141129b7ae6e884d17e8c78c0afe91cef5790d51c0241a0d40"
    }
    

    其中:

    sign =

    sha256(sha256(parametersWithoutSign.getBytes()))

    =1111111111111111


    5. 响应

    • 验证请求:服务方按顺序验证请求

      • 1)验证用户。验证requester是否在用户列表中,用户列表由余额大于pricePerRequest的FCH地址构成。不在列表返回1000。

      • 2)验证请求对象。验证签名内容中的url值是否与服务方当前接口的url相同,防止重放攻击。不同则返回1001。

      • 3)验证时间戳。验证当前时间戳减请求参数中timestamp的绝对值是否小于服务方设定的windowTime,防止重放攻击。过期返回1002.

      • 4)验证symKey时效。检查服务器保存的requeter的symKey是否过期。过期返回1004.

      • 5)验证签名。在请求参数中加入requester的symKey做两次sha256哈希,验证值是否与sign的值一致。不一致返回1003。

    • 响应状态

    code message 说明 响应参数
    0 Success. 请求成功.返回数据和签名 data, apiBalance
    1000 Please purchase the service. 请购买该服务。返回购买信息 receivingAccount, pricePerRequst, minPayment, currency
    1001 The URL you requested is wrong. 请求中的url与服务方接口url不符,返回服务方接口url url
    1002 Request expired, 请求已过期。返回服务方设定的时间窗口长度。 windowTime
    1003 Failed to verify signature. 验证签名失败
    1004 The symKey has expired, please connect again. symKey过期,请重新连接
    1005 Too much data requested. 请求数据太多。返回最大请求数量。 maxSize
    1006 No data meeting the conditions. 没查到符合条件的数据
    1007 Other error,please contact the service provider. 其他错误,请联系服务方.
    2000~ API服务商自定义响应码、响应信息和响应参数.
    • 响应参数
    参数 类型 说明 适用状态
    code int 响应状态码 all
    message string 响应状态描述 all
    data object 正常返回非列表数据,由具体APIP定义 0
    data.receivingAccount string 1000状态,服务方链上发布的充值收款地址,缺省为服务发布者地址 1000
    data.pricePerRequst string 服务方每次请求价格 1000
    data.minPayment string 服务方最低充值金额 1000
    data.currency string 充值币种,缺省为"FCH",法币则遵循ISO4217 1000
    data.url string 服务方当前接口的url 1001
    data.windowTime timestamp 服务方设置的时间窗口长度,精确到毫秒 1002
    data.maxSize int 服务方设定的最大响应数量 1005
    apiBalance int64 请求方当前服务余额 all
    sign string 将symKey加入响应参数做两次sha256哈希的签名值 all
    • 示例
    {
    	"code": "0",
    	"message": "Success.",
    	"data": {
    		"total": 3,
    		"p0": [{
    			"p3": 3,
    			"p4": "c",
    			"p5": "BBBBB"
    		}, {
    			"p3": 5,
    			"p4": "b",
    			"p5": "CCCCC"
    		}, {
    			"p3": 4,
    			"p4": "a",
    			"p5": "aaaaa"
    		}],
    		"bestHeight": 100
    	},
    	"apiBalance": 55000,
    	"sign": "2f09d2f1af3432063969147b9eb156fe434ed728f52f19c975d7ddca4c6bd816"
    }
    
    

    其中

    sign=

    sha256(sha256({"apiBalance":55000,"code":"0","data":{"bestHeight":100,"p0":[{"p3":3,"p4":"c","p5":"BBBBB"},{"p3":5,"p4":"b","p5":"CCCCC"},{"p3":4,"p4":"a","p5":"aaaaa"}],"total":3},"message":"Success.","symKey":"d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09"}))

    = 2f09d2f1af3432063969147b9eb156fe434ed728f52f19c975d7ddca4c6bd816


    6. 请求方验证响应数据

    请求方收到数据后,取出sign,加入symKey序列化后,做两次sha256哈希,与sign值相比较,一致则接受数据。以防止中间人攻击。


    7. 请求方重置symKey

    请求方在1)希望重置symKey,或2)收到错误码1004,symKey过期时,或3)收到错误码1000,并完成充值时,用connect接口申请新的symKey。


    APIP简易查询语法

    • 通用语法仅实现简单查询功能,复杂查询功能语法由API服务商自行定义和发布。

    查询命令

    1. all (全查询)

    • 获取全部条目。
    {
    	"all":{}
    } 
    //查询所有条目。
    

    2. ids (id查询)

    • 获取给定id条目,可同时查询多个值。
    {
    	"ids":["1111111111","22222222222"]
    }查询id为"1111111111"或"22222222222"的条目
    

    3. terms (精确查询)

    • 对单一字段精确匹配,可同时查询多个值。
    {
    	"terms":{
    		"address":["F000000000000","F111111111111"];
    		}
    } //查询字符串字段“address”值为"F000000000000"或"F111111111111"的条目。
    
    {
    	"terms":{
    		"fee":["1000","2000"];
    		}
    } //查询整数字段“fee”的值为"1000"或"2000"的条目。
    

    4. part (部分查询)

    • 对单一字段,搜索包含特定值的条目,可使用通配符*和?。
    {
    	"part":{
    		"address":"arm?*“
    		}
    } //查询“address”字段值以“‘arm’加一个任意字符”开头的条目。
    

    5. matchs (模糊查询)

    • 对多个字段,分词模糊查询给定内容。
    {
    	"matchs":{
    		"query":"good bad",
    		"fileds":["article","post","reply"]
    		}
    } 
    //在"article","post"和"reply"字段中,模糊查询包含’good‘或’bad‘(不区分大小写)的条目,并给出评分。
    

    6. exist (非空查询)

    • 查询某个字段存在且非null的条目。
    {
    	"exist":"cid"
    } 
    //查询“cid”字段存在且非null的条目。
    

    7. nonexist (为空查询)

    • 查询某个字段不存在或为null的条目
    {
    	"nonexist":"cid"
    } 
    //查询“cid”字段不存在或为null的条目
    

    8. range (范围查询)

    • 对单个字段按范围查询,查询条件关系为与。
    {
    	"range": {
    		"amount": {
    			"gt": 3000,
    			"lte": 10000
    		}
    	}
    }//查询amount值大于3000,小于等于10000的条目。
    
    {
    	"range": {
    		"cid": {
    			"gt": "c",
    			"lte": "f"
    		}
    	}
    }//查询cid首字母为d、e和f的条目。
    

    分页命令

    1. size (请求数量)

    • 请求返回的条目数量。
    {
    	"size":1000
    } 
    //请求返回1000条。
    

    2. sort (请求排序)

    • 查询结果的排序条件
    {
    	"sort":{
    		"address":"asc",
    		"cdd":"desc"
    		}
    } 
    //第一级按"address"升序,第二级按cdd降序排列条目。
    

    3. after (上次末位)

    • 定位从某项之后开始获取。
    • 必须与sort一起使用,并且与sort的字段名一一对应。
    • 按照”sort“给出的顺序,从"after"值之后开始获取。
    • 没有“after”则从排序第一项开始获取。
    {
    	"after":["F000000000000",2000]
    } 
    //按照address一级升序和cdd二级降序的排序,从address为F000000000000,cdd为2000之后的那一项开始获取size个条目。
    

    其他规则

    查询命令只能“与”组合

    {
    	"part": {
    		"address": "*cash"
    	},
    	"range": {
    		"cid": {
    			"gt": "c",
    			"lte": "f"
    		}
    	},
    	"sort": {
    		"address": "asc",
    		"cdd": "desc"
    	},
    	"after": ["F000000000000", 2000],
    	"size": 1000
    }
    //查询"address"字段以“cash”结尾,且cid首字母为d、e或f的条目,
    //按"address"一级升序,"cdd"二级降序,从地址为"F000000000000",cdd为2000的条目之后开始,取1000条。
    

    分页命令默认值

    • size、sort、after可省略。
    • sort的默认值由各数据相应协议给出。
    • size默认为20条
    • after默认为空,即从排序首位置开始获取。

Log in to reply