取得資料庫中文件的變更

分散式資料庫中的變更

IBM Cloudant 資料庫已配送。 它們具有 Shard 及容錯性質。 這些性質表示 _changes 要求所提供的回應可能不同於您預期的行為。

特別是，如果您要求 _since 順序 ID 的變更清單，則會在回應中取得所要求的資訊。 但您也可以取得在序列 ID 所指示的變更之前所做的變更。 包含這些額外變更的原因，以及應用程式的含意，說明於 抄寫手冊。

任何使用 _changes 要求的應用程式都必須能夠正確處理變更清單，如下列清單所示:

• 與相同資訊的先前要求相比時，回應中列出的變更順序不同。
• 在序列 ID 指定的變更之前發生的變更。

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 引數指定預先定義的 過濾函數，以套用至 changes 資訊來源。 此外，還有數個內建過濾器可用:

_design

_design 過濾器只接受設計文件的變更。

_doc_ids

此過濾器只接受 doc_ids 參數中指定其 ID 之文件的變更。

_selector

傳回符合 selector 要求內文參數之文件的變更。 selector 語法 與 _find所用的語法相同。 如果您想要使用選取元過濾器，則必須使用 POST changes 資訊來源 (因為您無法提供具有 GET 要求的文件內文)。 請使用 _selector 方法來過濾，而不使用 _view 過濾方法，因為它更快速且更容易使用。

有關更多信息，請參閱 API 文件。

_view

啟用現有 對映函數 作為過濾器。

since 引數

使用 since 引數來取得在指定序列 ID 之後發生的變更清單。 如果 since ID 為 0 (預設值) 或省略，則要求會傳回所有變更。 如果 since ID 為 now，則要求會要求在現行時間之後進行變更。

IBM Cloudant 的分散式本質可能會影響您在回應中取得的結果。 例如，如果您兩次使用相同的 since 序列 ID 來要求變更清單，則結果清單中的變更順序可能不相同。

您也可能看到部分結果似乎來自 since 參數之前。 原因是您可能從 Shard 的不同抄本 (Shard 抄本) 取得結果。

Shard 抄本會自動且持續彼此抄寫，最後具有相同的資料。 不過，在任何時間點，Shard 抄本可能與另一個 Shard 抄本不同，因為它們之間的抄寫尚未完成。

當您要求變更清單時，通常會使用相同的抄本來回應。 但如果保留 Shard 抄本的節點無法使用，系統會替換在另一個節點上保留的對應 Shard 抄本。 為了協助確保您看到所有適用的變更，會使用抄本之間的最新檢查點。 使用檢查點實際上是將變更清單「回復」至最近確認 Shard 抄本彼此同意的時間點。 這個「回復」表示您可能會在「您提供的 since 序列 ID 之前」看到所列出的變更。

如果您多次提出 _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 清單的起始點。
• 雖然相同範圍的 Shard 副本包含相同的資料，但其 _changes 歷程通常是唯一的。 此差異是寫入套用至 Shard 的方式的結果。 例如，它們可能以不同的順序套用。 為了確保報告所指定順序的所有變更，可能需要進一步回到 Shard 的歷程，以尋找適當的起始點。 然後會從該起始點報告變更。 這個「回復」可能會出現重複的更新項目，或明顯在指定 since 值之前的更新項目。
• Shard 所報告的 _changes 一律依順序呈現。 但所有貢獻 Shard 之間的排序可能看起來不同。 如需相關資訊，請參閱 變更資訊來源範例。
• 序列值對於 Shard 而言是唯一的，但在 Shard 之間可能有所不同。 此變異表示如果您有來自不同 Shard 的序列值，則無法假設相同的序列值會參照不同 Shard 內的相同文件。

使用 POST 來取得變更

您也可以使用 POST 來查詢 changes 資訊來源，而不使用 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}