Änderungen in einer verteilten Datenbank

IBM Cloudant verwendet verteilte Datenbanken, die Shard- und fehlertolerante Merkmale aufweisen. Aufgrund dieser Merkmale weichen die von der Anforderung _changes zurückgegebenen Antworten möglicherweise von dem Verhalten ab, das Sie erwarten.

Insbesondere, wenn Sie mit dem Argument _since eine Liste der Änderungen ab einer bestimmten Sequenz-ID anfordern, erhalten Sie als Antwort die angeforderten Informationen. Die Antwort kann allerdings auch Änderungen enthalten, die vor der angegebenen Sequenz-ID vorgenommen wurden. Die Ursache für diese zusätzlichen Änderungen, zusammen mit den Auswirkungen auf Anwendungen, wird im Replikationshandbuch erläutert.

Jede Anwendung, die eine Anforderung _changes verwendet, muss eine Änderungsliste ordnungsgemäß verarbeiten können, wie nachfolgend angegeben:

• Abweichende Reihenfolge der als Antwort aufgelisteten Änderungen im Vergleich zu einer früheren Anforderung der gleichen Informationen.
• Änderungen, die vor der durch die Sequenz-ID angegebenen Änderung vorgenommen wurden.

Das Argument feed

Das Argument feed ändert die Vorgehensweise in IBM Cloudant beim Senden der Antwort. Standardmäßig _changes meldet alle Änderungen, dann wird die Verbindung geschlossen. Dies entspricht dem Ausführungsverhalten des Arguments feed=normal.

Wenn Sie feed=longpoll angegeben haben, bleiben Anforderungen an den Server aktiv, bis die Änderungen zurückgemeldet werden. Diese Option ist hilfreich für die fortlaufende Überwachung der Änderungen.

Wenn Sie feed=continuous festlegen, werden neue Änderungen gemeldet, sobald sie auftreten. Diese Option bedeutet, dass die Datenbankverbindung eine Weile geöffnet bleibt. Die Antwort kann jederzeit enden und die Clients sollten die Verbindung wiederherstellen, wenn sie weiterhin Änderungen empfangen möchten.

Jede Zeile in der kontinuierlichen Antwort ist entweder leer oder sie enthält ein JSON-Objekt, das eine einzelne Änderung darstellt. Diese Option stellt sicher, dass die folgenden Richtlinien eingehalten werden:

• Das Format der Berichtseinträge spiegelt die fortlaufenden Änderungen wider.
• Die Gültigkeit der JSON-Ausgabe bleibt erhalten.

Beispielantwort (gekürzt) für einen Feed mit kontinuierlichen Änderungen:

{
	"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
}

Das Argument filter

Das Argument filter gibt eine vordefinierte Filterfunktion an, die auf den Feed mit Änderungen angewendet werden soll. Außerdem stehen mehrere integrierte Filter zur Verfügung:

_design

Der Filter „ _design “ akzeptiert ausschließlich Änderungen an Designdokumenten.

_doc_ids

Dieser Filter akzeptiert nur Änderungen an Dokumenten, deren ID im Parameter „ doc_ids “ angegeben ist.

_selector

Gibt die Änderungen für Dokumente zurück, die dem Parameter „ selector “ im Anfragetext entsprechen. Die Selektorsyntax entspricht der Syntax, die für _findverwendet wird. Wenn Sie einen Selektorfilter verwenden möchten, müssen Sie den Feed „ POST changes“ nutzen (da Sie bei einer GET-Anfrage keinen Dokumenttext übermitteln können). Verwenden Sie die Filtermethode „ _selector “ anstelle der Filtermethode „ _view “, da sie schneller und einfacher zu handhaben ist.

Weitere Informationen finden Sie in der API-Dokumentation.

_view

Ermöglicht die Verwendung einer vorhandenen Zuordnungsfunktion als Filter.

Das Argument since

Verwenden Sie das Argument since, um eine Liste der Änderungen, die nach einer angegebenen Sequenz-ID aufgetreten sind. Wenn die ID für since auf den Wert '0' (Standardwert) gesetzt oder nicht angegeben ist, gibt die Anforderung alle Änderungen zurück. Wenn die ID für since auf now gesetzt ist, ruft die Anforderung Änderungen ab, die nach der aktuellen Uhrzeit vorgenommen werden.

Die verteilte Struktur von IBM Cloudant kann sich auf die Ergebnisse auswirken, die als Antwort zurückgegeben werden. Wenn Sie beispielsweise eine Änderungsliste unter Verwendung derselben Sequenz-ID im Argument since zweimal anfordern, werden möglicherweise zwei Ergebnislisten mit unterschiedlicher Änderungsreihenfolge zurückgegeben.

Außerdem kann es vorkommen, dass Ergebnisse angezeigt werden, die vor dem Parameter since zu liegen scheinen. Dies ist darauf zurückzuführen, dass möglicherweise Ergebnisse aus einem anderen Shard-Replikat zurückgegeben werden.

Shard-Replikate werden automatisch und fortlaufend repliziert, sodass sie schließlich die gleichen Daten enthalten. An einem bestimmten Zeitpunkt kann der Inhalte eines Shard-Replikats jedoch vom Inhalt eines anderen Shard-Replikats abweichen, da die Replikation noch nicht vollständig abgeschlossen ist.

Wenn Sie eine Änderungsliste anfordern, werden in der Regel die gleichen Replikate für die Antwort verwendet. Wenn der Knoten, der das Shard-Replikat enthält, jedoch nicht verfügbar ist, verwendet das System stattdessen ein entsprechendes Shard-Replikat, das sich auf einem anderen Knoten befindet. Um sicherzustellen, dass alle maßgeblichen Änderungen angezeigt werden, wird der neueste Prüfpunkt zwischen den Replikaten verwendet. Dadurch wird im Grunde die Liste der Änderungen auf den neuesten Zeitpunkt zurückgesetzt, an dem beide Shard-Replikate nachweislich übereingestimmt haben. Durch dieses 'Zurücksetzen' werden Änderungen aufgelistet, die 'vor' der von Ihnen angegebenen Sequenz-ID für since aufgetreten sind.

Wenn Sie eine Anforderung _changes mehrmals übergeben, muss Ihre Anwendung in der Lage sein, eine Änderung zu verarbeiten, die mehr als einmal gemeldet wird.

Weitere Informationen zum Ausführungsverhalten der Antwort für _changes finden Sie im Leitfaden zur Replikation.

Antworten von der Anforderung _changes

Die Antwort von einer Anforderung _changes ist ein JSON-Objekt mit einer Liste der Änderungen, die an Dokumenten in der Datenbank vorgenommen wurden. In der folgenden Tabelle wird die Bedeutung der einzelnen Felder beschrieben:

Beispielantwort (gekürzt) für eine Anforderung _changes:

{
	"results": [
		{
			"seq": "1-g1A...sIg",
			"id": "foo",
			"changes": [
				{
					"rev": "1-967...84d"
				}
			]
		}
	],
	"last_seq": "1-g1A...sIg",
	"pending": 0
}

Wichtige Hinweise zu _changes

• Die von der Anforderung _changes zurückgegebenen Ergebnisse sind nur teilweise geordnet. Mit anderen Worten: Die Reihenfolge wird bei mehreren Aufrufen möglicherweise nicht unverändert beibehalten. Zum Abrufen der aktuellen Liste können Sie bei Bedarf die Anforderung _changes mit dem Wert last_seq angeben. Die resultierende Liste dient als Ausgangspunkt für nachfolgende Anforderungen _changes, in denen das Abfrageargument since verwendet wird.
• Obwohl Shard-Kopien desselben Bereichs dieselben Daten enthalten, ist das zugehörige Protokoll der Änderungen (_changes) häufig eindeutig. Dieser Unterschied ist das Ergebnis der Vorgehensweise beim Anwenden von Schreibvorgängen auf das Shard. Sie können zum Beispiel in einer anderen Reihenfolge angewendet werden. Um sicherzustellen, dass alle Änderungen für Ihre angegebene Sequenz gemeldet werden, kann es erforderlich sein, einen früheren Ausgangspunkt im Shard-Protokoll zu finden, der besser geeignet ist. Die Änderungen werden dann ab diesem Ausgangspunkt gemeldet. Dieses 'Zurücksetzen' kann scheinbar zu doppelten Aktualisierungen führen oder zu Aktualisierungen, die anscheinend vor dem angegebenen Wert für since liegen.
• Von einem Shard gemeldete Änderungen (_changes) werden immer geordnet aufgelistet. Die Reihenfolge aller beitragenden Shards kann jedoch scheinbar abweichen. Weitere Informationen finden Sie unter Ein Beispiel für einen „Changes“-Feed.
• Die Sequenzwerte in einem Shard sind eindeutig, die Werte zwischen mehreren Shards können jedoch abweichen. Aufgrund dieser Abweichungen kann nicht davon ausgegangen werden, dass der gleiche Sequenzwert in verschiedenen Shards jeweils auf dasselbe Dokument in den verschiedenen Shards verweist.

Änderungen mit einer POST-Anforderung abrufen

Anstelle von GET kann auch POST verwendet werden, um den Feed mit Änderungen abzurufen. Der einzige Unterschied bei Verwendung von POST mit dem Filter docs_ids oder selector besteht darin, dass die Elemente "doc_ids" : [...] oder "selector": {...} im Anforderungshauptteil angegeben werden können. Alle anderen Parameter werden in der Abfragezeichenfolge erwartet, wie bei der Verwendung von GET.

Im folgenden Beispiel wird eine POST-Anforderung an den Endpunkt _changes unter Verwendung von HTTP gesendet:

POST /$DATABASE/_changes?filter=_selector HTTP/1.1
Host: $ACCOUNT.cloudant.com
Content-Type: application/json

Sehen Sie sich das folgende Beispiel für POST für den Endpunkt _changes an:

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))

Das vorherige Go-Beispiel erfordert den folgenden Importblock:

import (
   "encoding/json"
   "fmt"
   "github.com/IBM/cloudant-go-sdk/cloudantv1"
)

Für alle Go-Beispiele muss das Objekt service initialisiert sein. Weitere Informationen finden Sie in den Beispielen im Abschnitt 'Authentifizierung' in der API-Dokumentation.

Eine POST-Anforderung für den Endpunkt _changes kann zum Beispiel das folgende JSON-Objekt zurückgeben:

{"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}

Seitenaufteilung

Verwenden Sie den Parameter since wie ein Lesezeichen, um den Änderungsfeed zu paginieren. Spezifische Einzelheiten und Beispiele finden Sie in der API-Dokumentation unter Paging the changes feed.