Crea un connettore di contenuti

Un connettore di contenuti è un programma software utilizzato per esaminare i dati nel repository di un'azienda e compilare un'origine dati. Google fornisce le seguenti opzioni per lo sviluppo di connettori di contenuti:

• L'SDK Content Connector. Questa è una buona opzione se programmi in Java. L'SDK Content Connector è un wrapper per l'API REST che ti consente di creare rapidamente i connettori. Per creare un connettore di contenuti utilizzando l'SDK, consulta Creare un connettore di contenuti utilizzando l'SDK Content Connector.

• Un'API REST di basso livello o librerie API. Utilizza queste opzioni se non programmi in Java o se la tua base di codice è più adatta a un'API REST o a una libreria. Per creare un connettore di contenuti utilizzando l'API REST, consulta Creare un connettore di contenuti utilizzando l'API REST.

Un tipico connettore di contenuti esegue le seguenti attività:

1. Legge ed elabora i parametri di configurazione.
2. Estrae parti distinte di dati indicizzabili, chiamate "elementi", dal repository di contenuti di terze parti.
3. Combina ACL, metadati e dati dei contenuti in elementi indicizzabili.
4. Indicizza gli elementi nell'origine dati Cloud Search.
5. (Facoltativo) Ascolta le notifiche di modifica dal repository di contenuti di terze parti. Le notifiche di modifica vengono convertite in richieste di indicizzazione per mantenere aggiornata l'origine dati di Cloud Search con il repository di terze parti. Il connettore esegue questa operazione solo se il repository supporta il rilevamento delle modifiche.

Creare un connettore di contenuti utilizzando l'SDK Content Connector

Le sezioni seguenti spiegano come creare un connettore di contenuti utilizzando l'SDK Content Connector.

Configura le dipendenze

Per utilizzare l'SDK, devi includere determinate dipendenze nel file di compilazione. Fai clic su una scheda di seguito per visualizzare le dipendenze per il tuo ambiente di build:

<dependency>
<groupId>com.google.enterprise.cloudsearch</groupId>
<artifactId>google-cloudsearch-indexing-connector-sdk</artifactId>
<version>v1-0.0.3</version>
</dependency>

compile group: 'com.google.enterprise.cloudsearch',
        name: 'google-cloudsearch-indexing-connector-sdk',
        version: 'v1-0.0.3'

Crea la configurazione del connettore

Ogni connettore ha un file di configurazione contenente i parametri utilizzati dal connettore, ad esempio l'ID del repository. I parametri sono definiti come coppie chiave-valore, ad esempio api.sourceId=1234567890abcdef.

L'SDK Google Cloud Search contiene diversi parametri di configurazione forniti da Google utilizzati da tutti i connettori. Devi dichiarare i seguenti parametri forniti da Google nel file di configurazione:

• Per un connettore di contenuti, devi dichiarare api.sourceId e api.serviceAccountPrivateKeyFile perché questi parametri identificano la posizione del tuo repository e la chiave privata necessaria per accedere al repository.

• Per un connettore di identità, devi dichiarare api.identitySourceId poiché questo parametro identifica la posizione dell'origine dell'identità esterna. Se sincronizzi gli utenti, devi anche dichiarare api.customerId come ID univoco per l'account Google Workspace della tua azienda.

A meno che tu non voglia sostituire i valori predefiniti di altri parametri forniti da Google, non è necessario dichiararli nel file di configurazione. Per ulteriori informazioni sui parametri di configurazione forniti da Google, ad esempio su come generare determinati ID e chiavi, consulta Parametri di configurazione forniti da Google.

Puoi anche definire i tuoi parametri specifici del repository da utilizzare nel file di configurazione.

Passa il file di configurazione al connettore

Imposta la proprietà di sistema config per passare il file di configurazione al connettore. Puoi impostare la proprietà utilizzando l'argomento -D all'avvio del connettore. Ad esempio, il seguente comando avvia il connettore con il file di configurazione MyConfig.properties:

java -classpath myconnector.jar;... -Dconfig=MyConfig.properties MyConnector

Se questo argomento non è presente, l'SDK tenta di accedere a un file di configurazione predefinito denominato connector-config.properties.

Determina la strategia di attraversamento

La funzione principale di un connettore di contenuti è attraversare un repository e indicizzare i relativi dati. Devi implementare una strategia di attraversamento in base alle dimensioni e al layout dei dati nel tuo repository. Puoi progettare la tua strategia o scegliere tra le seguenti strategie implementate nell'SDK:

Strategia di attraversamento completa

Una strategia di attraversamento completa esegue la scansione dell'intero repository e indicizza in modo cieco ogni elemento. Questa strategia viene comunemente utilizzata quando hai un piccolo repository e puoi permetterti l'overhead di eseguire un attraversamento completo ogni volta che esegui l'indicizzazione.

Questa strategia di attraversamento è adatta per piccoli repository con dati prevalentemente statici e non gerarchici. Puoi utilizzare questa strategia di attraversamento anche quando il rilevamento delle modifiche è difficile o non supportato dal repository.

Strategia di attraversamento dell'elenco

Una strategia di attraversamento dell'elenco esegue la scansione dell'intero repository, inclusi tutti i nodi secondari, determinando lo stato di ogni elemento. Il connettore esegue quindi un secondo passaggio e indicizza solo gli elementi nuovi o aggiornati dall'ultimo indicizzazione. Questa strategia viene comunemente utilizzata per eseguire aggiornamenti incrementali di un indice esistente (anziché dover eseguire un'esplorazione completa ogni volta che l'indice viene aggiornato).

Questa strategia di attraversamento è adatta quando il rilevamento delle modifiche è difficile o non supportato dal repository, quando hai dati non gerarchici e quando lavori con set di dati molto grandi.

Percorso del grafo

Una strategia di attraversamento del grafico esegue la scansione dell'intero nodo principale determinando lo stato di ciascun elemento. Il connettore esegue quindi un secondo passaggio e indicizza solo gli elementi nel nodo principale che sono nuovi o sono stati aggiornati dall'ultima indicizzazione. Infine, il connettore passa tutti gli ID secondari e poi indicizza gli elementi nei nodi secondari che sono nuovi o sono stati aggiornati. Il connettore continua in modo ricorsivo tra tutti i nodi secondari finché non sono stati indirizzati tutti gli elementi. Questo tipo di attraversamento viene solitamente utilizzato per i repository gerarchici in cui non è pratico elencare tutti gli ID.

Questa strategia è adatta se hai dati gerarchici che devono essere sottoposti a scansione, ad esempio una serie di directory o pagine web.

Ognuna di queste strategie di attraversamento è implementata da una classe di connettore di modelli nell'SDK. Sebbene tu possa implementare la tua strategia di attraversamento, questi modelli accelerano notevolmente lo sviluppo del connettore. Per creare un connettore utilizzando un modello, vai alla sezione corrispondente alla tua strategia di attraversamento:

• Creare un connettore di attraversamento completo utilizzando una classe di modello
• Creare un connettore di attraversamento dell'elenco utilizzando una classe di modello
• Creare un connettore di attraversamento del grafo utilizzando una classe modello

Creare un connettore di attraversamento completo utilizzando una classe modello

Questa sezione della documentazione fa riferimento agli snippet di codice dell'esempio FullTraversalSample.

Implementa il punto di contatto del connettore

L'entry point di un connettore è il metodo main(). Il compito principale di questo metodo è creare un'istanza della classe Application e invocarne il metodo start() per eseguire il connettore.

Prima di chiamare application.start(), utilizza la classe IndexingApplication.Builder per creare un'istanza del FullTraversalConnector modello. Il metodo FullTraversalConnector accetta un oggetto Repository i cui metodi implementi. Il seguente snippet di codice mostra come implementare il metodo main():

/**
 * This sample connector uses the Cloud Search SDK template class for a full
 * traversal connector.
 *
 * @param args program command line arguments
 * @throws InterruptedException thrown if an abort is issued during initialization
 */
public static void main(String[] args) throws InterruptedException {
  Repository repository = new SampleRepository();
  IndexingConnector connector = new FullTraversalConnector(repository);
  IndexingApplication application = new IndexingApplication.Builder(connector, args).build();
  application.start();
}

Dietro le quinte, l'SDK chiama il metodo initConfig() dopo che il metodo main() del connettore chiama Application.build. Il metodo initConfig() esegue le seguenti attività:

1. Chiama il metodo Configuation.isInitialized() per assicurarsi che Configuration non sia stato inizializzato.
2. Inizializza un oggetto Configuration con le coppie chiave-valore fornite da Google. Ogni coppia chiave-valore viene archiviata in un oggetto ConfigValue all'interno dell'oggetto Configuration.

Implementa l'interfaccia Repository

L'unico scopo dell'oggetto Repository è eseguire il traversale e l'indicizzazione degli elementi del repository. Quando utilizzi un modello, devi solo sostituire determinati metodi all'interno dell'interfaccia Repository per creare un connettore di contenuti. I metodi che sostituisci dipendono dal templato e dalla strategia di attraversamento che utilizzi. Per FullTraversalConnector, sostituisci i seguenti metodi:

• Il metodo init(). Per eseguire la configurazione e l'inizializzazione del repository di dati, sostituisci il metodo init().

• Il metodo getAllDocs(). Per eseguire la scansione e indicizzare tutti gli elementi nel repository di dati, sostituisci il metodo getAllDocs(). Questo metodo viene chiamato una volta per ogni attraversamento pianificato (come definito dalla configurazione).

• (Facoltativo) Il metodo getChanges(). Se il tuo repository supporta il rilevamento delle modifiche, sostituisci il metodo getChanges(). Questo metodo viene chiamato una volta per ogni traversal incrementale pianificato (come definito dalla configurazione) per recuperare gli elementi modificati e indicizzarli.

• (Facoltativo) Il metodo close(). Se devi eseguire la pulizia del repository, sostituisci il metodo close(). Questo metodo viene chiamato una volta durante l'arresto del connettore.

Ciascuno dei metodi dell'oggetto Repository restituisce un tipo di ApiOperation oggetto. Un oggetto ApiOperation esegue un'azione sotto forma di una singola chiamata o forse di più chiamate IndexingService.indexItem() per eseguire l'indicizzazione effettiva del repository.

Ottenere i parametri di configurazione personalizzati

Nell'ambito della gestione della configurazione del connettore, dovrai recuperare eventuali parametri personalizzati dall'oggetto Configuration. Questa operazione viene solitamente eseguita in un metodo init() di una Repository classe.

La classe Configuration ha diversi metodi per ottenere tipi di dati diversi da una configurazione. Ogni metodo restituisce un oggetto ConfigValue. Poi, utilizzerai il metodo get() dell'oggetto ConfigValue per recuperare il valore effettivo. Il seguente snippet, proveniente da FullTraversalSample, mostra come recuperare un singolo valore intero personalizzato da un oggetto Configuration:

@Override
public void init(RepositoryContext context) {
  log.info("Initializing repository");
  numberOfDocuments = Configuration.getInteger("sample.documentCount", 10).get();
}

Per ottenere e analizzare un parametro contenente più valori, utilizza uno degli analizzatori di tipo della classe Configuration per analizzare i dati in blocchi distinti. Lo snippet seguente, del connettore del tutorial, utilizza il metodo getMultiValue per ottenere un elenco di nomi di repository GitHub:

ConfigValue<List<String>> repos = Configuration.getMultiValue(
    "github.repos",
    Collections.emptyList(),
    Configuration.STRING_PARSER);

Esegui un'esplorazione completa

Sostituisci getAllDocs() per eseguire un attraversamento completo e indicizzare il repository. Il metodo getAllDocs() accetta un checkpoint. Il checkpoint viene utilizzato per riprendere l'indicizzazione da un elemento specifico se il processo viene interrotto. Per ogni elemento del repository, svolgi i seguenti passaggi nel metodo getAllDocs():

1. Imposta le autorizzazioni.
2. Imposta i metadati dell'elemento che stai indicizzando.
3. Combina i metadati e l'elemento in un unico elemento indicizzato RepositoryDoc.
4. Impacchetta ogni elemento indicizzato in un iteratore restituito dal metodo getAllDocs(). Tieni presente che getAllDocs() restituisce effettivamente un CheckpointCloseableIterable che è un'iterazione di ApiOperation oggetti, ciascuno dei quali rappresenta una richiesta API eseguita su un RepositoryDoc, ad esempio l'indicizzazione.

Se l'insieme di elementi è troppo grande per essere elaborato in una singola chiamata, includi un checkpoint e imposta hasMore(true) per indicare che sono disponibili altri elementi per l'indicizzazione.

Impostare le autorizzazioni per un elemento

Il tuo repository utilizza un elenco di controllo dell'accesso (ACL) per identificare gli utenti o i gruppi che hanno accesso a un elemento. Un ACL è un elenco di ID di gruppi o utenti che possono accedere all'elemento.

Devi duplicare l'ACL utilizzato dal tuo repository per assicurarti che solo gli utenti con accesso a un elemento possano visualizzarlo in un risultato di ricerca. L'ACL per un elemento deve essere inclusa durante l'indicizzazione di un elemento in modo che Google Cloud Search disponga delle informazioni necessarie per fornire il livello di accesso corretto all'elemento.

L'SDK Content Connector fornisce un ampio insieme di classi e metodi ACL per modellare le ACL della maggior parte dei repository. Devi analizzare l'ACL per ogni elemento nel tuo repository e creare un'ACL corrispondente per Google Cloud Search quando esegui l'indicizzazione di un elemento. Se l'ACL del tuo repository utilizza concetti come l'eredità ACL, la relativa definizione può essere complicata. Per ulteriori informazioni sugli ACL di Google Cloud Search, consulta ACL di Google Cloud Search.

Nota:l'API Cloud Search Indexing supporta le ACL a dominio singolo. Non supporta le ACL interdominio. Utilizza la classe Acl.Builder per impostare l'accesso a ciascun elemento utilizzando un ACL. Lo snippet di codice riportato di seguito, tratto dall'esempio di attraversamento completo, consente a tutti gli utenti o "principali" (getCustomerPrincipal()) di essere "lettori" di tutti gli elementi (.setReaders()) quando viene eseguita una ricerca.

// Make the document publicly readable within the domain
Acl acl = new Acl.Builder()
    .setReaders(Collections.singletonList(Acl.getCustomerPrincipal()))
    .build();

Per modellare correttamente gli ACL per il repository, devi conoscerli. Ad esempio, potresti indicizzare i file all'interno di un file system che utilizza una sorta di modello di ereditarietà in cui le cartelle secondarie ereditano le autorizzazioni dalle cartelle principali. La definizione dell'eredità ACL richiede informazioni aggiuntive descritte nelle ACL di Google Cloud Search

Impostare i metadati di un elemento

I metadati vengono archiviati in un oggetto Item. Per creare un Item, devi avere almeno un ID stringa univoco, un tipo di elemento, un ACL, un URL e una versione per l'elemento. Il seguente snippet di codice mostra come creare un Item utilizzando la classe di supporto IndexingItemBuilder.

// Url is required. Use google.com as a placeholder for this sample.
String viewUrl = "https://www.google.com";

// Version is required, set to current timestamp.
byte[] version = Longs.toByteArray(System.currentTimeMillis());

// Using the SDK item builder class to create the document with appropriate attributes
// (this can be expanded to include metadata fields etc.)
Item item = IndexingItemBuilder.fromConfiguration(Integer.toString(id))
    .setItemType(IndexingItemBuilder.ItemType.CONTENT_ITEM)
    .setAcl(acl)
    .setSourceRepositoryUrl(IndexingItemBuilder.FieldOrValue.withValue(viewUrl))
    .setVersion(version)
    .build();

Crea l'elemento indicizzato

Dopo aver impostato i metadati dell'elemento, puoi creare l'elemento indicizzato effettivo utilizzando la classe RepositoryDoc.Builder. L'esempio seguente mostra come creare un singolo elemento indicizzato.

// For this sample, content is just plain text
String content = String.format("Hello world from sample doc %d", id);
ByteArrayContent byteContent = ByteArrayContent.fromString("text/plain", content);

// Create the fully formed document
RepositoryDoc doc = new RepositoryDoc.Builder()
    .setItem(item)
    .setContent(byteContent, IndexingService.ContentFormat.TEXT)
    .build();

Un RepositoryDoc è un tipo di ApiOperation che esegue la richiesta IndexingService.indexItem() effettiva.

Puoi anche utilizzare il metodo setRequestMode() della classe RepositoryDoc.Builder per identificare la richiesta di indicizzazione come ASYNCHRONOUS o SYNCHRONOUS:

ASYNCHRONOUS

La modalità asincrona comporta una latenza dall'indicizzazione alla pubblicazione più lunga e consente una quota di throughput elevata per le richieste di indicizzazione. La modalità asincrona è consigliata per l'indicizzazione iniziale (backfill) dell'intero repository.

SYNCHRONOUS

La modalità sincrona comporta una latenza dall'indicizzazione alla pubblicazione più breve e supporta una quota di throughput limitata. La modalità sincrona è consigliata per l'indicizzazione di aggiornamenti e modifiche al repository. Se non specificato, la modalità di richiesta predefinita è SYNCHRONOUS.

Raggruppa ogni elemento indicizzato in un iteratore

Il metodo getAllDocs() restituisce un Iterator, nello specifico un CheckpointCloseableIterable, di RepositoryDoc oggetti. Puoi utilizzare la classe CheckpointClosableIterableImpl.Builder per creare e restituire un iteratore. Il seguente snippet di codice mostra come costruire e restituire un iteratore.

CheckpointCloseableIterable<ApiOperation> iterator =
  new CheckpointCloseableIterableImpl.Builder<>(allDocs).build();

L'SDK esegue ogni chiamata di indicizzazione racchiusa nell'iteratore.

Passaggi successivi

Ecco alcuni passaggi successivi che puoi intraprendere:

• (Facoltativo) Se la velocità di elaborazione dell'indicizzazione sembra lenta, consulta l'articolo Aumentare la frequenza di indicizzazione per FullTraversalConnector.
• (Facoltativo) Implementa il metodo close() per rilasciare eventuali risorse prima dell'arresto.
• (Facoltativo) Crea un connettore di identità utilizzando l'SDK Content Connector.

Creare un connettore di attraversamento dell'elenco utilizzando una classe di modello

La coda di indicizzazione di Cloud Search viene utilizzata per contenere ID e valori hash facoltativi per ogni elemento del repository. Un connettore di attraversamento dell'elenco invia gli ID elemento alla coda di indicizzazione di Google Cloud Search e li recupera uno alla volta per l'indicizzazione. Google Cloud Search gestisce le code e confronta i relativi contenuti per determinare lo stato degli elementi, ad esempio se un elemento è stato eliminato dal repository. Per ulteriori informazioni sulla coda di indicizzazione di Cloud Search, consulta La coda di indicizzazione di Cloud Search.

Questa sezione della documentazione fa riferimento a snippet di codice dell'esempio ListTraversalSample.

Implementa il punto di contatto del connettore

L'entry point di un connettore è il metodo main(). Il compito principale di questo metodo è creare un'istanza della classe Application e invocarne il metodo start() per eseguire il connettore.

Prima di chiamare application.start(), utilizza la classe IndexingApplication.Builder per creare un'istanza del ListingConnector modello. ListingConnector accetta un oggetto Repository cuyos metodi implementi. Lo snippet seguente mostra come eseguire l'inizializzazione di ListingConnector e del relativo Repository associato:

/**
 * This sample connector uses the Cloud Search SDK template class for a
 * list traversal connector.
 *
 * @param args program command line arguments
 * @throws InterruptedException thrown if an abort is issued during initialization
 */
public static void main(String[] args) throws InterruptedException {
  Repository repository = new SampleRepository();
  IndexingConnector connector = new ListingConnector(repository);
  IndexingApplication application = new IndexingApplication.Builder(connector, args).build();
  application.start();
}

Dietro le quinte, l'SDK chiama il metodo initConfig() dopo che il metodo main() del connettore chiama Application.build. Il metodo initConfig():

1. Chiama il metodo Configuation.isInitialized() per assicurarsi che Configuration non sia stato inizializzato.
2. Inizializza un oggetto Configuration con le coppie chiave-valore fornite da Google. Ogni coppia chiave-valore viene memorizzata in un oggetto ConfigValue all'interno dell'oggetto Configuration.

Implementa l'interfaccia Repository

L'unico scopo dell'oggetto Repository è eseguire il traversale e l'indicizzazione degli elementi del repository. Quando utilizzi un modello, devi solo eseguire l'override di alcuni metodi all'interno dell'interfacciaRepository per creare un connettore di contenuti. I metodi che sostituisci dipendono dal modello e dalla strategia di attraversamento che utilizzi. Per ListingConnector, override i seguenti metodi:

• Il metodo init(). Per eseguire la configurazione e l'inizializzazione del repository di dati, sostituisci il metodo init().

• Il metodo getIds(). Per recuperare gli ID e i valori hash per tutti i record nel repository, override il metodo getIds().

• Il metodo getDoc(). Per aggiungere nuovi elementi, aggiornare, modificare o eliminare elementi dall'indice, sostituisci il metodogetDoc().

• (Facoltativo) Il metodo getChanges(). Se il tuo repository supporta il rilevamento delle modifiche, sostituisci il metodo getChanges(). Questo metodo viene chiamato una volta per ogni traversal incrementale pianificato (come definito dalla configurazione) per recuperare gli elementi modificati e indicizzarli.

• (Facoltativo) Il metodo close(). Se devi eseguire la pulizia del repository, sostituisci il metodo close(). Questo metodo viene chiamato una volta durante l'arresto del connettore.

Ciascuno dei metodi dell'oggetto Repository restituisce un tipo di ApiOperation oggetto. Un oggetto ApiOperation esegue un'azione sotto forma di una singola chiamata o forse di più chiamate IndexingService.indexItem() per eseguire l'indicizzazione effettiva del repository.

Ottenere i parametri di configurazione personalizzati

Nell'ambito della gestione della configurazione del connettore, dovrai recuperare eventuali parametri personalizzati dall'oggetto Configuration. Questa operazione viene solitamente eseguita in un metodo init() di una Repository classe.

La classe Configuration ha diversi metodi per ottenere tipi di dati diversi da una configurazione. Ogni metodo restituisce un oggetto ConfigValue. Poi, utilizzerai il metodo get() dell'oggetto ConfigValue per recuperare il valore effettivo. Il seguente snippet, proveniente da FullTraversalSample, mostra come recuperare un singolo valore intero personalizzato da un oggetto Configuration:

@Override
public void init(RepositoryContext context) {
  log.info("Initializing repository");
  numberOfDocuments = Configuration.getInteger("sample.documentCount", 10).get();
}

Per ottenere e analizzare un parametro contenente più valori, utilizza uno degli analizzatori di tipo della classe Configuration per analizzare i dati in blocchi distinti. Lo snippet seguente, del connettore del tutorial, utilizza il metodo getMultiValue per ottenere un elenco di nomi di repository GitHub:

ConfigValue<List<String>> repos = Configuration.getMultiValue(
    "github.repos",
    Collections.emptyList(),
    Configuration.STRING_PARSER);

Esegui l'esplorazione dell'elenco

Sostituisci metodo getIds() per recuperare gli ID e i valori hash di tutti i record nel repository. Il metodo getIds() accetta un checkpoint. Il checkpoint viene utilizzato per riprendere l'indicizzazione da un elemento specifico se il processo viene interrotto.

Successivamente, sostituisci il metodo getDoc() per gestire ogni elemento nella coda di indicizzazione di Cloud Search.

Invia gli ID elemento e i valori hash

Sostituisci getIds() per recuperare gli ID elemento e i relativi valori hash dei contenuti associati dal repository. Le coppie di ID e valori hash vengono poi pacchettizzate in una richiesta di operazione push alla coda di indicizzazione di Cloud Search. In genere, gli ID principali o principali vengono inviati prima, seguiti dagli ID secondari finché l'intera gerarchia di elementi non è stata elaborata.

Il metodo getIds() accetta un checkpoint che rappresenta l'ultimo elemento da indicizzare. Il checkpoint può essere utilizzato per riprendere l'indicizzazione da un elemento specifico se il processo viene interrotto. Per ogni elemento del repository, svolgi i seguenti passaggi nel metodo getIds():

• Recupera ogni ID elemento e il valore hash associato dal repository.
• Raggruppa ogni coppia di ID e valore hash in un PushItems.
• Combina ogni PushItems in un iteratore restituito dal metodo getIds(). Tieni presente che getIds() restituisce effettivamente un CheckpointCloseableIterable che è un'iterazione di ApiOperation oggetti, ciascuno dei quali rappresenta una richiesta API eseguita su un RepositoryDoc , ad esempio l'invio degli elementi alla coda.

Il seguente snippet di codice mostra come recuperare ogni ID articolo e valore hash e inserirli in un PushItems. Un PushItems è una richiesta ApiOperation per inviare un elemento alla coda di indicizzazione di Cloud Search.

PushItems.Builder allIds = new PushItems.Builder();
for (Map.Entry<Integer, Long> entry : this.documents.entrySet()) {
  String documentId = Integer.toString(entry.getKey());
  String hash = this.calculateMetadataHash(entry.getKey());
  PushItem item = new PushItem().setMetadataHash(hash);
  log.info("Pushing " + documentId);
  allIds.addPushItem(documentId, item);
}

Il seguente snippet di codice mostra come utilizzare la classe PushItems.Builder per pacchettizzare gli ID e i valori hash in un singolo push ApiOperation.

ApiOperation pushOperation = allIds.build();
CheckpointCloseableIterable<ApiOperation> iterator =
  new CheckpointCloseableIterableImpl.Builder<>(
      Collections.singletonList(pushOperation))
  .build();
return iterator;

Gli elementi vengono inviati alla coda di indicizzazione di Cloud Search per l'ulteriore elaborazione.

Recupera e gestisci ogni elemento

Sostituisci getDoc() per gestire ogni elemento nella coda di indicizzazione di Cloud Search. Un elemento può essere nuovo, modificato, invariato o non esistere più nel repository di origine. Recupera e indicizza ogni elemento nuovo o modificato. Rimuovi dall'indice gli elementi che non esistono più nel repository di origine.

Il metodo getDoc() accetta un elemento dalla coda di indicizzazione di Google Cloud Search. Per ogni elemento della coda, svolgi i seguenti passaggi nel metodo getDoc():

1. Verifica se l'ID dell'elemento, all'interno della coda di indicizzazione di Cloud Search, è presente nel repository. In caso contrario, elimina l'elemento dall'indice.

2. Esegui il polling dell'indice per lo stato dell'elemento e, se un elemento non è modificato (ACCEPTED), non fare nulla.

3. Indice modificato o nuovi elementi:

   1. Imposta le autorizzazioni.
   2. Imposta i metadati dell'elemento che stai indicizzando.
   3. Combina i metadati e l'elemento in un unico elemento indicizzato RepositoryDoc.
   4. Restituire il RepositoryDoc.

Nota: il modello ListingConnector non supporta la restituzione di null nel metodo getDoc(). Il ritorno di null genera un NullPointerException.

Gestire gli elementi eliminati

Lo snippet di codice seguente mostra come determinare se un elemento esiste nel repository e, in caso contrario, eliminarlo.

String resourceName = item.getName();
int documentId = Integer.parseInt(resourceName);

if (!documents.containsKey(documentId)) {
  // Document no longer exists -- delete it
  log.info(() -> String.format("Deleting document %s", item.getName()));
  return ApiOperations.deleteItem(resourceName);
}

Tieni presente che documents è una struttura di dati che rappresenta il repository. Se documentID non viene trovato in documents, restituisce APIOperations.deleteItem(resourceName) per eliminare l'elemento dall'indice.

Gestire gli elementi invariati

Lo snippet di codice seguente mostra come eseguire il polling dello stato dell'elemento nella coda di indicizzazione di Cloud Search e gestire un elemento invariato.

String currentHash = this.calculateMetadataHash(documentId);
if (this.canSkipIndexing(item, currentHash)) {
  // Document neither modified nor deleted, ack the push
  log.info(() -> String.format("Document %s not modified", item.getName()));
  PushItem pushItem = new PushItem().setType("NOT_MODIFIED");
  return new PushItems.Builder().addPushItem(resourceName, pushItem).build();
}

Per determinare se l'elemento è invariato, controlla il relativo stato e gli altri metadati che potrebbero indicare una modifica. Nell'esempio, l'hash dei metadati viene utilizzato per determinare se l'elemento è stato modificato.

/**
 * Checks to see if an item is already up to date
 *
 * @param previousItem Polled item
 * @param currentHash  Metadata hash of the current github object
 * @return PushItem operation
 */
private boolean canSkipIndexing(Item previousItem, String currentHash) {
  if (previousItem.getStatus() == null || previousItem.getMetadata() == null) {
    return false;
  }
  String status = previousItem.getStatus().getCode();
  String previousHash = previousItem.getMetadata().getHash();
  return "ACCEPTED".equals(status)
      && previousHash != null
      && previousHash.equals(currentHash);
}

Impostare le autorizzazioni per un elemento

Il tuo repository utilizza un elenco di controllo dell'accesso (ACL) per identificare gli utenti o i gruppi che hanno accesso a un elemento. Un ACL è un elenco di ID di gruppi o utenti che possono accedere all'elemento.

Devi duplicare l'ACL utilizzato dal tuo repository per assicurarti che solo gli utenti con accesso a un elemento possano visualizzarlo in un risultato di ricerca. L'ACL per un elemento deve essere inclusa durante l'indicizzazione di un elemento in modo che Google Cloud Search disponga delle informazioni necessarie per fornire il livello di accesso corretto all'elemento.

L'SDK Content Connector fornisce un ampio insieme di classi e metodi ACL per modellare le ACL della maggior parte dei repository. Devi analizzare l'ACL per ogni elemento nel tuo repository e creare un'ACL corrispondente per Google Cloud Search quando esegui l'indicizzazione di un elemento. Se le ACL del tuo repository utilizzano concetti come l'eredità ACL, la loro definizione può essere complicata. Per ulteriori informazioni sugli ACL di Google Cloud Search, consulta ACL di Google Cloud Search.

Nota:l'API Cloud Search Indexing supporta le ACL a dominio singolo. Non supporta le ACL interdominio. Utilizza la classe Acl.Builder per impostare l'accesso a ciascun elemento utilizzando un ACL. Lo snippet di codice riportato di seguito, tratto dall'esempio di attraversamento completo, consente a tutti gli utenti o "principali" (getCustomerPrincipal()) di essere "lettori" di tutti gli elementi (.setReaders()) quando viene eseguita una ricerca.

// Make the document publicly readable within the domain
Acl acl = new Acl.Builder()
    .setReaders(Collections.singletonList(Acl.getCustomerPrincipal()))
    .build();

Per modellare correttamente gli ACL per il repository, devi conoscerli. Ad esempio, potresti indicizzare i file all'interno di un file system che utilizza una sorta di modello di ereditarietà in cui le cartelle secondarie ereditano le autorizzazioni dalle cartelle principali. La definizione dell'eredità ACL richiede informazioni aggiuntive descritte nelle ACL di Google Cloud Search

Impostare i metadati di un elemento

I metadati vengono archiviati in un oggetto Item. Per creare un Item, devi avere almeno un ID stringa univoco, un tipo di elemento, un ACL, un URL e una versione per l'elemento. Il seguente snippet di codice mostra come creare un Item utilizzando la classe di supporto IndexingItemBuilder.

// Url is required. Use google.com as a placeholder for this sample.
String viewUrl = "https://www.google.com";

// Version is required, set to current timestamp.
byte[] version = Longs.toByteArray(System.currentTimeMillis());

// Set metadata hash so queue can detect changes
String metadataHash = this.calculateMetadataHash(documentId);

// Using the SDK item builder class to create the document with
// appropriate attributes. This can be expanded to include metadata
// fields etc.
Item item = IndexingItemBuilder.fromConfiguration(Integer.toString(documentId))
    .setItemType(IndexingItemBuilder.ItemType.CONTENT_ITEM)
    .setAcl(acl)
    .setSourceRepositoryUrl(IndexingItemBuilder.FieldOrValue.withValue(viewUrl))
    .setVersion(version)
    .setHash(metadataHash)
    .build();

Creare un elemento indicizzato

Dopo aver impostato i metadati per l'elemento, puoi creare l'elemento indicizzato effettivo utilizzando RepositoryDoc.Builder. L'esempio seguente mostra come creare un singolo elemento indicizzato.

// For this sample, content is just plain text
String content = String.format("Hello world from sample doc %d", documentId);
ByteArrayContent byteContent = ByteArrayContent.fromString("text/plain", content);

// Create the fully formed document
RepositoryDoc doc = new RepositoryDoc.Builder()
    .setItem(item)
    .setContent(byteContent, IndexingService.ContentFormat.TEXT)
    .build();

Un RepositoryDoc è un tipo di ApiOperation che esegue la richiesta IndexingService.indexItem() effettiva.

Puoi anche utilizzare il metodo setRequestMode() della classe RepositoryDoc.Builder per identificare la richiesta di indicizzazione come ASYNCHRONOUS o SYNCHRONOUS:

ASYNCHRONOUS

La modalità asincrona comporta una latenza dall'indicizzazione alla pubblicazione più lunga e consente una quota di throughput elevata per le richieste di indicizzazione. La modalità asincrona è consigliata per l'indicizzazione iniziale (backfill) dell'intero repository.

SYNCHRONOUS

La modalità sincrona comporta una latenza dall'indicizzazione alla pubblicazione più breve e supporta una quota di throughput limitata. La modalità sincrona è consigliata per l'indicizzazione di aggiornamenti e modifiche al repository. Se non specificato, la modalità di richiesta predefinita è SYNCHRONOUS.

Passaggi successivi

Ecco alcuni passaggi successivi che puoi intraprendere:

• (Facoltativo) Implementa il metodo close() per rilasciare eventuali risorse prima dell'arresto.
• (Facoltativo) Crea un connettore di identità utilizzando l'SDK Content Connector.

Creare un connettore di attraversamento del grafo utilizzando una classe di modello

La coda di indicizzazione di Cloud Search viene utilizzata per contenere ID e valori hash facoltativi per ogni elemento del repository. Un connettore di attraversamento del grafo invia gli ID elemento alla fila di indicizzazione di Google Cloud Search e li recupera uno alla volta per l'indicizzazione. Google Cloud Search gestisce le code e ne confronta i contenuti per determinare lo stato degli elementi, ad esempio se un elemento è stato eliminato dal repository. Per ulteriori informazioni sulla coda di indicizzazione di Cloud Search, consulta La coda di indicizzazione di Google Cloud Search.

Durante l'indicizzazione, i contenuti degli elementi vengono recuperati dal repository di dati e gli eventuali ID elemento secondario vengono inviati alla coda. Il connettore procede con l'elaborazione ricorsiva degli ID principali e secondari finché non vengono gestiti tutti gli elementi.

Questa sezione della documentazione fa riferimento a snippet di codice dell'esempio GraphTraversalSample.

Implementa il punto di contatto del connettore

L'entry point di un connettore è il metodo main(). Il compito principale di questo metodo è creare un'istanza della classe Application e invocarne il metodo start() per eseguire il connettore.

Prima di chiamare application.start(), utilizza la classe IndexingApplication.Builder per creare un'istanza del modello ListingConnector. Il metodo ListingConnector accetta un oggetto Repository i cui metodi implementi.

Lo snippet seguente mostra come eseguire l'inizializzazione di ListingConnector e del relativo Repository associato:

/**
 * This sample connector uses the Cloud Search SDK template class for a graph
 * traversal connector.
 *
 * @param args program command line arguments
 * @throws InterruptedException thrown if an abort is issued during initialization
 */
public static void main(String[] args) throws InterruptedException {
  Repository repository = new SampleRepository();
  IndexingConnector connector = new ListingConnector(repository);
  IndexingApplication application = new IndexingApplication.Builder(connector, args).build();
  application.start();
}

Dietro le quinte, l'SDK chiama il metodo initConfig() dopo che il metodo main() del connettore chiama Application.build. Il metodo initConfig():

1. Chiama il metodo Configuation.isInitialized() per assicurarsi che Configuration non sia stato inizializzato.
2. Inizializza un oggetto Configuration con le coppie chiave-valore fornite da Google. Ogni coppia chiave-valore viene archiviata in un oggetto ConfigValue all'interno dell'oggetto Configuration.

Implementa l'interfaccia Repository

L'unico scopo dell'oggetto Repository è eseguire il traversale e l'indicizzazione degli elementi del repository. Quando utilizzi un modello, devi solo sostituire determinati metodi all'interno dell'interfacciaRepository per creare un connettore di contenuti. I metodi sostituiti dipendono dal modello e dalla strategia di attraversamento utilizzati. Per ListingConnector, override i seguenti metodi:

• Il metodo init(). Per eseguire la configurazione e l'inizializzazione del repository di dati, sostituisci il metodo init().

• Il metodo getIds(). Per recuperare gli ID e i valori hash per tutti i record nel repository, override il metodo getIds().

• Il metodo getDoc(). Per aggiungere nuovi elementi, aggiornare, modificare o eliminare elementi dall'indice, sostituisci il metodogetDoc().

• (Facoltativo) Il metodo getChanges(). Se il tuo repository supporta il rilevamento delle modifiche, sostituisci il metodo getChanges(). Questo metodo viene chiamato una volta per ogni traversal incrementale pianificato (come definito dalla configurazione) per recuperare gli elementi modificati e indicizzarli.

• (Facoltativo) Il metodo close(). Se devi eseguire la pulizia del repository, sostituisci il metodo close(). Questo metodo viene chiamato una volta durante l'arresto del connettore.

Ciascuno dei metodi dell'oggetto Repository restituisce un tipo di oggetto ApiOperation. Un oggetto ApiOperation esegue un'azione sotto forma di una o più chiamate IndexingService.indexItem() per eseguire l'indicizzazione effettiva del tuo repository.

Ottenere i parametri di configurazione personalizzati

Nell'ambito della gestione della configurazione del connettore, dovrai recuperare eventuali parametri personalizzati dall'oggetto Configuration. Questa operazione viene solitamente eseguita nel metodo init() di una Repository classe.

La classe Configuration ha diversi metodi per ottenere tipi di dati diversi da una configurazione. Ogni metodo restituisce un oggetto ConfigValue. Poi, utilizzerai il metodo get() dell'oggetto ConfigValue per recuperare il valore effettivo. Il seguente snippet, proveniente da FullTraversalSample, mostra come recuperare un singolo valore intero personalizzato da un oggetto Configuration:

@Override
public void init(RepositoryContext context) {
  log.info("Initializing repository");
  numberOfDocuments = Configuration.getInteger("sample.documentCount", 10).get();
}

Per ottenere e analizzare un parametro contenente più valori, utilizza uno degli analizzatori di tipo della classe Configuration per analizzare i dati in blocchi distinti. Il seguente snippet del connettore del tutorial utilizza il metodo getMultiValue per ottenere un elenco di nomi di repository GitHub:

ConfigValue<List<String>> repos = Configuration.getMultiValue(
    "github.repos",
    Collections.emptyList(),
    Configuration.STRING_PARSER);

Esegui l'esplorazione del grafo

Sostituisci metodo getIds() per recuperare gli ID e i valori hash di tutti i record nel repository. Il metodo getIds() accetta un checkpoint. Il checkpoint viene utilizzato per riprendere l'indicizzazione da un elemento specifico se il processo viene interrotto.

Successivamente, sostituisci il metodo getDoc() per gestire ogni elemento nella coda di indicizzazione di Cloud Search.

Invia gli ID elemento e i valori hash

Sostituisci getIds() per recuperare gli ID elemento e i relativi valori hash dei contenuti associati dal repository. Le coppie di ID e valori hash vengono poi pacchettizzate in una richiesta di operazione push alla coda di indicizzazione di Cloud Search. In genere, gli ID principali o principali vengono inviati prima, seguiti dagli ID secondari finché l'intera gerarchia di elementi non è stata elaborata.

Il metodo getIds() accetta un checkpoint che rappresenta l'ultimo elemento da indicizzare. Il checkpoint può essere utilizzato per riprendere l'indicizzazione da un elemento specifico se il processo viene interrotto. Per ogni elemento del repository, svolgi i seguenti passaggi nel metodo getIds():

• Recupera ogni ID elemento e il valore hash associato dal repository.
• Raggruppa ogni coppia di ID e valore hash in un PushItems.
• Combina ogni PushItems in un iteratore restituito dal metodo getIds(). Tieni presente che getIds() restituisce effettivamente un CheckpointCloseableIterable che è un'iterazione di ApiOperation oggetti, ciascuno dei quali rappresenta una richiesta API eseguita su un RepositoryDoc , ad esempio l'invio degli elementi alla coda.

Il seguente snippet di codice mostra come recuperare ogni ID articolo e valore hash e inserirli in un PushItems. Un PushItems è una ApiOperation richiesta di invio di un elemento alla coda di indicizzazione di Cloud Search.

PushItems.Builder allIds = new PushItems.Builder();
PushItem item = new PushItem();
allIds.addPushItem("root", item);

Il seguente snippet di codice mostra come utilizzare la classe PushItems.Builder per pacchettizzare gli ID e i valori hash in un unico push ApiOperation.

ApiOperation pushOperation = allIds.build();
CheckpointCloseableIterable<ApiOperation> iterator =
  new CheckpointCloseableIterableImpl.Builder<>(
      Collections.singletonList(pushOperation))
  .build();

Gli elementi vengono inviati alla coda di indicizzazione di Cloud Search per l'ulteriore elaborazione.

Recupera e gestisci ogni elemento

Sostituisci getDoc() per gestire ogni elemento nella coda di indicizzazione di Cloud Search. Un elemento può essere nuovo, modificato, invariato o non esistere più nel repository di origine. Recupera e indicizza ogni elemento nuovo o modificato. Rimuovi dall'indice gli elementi che non esistono più nel repository di origine.

Il metodo getDoc() accetta un elemento dalla coda di indicizzazione di Cloud Search. Per ogni elemento della coda, svolgi i seguenti passaggi nel metodo getDoc():

1. Verifica se l'ID dell'elemento, all'interno della coda di indicizzazione di Cloud Search, è presente nel repository. In caso contrario, elimina l'elemento dall'indice. Se l'articolo esiste, vai al passaggio successivo.

2. Indice modificato o nuovi elementi:

   1. Imposta le autorizzazioni.
   2. Imposta i metadati dell'elemento che stai indicizzando.
   3. Combina i metadati e l'elemento in un unico elemento indicizzato RepositoryDoc.
   4. Inserisci gli ID secondari nella coda di indicizzazione di Cloud Search per l'ulteriore elaborazione.
   5. Restituire il RepositoryDoc.

Gestire gli elementi eliminati

Il seguente snippet di codice mostra come determinare se un elemento esiste nell'indice e, in caso contrario, eliminarlo.

String resourceName = item.getName();
if (documentExists(resourceName)) {
  return buildDocumentAndChildren(resourceName);
}
// Document doesn't exist, delete it
log.info(() -> String.format("Deleting document %s", resourceName));
return ApiOperations.deleteItem(resourceName);

Impostare le autorizzazioni per un elemento

Il tuo repository utilizza un elenco di controllo dell'accesso (ACL) per identificare gli utenti o i gruppi che hanno accesso a un elemento. Un ACL è un elenco di ID di gruppi o utenti che possono accedere all'elemento.

Devi duplicare l'ACL utilizzato dal tuo repository per assicurarti che solo gli utenti con accesso a un elemento possano visualizzarlo in un risultato di ricerca. L'ACL per un elemento deve essere inclusa durante l'indicizzazione di un elemento in modo che Google Cloud Search disponga delle informazioni necessarie per fornire il livello di accesso corretto all'elemento.

L'SDK Content Connector fornisce un ampio insieme di classi e metodi ACL per modellare le ACL della maggior parte dei repository. Devi analizzare l'ACL per ogni elemento nel tuo repository e creare un'ACL corrispondente per Google Cloud Search quando esegui l'indicizzazione di un elemento. Se l'ACL del tuo repository utilizza concetti come l'eredità ACL, la relativa definizione può essere complicata. Per ulteriori informazioni sugli ACL di Google Cloud Search, consulta ACL di Google Cloud Search.

Nota:l'API Cloud Search Indexing supporta le ACL a dominio singolo. Non supporta le ACL interdominio. Utilizza la classe Acl.Builder per impostare l'accesso a ciascun elemento utilizzando un ACL. Lo snippet di codice riportato di seguito, tratto dall'esempio di attraversamento completo, consente a tutti gli utenti o "principali" (getCustomerPrincipal()) di essere "lettori" di tutti gli elementi (.setReaders()) quando viene eseguita una ricerca.

// Make the document publicly readable within the domain
Acl acl = new Acl.Builder()
    .setReaders(Collections.singletonList(Acl.getCustomerPrincipal()))
    .build();

Per modellare correttamente gli ACL per il repository, devi conoscerli. Ad esempio, potresti indicizzare i file all'interno di un file system che utilizza una sorta di modello di ereditarietà in cui le cartelle secondarie ereditano le autorizzazioni dalle cartelle principali. La definizione dell'eredità ACL richiede informazioni aggiuntive descritte nelle ACL di Google Cloud Search

Impostare i metadati di un elemento

I metadati vengono archiviati in un oggetto Item. Per creare un Item, devi avere almeno un ID stringa univoco, un tipo di elemento, un ACL, un URL e una versione per l'elemento. Il seguente snippet di codice mostra come creare un Item utilizzando la classe di supporto IndexingItemBuilder.

// Url is required. Use google.com as a placeholder for this sample.
String viewUrl = "https://www.google.com";

// Version is required, set to current timestamp.
byte[] version = Longs.toByteArray(System.currentTimeMillis());

// Using the SDK item builder class to create the document with
// appropriate attributes. This can be expanded to include metadata
// fields etc.
Item item = IndexingItemBuilder.fromConfiguration(documentId)
    .setItemType(IndexingItemBuilder.ItemType.CONTENT_ITEM)
    .setAcl(acl)
    .setSourceRepositoryUrl(IndexingItemBuilder.FieldOrValue.withValue(viewUrl))
    .setVersion(version)
    .build();

Crea l'elemento indicizzato

Dopo aver impostato i metadati per l'elemento, puoi creare l'elemento indicizzato effettivo utilizzando RepositoryDoc.Builder. L'esempio seguente mostra come creare un singolo elemento indicizzato.

// For this sample, content is just plain text
String content = String.format("Hello world from sample doc %s", documentId);
ByteArrayContent byteContent = ByteArrayContent.fromString("text/plain", content);

RepositoryDoc.Builder docBuilder = new RepositoryDoc.Builder()
    .setItem(item)
    .setContent(byteContent, IndexingService.ContentFormat.TEXT);

Un RepositoryDoc è un tipo di ApiOperation che esegue la richiesta IndexingService.indexItem() effettiva.

Puoi anche utilizzare il metodo setRequestMode() della classe RepositoryDoc.Builder per identificare la richiesta di indicizzazione come ASYNCHRONOUS o SYNCHRONOUS:

ASYNCHRONOUS

La modalità asincrona comporta una latenza dall'indicizzazione alla pubblicazione più lunga e consente una quota di throughput elevata per le richieste di indicizzazione. La modalità asincrona è consigliata per l'indicizzazione iniziale (backfill) dell'intero repository.

SYNCHRONOUS

La modalità sincrona comporta una latenza dall'indicizzazione alla pubblicazione più breve e supporta una quota di throughput limitata. La modalità sincrona è consigliata per l'indicizzazione di aggiornamenti e modifiche al repository. Se non specificato, la modalità di richiesta predefinita è SYNCHRONOUS.

Inserisci gli ID secondari nella coda di indicizzazione di Cloud Search

Il seguente snippet di codice mostra come includere gli ID secondari per l'elemento principale attualmente in fase di elaborazione nella coda per l'elaborazione. Questi ID vengono elaborati dopo l'indicizzazione dell'elemento principale.

// Queue the child nodes to visit after indexing this document
Set<String> childIds = getChildItemNames(documentId);
for (String id : childIds) {
  log.info(() -> String.format("Pushing child node %s", id));
  PushItem pushItem = new PushItem();
  docBuilder.addChildId(id, pushItem);
}

RepositoryDoc doc = docBuilder.build();

Passaggi successivi

Ecco alcuni passaggi successivi che puoi intraprendere:

• (Facoltativo) Implementa il metodo close() per rilasciare eventuali risorse prima dell'arresto.
• (Facoltativo) Crea un connettore di identità utilizzando l'SDK Identity Connector.

Creare un connettore di contenuti utilizzando l'API REST

Le sezioni seguenti spiegano come creare un connettore di contenuti utilizzando l'API REST.

Determina la strategia di attraversamento

La funzione principale di un connettore di contenuti è attraversare un repository e indicizzare i relativi dati. Devi implementare una strategia di attraversamento in base alle dimensioni e al layout dei dati nel tuo repository. Di seguito sono riportate tre strategie di traversale comuni:

Strategia di attraversamento completa

Una strategia di attraversamento completa esegue la scansione dell'intero repository e indicizza in modo cieco ogni elemento. Questa strategia viene comunemente utilizzata quando hai un piccolo repository e puoi permetterti l'overhead di eseguire un attraversamento completo ogni volta che esegui l'indicizzazione.

Questa strategia di attraversamento è adatta per piccoli repository con dati prevalentemente statici e non gerarchici. Puoi utilizzare questa strategia di attraversamento anche quando il rilevamento delle modifiche è difficile o non supportato dal repository.

Strategia di attraversamento dell'elenco

Una strategia di attraversamento dell'elenco esegue la scansione dell'intero repository, inclusi tutti i nodi secondari, determinando lo stato di ogni elemento. Il connettore esegue quindi un secondo passaggio e indicizza solo gli elementi nuovi o aggiornati dall'ultimo indicizzazione. Questa strategia viene comunemente utilizzata per eseguire aggiornamenti incrementali di un indice esistente (anziché dover eseguire un'esplorazione completa ogni volta che l'indice viene aggiornato).

Questa strategia di attraversamento è adatta quando il rilevamento delle modifiche è difficile o non supportato dal repository, quando hai dati non gerarchici e quando lavori con set di dati molto grandi.

Percorso del grafo

Una strategia di attraversamento del grafico esegue la scansione dell'intero nodo principale determinando lo stato di ciascun elemento. Il connettore esegue quindi un secondo passaggio e indicizza solo gli elementi nel nodo principale che sono nuovi o sono stati aggiornati dall'ultima indicizzazione. Infine, il connettore passa tutti gli ID secondari e poi indicizza gli elementi nei nodi secondari che sono nuovi o sono stati aggiornati. Il connettore continua in modo ricorsivo tra tutti i nodi secondari finché non sono stati indirizzati tutti gli elementi. Questo tipo di attraversamento viene solitamente utilizzato per i repository gerarchici in cui non è pratico elencare tutti gli ID.

Questa strategia è adatta se hai dati gerarchici che devono essere sottoposti a scansione, ad esempio directory di serie o pagine web.

Implementa la strategia di attraversamento e indicizza gli elementi

Ogni elemento indicizzabile per Cloud Search è definito elemento nell'API Cloud Search. Un elemento può essere un file, una cartella, una riga in un file CSV o un record di database.

Una volta registrato lo schema, puoi compilare l'indice:

1. (Facoltativo) Utilizzo di items.upload per caricare file di dimensioni superiori a 100 KiB per l'indicizzazione. Per i file più piccoli, incorpora i contenuti come inlineContent utilizzando items.index.

2. (Facoltativo) Utilizzo di media.upload per caricare file multimediali per l'indicizzazione.

3. Utilizza items.index per indicizzare l'elemento. Ad esempio, se lo schema utilizza la definizione dell'oggetto nello schema movie, una richiesta di indicizzazione per un singolo elemento sarà simile alla seguente:

   {
     "name": "datasource/<data_source_id>/items/titanic",
     "acl": {
       "readers": [
         {
           "gsuitePrincipal": {
             "gsuiteDomain": true
           }
         }
       ]
     },
     "metadata": {
       "title": "Titanic",
       "viewUrl": "http://www.imdb.com/title/tt2234155/?ref_=nv_sr_1",
       "objectType": "movie"
     },
     "structuredData": {
       "object": {
         "properties": [
           {
             "name": "movieTitle",
             "textValues": {
               "values": [
                 "Titanic"
               ]
             }
           },
           {
             "name": "releaseDate",
             "dateValues": {
               "values": [
                 {
                   "year": 1997,
                   "month": 12,
                   "day": 19
                 }
               ]
             }
           },
           {
             "name": "actorName",
             "textValues": {
               "values": [
                 "Leonardo DiCaprio",
                 "Kate Winslet",
                 "Billy Zane"
               ]
             }
           },
           {
             "name": "genre",
             "enumValues": {
               "values": [
                 "Drama",
                 "Action"
               ]
             }
           },
           {
             "name": "userRating",
             "integerValues": {
               "values": [
                 8
               ]
             }
           },
           {
             "name": "mpaaRating",
             "textValues": {
               "values": [
                 "PG-13"
               ]
             }
           },
           {
             "name": "duration",
             "textValues": {
               "values": [
                 "3 h 14 min"
               ]
             }
           }
         ]
       }
     },
     "content": {
       "inlineContent": "A seventeen-year-old aristocrat falls in love with a kind but poor artist aboard the luxurious, ill-fated R.M.S. Titanic.",
       "contentFormat": "TEXT"
     },
     "version": "01",
     "itemType": "CONTENT_ITEM"
   }
   

4. (Facoltativo) Utilizza le chiamate items.get per verificare che un elemento sia stato indicizzato.

Per eseguire un'esplorazione completa, devi indicizzare periodicamente l'intero repository. Per eseguire un'esplorazione di un elenco o di un grafo, devi implementare il codice per gestire le modifiche del repository.

Gestire le modifiche al repository

Puoi raccogliere e indicizzare periodicamente ogni elemento di un repository per eseguire un'indicizzazione completa. Sebbene sia efficace per garantire l'aggiornamento dell'indice, un'indicizzazione completa può essere costosa quando si tratta di repository più grandi o gerarchici.

Anziché utilizzare le chiamate di indicizzazione per indicizzare un intero repository di tanto in tanto, puoi anche utilizzare la coda di indicizzazione di Google Cloud come meccanismo per monitorare le modifiche e indicizzare solo gli elementi che sono stati modificati. Puoi utilizzare le richieste items.push per inviare elementi alla coda per il successivo polling e aggiornamento. Per ulteriori informazioni sulla coda di indicizzazione di Google Cloud, consulta la pagina Coda di indicizzazione di Google Cloud.

Per ulteriori informazioni sull'API Google Cloud Search, consulta la pagina relativa all'API Cloud Search.