Un connettore di contenuti è un programma software utilizzato per trasferire i dati nel repository di un'azienda e completare un'origine dati. Google offre le seguenti opzioni per lo sviluppo di connettori di contenuti:
L'SDK Content Connector. Questa è una buona opzione se stai programmando in Java. L'SDK Content Connector è un wrapper attorno all'API REST che consente di creare rapidamente connettori. Per creare un connettore di contenuti utilizzando l'SDK, consulta Creare un connettore di contenuti utilizzando l'SDK Content Connector.
Un'API REST o librerie API di basso livello. Utilizza queste opzioni se non stai programmando in Java o se il tuo codebase supporta meglio un'API REST o 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à:
- Legge ed elabora i parametri di configurazione.
- Estrae blocchi discreti di dati indicizzabili, chiamati "elementi", dal repository di contenuti di terze parti.
- Combina ACL, metadati e dati sui contenuti in elementi indicizzabili.
- Indicizza gli elementi nell'origine dati di Cloud Search.
- (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 sincronizzata l'origine dati di Cloud Search con il repository di terze parti. Il connettore esegue questa attività 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 build. Fai clic su una scheda in basso per visualizzare le dipendenze per il tuo ambiente di build:
Maven
<dependency>
<groupId>com.google.enterprise.cloudsearch</groupId>
<artifactId>google-cloudsearch-indexing-connector-sdk</artifactId>
<version>v1-0.0.3</version>
</dependency>
Gradle
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 di Google Cloud Search contiene diversi parametri di configurazione forniti da Google utilizzati da tutti i connettori. Nel file di configurazione devi dichiarare i seguenti parametri forniti da Google:
- Per un connettore di contenuti, devi dichiarare
api.sourceId
eapi.serviceAccountPrivateKeyFile
poiché questi parametri identificano la località del repository e la chiave privata necessarie per accedere al repository.
- Per un connettore di identità, devi dichiarare
api.identitySourceId
, poiché questo parametro identifica la località dell'origine identità esterna. Se sincronizzi gli utenti, devi anche dichiarareapi.customerId
come ID univoco per l'account Google Workspace della tua azienda.
A meno che tu non voglia eseguire l'override dei 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 l'articolo sui parametri di configurazione forniti da Google.
Puoi anche definire 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
.
Stabilire la strategia di attraversamento
La funzione principale di un connettore di contenuti è attraversare un repository e indicizzarne i dati. Devi implementare una strategia di attraversamento basata sulle dimensioni e sul layout dei dati nel repository. Puoi progettare la tua strategia o scegliere tra le seguenti strategie implementate nell'SDK:
- Strategia di attraversamento completo
Una strategia di attraversamento completo analizza l'intero repository e indicizza in modo cieco ogni elemento. Questa strategia viene solitamente utilizzata quando si dispone di un repository di piccole dimensioni e può portare l'overhead associato a un full traversal ogni volta che si esegue l'indicizzazione.
Questa strategia di attraversamento è adatta a repository di piccole dimensioni con dati per lo più 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 elenco
Una strategia di trasferimento elenco esegue la scansione dell'intero repository, inclusi tutti i nodi figlio, determinando lo stato di ogni elemento. Quindi, il connettore accetta un secondo passaggio e indicizza solo gli elementi nuovi o aggiornati dopo l'ultima indicizzazione. Questa strategia viene solitamente utilizzata per eseguire aggiornamenti incrementali a un indice esistente (anziché dover eseguire un attraversamento completo ogni volta che viene aggiornato l'indice).
Questa strategia di attraversamento è adatta quando il rilevamento delle modifiche è difficile o non è supportata dal repository, hai dati non gerarchici e utilizzi set di dati molto grandi.
- Attraversamento grafico
Una strategia di attraversamento grafico analizza l'intero nodo padre per determinare lo stato di ciascun elemento. Quindi, il connettore riceve una seconda verifica e indicizza solo gli elementi nel nodo principale che sono nuovi o sono stati aggiornati dopo l'ultima indicizzazione. Infine, il connettore passa tutti gli ID figlio, quindi indicizza gli elementi nei nodi figlio nuovi o che sono stati aggiornati. Il connettore continua in modo ricorsivo attraverso tutti i nodi figlio fino a quando tutti gli elementi non sono stati gestiti. Questo attraversamento viene in genere utilizzato per i repository gerarchici, in cui l'elenco di tutti gli ID non è pratico.
Questa strategia è adatta se hai dati gerarchici che devono essere sottoposti a scansione, come una serie di directory o pagine web.
Ognuna di queste strategie di attraversamento viene implementata da una classe di connettori modelli nell'SDK. Sebbene sia possibile implementare la tua strategia di trasferimento, questi modelli velocizzano notevolmente lo sviluppo del connettore. Per creare un connettore utilizzando un modello, procedi alla sezione corrispondente alla strategia di trasferimento:
- Crea un connettore di attraversamento completo utilizzando una classe modello
- Crea un connettore di attraversamento elenco utilizzando una classe modello
- Crea un connettore di attraversamento grafico utilizzando una classe modello
Crea un connettore di attraversamento completo utilizzando una classe modello
Questa sezione dei documenti fa riferimento agli snippet di codice dell'esempio FullTraversalSample.
Implementa il punto di ingresso del connettore
Il punto di ingresso di un connettore è il
metodo main()
. L'attività principale di questo metodo è creare un'istanza della classe Application
e richiamare il metodo start()
per eseguire il connettore.
Prima di chiamare
application.start()
,
utilizza la classe
IndexingApplication.Builder
per creare un'istanza del modello
FullTraversalConnector
. FullTraversalConnector
accetta un oggetto Repository
di cui implementi i metodi. Il seguente snippet di codice mostra come implementare il metodo main()
:
In background, l'SDK chiama il metodo
initConfig()
dopo le chiamate al metodo main()
del connettore
Application.build
.
Il metodo initConfig()
esegue le attività seguenti:
- Chiama il metodo
Configuation.isInitialized()
per garantire cheConfiguration
non sia stato inizializzato. - Inizializza un oggetto
Configuration
con le coppie chiave-valore fornite da Google. Ogni coppia chiave-valore è archiviata in un oggettoConfigValue
all'interno dell'oggettoConfiguration
.
Implementa l'interfaccia di Repository
L'unico scopo dell'oggetto Repository
è eseguire l'attraversamento e
l'indicizzazione degli elementi del repository. Quando utilizzi
un modello, devi eseguire l'override solo di alcuni metodi nell'interfaccia Repository
per creare un connettore di contenuti. I metodi da sostituire dipendono dal modello
e dalla strategia di attraversamento utilizzati. Per FullTraversalConnector
, sostituisci i seguenti metodi:
Il metodo
init()
. Per eseguire qualsiasi configurazione e inizializzazione del repository di dati, sostituisci il metodoinit()
.Il metodo
getAllDocs()
. Per attraversare e indicizzare tutti gli elementi nel repository di dati, sostituisci il metodogetAllDocs()
. Questo metodo viene chiamato una volta per ogni attraversamento pianificato (come definito dalla tua configurazione).(Facoltativo) Il metodo
getChanges()
. Se il repository supporta il rilevamento delle modifiche, sostituisci il metodogetChanges()
. Questo metodo viene chiamato una volta per ogni attraversamento incrementale pianificato (come definito dalla tua configurazione) al fine di recuperare gli elementi modificati e indicizzarli.(Facoltativo) Il metodo
close()
. Se devi eseguire la pulizia del repository, sostituisci il metodoclose()
. 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 singola o
forse più chiamate IndexingService.indexItem()
per eseguire l'indicizzazione effettiva del repository.
Ottieni parametri di configurazione personalizzati
Come parte della gestione della configurazione del connettore, dovrai ottenere tutti i parametri personalizzati dall'oggetto Configuration
. Questa attività viene in genere eseguita nel metodo init()
di una classe Repository
.
La classe Configuration
prevede diversi metodi per ottenere diversi tipi di dati da una configurazione. Ogni metodo restituisce un oggetto ConfigValue
. Utilizzerai quindi il metodo get()
dell'oggetto ConfigValue
per recuperare il valore effettivo.
Il seguente snippet, da FullTraversalSample
, mostra come recuperare un singolo valore intero personalizzato da un oggetto Configuration
:
Per recuperare e analizzare un parametro contenente diversi valori, utilizza uno dei parser
di tipo di classe Configuration
per analizzare i dati in blocchi discreti.
Lo snippet seguente, del connettore tutorial utilizza il metodo getMultiValue
per ottenere un elenco dei nomi dei repository GitHub:
Eseguire un attraversamento completo
Esegui l'override di getAllDocs()
per eseguire un attraversamento completo e indicizzare il repository. Il metodo getAllDocs()
accetta un checkpoint. Il checkpoint viene utilizzato per riprendere l'indicizzazione di un elemento specifico in caso di interruzione del processo. Per ogni elemento del tuo repository, esegui questi passaggi nel metodo getAllDocs()
:
- Imposta le autorizzazioni.
- Imposta i metadati per l'elemento che stai indicizzando.
- Combina i metadati e l'elemento in un'unica
RepositoryDoc
indicizzabile. - Pacchettizza ogni elemento indicizzabile in un iteratore restituito dal metodo
getAllDocs()
. Tieni presente chegetAllDocs()
restituisce in realtà unCheckpointCloseableIterable
, ovvero un'iterazione di oggettiApiOperation
, ciascuno dei quali rappresenta una richiesta API eseguita su unRepositoryDoc
, 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 più elementi sono disponibili per l'indicizzazione.
Impostare le autorizzazioni per un elemento
Il 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 per i gruppi o gli 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 vedere l'elemento in un risultato di ricerca. L'ACL di un elemento deve essere incluso durante l'indicizzazione di un elemento, in modo che Google Cloud Search abbia le informazioni necessarie per fornire il livello di accesso corretto all'elemento.
L'SDK Content Connector fornisce un ricco set di classi e metodi ACL per modellare gli ACL della maggior parte dei repository. Devi analizzare l'ACL per ogni elemento del repository e creare un ACL corrispondente per Google Cloud Search quando esegui l'indicizzazione di un elemento. Se l'ACL del repository utilizza concetti come l'ereditarietà ACL, la modellazione dell'ACL può essere complessa. Per ulteriori informazioni sugli ACL di Google Cloud Search, consulta la pagina relativa agli ACL di Google Cloud Search.
Nota:l'API Cloud Search Index supporta gli ACL a dominio singolo. Non supporta gli ACL tra domini. Usa la classe Acl.Builder
per impostare l'accesso a ciascun elemento tramite un ACL. Il seguente snippet di codice, tratto
dall'esempio di attraversamento completo, consente
a tutti gli utenti o alle "entità"
(getCustomerPrincipal()
)
di essere "lettori" di tutti gli elementi
(.setReaders()
)
quando eseguono una ricerca.
Devi comprendere gli ACL per modellare correttamente gli ACL per il repository. Ad esempio, è possibile che tu stia indicizzando 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. L'ereditarietà degli ACL di modellazione richiede ulteriori informazioni trattate negli ACL di Google Cloud Search
Impostare i metadati per un elemento
I metadati sono archiviati in un oggetto Item
. Per creare un Item
, devi disporre almeno di 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 helper IndexingItemBuilder
.
Crea l'elemento indicizzabile
Dopo aver impostato i metadati per l'elemento, puoi creare l'elemento indicizzabile effettivo utilizzando la classe RepositoryDoc.Builder
. L'esempio seguente mostra come creare un singolo elemento indicizzabile.
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 più lunga dall'indicizzazione alla pubblicazione e gestisce una quota di velocità effettiva elevata per le richieste di indicizzazione. La modalità asincrona è consigliata per l'indicizzazione iniziale (backfill) dell'intero repository.
SYNCHRONOUS
- La modalità sincrona produce una latenza più breve dall'indicizzazione alla pubblicazione e
gestisce una quota di velocità effettiva limitata. La modalità sincrona è consigliata per l'indicizzazione di aggiornamenti e modifiche al repository. Se
non specificata, la modalità di richiesta è impostata su
SYNCHRONOUS
per impostazione predefinita.
Pacchettizza ogni elemento indicizzabile in un iteratore
Il metodo getAllDocs()
restituisce un elemento Iterator
, in particolare un
CheckpointCloseableIterable
di
RepositoryDoc
oggetti. Puoi utilizzare la classe CheckpointClosableIterableImpl.Builder
per costruire e restituire un iteratore. Il seguente snippet di codice mostra
come creare e restituire un iteratore.
L'SDK esegue ogni chiamata di indicizzazione racchiusa nell'iteratore.
Passaggi successivi
Di seguito sono riportati alcuni passaggi che puoi eseguire:
- (Facoltativo) Se la velocità effettiva di indicizzazione sembra lenta, consulta la sezione 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.
Crea un connettore di attraversamento elenco utilizzando una classe di modello
La coda di indicizzazione di Cloud Search viene utilizzata per memorizzare ID e valori hash facoltativi per ogni elemento nel repository. Un connettore elenco attraversamento invia gli ID elemento alla coda di indicizzazione di Google Cloud Search e li recupera uno alla volta per l'indicizzazione. Google Cloud Search conserva le code e confronta i contenuti delle code 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 agli snippet di codice dell'esempio ListTraversalSample.
Implementa il punto di ingresso del connettore
Il punto di ingresso di un connettore è il
metodo main()
. L'attività principale di questo metodo è creare un'istanza della classe Application
e richiamare il metodo start()
per eseguire il connettore.
Prima di chiamare
application.start()
,
utilizza la classe
IndexingApplication.Builder
per creare un'istanza del modello
ListingConnector
. ListingConnector
accetta un oggetto
Repository
di cui implementi i metodi. Lo snippet seguente mostra come
identificare ListingConnector
e il relativo Repository
associato:
In background, l'SDK chiama il metodo
initConfig()
dopo le chiamate al metodo main()
del connettore
Application.build
.
Il metodo initConfig()
:
- Chiama il metodo
Configuation.isInitialized()
per garantire cheConfiguration
non sia stato inizializzato. - Inizializza un oggetto
Configuration
con le coppie chiave-valore fornite da Google. Ogni coppia chiave-valore è archiviata in un oggettoConfigValue
all'interno dell'oggettoConfiguration
.
Implementa l'interfaccia di Repository
L'unico scopo dell'oggetto Repository
è eseguire l'attraversamento e
l'indicizzazione degli elementi del repository. Quando utilizzi un modello, devi sostituire solo alcuni metodi nell'interfaccia Repository
per creare un connettore di contenuti.
I metodi da sostituire dipendono dal modello e dalla strategia di attraversamento utilizzati. Per ListingConnector
, sostituisci i seguenti metodi:
Il metodo
init()
. Per eseguire qualsiasi configurazione e inizializzazione del repository di dati, sostituisci il metodoinit()
.Il metodo
getIds()
. Per recuperare gli ID e i valori hash per tutti i record nel repository, esegui l'override del metodogetIds()
.Il metodo
getDoc()
. Per aggiungere nuovi elementi, aggiornare, modificare o eliminare elementi dall'indice, sostituisci il metodogetDoc()
.(Facoltativo) Il metodo
getChanges()
. Se il repository supporta il rilevamento delle modifiche, sostituisci il metodogetChanges()
. Questo metodo viene chiamato una volta per ogni attraversamento incrementale pianificato (come definito dalla tua configurazione) al fine di recuperare gli elementi modificati e indicizzarli.(Facoltativo) Il metodo
close()
. Se devi eseguire la pulizia del repository, sostituisci il metodoclose()
. 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 singola o
forse più chiamate IndexingService.indexItem()
per eseguire l'indicizzazione effettiva del repository.
Ottieni parametri di configurazione personalizzati
Come parte della gestione della configurazione del connettore, dovrai ottenere tutti i parametri personalizzati dall'oggetto Configuration
. Questa attività viene in genere eseguita nel metodo init()
di una classe Repository
.
La classe Configuration
prevede diversi metodi per ottenere diversi tipi di dati da una configurazione. Ogni metodo restituisce un oggetto ConfigValue
. Utilizzerai quindi il metodo get()
dell'oggetto ConfigValue
per recuperare il valore effettivo.
Il seguente snippet, da FullTraversalSample
, mostra come recuperare un singolo valore intero personalizzato da un oggetto Configuration
:
Per recuperare e analizzare un parametro contenente diversi valori, utilizza uno dei parser
di tipo di classe Configuration
per analizzare i dati in blocchi discreti.
Lo snippet seguente, del connettore tutorial utilizza il metodo getMultiValue
per ottenere un elenco dei nomi dei repository GitHub:
Eseguire il trasferimento elenco
Esegui l'override del metodo getIds()
per recuperare gli ID e i valori hash per tutti i record nel repository.
Il metodo getIds()
accetta un checkpoint. Il checkpoint viene utilizzato per riprendere
l'indicizzazione di un elemento specifico in caso di interruzione del processo.
Poi, sostituisci il metodo getDoc()
per gestire ogni elemento nella coda di indicizzazione di Cloud Search.
Invia ID elemento e valori hash
Esegui l'override di getIds()
per recuperare gli ID elemento e i valori hash dei contenuti associati dal repository. Le coppie ID e valore hash vengono quindi pacchettizzate in una richiesta dell'operazione push alla coda di indicizzazione di Cloud Search. In genere, gli ID radice o principali vengono inviati per primi, seguiti dagli ID secondari, fino a quando 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 in un elemento specifico in caso di interruzione del processo. Per ogni elemento del repository, esegui questi
passaggi nel metodo getIds()
:
- Recupera ogni ID elemento e il valore hash associato dal repository.
- Pacchettizza ogni coppia ID e valore hash in una
PushItems
. - Combina ogni
PushItems
in un iteratore restituito dal metodogetIds()
. Tieni presente chegetIds()
in realtà restituisce unCheckpointCloseableIterable
, ovvero un'iterazione di oggettiApiOperation
, ciascuno dei quali rappresenta una richiesta API eseguita su un elementoRepositoryDoc
, ad esempio il push degli elementi in coda.
Il seguente snippet di codice mostra come ottenere ogni ID articolo e ogni valore hash e
inserirli in un
PushItems
.
Una PushItems
è una richiesta ApiOperation
per eseguire il push di un elemento alla coda di indicizzazione di Cloud Search.
Il seguente snippet di codice mostra come utilizzare la classe PushItems.Builder
per pacchettizzare gli ID e i valori hash in un'unica push ApiOperation
.
Gli elementi vengono inviati alla coda di indicizzazione di Cloud Search per ulteriori elaborazioni.
Recupera e gestisci ogni elemento
Esegui l'override di getDoc()
per gestire ogni elemento nella coda di indicizzazione di Cloud Search.
Un elemento può essere nuovo, modificato, non modificato o non può più esistere 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 nella coda, esegui questi passaggi nel
metodo getDoc()
:
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.
Esegui un sondaggio nell'indice per verificare lo stato dell'elemento e, se un elemento non è stato modificato (
ACCEPTED
), non fare nulla.Indice modificato o nuovi elementi:
- Imposta le autorizzazioni.
- Imposta i metadati per l'elemento che stai indicizzando.
- Combina i metadati e l'elemento in un'unica
RepositoryDoc
indicizzabile. - Restituisci
RepositoryDoc
.
Nota: il modello ListingConnector
non supporta la restituzione di null
sul
metodo getDoc()
. La restituzione di null
comporta la restituzione di un NullPointerException.
Gestire gli elementi eliminati
Il seguente snippet di codice mostra come determinare se un elemento esiste nel repository e, in caso contrario, eliminarlo.
Tieni presente che documents
è una struttura di dati che rappresenta il repository. Se documentID
non viene trovato in documents
, restituisci APIOperations.deleteItem(resourceName)
per eliminare l'elemento dall'indice.
Gestire gli elementi che non sono stati modificati
Il seguente snippet di codice mostra come eseguire il polling dello stato di un elemento nella coda di indicizzazione di Cloud Search e gestire un elemento invariato.
Per determinare se l'elemento non è stato modificato, controllane lo stato e altri metadati che potrebbero indicare una modifica. Nell'esempio, viene usato l'hash dei metadati per determinare se l'elemento è stato modificato.
Impostare le autorizzazioni per un elemento
Il 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 per i gruppi o gli 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 vedere l'elemento in un risultato di ricerca. L'ACL di un elemento deve essere incluso durante l'indicizzazione di un elemento, in modo che Google Cloud Search abbia le informazioni necessarie per fornire il livello di accesso corretto all'elemento.
L'SDK Content Connector fornisce un ricco set di classi e metodi ACL per modellare gli ACL della maggior parte dei repository. Devi analizzare l'ACL per ogni elemento del repository e creare un ACL corrispondente per Google Cloud Search quando esegui l'indicizzazione di un elemento. Se l'ACL del repository utilizza concetti come l'ereditarietà ACL, la modellazione dell'ACL può essere complessa. Per ulteriori informazioni sugli ACL di Google Cloud Search, consulta la pagina relativa agli ACL di Google Cloud Search.
Nota:l'API Cloud Search Index supporta gli ACL a dominio singolo. Non supporta gli ACL tra domini. Usa la classe Acl.Builder
per impostare l'accesso a ciascun elemento tramite un ACL. Il seguente snippet di codice, tratto
dall'esempio di attraversamento completo, consente
a tutti gli utenti o alle "entità"
(getCustomerPrincipal()
)
di essere "lettori" di tutti gli elementi
(.setReaders()
)
quando eseguono una ricerca.
Devi comprendere gli ACL per modellare correttamente gli ACL per il repository. Ad esempio, è possibile che tu stia indicizzando 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. L'ereditarietà degli ACL di modellazione richiede ulteriori informazioni trattate negli ACL di Google Cloud Search
Impostare i metadati per un elemento
I metadati sono archiviati in un oggetto Item
. Per creare un Item
, devi disporre almeno di 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 helper IndexingItemBuilder
.
Creare un elemento indicizzabile
Dopo aver impostato i metadati per l'elemento, puoi creare l'effettivo elemento indicizzabile utilizzando RepositoryDoc.Builder
.
L'esempio seguente mostra come creare un singolo elemento indicizzabile.
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 più lunga dall'indicizzazione alla pubblicazione e gestisce una quota di velocità effettiva elevata per le richieste di indicizzazione. La modalità asincrona è consigliata per l'indicizzazione iniziale (backfill) dell'intero repository.
SYNCHRONOUS
- La modalità sincrona produce una latenza più breve dall'indicizzazione alla pubblicazione e
gestisce una quota di velocità effettiva limitata. La modalità sincrona è consigliata per l'indicizzazione di aggiornamenti e modifiche al repository. Se
non specificata, la modalità di richiesta è impostata su
SYNCHRONOUS
per impostazione predefinita.
Passaggi successivi
Di seguito sono riportati alcuni passaggi che puoi eseguire:
- (Facoltativo) Implementa il metodo
close()
per rilasciare eventuali risorse prima dell'arresto. - (Facoltativo) Crea un connettore di identità utilizzando l'SDK Content Connector.
Crea un connettore di attraversamento grafico utilizzando una classe modello
La coda di indicizzazione di Cloud Search viene utilizzata per memorizzare gli ID e i valori hash facoltativi per ogni elemento nel repository. Un connettore di attraversamento grafico invia gli ID elemento alla coda di indicizzazione di Google Cloud Search e li recupera uno alla volta per l'indicizzazione. Google Cloud Search conserva le code e confronta i contenuti delle code per determinare lo stato degli elementi, ad esempio se un elemento è stato eliminato dal repository. Per saperne di più sulla coda di indicizzazione di Cloud Search, consulta La coda di indicizzazione di Google Cloud Search.
Durante l'indice, i contenuti degli elementi vengono recuperati dal repository di dati e gli ID degli elementi secondari 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 agli snippet di codice dell'esempio GraphTraversalSample.
Implementa il punto di ingresso del connettore
Il punto di ingresso di un connettore è il
metodo main()
. L'attività principale di questo metodo è creare un'istanza della classe Application
e richiamare il metodo start()
per eseguire il connettore.
Prima di chiamare
application.start()
,
utilizza la classe
IndexingApplication.Builder
per creare un'istanza del modello ListingConnector
. ListingConnector
accetta un oggetto Repository
di cui implementi i metodi.
Lo snippet seguente mostra come
identificare ListingConnector
e il relativo Repository
associato:
In background, l'SDK chiama il metodo
initConfig()
dopo le chiamate al metodo main()
del connettore
Application.build
.
Il metodo initConfig()
:
- Chiama il metodo
Configuation.isInitialized()
per garantire cheConfiguration
non sia stato inizializzato. - Inizializza un oggetto
Configuration
con le coppie chiave-valore fornite da Google. Ogni coppia chiave-valore è archiviata in un oggettoConfigValue
all'interno dell'oggettoConfiguration
.
Implementa l'interfaccia di Repository
L'unico scopo
dell'oggetto Repository
è eseguire l'attraversamento e l'indicizzazione degli elementi
del repository. Quando utilizzi un modello, devi eseguire l'override solo di alcuni metodi nell'interfaccia Repository
per creare un connettore di contenuti. I metodi da sostituire dipendono dal modello e dalla strategia di attraversamento utilizzati. Per ListingConnector
, esegui l'override dei seguenti metodi:
Il metodo
init()
. Per eseguire qualsiasi configurazione e inizializzazione del repository di dati, sostituisci il metodoinit()
.Il metodo
getIds()
. Per recuperare gli ID e i valori hash per tutti i record nel repository, esegui l'override del metodogetIds()
.Il metodo
getDoc()
. Per aggiungere nuovi elementi, aggiornare, modificare o eliminare elementi dall'indice, sostituisci il metodogetDoc()
.(Facoltativo) Il metodo
getChanges()
. Se il repository supporta il rilevamento delle modifiche, sostituisci il metodogetChanges()
. Questo metodo viene chiamato una volta per ogni attraversamento incrementale pianificato (come definito dalla tua configurazione) al fine di recuperare gli elementi modificati e indicizzarli.(Facoltativo) Il metodo
close()
. Se devi eseguire la pulizia del repository, sostituisci il metodoclose()
. 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 forse più chiamate
IndexingService.indexItem()
per eseguire l'indicizzazione effettiva del tuo repository.
Ottieni parametri di configurazione personalizzati
Come parte della gestione della configurazione del connettore, dovrai ottenere tutti i parametri personalizzati dall'oggetto Configuration
. Questa attività viene in genere eseguita nel metodo init()
di una classe Repository
.
La classe Configuration
prevede diversi metodi per ottenere diversi tipi di dati da una configurazione. Ogni metodo restituisce un oggetto ConfigValue
. Utilizzerai quindi il metodo get()
dell'oggetto ConfigValue
per recuperare il valore effettivo.
Il seguente snippet, da FullTraversalSample
, mostra come recuperare un singolo valore intero personalizzato da un oggetto Configuration
:
Per recuperare e analizzare un parametro contenente diversi valori, utilizza uno dei parser
di tipo di classe Configuration
per analizzare i dati in blocchi discreti.
Lo snippet seguente, del connettore tutorial utilizza il metodo getMultiValue
per ottenere un elenco dei nomi dei repository GitHub:
Eseguire l'attraversamento del grafico
Esegui l'override del metodo getIds()
per recuperare gli ID e i valori hash per tutti i record nel repository.
Il metodo getIds()
accetta un checkpoint. Il checkpoint viene utilizzato per riprendere
l'indicizzazione di un elemento specifico in caso di interruzione del processo.
Poi, sostituisci il metodo getDoc()
per gestire ogni elemento nella coda di indicizzazione di Cloud Search.
Invia ID elemento e valori hash
Esegui l'override di getIds()
per recuperare gli ID elemento e i valori hash dei contenuti associati dal repository. Le coppie ID e valore hash vengono quindi pacchettizzate in una richiesta dell'operazione push alla coda di indicizzazione di Cloud Search. In genere, gli ID radice o principali vengono inviati per primi, seguiti dagli ID secondari, fino a quando 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 in un elemento specifico in caso di interruzione del processo. Per ogni elemento del repository, esegui questi
passaggi nel metodo getIds()
:
- Recupera ogni ID elemento e il valore hash associato dal repository.
- Pacchettizza ogni coppia ID e valore hash in una
PushItems
. - Combina ogni
PushItems
in un iteratore restituito dal metodogetIds()
. Tieni presente chegetIds()
in realtà restituisce unCheckpointCloseableIterable
, ovvero un'iterazione di oggettiApiOperation
, ciascuno dei quali rappresenta una richiesta API eseguita su un elementoRepositoryDoc
, ad esempio il push degli elementi in coda.
Il seguente snippet di codice mostra come ottenere ogni ID articolo e ogni valore hash e
inserirli in un
PushItems
. Una richiesta PushItems
è una
richiesta ApiOperation
per eseguire il push di un elemento alla coda di indicizzazione di Cloud Search.
Il seguente snippet di codice mostra come utilizzare la classe PushItems.Builder
per pacchettizzare gli ID e i valori hash in un'unica push ApiOperation
.
Gli elementi vengono inviati alla coda di indicizzazione di Cloud Search per ulteriori elaborazioni.
Recupera e gestisci ogni elemento
Esegui l'override di getDoc()
per gestire ogni elemento nella coda di indicizzazione di Cloud Search.
Un elemento può essere nuovo, modificato, non modificato o non può più esistere 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 nella coda, esegui questi passaggi nel
metodo getDoc()
:
Verifica se l'ID dell'elemento, all'interno della coda di indicizzazione di Cloud Search, esiste nel repository. In caso contrario, elimina l'elemento dall'indice. Se l'elemento esiste, continua con il passaggio successivo.
Indice modificato o nuovi elementi:
- Imposta le autorizzazioni.
- Imposta i metadati per l'elemento che stai indicizzando.
- Combina i metadati e l'elemento in un'unica
RepositoryDoc
indicizzabile. - Inserisci gli ID figlio nella coda di indicizzazione di Cloud Search per ulteriori elaborazioni.
- Restituisci
RepositoryDoc
.
Gestire gli elementi eliminati
Il seguente snippet di codice mostra come determinare se un elemento esiste nell'indice e come eliminarlo.
Impostare le autorizzazioni per un elemento
Il 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 per i gruppi o gli 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 vedere l'elemento in un risultato di ricerca. L'ACL di un elemento deve essere incluso durante l'indicizzazione di un elemento, in modo che Google Cloud Search abbia le informazioni necessarie per fornire il livello di accesso corretto all'elemento.
L'SDK Content Connector fornisce un ricco set di classi e metodi ACL per modellare gli ACL della maggior parte dei repository. Devi analizzare l'ACL per ogni elemento del repository e creare un ACL corrispondente per Google Cloud Search quando esegui l'indicizzazione di un elemento. Se l'ACL del repository utilizza concetti come l'ereditarietà ACL, la modellazione dell'ACL può essere complessa. Per ulteriori informazioni sugli ACL di Google Cloud Search, consulta la pagina relativa agli ACL di Google Cloud Search.
Nota:l'API Cloud Search Index supporta gli ACL a dominio singolo. Non supporta gli ACL tra domini. Usa la classe Acl.Builder
per impostare l'accesso a ciascun elemento tramite un ACL. Il seguente snippet di codice, tratto
dall'esempio di attraversamento completo, consente
a tutti gli utenti o alle "entità"
(getCustomerPrincipal()
)
di essere "lettori" di tutti gli elementi
(.setReaders()
)
quando eseguono una ricerca.
Devi comprendere gli ACL per modellare correttamente gli ACL per il repository. Ad esempio, è possibile che tu stia indicizzando 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. L'ereditarietà degli ACL di modellazione richiede ulteriori informazioni trattate negli ACL di Google Cloud Search
Impostare i metadati per un elemento
I metadati sono archiviati in un oggetto Item
. Per creare un Item
, devi disporre almeno di 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 helper IndexingItemBuilder
.
Crea l'elemento indicizzabile
Dopo aver impostato i metadati per l'elemento, puoi creare l'effettivo elemento indicizzabile utilizzando RepositoryDoc.Builder
.
L'esempio seguente mostra come creare un singolo elemento indicizzabile.
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 più lunga dall'indicizzazione alla pubblicazione e gestisce una quota di velocità effettiva elevata per le richieste di indicizzazione. La modalità asincrona è consigliata per l'indicizzazione iniziale (backfill) dell'intero repository.
SYNCHRONOUS
- La modalità sincrona produce una latenza più breve dall'indicizzazione alla pubblicazione e
gestisce una quota di velocità effettiva limitata. La modalità sincrona è consigliata per l'indicizzazione di aggiornamenti e modifiche al repository. Se
non specificata, la modalità di richiesta è impostata su
SYNCHRONOUS
per impostazione predefinita.
Inserisci gli ID figlio nella coda di indicizzazione di Cloud Search
Il seguente snippet di codice mostra come includere gli ID figlio per l'elemento principale in fase di elaborazione nella coda per l'elaborazione. Questi ID vengono elaborati dopo l'indicizzazione dell'elemento principale.
Passaggi successivi
Di seguito sono riportati alcuni passaggi che puoi eseguire:
- (Facoltativo) Implementa il metodo
close()
per rilasciare eventuali risorse prima dell'arresto. - (Facoltativo) Crea un connettore di identità utilizzando l'SDK Identity Connector.
crea un connettore di contenuti utilizzando l'API REST
Le sezioni seguenti spiegano come creare un connettore di contenuti utilizzando l'API REST.
Stabilire la strategia di attraversamento
La funzione principale di un connettore di contenuti è attraversare un repository e indicizzarne i dati. Devi implementare una strategia di attraversamento basata sulle dimensioni e sul layout dei dati nel repository. Di seguito sono riportate tre strategie di attraversamento comuni:
- Strategia di attraversamento completo
Una strategia di attraversamento completo analizza l'intero repository e indicizza in modo cieco ogni elemento. Questa strategia viene solitamente utilizzata quando si dispone di un repository di piccole dimensioni e può portare l'overhead associato a un full traversal ogni volta che si esegue l'indicizzazione.
Questa strategia di attraversamento è adatta a repository di piccole dimensioni con dati per lo più 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 elenco
Una strategia di trasferimento elenco esegue la scansione dell'intero repository, inclusi tutti i nodi figlio, determinando lo stato di ogni elemento. Quindi, il connettore accetta un secondo passaggio e indicizza solo gli elementi nuovi o aggiornati dopo l'ultima indicizzazione. Questa strategia viene solitamente utilizzata per eseguire aggiornamenti incrementali a un indice esistente (anziché dover eseguire un attraversamento completo ogni volta che viene aggiornato l'indice).
Questa strategia di attraversamento è adatta quando il rilevamento delle modifiche è difficile o non è supportata dal repository, hai dati non gerarchici e utilizzi set di dati molto grandi.
- Attraversamento grafico
Una strategia di attraversamento grafico analizza l'intero nodo padre per determinare lo stato di ciascun elemento. Quindi, il connettore riceve una seconda verifica e indicizza solo gli elementi nel nodo principale che sono nuovi o sono stati aggiornati dopo l'ultima indicizzazione. Infine, il connettore passa tutti gli ID figlio, quindi indicizza gli elementi nei nodi figlio nuovi o che sono stati aggiornati. Il connettore continua in modo ricorsivo attraverso tutti i nodi figlio fino a quando tutti gli elementi non sono stati gestiti. Questo attraversamento viene in genere utilizzato per i repository gerarchici, in cui l'elenco di tutti gli ID non è pratico.
Questa strategia è adatta se hai dati gerarchici che devono essere sottoposti a scansione, ad esempio directory di serie o pagine web.
Implementazione della strategia di attraversamento e degli elementi di indice
Ogni elemento indicizzabile per Cloud Search è definito elemento nell'API Cloud Search. Un elemento può essere un file, una cartella, una riga di un file CSV o un record di database.
Una volta registrato lo schema, puoi completare l'indice in base a:
(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 utilizzandoitems.index
.(Facoltativo) Utilizzare
media.upload
per caricare file multimediali da indicizzare.Utilizzo di
items.index
per indicizzare l'elemento. Ad esempio, se il tuo schema utilizza la definizione dell'oggetto nello schema filmato, una richiesta di indicizzazione per un singolo elemento avrebbe il seguente aspetto:{ "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" }
(Facoltativo) Utilizzo delle chiamate items.get per verificare che un item sia stato indicizzato.
Per eseguire un attraversamento completo, reindicizza periodicamente l'intero repository. Per eseguire un attraversamento elenco o grafico, devi implementare il codice per gestire le modifiche al repository.
Gestire le modifiche al repository
Puoi raccogliere e indicizzare periodicamente ogni elemento da un repository per eseguire un'indicizzazione completa. Sebbene efficace nel garantire che l'indice sia aggiornato, un'indicizzazione completa può essere costosa quando si gestiscono repository più grandi o gerarchici.
Anziché utilizzare ogni tanto le chiamate di indice per indicizzare un intero repository, puoi anche utilizzare la coda di indicizzazione di Google Cloud come meccanismo per monitorare le modifiche e indicizzare solo gli elementi che sono cambiati. Puoi utilizzare le richieste items.push per inviare elementi alla coda in modo da eseguire il polling e l'aggiornamento in un secondo momento. Per ulteriori informazioni sulla coda di indicizzazione di Google Cloud, consulta Coda di indicizzazione di Google Cloud.
Per ulteriori informazioni sull'API Google Cloud Search, consulta la pagina relativa all'API Cloud Search.