Le code di indicizzazione di Google Cloud Search

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

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

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

• Assegna la priorità agli elementi nelle code in base allo stato degli elementi.

• Mantieni informazioni aggiuntive sullo stato per un'integrazione efficiente, come checkpoint, token di modifica e così via.

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

Stato e priorità

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

• ERROR: l'elemento ha riscontrato un errore asincrono durante il processo di indicizzazione e deve essere reindicizzato.

• MODIFIED: elemento che è stato indicizzato in precedenza e modificato nel repository dopo l'ultima indicizzazione.

• NEW_ITEM. Elemento non indicizzato.

• ACCEPTED: documento che è stato indicizzato in precedenza e non ha subito modifiche nel repository dall'ultima indicizzazione.

Quando due elementi in una coda hanno lo stesso stato, viene assegnata una priorità più alta agli elementi che sono in coda per il periodo di tempo più lungo.

Panoramica dell'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 relative alla coda (SDK Connector).

Figura 1. Indicizzazione dei passaggi per aggiungere o aggiornare un elemento

1. Il connettore di contenuti utilizza items.push per eseguire il push degli elementi (metadati e hash) in una coda di indicizzazione per stabilire lo stato dell'elemento (MODIFIED, NEW_ITEM, DELETED). In particolare:

   • Durante 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, lo stato dell'elemento è 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 ulteriori informazioni su come viene stabilito lo stato degli elementi, consulta l'articolo di esempio sull'esplorazione dei repository GitHub nel tutorial introduttivo di Cloud Search.

   In genere, il push è associato ai processi di trasferimento dei contenuti e/o di rilevamento delle modifiche all'interno del connettore.

2. Il connettore di contenuti utilizza items.poll per eseguire il polling della coda per determinare gli elementi da indicizzare. Cloud Search indica al connettore quali elementi hanno più bisogno di indicizzazione, ordinati prima per codice di stato e poi per tempo nella coda.

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

4. Il connettore utilizza items.index per indicizzare gli elementi. L'elemento entra nello stato ACCEPTED solo al termine dell'elaborazione dell'elemento da parte di Cloud Search.

Un connettore può anche eliminare un elemento se non esiste più nel repository oppure eseguire nuovamente il push di un elemento se non è stato modificato o se si verifica un errore nel repository di origine. Per informazioni sull'eliminazione 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 potrebbero 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 con 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 il secondo attraversamento eseguito con una strategia di attraversamento completo. Questi passaggi utilizzano le chiamate API REST. Per chiamate SDK equivalenti, consulta Operazioni code (SDK Connector).

Figura 2. Eliminazione di elementi

Nota: nel seguente elenco di passaggi, i passaggi da 1 a 4 non sono mostrati nella Figura 2 in quanto corrispondono ai passaggi 1-4 del diagramma precedente e non rientrano nell'ambito di questa sezione. Il passaggio 5 non è visualizzato perché la chiamata a deleteQueueItems in una coda vuota non rientra nell'ambito di questa sezione. Questo diagramma è incentrato sul secondo attraversamento.

1. Al momento del trasferimento iniziale, il connettore di contenuti utilizza items.push per eseguire il push degli elementi (metadati e hash) in una coda di indicizzazione "coda A" come NEW_ITEM, poiché non esiste nella coda. A ogni elemento è 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'elemento viene inviato di nuovo o reindicizzato.

2. Il connettore di contenuti utilizza items.poll per eseguire il polling della coda A per determinare gli elementi da indicizzare. Cloud Search indica al connettore quali elementi hanno più bisogno di indicizzazione, ordinati prima per codice di stato e poi per tempo nella coda.

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

4. Il connettore utilizza items.index per indicizzare gli elementi. L'elemento entra nello stato ACCEPTED solo al termine dell'elaborazione dell'elemento da parte di Cloud Search.

5. Il metodo deleteQueueItems è chiamato "coda B". Tuttavia, nessun elemento è stato inviato alla coda B, quindi non può essere eliminato.

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

   • Durante 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, lo stato dell'elemento 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 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 di contenuti utilizza items.poll per eseguire il polling della coda per determinare gli elementi da indicizzare. Cloud Search indica al connettore quali elementi hanno più bisogno di indicizzazione, ordinati prima per codice di stato e poi per tempo nella coda.

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

9. Il connettore utilizza items.index per indicizzare gli elementi. L'elemento entra nello stato ACCEPTED solo al termine dell'elaborazione dell'elemento da parte di Cloud Search.

10. Infine, l'elemento deleteQueueItems viene richiamato nella coda A per eliminare tutti gli elementi di CCloud Search indicizzati in precedenza che hanno ancora un'etichetta "A" della coda.

11. Con gli attraversamenti completi successivi, la coda utilizzata per l'indicizzazione e quella utilizzata per l'eliminazione vengono scambiate.

Operazioni in coda (SDK Connector)

L'SDK del connettore di contenuti fornisce operazioni per il push e il pull di elementi da una coda.

Per pacchettizzare un elemento ed eseguirne il push in una coda, utilizza la classe del builder pushItems.

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

Operazioni in coda (API REST)

L'API REST offre i due metodi seguenti per eseguire il push degli elementi e il pull degli elementi da una coda:

• Per inviare un elemento a una coda, utilizza Items.push.
• Per sottoporre a sondaggio gli elementi nella coda, utilizza Items.poll.

Puoi anche utilizzare Items.index per inviare elementi alla coda durante l'indicizzazione. Gli elementi inviati alla coda durante l'indicizzazione non richiedono un elemento type e gli 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 di push. Per un elenco di valori type, consulta il campo item.type nel metodo Items.push.

L'invio 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.

Un elemento sottoposto a polling è prenotato, ovvero non può essere restituito da un'altra chiamata a Items.poll. Se utilizzi Items.push con type come voci del sondaggio NOT_MODIFIED, REPOSITORY_ERROR o REQUEUE, annulla la prenotazione. Per ulteriori informazioni sulle voci prenotate e non prenotate, consulta la sezione Items.poll.

Items.push con hash

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

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

Items.poll

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

Per impostazione predefinita, in base alla priorità possono essere restituite le voci di qualsiasi sezione della coda. 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 è stata nuovamente accodata da Items.index.
• Items.push viene chiamato con un valore type di NOT_MODIFIED, REPOSITORY_ERROR o REQUEUE.