Modifiche in un database distribuito

Sono distribuiti IBM Cloudant database. Hanno caratteristiche di shard e fault-tolerant. Queste caratteristiche indicano che le risposte fornite dalla richiesta _changes potrebbero essere diverse dal comportamento previsto.

In particolare, se si richiede un elenco di modifiche _since un identificativo di sequenza, si ottengono le informazioni richieste in risposta. Ma è anche possibile ottenere le modifiche che sono state apportate prima della modifica indicata dall'identificativo della sequenza. Il motivo per cui queste modifiche aggiuntive sono incluse, insieme alle implicazioni per le applicazioni, è spiegato nel Guida di replica.

Qualsiasi applicazione che utilizza la richiesta _changes deve essere in grado di elaborare correttamente un elenco di modifiche come mostrato nel seguente elenco:

• Un ordine differente per le modifiche elencate nella risposta, rispetto a una richiesta precedente per le stesse informazioni.
• Le modifiche che si verificano prima della modifica specificata dall'identificatore sequenza.

L'argomento feed

L'argomento feed modifica il modo in cui la risposta viene inviata da IBM Cloudant. Per impostazione predefinita, _changes riporta tutte le modifiche, quindi la connessione viene chiusa. Questo comportamento è uguale all'utilizzo dell'argomento feed=normal.

Se si imposta feed=longpoll, le richieste inviate al server restano aperte fino a quando non vengono riportate le modifiche. Questa opzione è utile quando il monitoraggio cambia continuamente.

Se si imposta feed=continuous, le nuove modifiche vengono riportate man mano che si verificano. Questa opzione indica che la connessione al database rimane aperta per un certo tempo. La risposta può terminare in qualsiasi momento e i client devono riconnettersi se desiderano continuare a ricevere le modifiche.

Ogni riga nella risposta continua è vuota o un oggetto JSON che rappresenta una singola modifica. L'opzione garantisce il rispetto delle linee guida seguenti:

• Il formato delle voci del report riflette la natura continua delle modifiche.
• La validità dell'output JSON viene mantenuta.

Vedere il seguente esempio (abbreviato) di risposte da un feed di modifiche continue:

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

L'argomento filter

L'argomento filter indica un valore predefinito funzione filtro da applicare al feed delle modifiche. Inoltre, sono disponibili diversi filtri integrati:

_design

Il filtro _design accetta solo modifiche ai documenti di progetto.

_doc_ids

Questo filtro accetta solo le modifiche per i documenti il cui ID è specificato nel parametro doc_ids.

_selector

Restituisce le modifiche per i documenti che corrispondono al parametro del corpo della richiesta selector. La sintassi del selettore è uguale alla sintassi utilizzata per _find. Se si desidera utilizzare un filtro selettore, è necessario utilizzare il feed delle modifiche di POST (poiché non è possibile fornire un corpo del documento con una richiesta GET). Utilizzare il metodo _selector di filtraggio invece del metodo di filtro _view perché è più veloce e più facile da utilizzare.

Per ulteriori informazioni, consultare la documentazione dell'API.

_view

Abilita l'utilizzo di una funzione mappa esistente come filtro.

L'argomento since

Utilizzare l'argomento since per ottenere un elenco di modifiche che si sono verificate dopo un identificativo di sequenza specificato. Se l'identificativo since è 0 (il valore predefinito) o omesso, la richiesta restituisce tutte le modifiche. Se l'identificativo since è now, la richiesta richiede le modifiche apportate dopo l'ora corrente.

La natura distribuita di IBM Cloudant può influenzare i risultati che ottieni in risposta. Ad esempio, se si richiede un elenco di modifiche due volte, utilizzando lo stesso identificativo di sequenza since per entrambe le volte, l'ordine delle modifiche nell'elenco risultante potrebbe non essere lo stesso.

È anche possibile visualizzare alcuni risultati che sembrano provenire da prima del parametro since. Il motivo è che potresti ottenere i risultati da una replica diversa di un frammento (una replica del frammento).

Le repliche dei frammenti vengono replicate automaticamente e continuamente l'una sull'altra e alla fine hanno gli stessi dati. Tuttavia, in qualsiasi momento, una replica del frammento potrebbe differire da un'altra replica del frammento perché la replica tra loro non è ancora completa.

Quando si richiede un elenco di modifiche, di solito vengono utilizzate le stesse repliche per rispondere. Ma se il nodo che contiene la replica del frammento non è disponibile, il sistema sostituisce una replica del frammento corrispondente che si trova su un altro nodo. Per essere certi di visualizzare tutte le modifiche applicabili, viene utilizzato il punto di controllo più recente tra le repliche. L'utilizzo del checkpoint è effettivamente "rollback" dell'elenco delle modifiche al momento più recente in cui è stato confermato che le repliche del frammento sono concordi tra loro. Questo "rollback" indica che è possibile visualizzare le modifiche elencate che hanno avuto luogo "prima" dell'identificativo di sequenza since fornito.

L'applicazione deve essere in grado di gestire una modifica riportata più di una volta se si effettua una richiesta _changes più volte.

Per ulteriori informazioni sul comportamento della risposta _changes, consultare guida di replica.

Risposte dalla richiesta _changes

La risposta da una richiesta _changes è un oggetto JSON che contiene un elenco delle modifiche apportate ai documenti all'interno del database. La seguente tabella descrive il significato dei singoli campi:

Vedi il seguente esempio (abbreviato) di risposta a una richiesta _changes:

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

Note importanti su _changes

• I risultati restituiti da _changes sono parzialmente ordinati. In altre parole, l'ordine potrebbe non essere conservato per più chiamate. È possibile decidere di ottenere un elenco corrente utilizzando _changes e includendo il valore last_seq. L'elenco risultante fornisce il punto di partenza per gli elenchi _changes successivi che utilizzano l'argomento query since.
• Sebbene le copie di frammenti dello stesso intervallo contengano gli stessi dati, la loro cronologia _changes è spesso univoca. Questa differenza è il risultato di come le scritture sono state applicate al frammento. Ad esempio, potrebbero essere applicati in un ordine diverso. Per essere certi che tutte le modifiche vengano riportate per la sequenza specificata, potrebbe essere necessario tornare indietro nella cronologia del frammento per trovare un punto di partenza adatto. Le modifiche vengono quindi riportate da quel punto di partenza. Questo "rollback" potrebbe dare l'aspetto di aggiornamenti duplicati o aggiornamenti apparentemente prima del valore since specificato.
• _changes riportati da un frammento sono sempre presentati in ordine. Ma l'ordine tra tutti i frammenti che contribuiscono potrebbe sembrare diverso. Per ulteriori informazioni, consultare Esempio di feed delle modifiche.
• I valori di sequenza sono univoci per un frammento, ma possono variare tra i frammenti. Questa variazione indica che, se si dispone di valori di sequenza da frammenti differenti, non è possibile presumere che lo stesso valore di sequenza si riferisca allo stesso documento all'interno di frammenti differenti.

Utilizzo di POST per ottenere le modifiche

Invece di GET, è anche possibile utilizzare POST per eseguire query del feed delle modifiche. L'unica differenza, se stai utilizzando POST e stai utilizzando uno dei filtri docs_ids o selector, è che è possibile includere le parti "doc_ids" : [...] o "selector": {...} nel corpo della richiesta. Tutti gli altri parametri sono previsti nella stringa di query, come l'utilizzo di GET.

Si veda il seguente esempio che utilizza HTTP per POST all'endpoint _changes:

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

Vedi il seguente esempio per POST sull'endpoint _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))

L'esempio Go precedente richiede il seguente blocco di importazione:

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

Tutti gli esempi Go richiedono l'iniziazione dell'oggetto service. Per ulteriori informazioni, vedi la sezione Autenticazione della documentazione API per degli esempi.

Quando si POST all'endpoint _changes, viene visualizzato un esempio simile al seguente oggetto 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}

Paginazione

Utilizzare il parametro since come un segnalibro per impaginare il feed delle modifiche. Per dettagli ed esempi specifici, consultare l'argomento della documentazione API Paginazione del feed delle modifiche.