Questa guida è destinata al file CSV (valori separati da virgole) di Google Cloud Search degli amministratori del connettore, ossia chiunque sia responsabile del download, alla configurazione, all'esecuzione e al monitoraggio del connettore.
Questa guida include istruzioni per eseguire le attività principali correlate al formato CSV. il deployment dei connettori:
- Scarica il software del connettore CSV di Google Cloud Search
- Configurare il connettore per l'utilizzo con una specifica origine dati CSV
- Esegui il deployment del connettore ed esegui
Per comprendere i concetti esposti in questo documento, devi conoscere le nozioni di base di Google Workspace, file CSV ed elenchi di controllo dell'accesso (ACL).
Panoramica del connettore CSV di Google Cloud Search
Il connettore CSV di Cloud Search funziona con qualsiasi testo con valori separati da virgole (CSV) . Un file CSV memorizza dati tabulari e ogni riga del file è una record.
Il connettore CSV di Google Cloud Search estrae singole righe da un file CSV e li indicizza in Cloud Search tramite l'API Index di Cloud Search. Una volta indicizzato correttamente, le singole righe dei file CSV sono disponibili per la ricerca tramite Client di Cloud Search o API Query di Cloud Search. Il connettore CSV inoltre supporta il controllo l'accesso ai contenuti nei risultati di ricerca, utilizzando ACL.
Il connettore CSV di Google Cloud Search può essere installato su Linux o Windows. Prima del giorno di eseguire il deployment del connettore CSV Google Cloud Search, assicurati di avere i seguenti componenti obbligatori:
- Java JRE 1.8 installato su un computer che esegue il CSV di Google Cloud Search connettore
le informazioni di Google Workspace necessarie per stabilire relazioni tra Google Cloud Search e l'origine dati:
- Chiave privata Google Workspace (che contiene l'ID dell'account di servizio)
- ID origine dati Google Workspace
In genere, l'amministratore di Google Workspace del dominio può fornire queste credenziali per te.
Passi per il deployment
Per eseguire il deployment del connettore CSV di Google Cloud Search, segui questi passaggi:
- Installare il software del connettore CSV di Google Cloud Search
- Specifica la configurazione del connettore CSV
- Configurare l'accesso all'origine dati Google Cloud Search
- Configurare l'accesso ai file CSV
- Specificare i nomi delle colonne da indicizzare, le colonne chiave univoche e le colonne data/ora
- Specificare le colonne da utilizzare negli URL dei risultati di ricerca cliccabili
- Specificare le informazioni sui metadati, i formati delle colonne
- Pianificare il trasferimento dei dati
- Specificare le opzioni dell'elenco di controllo dell'accesso (ACL)
1. Installa l'SDK
Installa l'SDK nel tuo Repository Maven locale.
Clona il repository SDK da GitHub.
$ git clone https://github.com/google-cloudsearch/connector-sdk.git $ cd connector-sdk/csv
Controlla la versione dell'SDK che ti interessa:
$ git checkout tags/v1-0.0.3Crea il connettore:
$ mvn packageCopia il file ZIP del connettore nella directory di installazione locale:
$ cp target/google-cloudsearch-csv-connector-v1-0.0.3.zip installation-dir $ cd installation-dir $ unzip google-cloudsearch-csv-connector-v1-0.0.3.zip $ cd google-cloudsearch-csv-connector-v1-0.0.3
2. Specifica la configurazione del connettore CSV
In qualità di amministratore del connettore, puoi controllare il comportamento del connettore CSV e che definiscono i parametri nel file di configurazione del connettore. I parametri configurabili includono:
- Accedere a un'origine dati
- Percorso del file CSV
- Definizioni delle colonne CSV
- Colonne che definiscono un ID univoco
- Opzioni di attraversamento
- Opzioni ACL per limitare l'accesso ai dati
Per consentire al connettore di accedere correttamente a un file CSV e indicizzare i contenuti pertinenti, occorre prima creare il relativo file di configurazione.
Per creare un file di configurazione:
- Apri un editor di testo a tua scelta e assegna un nome al file di configurazione.
Aggiungi le coppie key=value ai contenuti del file come descritto di seguito sezioni. - Salva e assegna un nome al file di configurazione.
Google consiglia di assegnare un nome al file di configurazioneconnector-config.propertiesquindi nessun parametro aggiuntivo della riga di comando necessaria per eseguire il connettore.
Poiché è possibile specificare il percorso del file di configurazione nella riga di comando, la posizione standard del file non è necessaria. Tuttavia, mantieni il file di configurazione nella stessa directory del connettore per semplificare il monitoraggio e l'esecuzione di rete.
Per assicurarti che il connettore riconosca il file di configurazione, specificane il percorso in
la riga di comando. In caso contrario, il connettore utilizza
connector-config.properties nella tua directory locale come
il nome predefinito del file. Per informazioni su come specificare il percorso di configurazione
dalla riga di comando, vedi Eseguire il connettore CSV di Cloud Search.
3. Configurare l'accesso all'origine dati Google Cloud Search
I primi parametri che ogni file di configurazione deve specificare sono quelli necessarie per accedere all'origine dati Cloud Search, come illustrato di seguito tabella. In genere sono necessari l'ID origine dati, l'ID account di servizio e percorso del file della chiave privata dell'account di servizio per configurare l'accesso del connettore a Cloud Search. I passaggi necessari per configurare un'origine dati sono descritti in Gestire le origini dati di terze parti
| Impostazione | Parametro |
| ID origine dati | api.sourceId=1234567890abcdef
Obbligatorio. L'ID origine di Google Cloud Search configurato dall'amministratore di Google Workspace, come descritto in Gestire le origini dati di terze parti. |
| Percorso del file della chiave privata dell'account di servizio | api.serviceAccountPrivateKeyFile=./PrivateKey.json
Obbligatorio. Il file della chiave dell'account di servizio di Google Cloud Search per l'accessibilità del connettore CSV di Google Cloud Search. |
| ID origine identità | api.identitySourceId=x0987654321
Obbligatorio se utilizzi utenti e gruppi esterni. L'ID origine identità di Google Cloud Search configurato dall'amministratore di Google Workspace. |
4. Configurare i parametri del file CSV
Prima che il connettore possa attraversare un file CSV ed estrarne i dati per devi identificare il percorso del file. Puoi anche specificare il formato file e il tipo di codifica del file. Aggiungi i seguenti parametri per specificare le proprietà del file CSV nel file di configurazione.
| Impostazione | Parametro |
| Percorso del file CSV | csv.filePath=./movie_content.csv
Obbligatorio. Il percorso del file CSV a cui accedere ed estrarre i contenuti per l'indicizzazione. |
| Formato file | csv.format=DEFAULT
Il formato del file. I valori possibili sono quelli della classe CSV CSVFormat di Apache Commons. I valori del formato includono: |
| Modificatore formato file | csv.format.withMethod=value
Una modifica alla modalità di gestione del file da parte di Cloud Search. I metodi possibili sono quelli della classe CSV CSVFormat di Apache Commons CSV e includono quelli che contengono un singolo carattere, una stringa o un valore booleano. Ad esempio, per specificare un punto e virgola come delimitatore, utilizza |
| Tipo di codifica file | csv.fileEncoding=UTF-8
Il set di caratteri Java da utilizzare quando Cloud Search legge il file. Se non specificato, Cloud Search utilizza il set di caratteri predefinito della piattaforma. |
5. Specifica i nomi delle colonne da indicizzare e le colonne chiave univoche
Affinché il connettore possa accedere ai file CSV e indicizzarli, devi fornire informazioni sulle definizioni delle colonne nel file di configurazione. Se di configurazione del file di configurazione non contiene i parametri che specificano i nomi delle colonne all'indice e alle colonne chiave univoche, vengono usati i valori predefiniti.
| Impostazione | Parametro |
| Colonne da indicizzare | csv.csvColumns=movieId,movieTitle,description,actors,releaseDate,year,userratings...
I nomi delle colonne da indicizzare dal file CSV. Se |
| Colonne chiave univoche | csv.uniqueKeyColumns=movieId
Le colonne CSV i cui valori verranno utilizzati per generare l'ID univoco di ciascun record. Se non specificato, l'hash del record CSV deve essere utilizzato come chiave univoca. Il valore predefinito è l'hash del record. |
6. Specifica le colonne da utilizzare negli URL dei risultati di ricerca cliccabili
Quando un utente esegue una ricerca con Google Cloud Search, risponde mostrando un risultato pagina che includa URL cliccabili per ogni risultato. Per attivare questa funzione, devi devi aggiungere al file di configurazione il parametro indicato nella tabella seguente.
| Impostazione | Parametro |
| Formato dell'URL del risultato di ricerca | url.format=https://mymoviesite.com/movies/{0}
Obbligatorio. Il formato per creare l'URL di visualizzazione per i contenuti CSV. |
| Parametri URL dei risultati di ricerca. | url.columns=movieId
Obbligatorio. I nomi delle colonne CSV i cui valori verranno utilizzati per generare l'URL di visualizzazione del record. |
| Parametri URL dei risultati di ricerca di cui eseguire l'interpretazione letterale | url.columnsToEscape=movieId
(Facoltativo) I nomi delle colonne CSV i cui valori saranno rappresentati da URL con caratteri di escape per generare un URL di visualizzazione valido. |
7. Specifica le informazioni sui metadati, i formati delle colonne e la qualità della ricerca
Puoi aggiungere al file di configurazione parametri che specificano:
Parametri di configurazione dei metadati
In Parametri di configurazione dei metadati sono descritte le colonne CSV utilizzate per la compilazione metadati degli elementi. Se il file di configurazione non contiene questi parametri, vengono utilizzati i valori predefiniti. La tabella seguente mostra questi parametri.
| Impostazione | Parametro |
| Titolo | itemMetadata.title.field=movieTitle
itemMetadata.title.defaultValue=Gone with the Wind
L'attributo di metadati che contiene il valore corrispondente al titolo del documento. Il valore predefinito è una stringa vuota. |
| URL | itemMetadata.sourceRepositoryUrl.field=url
itemMetadata.sourceRepositoryUrl.defaultValue=https://www.imdb.com/title/tt0031381/
L'attributo di metadati che contiene il valore dell'URL del documento per i risultati di ricerca. |
| Timestamp creazione | itemMetadata.createTime.field=releaseDate
itemMetadata.createTime.defaultValue=1940-01-17
L'attributo di metadati che contiene il valore del timestamp di creazione del documento. |
| Ora dell'ultima modifica | itemMetadata.updateTime.field=releaseDate
itemMetadata.updateTime.defaultValue=1940-01-17
L'attributo di metadati che contiene il valore del timestamp dell'ultima modifica per il documento. |
| Lingua del documento | itemMetadata.contentLanguage.field=languageCode
itemMetadata.contentLanguage.defaultValue=en-US
La lingua dei contenuti per i documenti da indicizzare. |
| Tipo di oggetto schema | itemMetadata.objectType.field=typeitemMetadata.objectType.defaultValue=movie
Il tipo di oggetto utilizzato dal connettore, come definito nel schema. Il connettore non indicizza i dati strutturati se questa proprietà non è specificata. |
Formati data/ora
I formati di data e ora specificano i formati previsti negli attributi dei metadati. Se il file di configurazione non contiene questo parametro, vengono utilizzati i valori predefiniti. La tabella seguente mostra questo parametro.
| Impostazione | Parametro |
| Altri formati data/ora | structuredData.dateTimePatterns=MM/dd/uuuu HH:mm:ssXXX
Un elenco separato da punti e virgola di pattern aggiuntivi java.time.format.DateTimeFormatter. I pattern vengono utilizzati durante l'analisi dei valori stringa per qualsiasi campo data o data/ora nei metadati o nello schema. Il valore predefinito è un elenco vuoto, ma sono sempre supportati i formati RFC 3339 e RFC 1123. |
Formati colonna
I formati colonna specificano le informazioni sulle colonne che devono far parte di i contenuti disponibili per la ricerca. Se il file di configurazione non contiene vengono utilizzati i valori predefiniti. La tabella seguente mostra questi parametri.
| Impostazione | Parametro |
| Ignora intestazione | csv.skipHeaderRecord=true
Booleano. Ignora il record di intestazione (prima riga) nel file CSV. Se hai impostato |
| Colonne a più valori | csv.multiValueColumns=genre,actors
I nomi delle colonne nel file CSV che hanno più valori. Il valore predefinito è una stringa vuota. |
| Delimitatore per colonne con più valori | csv.multiValue.genre=;
Il delimitatore per le colonne con più valori. Il delimitatore predefinito è una virgola. |
Qualità della ricerca
Il connettore CSV di Cloud Search consente la formattazione HTML automatica per i campi di dati. Il connettore definisce i campi dei dati all'inizio dell'esecuzione del connettore, e poi utilizza un modello di contenuti per formattare ciascun record di dati prima di caricarlo in Cloud Search.
Il modello di contenuti definisce l'importanza del valore di ciascun campo per la ricerca. Il campo del titolo è obbligatorio ed è definito con la priorità più alta. Puoi designa i livelli di importanza della qualità della ricerca per tutti gli altri campi di contenuti: alta, media o bassa. Qualsiasi campo di contenuti non definito in una categoria specifica il valore predefinito è bassa priorità. La tabella seguente mostra questi parametri.
| Impostazione | Parametro |
| Titolo contenuti | contentTemplate.csv.title=movieTitle
Il titolo dei contenuti rappresenta il campo con la qualità di ricerca più elevata. |
| Qualità di ricerca elevata per i campi dei contenuti | contentTemplate.csv.quality.high=actors
Campi dei contenuti con un valore di qualità di ricerca elevato. Il valore predefinito è una stringa vuota. |
| Scarsa qualità di ricerca per i campi dei contenuti | contentTemplate.csv.quality.low=genre
Campi dei contenuti con un valore di qualità di ricerca basso. Il valore predefinito è una stringa vuota. |
| Qualità di ricerca media per i campi di contenuti | contentTemplate.csv.quality.medium=description
Campi dei contenuti con un valore di qualità di ricerca medio. Il valore predefinito è una stringa vuota. |
| Campi di contenuti non specificati | contentTemplate.csv.unmappedColumnsMode=IGNORE
Modalità di gestione dei campi di contenuti non specificati da parte del connettore. I valori validi sono:
|
8. Pianifica attraversamento dati
Il trasferimento è il processo del connettore per il rilevamento di contenuti dai dati sorgente, in questo caso un file CSV. Durante l'esecuzione, il connettore CSV attraverserà le righe di un file CSV e indicizzare ogni riga in Cloud Search tramite tramite Google Cloud CLI o tramite l'API Compute Engine.
Il attraversamento completo indicizza tutte le colonne del file. L'attraversamento incrementale indicizza solo le colonne aggiunte o modificate dall'attraversamento precedente. Il connettore CSV esegue solo attraversamenti completi. Non esegue attraversamenti incrementali.
I parametri di pianificazione determinano la frequenza di attesa del connettore tra attraversamenti. Se il file di configurazione non contiene parametri di pianificazione, vengono utilizzati i valori predefiniti. La tabella seguente mostra questi parametri.
| Impostazione | Parametro |
| Traversale completo dopo un intervallo | schedule.traversalIntervalSecs=7200
Il connettore esegue un attraversamento completo dopo un intervallo specificato. Specifica l'intervallo tra gli attraversamenti in secondi. Il valore predefinito è 86400 (numero di secondi in un giorno). |
| Traversale completo all'avvio del connettore | schedule.performTraversalOnStart=false
Il connettore esegue un attraversamento completo all'avvio del connettore, anziché attendere la scadenza del primo intervallo. Il valore predefinito è true. |
9. Specifica le opzioni dell'elenco di controllo di accesso (ACL)
Il connettore CSV di Google Cloud Search supporta le autorizzazioni tramite ACL per controllare ai contenuti del file CSV nei risultati di ricerca. Esistono più ACL disponibili per proteggere l'accesso degli utenti ai record indicizzati.
Se al repository sono associate singole informazioni ACL Caricare tutte le informazioni ACL per controllare l'accesso ai documenti in Cloud Search. Se il repository fornisce informazioni ACL parziali o assenti, puoi fornire le informazioni ACL nei seguenti parametri, che l'SDK fornisce di rete.
Il connettore si basa sull'abilitazione degli ACL predefiniti nel file di configurazione. A
abilitare gli ACL predefiniti, impostare defaultAcl.mode su una modalità diversa da none e
configurala con defaultAcl.*
| Impostazione | Parametro |
| Modalità ACL | defaultAcl.mode=fallback
Obbligatorio. Il connettore CSV si basa sulla funzionalità ACL predefinita. Il connettore supporta solo la modalità di riserva. |
| Nome ACL predefinito | defaultAcl.name=VIRTUAL_CONTAINER_FOR_CONNECTOR_1
(Facoltativo) Consente di eseguire l'override del nome del container virtuale utilizzato dal connettore per configurare gli ACL predefiniti. Il valore predefinito è "DEFAULT_ACL_VIRTUAL_CONTAINER". Ti consigliamo di sostituire questo valore se più connettori indicizzano i contenuti nella stessa origine dati. |
| ACL pubblico predefinito | defaultAcl.public=true
L'ACL predefinito utilizzato per l'intero repository è impostato sull'accesso al dominio pubblico. Il valore predefinito è false. |
| Lettori di gruppi ACL comuni | defaultAcl.readers.groups=google:group1, group2 |
| Lettori ACL comuni | defaultAcl.readers.users=user1, user2, google:user3 |
| Lettori dei gruppi rifiutati ACL comuni | defaultAcl.denied.groups=group3 |
| Lettori ACL comuni rifiutati | defaultAcl.denied.users=user4, user5 |
| Accesso all'intero dominio | Per specificare che ogni record indicizzato sia accessibile pubblicamente da tutti gli utenti del dominio, imposta entrambe le opzioni seguenti con valori:
|
| ACL definito comune | Per specificare un ACL per ogni record del repository di dati, imposta tutti i valori parametro seguenti:
|
Definizione dello schema
Cloud Search consente l'indicizzazione e la pubblicazione di contenuti strutturati e non strutturati. Per supportare le query di dati strutturati sui tuoi dati, devi: Configura schema per l'origine dati.
Una volta definito, il connettore CSV può fare riferimento a uno schema definito per creare le richieste di indicizzazione. Per fornire un esempio illustrativo, consideriamo un file CSV contenente informazioni su Movies.
Supponiamo che il file CSV di input abbia i seguenti contenuti.
- movieId
- movieTitle
- descrizione
- anno
- releaseDate
- attori (più valori separati da virgole (,))
- genere (più valori)
- valutazioni
In base alla struttura dei dati sopra indicata, puoi definire lo schema per un'origine dati in che vuoi indicizzare dal file CSV.
{
"objectDefinitions": [
{
"name": "movie",
"propertyDefinitions": [
{
"name": "actors",
"isReturnable": true,
"isRepeatable": true,
"isFacetable": true,
"textPropertyOptions": {
"operatorOptions": {
"operatorName": "actor"
}
}
},
{
"name": "releaseDate",
"isReturnable": true,
"isRepeatable": false,
"isFacetable": false,
"datePropertyOptions": {
"operatorOptions": {
"operatorName": "released",
"lessThanOperatorName": "releasedbefore",
"greaterThanOperatorName": "releasedafter"
}
}
},
{
"name": "movieTitle",
"isReturnable": true,
"isRepeatable": false,
"isFacetable": false,
"textPropertyOptions": {
"retrievalImportance": {
"importance": "HIGHEST"
},
"operatorOptions": {
"operatorName": "title"
}
}
},
{
"name": "genre",
"isReturnable": true,
"isRepeatable": true,
"isFacetable": true,
"enumPropertyOptions": {
"operatorOptions": {
"operatorName": "genre"
},
"possibleValues": [
{
"stringValue": "Action"
},
{
"stringValue": "Documentary"
},
{
"stringValue": "Drama"
},
{
"stringValue": "Crime"
},
{
"stringValue": "Sci-fi"
}
]
}
},
{
"name": "userRating",
"isReturnable": true,
"isRepeatable": false,
"isFacetable": true,
"integerPropertyOptions": {
"orderedRanking": "ASCENDING",
"maximumValue": "10",
"operatorOptions": {
"operatorName": "score",
"lessThanOperatorName": "scorebelow",
"greaterThanOperatorName": "scoreabove"
}
}
}
]
}
]
}
File di configurazione di esempio
Il file di configurazione di esempio seguente mostra le coppie di parametri key=value
che definiscono il comportamento di un connettore di esempio.
# data source access
api.sourceId=1234567890abcd
api.serviceAccountPrivateKeyFile=./PrivateKey.json
# CSV data structure
csv.filePath=./movie_content.csv
csv.csvColumns=movieId,movieTitle,description,releaseYear,genre,actors,ratings,releaseDate
csv.skipHeaderRecord=true
url.format=https://mymoviesite.com/movies/{0}
url.columns=movieId
csv.datetimeFormat.releaseDate=yyyy-mm-dd
csv.multiValueColumns=genre,actors
csv.multiValue.genre=;
contentTemplate.csv.title=movieTitle
# metadata structured data and content
itemMetadata.title.field=movieTitle
itemMetadata.createTime.field=releaseDate
itemMetadata.contentLanguage.defaultValue=en-US
itemMetadata.objectType.defaultValue=movie
contentTemplate.csv.quality.medium=description
contentTemplate.csv.unmappedColumnsMode=IGNORE
#ACLs
defaultAcl.mode=fallback
defaultAcl.public=true
Per una descrizione dettagliata di ciascun parametro, consulta la sezione riferimento.
Eseguire il connettore CSV di Cloud Search
Per eseguire il connettore dalla riga di comando, digita il seguente comando:
$ java -jar google-cloudsearch-csv-connector-v1-0.0.3.jar -Dconfig=my.config
Per impostazione predefinita, i log del connettore sono disponibili nell'output standard. Puoi accedere ai file
specificando logging.properties.