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》。
接口标识
- 通用标识
接口名称@PID#[所属APIP协议的PID]
- 简化标识
接口名称@协议类型+协议编号
简化标识不一定唯一,主要便于人类记忆和识别,重要场景或机器识别应采用唯一标识。
- 示例:
APIP1的balance接口的通用标识为:balance@PID#[APIP1协议文本的哈希值,待确认]
简化标识为:balance@APIP1
。
接口url的构成
接口的url分为两部分:urlHead
和urlTail
。
- 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/
- urlTail
urlTail
是该API服务方按照APIP协议,在链上发布API服务时声明的具体接口的具体位置。格式为:
apip[协议编号]/v[版本号]/[接口名称]
示例:
apip1/v1/connect
- url
接口的完整url = urlHead + urlTail
示例:
https://www.sign.cash/api/apip1/v1/connect
时间戳格式
APIP协议涉及的时间戳,若无特定说明,默认为13位,精确到毫秒
。
来自Freecash区块数据的时间戳为10位。
密码算法
哈希算法
无特殊说明,哈希算法采用两次sha256算法,即:sha256(sha256(byte[] message_bytes))
,哈希值为Hex,字母为小写.
加密算法
无特殊说明,文本和文件加解密采用ECC256k1-AESCBC算法,协议PID为[待开发完成后发布]。
签名算法
-
对称密码签名:无特殊说明,对称密码签名验证采用数据加入sessionKey后序列化,做两次sha256哈希算法得到签名。
-
非对称密码签名:无特殊说明,非对称密码签名验证采用椭圆曲线算法(ECDSA)算法,以签发者私钥对数据进行签名,协议PID为[待开发完成后发布]。
示例身份信息
APIP协议默认采用以下请求方身份信息:
requester
:FEk41Kqjar45fLDriztUDTUkdki7mmcjWK
requester的公钥pubKey
:030be1d7e633feb2338a74a860e76d893bac525f35a5813cb7b21e27ba1bc8312a
requester的私钥priKey
:L2bHRej6Fxxipvb4TiR5bu1rkT3tRp8yWEsUy4R1Zb8VMm2x7sd8
requester获得的对称密钥sessionKey
:d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09
API服务流程
按照APIP协议,服务方
(API服务的提供者,简称APISP)为请求方
(API服务的使用者,APP或用户个人)提供API服务的一般流程为:
- 服务方 开发部署API服务
服务方选择一个或多个链上注册的APIP协议,开发和部署相应的API服务。
- 服务方 链上注册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”]
"protocols": [string array, 所遵循的协议]
"urls": [string array, API的url的首部]
"pubKeyAdmin": "02966dc682850550b1df046f2a03cfe546c4e4cf83f739d1497f6c292fabdad1b4",
"params":{
"urlHead": [string, API访问位置的共同部分,如http://sign.cash/api/],
"account":[string,收款账号,缺省为发布者FCH'地址],
"currency": [string,支付的币种,缺省为FCH,法币则遵循ISO4217,如'CNY'],
"pricePerRequest": [float, 每次请求的服务收费,采用选用货币的标准单位],
"minPayment": [float, 最低单次购买金额,采用选用货币的标准单位]
}
}
- 请求方 链上查询API服务
请求方在链上查询自己所需要的API服务方,获得订购方式(receivingAccount,pricePerRequest,minPayment,currency)和API路径的共同部分(urlHead)。
- 请求方 链下订购API服务
请求方按照订购方式,向服务方订购API服务。服务方记录请求方的身份(FCH地址)和充值余额,开始服务。
- 请求方 发出连接服务请求
请求方通过connect接口,向服务方发起包含自身pubKey的连接请求和私钥签名,以获得后续数据请求使用的对称密钥sessionKey
,详情参见[##connect接口](##connect接口)。
- 服务方 验证请求分配密钥
服务方对请求进行安全验证后,发放用请求方pubKey加密的对称密钥sessionKey。具有相同urlHead的接口共用同一个sessionKey。
- 请求方 解密保存sessionKey
请求方用自己的私钥priKey解密密文,获得sessionKey,保存用于后续数据请求。
1-7步骤的流程图:

- 请求方 发出数据服务请求
请求方根据自身数据需求,选择服务方的对应接口,构造API的url和请求参数并签名后,向服务方发出数据请求。详情参见[##数据服务接口](##数据服务接口)
- 服务方 验证请求返回数据
服务方收到请求后,进行安全验证无误后,返回响应数据和签名给请求方。
- 请求方 验证签名接受数据
请求方收到响应数据后,验证签名是否无误则接受数据,服务完成。
8-10的流程图:

谁是API的请求方
APP有两种请求方
设定逻辑:
1.用户作为请求方
-
1)用户通过APP或其他途径用自己的FCH地址购买服务。
-
2)用户进入APP需要获取数据时,用自己的私钥签名发起connect连接请求。
-
3)APP为用户在本地保存sessionKey,用于向API服务方发起数据请求。
-
4)特点:符合密码经济中“用户掌握数据”的安全准则,减少对APP的依赖,更加安全、开放、去中心化。
2.APP作为请求方
-
1)APP发布者用自己的地址向API服务方购买服务,获得sessionKey。
-
2)用户使用APP时,所需要的数据由APP向API服务方提出请求。
-
3)特点:符合传统开发习惯,便于APP运营者掌控数据,有中心化风险。
如何购买API服务
请求方购买API服务的方式由服务方在链上注册服务时,在data.desc
字段描述,在data.params
字段给出相关参数。服务方未特殊声明,则默认采用以下方式:
- 服务方链上注册服务时在data.params中声明收费信息
{
"urlHead": [string, API访问位置的共同部分,如http://sign.cash/api/],
"account":[string,收款账号,缺省为发布者FCH'地址],
"currency": [string,支付的币种,缺省为FCH,法币则遵循ISO4217,如'CNY'],
"pricePerRequest": [float, 每次请求的服务收费,采用选用货币的标准单位],
"minPayment": [float, 最低单次购买金额,采用选用货币的标准单位]
}
-
请求方链上获取收费信息的两种方式
-
请求方链上购买服务的两种方式
-
请求方的购买标记
,即购买交易的OP_RETURN内容,如下:
{
"type": "APIP"
"sn": 1,
"ver": 1,
"name": "OpenAPI",
"pid": [string, FEIP1V7 协议文本的双sha256哈希值,该协议正式发布前暂时留空],
"data": {
"op":"buy",
"sid":[string,所购买服务的sid,必填]
}
}
-
API服务方启动服务
-
API服务方收到有购买标记的交易后,自动登记第一个输入的FCH地址为用户ID,并登记余额,开始服务。
-
请求方的每次请求按pricePerRequest
计减余额。
-
余额一旦小于pricePerRequest
则服务终止,删除该用户信息,以防止用户信息累计过多,并防止与此相关的攻击。
connect接口
connect接口用来向服务方申请获得sessionKey,sessionKey用于后续数据请求的签名和验证。
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 |
time |
time stamp |
精确到毫秒的时间戳,防止重放攻击 |
Y |
sign |
string |
用请求方私钥priKey对序列化后的其他参数的签名,防止身份伪造 |
Y |
请求方用自己的私钥priKey对除sign之外的请求参数序列化后,进行签名,得到sign,加入请求json。
请求参数
{
"pubKey": "030be1d7e633feb2338a74a860e76d893bac525f35a5813cb7b21e27ba1bc8312a",
"url": "https://www.sign.cash/api/apip1/v1/connect",
"time": 1635513688254,
"sign": "H6d+wvrsj5Bgh4Y2GeOFujYvXijMK1FG97bSDd7zaX8VY78X3a2Ey2Success.wpyo5ASiwWA8cW6gP1rejWjZMbPcS3k\u003d"
}
其中,sign为私钥priKey(L2bHRej6Fxxipvb4TiR5bu1rkT3tRp8yWEsUy4R1Zb8VMm2x7sd8)对序列化后的其他请求参数({"pubKey":"030be1d7e633feb2338a74a860e76d893bac525f35a5813cb7b21e27ba1bc8312a","time":"1635513688254","url":"https://www.sign.cash/api/apip1/v1/connect"})所做的签名。
请求方保存API服务信息
请求方为其使用的每个APIP协议,分别保存以下信息:
信息名称 |
类型 |
说明 |
必填 |
sid |
string |
接口服务的SID,即服务方在链上注册服务时的txid |
Y |
pid |
string |
APIP协议的PID |
N |
title |
string |
APIP协议的标题,如:APIP1V1_OpenAPI(zh-CN) |
N |
sn |
int |
APIP协议编号 |
Y |
ver |
int |
APIP协议版本号 |
Y |
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 |
sessionKey |
string |
当前生效的sessionKey,相同urlHead的各接口使用同一个sessionKey |
N |
sessionName |
string |
sessionKey的双sha256哈希值的后6字节base64编码,请求时代表请求方 |
N |
time |
time stamp |
当前生效的sessionKey获得的时间戳 |
N |
days |
int |
当前生效的sessionKey的有效天数 |
N |
apiBalance |
int64 |
请求方当前服务余额 |
all |
5. 响应
-
验证请求。服务方对请求依次验证:
-
1)验证用户。验证requester是否在用户列表中,用户列表由余额大于pricePerRequest的FCH地址构成。不在列表返回1000.
-
2)验证请求对象。验证签名内容中的“url”值是否与服务方当前接口的url相同,防止重放攻击。不同则返回1001
-
3)验证时间戳。验证当前时间戳减time的绝对值是否小于服务方设定的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.sessionKeyEncrypted |
string |
sessionKey的密文 |
0 |
data.days |
int |
sessionKey的有效天数 |
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 |
设服务方验证请求无误后,为该请求方分配sessionKey
为:"d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09"。
请求方公钥pubKey
为:"030be1d7e633feb2338a74a860e76d893bac525f35a5813cb7b21e27ba1bc8312a"。
则响应参数为:
{
"code": "0",
"message": "Success.",
"data": {
"sessionKeyEncrypted": "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地址未保存,则视为新用户。 |
sessionName |
string |
sessionKey的双sha256哈希值的后6字节base64编码,请求时代表请求方 |
sessionKey |
string |
该用户当前的sessionKey |
time |
int |
当前sessionKey发放时间,用于控制连接的有效期 |
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 |
请求方的sessionName |
Y |
url |
string |
当前所请求api的url |
Y |
time |
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协议规定。
将sessionKey
加入除sign以外的其他请求参数并序列化后,做两次sha256计算,获得sign
。
查询address包含“armX”,且1000<amount<=2000的条目,按amount升序排列,取前20条。
请求参数parameters
:
{
"requester": "1111111111",
"time": 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)验证时间戳。验证当前时间戳减请求参数中time
的绝对值是否小于服务方设定的windowTime,防止重放攻击。过期返回1002.
-
4)验证sessionKey
时效。检查服务器保存的requeter的sessionKey是否过期。过期返回1004.
-
5)验证签名。在请求参数中加入requester的sessionKey
做两次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 sessionKey has expired, please connect again. |
sessionKey过期,请重新连接 |
|
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 |
将sessionKey加入响应参数做两次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.","sessionKey":"d2c03bbc1ba1380eafc395374e8da61f92545a1aac5d30b0c19289a69bd34a09"}))
= 2f09d2f1af3432063969147b9eb156fe434ed728f52f19c975d7ddca4c6bd816
6. 请求方验证响应数据
请求方收到数据后,取出sign,加入sessionKey
序列化后,做两次sha256哈希,与sign值相比较,一致则接受数据。以防止中间人攻击。
7. 请求方重置sessionKey
请求方在1)希望重置sessionKey,或2)收到错误码1004,sessionKey过期时,或3)收到错误码1000,并完成充值时,用connect
接口申请新的sessionKey。
APIP简易查询语法
- 通用语法仅实现简单查询功能,复杂查询功能语法由API服务商自行定义和发布。
查询命令
1. all (全查询)
{
"all":{}
}
//查询所有条目。
2. ids (id查询)
{
"ids":["0000000000000","1111111111111"]
}查询id为"1111111111"或"22222222222"的条目
3. terms (精确查询)
{
"terms":{
"querys":["0000000000000","1111111111111"],
"fields":["pid","sid"]
}
} //查询字符串字段“address”值为"F000000000000"或"F111111111111"的条目。
{
"terms":{
"querys":["1000","2000"],
"fields":["cd","cdd"]
}
} //查询整数字段“fee”的值为"1000"或"2000"的条目。
4. part (部分查询)
- 对单一字段,搜索包含特定值的条目,可使用通配符*和?。
{
"part":{
"query":"arm?*“,
"fields":["addr","cid"]
}
} //查询“address”字段值以“‘arm’加一个任意字符”开头的条目。
5. match (模糊查询)
{
"match":{
"query":"good bad",
"fields":["article","post","reply"]
}
}
//在"article","post"和"reply"字段中,模糊查询包含’good‘或’bad‘(不区分大小写)的条目,并给出评分。
6. exist (非空查询)
{
"exist":"cid"
}
//查询“cid”字段存在且非null的条目。
7. nonexist (为空查询)
{
"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": {
"query":"*cash",
"fields":["addr"]
},
"range": {
"cid": {
"gt": "c",
"lte": "f"
}
},
"sort": {
"address": "asc",
"cdd": "desc"
},
"after": ["F000000000000", 2000],
"size": 1000
}
//查询"addr"字段以“cash”结尾,且cid首字母为d、e或f的条目,
//按"address"一级升序,"cdd"二级降序,从地址为"F000000000000",cdd为2000的条目之后开始,取1000条。
分页命令默认值
- size、sort、after可省略。
- sort的默认值由各数据相应协议给出。
- size默认为20条
- after默认为空,即从排序首位置开始获取。