IBM Cloud Docs
获取对数据库中文档的更改

获取对数据库中文档的更改

https://$ACCOUNT.cloudant.com/$DATABASE/_changes 发送 GET 请求 返回对数据库中文档所作的更改 (包括插入,更新和删除) 的列表。

接收到 _changes 请求时,将要求数据库每个分片的一个副本提供更改列表。 这些响应将合并并返回到原始请求客户机。

_changes 端点接受多个可选查询参数:

_changes 端点的查询参数
自变量 描述 支持的值 缺省
conflicts 仅当 include_docstrue 时才能设置。 向每个文档添加有关冲突的信息。 布尔值
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=longpollfeed=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 参数指定预定义的 过滤函数 以应用于更改订阅源。 此外,还提供了多个内置过滤器:

_design

_design 过滤器仅接受对设计文档的更改。

_doc_ids

此过滤器仅接受其标识在 doc_ids 参数中指定的文档的更改。

_selector

返回与 selector 请求主体参数匹配的文档的更改。 选择器语法 与用于 _find的语法相同。 如果要使用选择器过滤器,那么必须使用 POST 更改订阅源 (因为无法向文档主体提供 GET 请求)。 使用 _selector 过滤方法而不是 _view 过滤方法,因为它更快,更容易使用。

更多信息,请参阅 API 文档

_view

允许使用现有 映射函数 作为过滤器。

since 参数

使用 since 参数可获取在指定序列标识之后发生的更改的列表。 如果 since 标识为 0 (缺省值) 或省略,那么请求将返回所有更改。 如果 since 标识为 now,那么请求将要求在当前时间之后进行更改。

IBM Cloudant 的分布式性质会影响您在响应中获得的结果。 例如,如果两次使用相同的 since 序列标识请求更改列表,那么结果列表中的更改顺序可能不相同。

您还可能会看到一些显示在 since 参数之前的结果。 原因是您可能从分片 (分片副本) 的另一个副本中获取结果。

分片副本会自动持续地相互复制,并最终具有相同的数据。 但是,在任何时间点,分片副本可能与另一个分片副本不同,因为它们之间的复制尚未完成。

当您请求更改列表时,通常使用相同的副本来响应。 但是,如果保存分片副本的节点不可用,那么系统将替换保存在另一个节点上的相应分片副本。 为了帮助确保您看到所有适用的更改,将使用副本之间的最新检查点。 使用该检查点实际上是将更改列表“回滚”到分片副本被确认为彼此同意的最近时间点。 此 "回滚" 表示您可能会看到 "在" 您提供的 since 序列标识之前 " 列出的更改。

如果多次发出 _changes 请求,那么应用程序必须能够处理多次报告的更改。

有关 _changes 响应行为的更多信息,请参阅 复制指南

来自 _changes 请求的响应

来自 _changes 请求的响应是一个 JSON 对象,其中包含对数据库中文档所作的更改的列表。 下表描述了各个字段的含义:

变化的 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_idsselector 过滤器,那么唯一的区别是可以在请求主体中包含 "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}