Questa guida è destinata agli amministratori del connettore CSV (comma-separated values) di Google Cloud Search responsabili del download, della configurazione, dell'esecuzione e del monitoraggio del connettore.
Questa guida include le istruzioni per le seguenti attività chiave:
- Scarica il software del connettore CSV di Cloud Search.
- Configura il connettore per un'origine dati CSV specifica.
- Esegui il deployment del connettore ed eseguilo.
Per comprendere i concetti descritti in questo documento, devi conoscere Google Workspace, i file CSV e gli elenchi di controllo dell'accesso (ACL).
Panoramica del connettore CSV di Cloud Search
Il connettore CSV di Cloud Search funziona con qualsiasi file di testo con valori separati da virgole (CSV). Un file CSV archivia dati tabulari, in cui ogni riga è un record di dati.
Il connettore estrae le righe da un file CSV e le indicizza in Cloud Search utilizzando l'API Indexing. Una volta indicizzate, le righe sono ricercabili tramite i client Cloud Search o l'API Query. Il connettore supporta anche gli ACL per controllare l'accesso degli utenti ai contenuti.
Puoi installare il connettore su Linux o Windows. Prima del deployment, assicurati di disporre dei seguenti componenti:
- Java JRE 1.8 installato sul computer che esegue il connettore.
- Informazioni su Google Workspace per stabilire le connessioni:
- Chiave privata Google Workspace (contenente l'ID account di servizio).
- ID origine dati Google Workspace.
In genere, le credenziali vengono fornite dall'amministratore di Google Workspace per il dominio.
Passi per il deployment
Per eseguire il deployment del connettore CSV di Cloud Search:
- Installare il software del connettore
- Specificare la configurazione del connettore
- Configurare l'accesso all'origine dati Cloud Search
- Configurare l'accesso ai file CSV
- Specifica nomi delle colonne, chiavi univoche e colonne data e ora
- Specificare le colonne per gli URL dei risultati di ricerca cliccabili
- Specificare i formati di metadati e colonne
- Pianificare l'attraversamento dei dati
- Specifica le opzioni ACL
1. Installa l'SDK
Installa l'SDK nel repository Maven locale.
Clona il repository dell'SDK da GitHub.
$ git clone https://github.com/google-cloudsearch/connector-sdk.git $ cd connector-sdk/csv
Controlla la versione selezionata:
$ git checkout tags/v1-0.0.3
Crea il connettore:
$ mvn package
Estrai e installa il connettore:
$ 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
Controlli il comportamento del connettore tramite i parametri nel file di configurazione. I parametri configurabili includono:
- Accesso all'origine dati.
- Posizione e definizioni del file CSV.
- Colonne ID univoco.
- Opzioni di attraversamento e ACL.
Per creare un file di configurazione:
- Apri un editor di testo e assegna al file il nome
connector-config.properties. - Aggiungi i parametri di configurazione come coppie
key=value, con ogni coppia su una nuova riga. Per un esempio di file di configurazione, vedi File di configurazione di esempio.
Conserva il file di configurazione nella stessa directory del connettore per semplificare
il monitoraggio. Per assicurarti che il connettore riconosca il file, specifica il percorso nella
riga di comando. In caso contrario, il connettore utilizza
connector-config.properties nella directory locale. Consulta
Esegui il connettore.
3. Configurare l'accesso all'origine dati Cloud Search
Il file di configurazione deve specificare i parametri per accedere all'origine dati Cloud Search. Devi disporre dell'ID origine dati, dell'ID service account e del percorso del file della chiave privata del service account.
| Impostazione | Parametro |
| ID origine dati | api.sourceId=1234567890abcdef
Obbligatorio. L'ID origine Cloud Search configurato dall'amministratore di Google Workspace. |
| Percorso della chiave privata del service account | api.serviceAccountPrivateKeyFile=./PrivateKey.json
Obbligatorio. Il file della chiave del service account per l'accessibilità del connettore. |
| ID origine identità | api.identitySourceId=x0987654321
Obbligatorio se utilizzi utenti e gruppi esterni. L'ID origine identità impostato dall'amministratore di Google Workspace. |
4. Configurare i parametri del file CSV
Identifica il percorso, il formato e la codifica del file.
| Impostazione | Parametro |
| Percorso del file CSV | csv.filePath=./movie_content.csv
Obbligatorio. Il percorso del file da indicizzare. |
| Formato file | csv.format=DEFAULT
Il formato del file. I valori possibili sono quelli della classe CSVFormat di Apache Commons CSV. I valori di formato includono: |
| Modificatore del formato file | csv.format.withMethod=value
Una modifica al modo in cui Cloud Search gestisce il file. I metodi possibili provengono dalla classe CSVFormat di Apache Commons CSV e includono quelli che accettano un singolo carattere, una stringa o un valore booleano. Ad esempio, per specificare un punto e virgola come delimitatore, utilizza |
| Tipo di codifica dei file | csv.fileEncoding=UTF-8
Il set di caratteri Java da utilizzare. Il valore predefinito è il set di caratteri della piattaforma. |
5. Specifica i nomi delle colonne da indicizzare e le colonne delle chiavi univoche
Fornisci le informazioni sulle colonne nel file di configurazione.
| Impostazione | Parametro |
| Colonne da indicizzare | csv.csvColumns=movieId,movieTitle,description,actors,releaseDate,year,userratings...
I nomi delle colonne da indicizzare dal file CSV. Per impostazione predefinita, la prima riga del file CSV viene utilizzata come intestazione. Se |
| Colonne chiave univoche | csv.uniqueKeyColumns=movieId
Colonne utilizzate per generare un ID univoco. Il valore predefinito è l'hashcode del record. |
6. Specifica le colonne per gli URL dei risultati di ricerca selezionabili
Attiva gli URL selezionabili per i risultati di ricerca.
| Impostazione | Parametro |
| Formato dell'URL dei risultati di ricerca | url.format=https://mymoviesite.com/movies/{0}
Obbligatorio. Il formato utilizzato per creare l'URL della visualizzazione. |
| Parametri URL | 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 da eseguire l'escape | url.columnsToEscape=movieId
Facoltativo. I nomi delle colonne CSV i cui valori verranno sottoposti all'escape dell'URL per generare un URL di visualizzazione valido. |
7. Specifica metadati, formati delle colonne e qualità della ricerca
Puoi aggiungere parametri al file di configurazione che specificano:
Parametri di configurazione dei metadati
Questi parametri descrivono le colonne per il popolamento dei metadati degli elementi.
| Impostazione | Parametro |
| Titolo | itemMetadata.title.field=movieTitle
itemMetadata.title.defaultValue=Gone with the Wind
L'attributo dei metadati per il 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 dei metadati per l'URL del documento nei risultati di ricerca. |
| Timestamp creazione | itemMetadata.createTime.field=releaseDate
itemMetadata.createTime.defaultValue=1940-01-17
L'attributo dei metadati per il timestamp di creazione del documento. |
| Ora dell'ultima modifica | itemMetadata.updateTime.field=releaseDate
itemMetadata.updateTime.defaultValue=1940-01-17
L'attributo dei metadati per il timestamp dell'ultima modifica del documento. |
| Lingua del documento | itemMetadata.contentLanguage.field=languageCode
itemMetadata.contentLanguage.defaultValue=en-US
La lingua dei contenuti per i documenti in fase di indicizzazione. |
| Tipo di oggetto di schema | itemMetadata.objectType.field=typeitemMetadata.objectType.defaultValue=movie
Il tipo di oggetto utilizzato dal connettore, come definito nello schema. Se questa proprietà non è specificata, il connettore non indicizzerà alcun dato strutturato. |
Formati data/ora
Questo parametro specifica formati di data e ora aggiuntivi per l'analisi dei valori stringa nei campi data o data e ora.
| Impostazione | Parametro |
| Altri formati di data e ora | structuredData.dateTimePatterns=MM/dd/uuuu HH:mm:ssXXX
Un elenco separato da punti e virgola di pattern java.time.format.DateTimeFormatter aggiuntivi. I pattern vengono utilizzati durante l'analisi dei valori stringa per qualsiasi campo di data o data e ora nei metadati o nello schema. Il valore predefinito è un elenco vuoto, ma i formati RFC 3339 e RFC 1123 sono sempre supportati.
|
Formati delle colonne
Questi parametri specificano come analizzare le colonne nel file CSV.
| Impostazione | Parametro |
| Ignora intestazione | csv.skipHeaderRecord=true
Ignora la prima riga. Il valore predefinito è false. |
| Colonne multivalore | csv.multiValueColumns=genre,actors
Nomi delle colonne con più valori. |
| Delimitatore per colonne con più valori | csv.multiValue.genre=;
Delimitatore per le colonne con più valori. Il delimitatore predefinito è una virgola. |
Qualità della ricerca
Il connettore utilizza un modello di contenuti per formattare i record. Il campo Titolo ha la priorità più alta. Puoi assegnare livelli di priorità (alta, media, bassa) ad altri campi.
| Impostazione | Parametro |
| Titolo contenuti |
contentTemplate.csv.title=movieTitle
Il titolo dei contenuti è il campo con la qualità di ricerca più elevata. |
| Elevata qualità della ricerca per i campi dei contenuti |
contentTemplate.csv.quality.high=actors
Campi dei contenuti a cui è stato assegnato un valore di qualità della ricerca elevato. Il valore predefinito è una stringa vuota. |
| Qualità della ricerca bassa per i campi dei contenuti |
contentTemplate.csv.quality.low=genre
Campi dei contenuti a cui è stato assegnato un valore di qualità della ricerca basso. Il valore predefinito è una stringa vuota. |
| Qualità della ricerca media per i campi dei contenuti |
contentTemplate.csv.quality.medium=description
Campi dei contenuti a cui è stato assegnato un valore di qualità della ricerca medio. Il valore predefinito è una stringa vuota. |
| Campi dei contenuti non specificati |
contentTemplate.csv.unmappedColumnsMode=IGNORE
Come il connettore gestisce i campi dei contenuti non specificati. I valori validi sono:
Il valore predefinito è APPEND. |
8. Pianificare l'attraversamento dei dati
L'attraversamento è il processo di scoperta dei contenuti. Il connettore attraversa le righe CSV e le indicizza utilizzando l'API Indexing. Il connettore CSV esegue solo attraversamenti completi.
| Impostazione | Parametro |
| Intervallo di attraversamento | schedule.traversalIntervalSecs=7200
Intervallo tra le traversate complete in secondi. Il valore predefinito è 86400 (un giorno). |
| Attraversamento all'avvio | schedule.performTraversalOnStart=false
Il connettore esegue un attraversamento all'avvio, anziché
attendere la scadenza del primo intervallo. Il valore predefinito è |
9. Specifica le opzioni ACL
Il connettore utilizza gli ACL per controllare l'accesso. Se il repository fornisce ACL,
caricali. In caso contrario, configura le ACL predefinite. Imposta defaultAcl.mode su un valore
diverso da none.
| Impostazione | Parametro |
| Modalità ACL | defaultAcl.mode=fallback
Obbligatorio. Il connettore supporta solo la modalità di fallback. |
| Nome ACL predefinito | defaultAcl.name=VIRTUAL_CONTAINER_FOR_CONNECTOR_1
Facoltativo. Esegue l'override del nome del container virtuale utilizzato dal connettore per
le ACL predefinite. Il valore predefinito è |
| ACL pubblico predefinito | defaultAcl.public=true
Imposta l'intero repository sull'accesso al dominio pubblico. Il valore predefinito è false. |
| Lettori del gruppo ACL comune | defaultAcl.readers.groups=google:group1, group2
|
| Lettori ACL comuni | defaultAcl.readers.users=user1, user2, google:user3
|
| Lettori del gruppo con ACL comuni negati | defaultAcl.denied.groups=group3
|
| Common Acl denied readers | defaultAcl.denied.users=user4, user5
|
| Accesso all'intero dominio | Per specificare che ogni record indicizzato sia accessibile pubblicamente a ogni utente del dominio, imposta entrambe le seguenti opzioni con i valori:
|
| ACL comuni definiti | Per definire un ACL comune per ogni record, imposta i seguenti parametri:
Si presume che utenti e gruppi siano definiti dal dominio locale, a meno che non siano preceduti
da " L'utente o il gruppo predefinito è una stringa vuota. Fornisci le opzioni per utenti e gruppi
solo se Se |
Definizione schema
Per supportare le query sui dati strutturati, configura uno schema per l'origine dati.
Prendiamo ad esempio un file CSV con le seguenti informazioni sui film:
- movieId
- movieTitle
- descrizione
- anno
- releaseDate
- attori (più valori separati da virgole (,)).
- genere (più valori)
- valutazioni
In base a questa struttura, puoi definire lo schema seguente per l'origine dati:
{
"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 seguente file di configurazione di esempio 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
Esegui il connettore
Per eseguire il connettore dalla riga di 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.