Le code di indicizzazione di Google Cloud Search

L'SDK Connector e l'API Google Cloud Search consentono la creazione di code di indicizzazione di Cloud Search utilizzate per eseguire le seguenti attività:

• Mantiene lo stato per documento (stato, valori hash e così via) che può essere utilizzato per mantenere sincronizzato l'indice con il repository.

• Mantiene un elenco di elementi da indicizzare come rilevati durante il processo di attraversamento.

• Assegna la priorità agli elementi nelle code in base al loro stato.

• Mantenere ulteriori informazioni sullo stato per un'integrazione efficiente, ad esempio checkpoint, token di modifica e così via.

Una coda è un'etichetta assegnata a un elemento indicizzato, ad esempio "default" per la coda predefinita o "B" per la coda B.

Stato e priorità

La priorità di un documento in una coda si basa sul suo codice ItemStatus. Di seguito sono riportati i possibili codici ItemStatus in ordine di priorità (gestiti dal primo all'ultimo):

• ERROR - L'elemento ha rilevato un errore asincrono durante l'indicizzazione e deve essere reindicizzato.

• MODIFIED - Elemento precedentemente indicizzato e modificato nel repository dall'ultima indicizzazione.

• NEW_ITEM: elemento non indicizzato.

• ACCEPTED - Documento precedentemente indicizzato e non modificato nel repository dall'ultima indicizzazione.

Quando due elementi in una coda hanno lo stesso stato, viene data la priorità più alta agli elementi che si trovano nella coda da più tempo.

Panoramica sull'utilizzo delle code di indicizzazione per indicizzare un elemento nuovo o modificato

La figura 1 mostra i passaggi per l'indicizzazione di un elemento nuovo o modificato utilizzando una coda di indicizzazione. Questi passaggi mostrano le chiamate API REST. Per le chiamate SDK equivalenti, consulta Operazioni di coda (SDK connettore).

Figura 1. Passaggi di indicizzazione per aggiungere o aggiornare un elemento

1. Il connettore dei contenuti utilizza items.push per inserire elementi (metadati e hash) in una coda di indicizzazione per stabilire lo stato dell'elemento (MODIFIED, NEW_ITEM, DELETED). Nello specifico:

   • Quando esegui il push, il connettore include esplicitamente un push type o contentHash.
   • Se il connettore non include type, Cloud Search utilizza automaticamente contentHash per determinare lo stato dell'elemento.
   • Se l'articolo è sconosciuto, il relativo stato viene impostato su NEW_ITEM.
   • Se l'elemento esiste e i valori hash corrispondono, lo stato viene mantenuto come ACCEPTED.
   • Se l'elemento esiste e gli hash sono diversi, lo stato diventa MODIFIED.

   Per saperne di più su come viene stabilito lo stato degli elementi, consulta il codice di esempio Attraversamento dei repository GitHub nel tutorial Guida introduttiva a Cloud Search.

   In genere, il push è associato ai processi di attraversamento dei contenuti e/o di rilevamento delle modifiche nel connettore.

2. Il connettore dei contenuti utilizza items.poll per eseguire il polling della coda e determinare gli elementi da indicizzare. Cloud Search comunica al connettore quali elementi devono essere indicizzati per primi, ordinati prima in base al codice di stato e poi in base al tempo di attesa in coda.

3. Il connettore recupera questi elementi dal repository e crea richieste API di indicizzazione.

4. Il connettore utilizza items.index per indicizzare gli elementi. L'elemento entra nello stato ACCEPTED solo dopo che Cloud Search ha completato l'elaborazione.

Un connettore può anche eliminare un elemento se non esiste più nel repository o inviarlo di nuovo se non è stato modificato o se si verifica un errore nel repository di origine. Per informazioni sulle eliminazioni di elementi, consulta la sezione successiva.

Nota: alcune strategie di attraversamento, come l'attraversamento completo, utilizzano più di una coda di indicizzazione. Per un esempio di come possono essere utilizzate due code, consulta la sezione successiva.

Panoramica dell'utilizzo delle code di indicizzazione per eliminare un elemento

La strategia di attraversamento completo utilizza un processo a due code per indicizzare gli elementi e rilevare le eliminazioni. La Figura 2 mostra i passaggi per eliminare un elemento utilizzando due code di indicizzazione. Nello specifico, la Figura 2 mostra la seconda traversata eseguita utilizzando una strategia di traversata completa. Questi passaggi utilizzano le chiamate API REST. Per chiamate SDK equivalenti, consulta Operazioni di coda (SDK connettore).

Figura 2. Eliminazione di elementi

Nota: nel seguente elenco di passaggi, i passaggi 1-4 non sono mostrati nella Figura 2 perché sono gli stessi dei passaggi 1-4 del diagramma precedente e non rientrano nell'ambito di questa sezione. Il passaggio 5 non viene mostrato perché la chiamata deleteQueueItems in una coda vuota non rientra nell'ambito di questa sezione. Questo diagramma si concentra sul secondo attraversamento.

1. Durante l'attraversamento iniziale, il connettore dei contenuti utilizza items.push per inserire elementi (metadati e hash) in una coda di indicizzazione, "coda A" come NEW_ITEM perché non esiste nella coda. A ogni elemento viene assegnata l'etichetta "A" per "coda A". I contenuti vengono indicizzati in Cloud Search.

   Nota: il connettore può assegnare un'etichetta di coda, utilizzando il campo queue dell'elemento, a un elemento durante un'operazione item.push o item.index. Questa etichetta può essere modificata ogni volta che l'articolo viene ripubblicato o reindicizzato.

2. Il connettore dei contenuti utilizza items.poll per eseguire il polling della coda A e determinare gli elementi da indicizzare. Cloud Search comunica al connettore quali elementi devono essere indicizzati per primi, ordinati prima in base al codice di stato e poi in base al tempo di attesa in coda.

3. Il connettore recupera questi elementi dal repository e crea richieste API di indicizzazione.

4. Il connettore utilizza items.index per indicizzare gli elementi. L'elemento entra nello stato ACCEPTED solo dopo che Cloud Search ha completato l'elaborazione.

5. Il metodo deleteQueueItems viene chiamato nella "coda B". Tuttavia, non sono stati inseriti elementi nella coda B, quindi non è possibile eliminare nulla.

6. Nel secondo attraversamento completo, il connettore dei contenuti utilizza items.push per inserire gli elementi (metadati e hash) nella coda B:

   • Quando esegui il push, il connettore include esplicitamente un push type o contentHash.
   • Se il connettore non include type, Cloud Search utilizza automaticamente contentHash per determinare lo stato dell'elemento.
   • Se l'elemento è sconosciuto, il relativo stato viene impostato su NEW_ITEM e l'etichetta della coda viene modificata in "B".
   • Se l'elemento esiste e i valori hash corrispondono, lo stato viene mantenuto come ACCEPTED e l'etichetta della coda viene modificata in "B".
   • Se l'elemento esiste e gli hash sono diversi, lo stato diventa MODIFIED e l'etichetta della coda viene modificata in "B."

7. Il connettore dei contenuti utilizza items.poll per eseguire il polling della coda e determinare gli elementi da indicizzare. Cloud Search comunica al connettore quali elementi devono essere indicizzati per primi, ordinati prima in base al codice di stato e poi in base al tempo di attesa in coda.

8. Il connettore recupera questi elementi dal repository e crea richieste API di indicizzazione.

9. Il connettore utilizza items.index per indicizzare gli elementi. L'elemento entra nello stato ACCEPTED solo dopo che Cloud Search ha completato l'elaborazione.

10. Infine, deleteQueueItems viene chiamato nella coda A per eliminare tutti gli elementi di CCloud Search precedentemente indicizzati che hanno ancora un'etichetta di coda "A".

11. Con le traversie complete successive, la coda utilizzata per l'indicizzazione e la coda utilizzata per l'eliminazione vengono scambiate.

Operazioni di coda (SDK connettore)

L'SDK Content Connector fornisce operazioni per inserire elementi in una coda ed estrarli.

Per creare un pacchetto e inserire un elemento in una coda, utilizza la classe di builder pushItems.

Non devi fare nulla di specifico per estrarre gli elementi da una coda per l'elaborazione. L'SDK estrae automaticamente gli elementi dalla coda, in ordine di priorità, utilizzando il metodo getDoc della classe Repository.

Operazioni di coda (API REST)

L'API REST fornisce i seguenti due metodi per inserire elementi in una coda ed estrarli:

• Per eseguire il push di un elemento in una coda, utilizza Items.push.
• Per eseguire il polling degli elementi nella coda, utilizza Items.poll.

Puoi anche utilizzare Items.index per inserire gli elementi nella coda durante l'indicizzazione. Gli elementi inseriti nella coda durante l'indicizzazione non richiedono un type e viene assegnato automaticamente lo stato ACCEPTED.

Items.push

Il metodo Items.push aggiunge gli ID alla coda. Questo metodo può essere chiamato con un valore type specifico che determina il risultato dell'operazione push. Per un elenco dei valori di type, consulta il campo item.type nel metodo Items.push.

Il push di un nuovo ID comporta l'aggiunta di una nuova voce con un codice NEW_ITEM ItemStatus.

Il payload facoltativo viene sempre archiviato, trattato come un valore opaco e restituito da Items.poll.

Quando un elemento viene sottoposto a polling, viene riservato, il che significa che non può essere restituito da un'altra chiamata a Items.poll. L'utilizzo di Items.push con type come NOT_MODIFIED, REPOSITORY_ERROR o REQUEUE, annulla la prenotazione delle voci sottoposte a polling. Per ulteriori informazioni sulle voci riservate e non riservate, consulta la sezione Items.poll.

Items.push con hash

L'API Google Cloud Search supporta la specifica di valori hash di metadati e contenuti nelle richieste Items.index. Anziché specificare type, i valori hash dei metadati e/o dei contenuti possono essere specificati con una richiesta push. La coda di indicizzazione di Cloud Search confronta i valori hash forniti con i valori memorizzati disponibili con l'elemento nell' origine dati. Se non corrispondono, la voce viene contrassegnata come MODIFIED. Se non esiste un elemento corrispondente nell'indice, lo stato è NEW_ITEM.

Nota: i valori hash forniti con le Items.push richieste non vengono salvati con l'articolo. Questi elementi vengono utilizzati solo per determinare se l'elemento è stato modificato.

Items.poll

Il metodo Items.poll recupera le voci con la priorità più alta dalla coda. I valori di stato richiesti e restituiti indicano lo stato o gli stati delle code di priorità richieste o lo stato degli ID restituiti.

Per impostazione predefinita, possono essere restituiti elementi di qualsiasi sezione della coda, in base alla priorità. Ogni voce restituita è riservata e non viene restituita da altre chiamate a Items.poll finché non si verifica uno dei seguenti casi:

• La prenotazione scade.
• La voce viene nuovamente messa in coda da Items.index.
• Items.push viene chiamato con un valore type di NOT_MODIFIED, REPOSITORY_ERROR o REQUEUE.