分布式数据库中的更改

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 对象，其中包含对数据库中文档所作的更改的列表。 下表描述了各个字段的含义:

请参阅以下示例 (缩写) 对 _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}