获取对数据库中文档的更改
向 https://$ACCOUNT.cloudant.com/$DATABASE/_changes
发送 GET
请求 返回对数据库中文档所作的更改 (包括插入,更新和删除) 的列表。
接收到 _changes
请求时,将要求数据库每个分片的一个副本提供更改列表。 这些响应将合并并返回到原始请求客户机。
_changes
端点接受多个可选查询参数:
自变量 | 描述 | 支持的值 | 缺省 |
---|---|---|---|
conflicts |
仅当 include_docs 为 true 时才能设置。 向每个文档添加有关冲突的信息。 |
布尔值 | 错 |
descending |
按顺序返回更改。 | 布尔值 | 错 |
doc_ids |
仅当 filter 设置为 _doc_ids 时使用。 过滤订阅源,以便仅发送对指定文档的更改。 注: doc_ids 参数仅适用于与 CouchDB 2.0兼容的 IBM Cloudant 版本。 有关更多信息,请参阅 GET / 文档。 |
文档标识的 JSON 数组 | |
feed |
需要的订阅源类型。 有关更多信息,请参阅 feed 信息。 |
"continuous" , "longpoll" , "normal" |
"normal" |
filter |
用于获取更新的 过滤器函数 的名称。 过滤器在 设计文档 中定义。 | string |
无过滤器。 |
heartbeat |
如果在 feed=longpoll 或 feed=continuous 期间未发生任何更改,那么将在此时间之后发送空行 (以毫秒计)。 |
任何正数 | 无脉动信号 |
include_docs |
包含文档作为结果的一部分。 | 布尔值 | 错 |
limit |
要返回的最大行数。 | 任何非负数 | 无 |
seq_interval |
指定响应中包含 seq 值的频率。 设置更高的值以增加 _changes 的吞吐量并减小响应大小。 注: 在非连续 _changes 方式下,将始终填充 last_seq 值。 |
任何正数 | 1 |
since |
在指定的序列标识之后启动更改结果。 有关更多信息,请参阅 since 信息。 |
序列标识或 now |
0 |
style |
指定在更改数组中返回的修订版数。 main_only 样式仅返回当前“获胜”修订版。 all_docs 样式返回所有叶修订版,包括冲突和已删除的先前冲突。 |
main_only , all_docs |
main_only |
timeout |
等待此数毫秒的数据,然后停止响应。 如果还提供了 heartbeat 设置,那么它优先于 timeout 设置。 |
任何正数 |
使用 include_docs=true
可能会产生 性能影响。
请参阅以下示例,该示例使用 HTTP 来获取对数据库中文档所作的更改的列表:
GET /$DATABASE/_changes HTTP/1.1
请参阅以下示例以获取对数据库中的文档进行的更改的列表:
curl -H "Authorization: Bearer $API_BEARER_TOKEN" -X GET "$SERVICE_URL/orders/_changes?limit=1"
分布式数据库中的更改
IBM Cloudant 数据库已分发。 它们具有分片和容错特性。 这些特征表示 _changes
请求提供的响应可能与您期望的行为不同。
尤其是,如果您要求提供更改列表 _since
序列标识,那么您将在响应中获取所请求的信息。 但是,您可能还会获得在序列标识指示的更改之前进行的更改。 包含这些额外更改的原因以及对应用程序的影响在以下内容中进行了说明:
复制指南。
使用 _changes
请求的任何应用程序都必须能够正确处理更改列表,如以下列表中所示:
- 与先前针对相同信息的请求相比,响应中列出的更改的顺序不同。
- 在序列标识指定的更改之前发生的更改。
feed
参数
feed
参数会更改 IBM Cloudant 发送响应的方式。 By default,
_changes
报告所有更改,然后关闭连接。 此行为与使用 feed=normal
参数相同。
如果设置 feed=longpoll
,那么发送到服务器的请求将保持打开状态,直到报告更改为止。 此选项有助于持续监视更改。
如果设置了 feed=continuous
,那么将在发生新更改时报告这些更改。 此选项表示数据库连接保持打开一段时间。 响应可能随时结束,如果客户希望继续接收更改,那么应重新连接。
连续响应中的每一行都为空或表示单个更改的 JSON 对象。 该选项确保满足以下准则:
- 报告条目的格式反映了更改的连续性质。
- 保留 JSON 输出的有效性。
请参阅来自连续更改订阅源的以下示例 (缩写) 响应:
{
"seq": "1-g1A...qyw",
"id": "2documentation22d01513-c30f-417b-8c27-56b3c0de12ac",
"changes": [
{
"rev": "1-967a00dff5e02add41819138abb3284d"
}
]
},
{
"seq": "2-g1A...ssQ",
"id": "1documentation22d01513-c30f-417b-8c27-56b3c0de12ac",
"changes": [
{
"rev": "1-967a00dff5e02add41819138abb3284d"
}
]
},
{
"seq": "3-g1A...qyy",
"id": "1documentation22d01513-c30f-417b-8c27-56b3c0de12ac",
"changes": [
{
"rev": "2-eec205a9d413992850a6e32678485900"
}
],
"deleted": true
},
{
"seq": "4-g1A...qyz",
"id": "2documentation22d01513-c30f-417b-8c27-56b3c0de12ac",
"changes": [
{
"rev": "2-eec205a9d413992850a6e32678485900"
}
],
"deleted": true
}
filter
参数
filter
参数指定预定义的
过滤函数 以应用于更改订阅源。 此外,还提供了多个内置过滤器:
since
参数
使用 since
参数可获取在指定序列标识之后发生的更改的列表。 如果 since
标识为 0 (缺省值) 或省略,那么请求将返回所有更改。 如果 since
标识为 now
,那么请求将要求在当前时间之后进行更改。
IBM Cloudant 的分布式性质会影响您在响应中获得的结果。 例如,如果两次使用相同的 since
序列标识请求更改列表,那么结果列表中的更改顺序可能不相同。
您还可能会看到一些显示在 since
参数之前的结果。 原因是您可能从分片 (分片副本) 的另一个副本中获取结果。
分片副本会自动持续地相互复制,并最终具有相同的数据。 但是,在任何时间点,分片副本可能与另一个分片副本不同,因为它们之间的复制尚未完成。
当您请求更改列表时,通常使用相同的副本来响应。 但是,如果保存分片副本的节点不可用,那么系统将替换保存在另一个节点上的相应分片副本。 为了帮助确保您看到所有适用的更改,将使用副本之间的最新检查点。 使用该检查点实际上是将更改列表“回滚”到分片副本被确认为彼此同意的最近时间点。 此 "回滚" 表示您可能会看到 "在" 您提供的 since
序列标识之前 " 列出的更改。
如果多次发出 _changes
请求,那么应用程序必须能够处理多次报告的更改。
有关 _changes
响应行为的更多信息,请参阅
复制指南。
来自 _changes
请求的响应
来自 _changes
请求的响应是一个 JSON 对象,其中包含对数据库中文档所作的更改的列表。 下表描述了各个字段的含义:
字段 | 描述 | Type |
---|---|---|
changes |
一个数组,用于列出对特定文档所作的更改。 | Array |
deleted |
指示是否已删除相应文档的布尔值。 如果存在,那么它始终具有值 true 。 |
布尔值 |
id |
文档标识。 | 字符串 |
last_seq |
最后一个序列标识的标识。 目前,此标识与 results 中最后一个项的序列标识相同。 |
字符串 |
results |
对数据库进行的更改的数组。 | Array |
seq |
更新序列标识。 | 字符串 |
请参阅以下示例 (缩写) 对 _changes
请求的响应:
{
"results": [
{
"seq": "1-g1A...sIg",
"id": "foo",
"changes": [
{
"rev": "1-967...84d"
}
]
}
],
"last_seq": "1-g1A...sIg",
"pending": 0
}
有关 _changes
的重要说明
_changes
返回的结果将部分排序。 换言之,对于多个调用,可能不会保留该顺序。 您可以决定使用_changes
并包含last_seq
值 来获取当前列表。 生成的列表提供了使用since
查询自变量的后续_changes
列表的起始点。- 虽然相同范围的分片副本包含相同的数据,但其
_changes
历史记录通常是唯一的。 此差异是对分片应用写操作的结果。 例如,它们可能以不同的顺序应用。 要确保针对指定序列报告所有更改,可能需要进一步返回到分片的历史记录以找到合适的起始点。 然后从该起始点报告更改。 此“回滚”可能会显示重复的更新或明显早于指定since
值的更新。 - 分片报告的
_changes
始终按顺序显示。 但是,所有添加片段之间的顺序可能不同。 有关更多信息,请参阅 更改订阅源示例。 - 序列值对于分片是唯一的,但可能因分片而异。 此变体表示,如果您具有来自不同分片的序列值,那么不能假定同一序列值引用不同分片中的同一文档。
使用 POST
获取更改
您还可以使用 POST
来查询更改订阅源,而不是 GET
。 如果您正在使用 POST
并且正在使用 docs_ids
或 selector
过滤器,那么唯一的区别是可以在请求主体中包含 "doc_ids" : [...]
或 "selector": {...}
部分。 所有其他参数都应该位于查询字符串中,与使用 GET
的参数相同。
请参阅以下使用 HTTP 到 POST
到 _changes
端点的示例:
POST /$DATABASE/_changes?filter=_selector HTTP/1.1
Host: $ACCOUNT.cloudant.com
Content-Type: application/json
请参阅 POST
到 _changes
端点的以下示例:
curl -H "Authorization: Bearer $API_BEARER_TOKEN" -X POST "$SERVICE_URL/orders/_changes" -H "Content-Type: application/json"'
import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.ChangesResult;
import com.ibm.cloud.cloudant.v1.model.PostChangesOptions;
Cloudant service = Cloudant.newInstance();
PostChangesOptions changesOptions = new PostChangesOptions.Builder()
.db("orders")
.build();
ChangesResult response =
service.postChanges(changesOptions).execute()
.getResult();
System.out.println(response);
import { CloudantV1 } from '@ibm-cloud/cloudant';
const service = CloudantV1.newInstance({});
service.postChanges({
db: 'orders'
}).then(response => {
console.log(response.result);
});
from ibmcloudant.cloudant_v1 import CloudantV1
service = CloudantV1.new_instance()
response = service.post_changes(
db='orders'
).get_result()
print(response)
postChangesOptions := service.NewPostChangesOptions(
"orders",
)
changesResult, response, err := service.PostChanges(postChangesOptions)
if err != nil {
panic(err)
}
b, _ := json.MarshalIndent(changesResult, "", " ")
fmt.Println(string(b))
先前的 Go 示例需要以下导入块:
import (
"encoding/json"
"fmt"
"github.com/IBM/cloudant-go-sdk/cloudantv1"
)
所有 Go 示例都需要初始化 service
对象。 有关更多信息,请参阅 API 文档的 认证部分 以获取示例。
POST
到 _changes
端点时,您会看到类似于以下 JSON 对象的示例:
{"results":[
{"seq":"1-g1AAAA...","id":"0007741142412418284","changes":[{"rev":"1-9d0c2676941ec3a3b3cc2f08fe9a51e0"}]},
{"seq":"2-g1AAAA...","id":"_design/applianceId","changes":[{"rev":"1-b1f67a8b672c1324680d6d7dc1e1fd3c"}]},
...
],
"last_seq":"18-g1AAAA...","pending":0}