Esegui il deployment di un connettore CSV

Questa guida è rivolta agli amministratori del connettore CSV (valori separati da virgola) di Google Cloud Search, ovvero a chiunque sia responsabile del download, della configurazione, dell'esecuzione e del monitoraggio del connettore.

Questa guida include istruzioni per eseguire attività chiave relative al deployment del connettore CSV:

  • Scarica il software del connettore CSV di Google Cloud Search
  • Configurare il connettore per l'utilizzo con un'origine dati CSV specifica
  • Esegui il deployment e l'esecuzione del connettore

Per comprendere i concetti di questo documento, devi conoscere le nozioni di base di Google Workspace, dei file CSV e degli elenchi di controllo dell'accesso (ACL).

Panoramica del connettore CSV di Google Cloud Search

Il connettore CSV di Cloud Search funziona con qualsiasi file di testo con valori separati da virgole (CSV). Un file CSV memorizza dati tabulari e ogni riga del file è un record di dati.

Il connettore CSV di Google Cloud Search estrae le singole righe da un file CSV e le indicizza in Cloud Search tramite l'API Indexing di Cloud Search. Una volta eseguita l'indicizzazione, le singole righe dei file CSV sono disponibili per la ricerca tramite i client di Cloud Search o l'API Query di Cloud Search. Il connettore CSV supporta anche il controllo dell'accesso degli utenti ai contenuti nei risultati di ricerca mediante le ACL.

Il connettore CSV di Google Cloud Search può essere installato su Linux o Windows. Prima di eseguire il deployment del connettore CSV di Google Cloud Search, assicurati di disporre dei seguenti componenti richiesti:

  • Java JRE 1.8 installato su un computer su cui è in esecuzione il connettore CSV di Google Cloud Search
  • Informazioni di Google Workspace necessarie per stabilire relazioni tra Google Cloud Search e l'origine dati:

    In genere, l'amministratore di Google Workspace del dominio può fornirti queste credenziali.

Passi per il deployment

Per eseguire il deployment del connettore CSV di Ricerca Google Cloud:

  1. Installare il software del connettore CSV di Google Cloud Search
  2. Specifica la configurazione del connettore CSV
  3. Configurare l'accesso all'origine dati di Google Cloud Search
  4. Configurare l'accesso ai file CSV
  5. Specifica i nomi delle colonne da indicizzare, le colonne con chiavi univoche e le colonne datetime
  6. Specificare le colonne da utilizzare negli URL dei risultati di ricerca cliccabili
  7. Specificare informazioni sui metadati, formati delle colonne
  8. Pianifica il traversale dei dati
  9. Specificare le opzioni dell'elenco di controllo dell'accesso (ACL)

1. Installa l'SDK

Installa l'SDK nel tuo repository Maven locale.

  1. Clona il repository SDK da GitHub.

    $ git clone https://github.com/google-cloudsearch/connector-sdk.git
    $ cd connector-sdk/csv
  2. Controlla la versione dell'SDK che ti interessa:

    $ git checkout tags/v1-0.0.3
  3. Crea il connettore:

    $ mvn package
  4. Copia 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 e gli attributi del connettore CSV che definiscono i parametri nel file di configurazione del connettore. I parametri configurabili includono:

  • Accesso a un'origine dati
  • Posizione del file CSV
  • Definizioni delle colonne CSV
  • Colonne che definiscono un ID univoco
  • Opzioni di attraversamento
  • Opzioni ACL per limitare l'accesso ai dati

Affinché il connettore possa accedere correttamente a un file CSV e indicizzare i contenuti pertinenti, devi prima creare il relativo file di configurazione.

Per creare un file di configurazione:

  1. Apri un editor di testo a tua scelta e assegna un nome al file di configurazione.
    Aggiungi coppie chiave=valore ai contenuti del file come descritto nelle sezioni seguenti.
  2. Salva e assegna un nome al file di configurazione.
    Google consiglia di assegnare un nome al file di configurazioneconnector-config.properties in modo che non siano necessari parametri aggiuntivi della riga di comando per eseguire il connettore.

Poiché puoi specificare il percorso del file di configurazione sulla riga di comando, non è necessaria una posizione del file standard. Tuttavia, mantieni il file di configurazione nella stessa directory del connettore per semplificare il monitoraggio e l'esecuzione del connettore.

Per assicurarti che il connettore riconosca il file di configurazione, specifica il relativo percorso sulla riga di comando. In caso contrario, il connettore utilizza connector-config.properties nella tua directory locale come nome file predefinito. Per informazioni su come specificare il percorso di configurazione sulla riga di comando, consulta Eseguire il connettore CSV di Cloud Search.

3. Configurare l'accesso all'origine dati di Google Cloud Search

I primi parametri che ogni file di configurazione deve specificare sono quelli necessari per accedere all'origine dati Cloud Search, come mostrato nella tabella seguente. In genere, per configurare l'accesso del connettore a Cloud Search, sono necessari l'ID origine dati, l'ID account di servizio e il percorso del file della chiave privata dell'account di servizio. 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 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 dell'origine identità di Google Cloud Search configurato dall'amministratore di Google Workspace.

4. Configura i parametri del file CSV

Prima che il connettore possa esaminare un file CSV ed estrarre i dati per l'indicizzazione, devi identificare il percorso del file. Puoi anche specificare il formato 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 provengono dalla classe CSVFormat di Apache Commons CSV.

I valori del formato includono: DEFAULT, EXCEL, INFORMIX_UNLOAD, INFORMIX_UNLOAD_CSV, MYSQL, RFC4180, ORACLE, POSTGRESQL_CSV, POSTGRESQL_TEXT e TDF. Se non specificato, Cloud Search utilizza DEFAULT.

Modificatore del formato file csv.format.withMethod=value

Una modifica alla modalità di gestione del file da parte di Cloud Search. 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 csv.format.withDelimiter=;. Per ignorare le righe vuote, utilizza csv.format.withIgnoreEmptyLines=true.

Tipo di codifica dei 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 con chiavi univoche

Affinché il connettore possa accedere e indicizzare i file CSV, devi fornire informazioni sulle definizioni di colonna nel file di configurazione. Se il file di configurazione non contiene i parametri che specificano i nomi delle colonne da indicizzare e le colonne con chiavi univoche, vengono utilizzati 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 csv.csvColumns non è impostato, la prima riga del file CSV viene utilizzata come intestazione. Se csv.csvColumns è impostato, ha la precedenza sulla prima riga del file CSV. Se hai impostato csv.csvColumns e la prima riga del file CSV è un elenco di nomi di colonna, devi impostare csv.skipHeaderRecord=true per evitare di tentare di indicizzare la prima riga come dati. I valori predefiniti sono le colonne nella riga di intestazione del file.

Colonne di chiavi univoche csv.uniqueKeyColumns=movieId

Le colonne CSV i cui valori verranno utilizzati per generare l'ID univoco di ogni record. Se non specificato, l'hash del record CSV deve essere utilizzato come chiave univoca. Il valore predefinito è l'hashcode del record.

6. Specificare le colonne da utilizzare negli URL dei risultati di ricerca cliccabili

Quando un utente esegue una ricerca utilizzando Google Cloud Search, la risposta è una pagina di risultati che include URL cliccabili per ogni risultato. Per attivare questa funzionalità, devi aggiungere il parametro mostrato nella tabella seguente al file di configurazione.

Impostazione Parametro
Formato dell'URL del risultato di ricerca url.format=https://mymoviesite.com/movies/{0}

Obbligatorio. Il formato per creare l'URL della 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 da eseguire con escape url.columnsToEscape=movieId

Facoltativo. I nomi delle colonne CSV di cui i valori verranno sottoposti a evocazione per generare un URL di visualizzazione valido.

7. Specifica informazioni sui metadati, formati delle colonne, qualità della ricerca

Puoi aggiungere al file di configurazione parametri che specificano:

Parametri di configurazione dei metadati

La sezione Parametri di configurazione dei metadati descrive le colonne CSV utilizzate per compilare i metadati degli elementi. Se il file di configurazione non contiene questi parametri, vengono utilizzati i valori predefiniti. La seguente tabella mostra questi parametri.

Impostazione Parametro
Titolo itemMetadata.title.field=movieTitle
itemMetadata.title.defaultValue=Gone with the Wind

L'attributo dei 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 dei 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 dei 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 dei metadati che contiene il valore del timestamp dell'ultima modifica del documento.

Lingua del documento itemMetadata.contentLanguage.field=languageCode
itemMetadata.contentLanguage.defaultValue=en-US

La lingua dei contenuti dei documenti sottoposti a indicizzazione.

Tipo di oggetto dello schema itemMetadata.objectType.field=type
itemMetadata.objectType.defaultValue=movie

Il tipo di oggetto utilizzato dal connettore, come definito nello schema. Il connettore non indicizzerà alcun dato strutturato se questa proprietà non è specificata.

Formati data/ora

I formati 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. Questo parametro è mostrato nella tabella seguente.

Impostazione Parametro
Altri formati data/ora structuredData.dateTimePatterns=MM/dd/uuuu HH:mm:ssXXX
Un elenco di pattern java.time.format.DateTimeFormatter aggiuntivi separati da punto e virgola. I pattern vengono utilizzati per analizzare i valori di stringa per eventuali campi data o data/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

I formati delle colonne specificano le informazioni sulle colonne che devono far parte del contenuto ricercabile. Se il file di configurazione non contiene questi parametri, vengono utilizzati i valori predefiniti. La seguente tabella mostra questi parametri.

Impostazione Parametro
Ignora intestazione csv.skipHeaderRecord=true

Booleano. Ignora il record di intestazione (prima riga) nel file CSV. Se hai impostato csv.csvColumns e il file CSV ha una riga di intestazione, devi impostare skipHeaderRecord=true. In questo modo viene impedita l'indicizzazione della prima riga del file come dati. Se il file CSV non ha una riga di intestazione, imposta skipHeaderRecord=false. Il valore predefinito è false.

Colonne con 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 di dati all'inizio dell'esecuzione del connettore, quindi utilizza un modello di contenuti per formattare ogni record di dati prima di caricarlo su Cloud Search.

Il modello di contenuti definisce l'importanza di ciascun valore di campo per la ricerca. Il campo del titolo è obbligatorio ed è definito come la priorità più alta. Puoi designare livelli di importanza della qualità della ricerca per tutti gli altri campi dei contenuti: alto, medio o basso. Per impostazione predefinita, a qualsiasi campo dei contenuti non definito in una categoria specifica viene assegnata una priorità bassa. La seguente tabella mostra questi parametri.

Impostazione Parametro
Titolo contenuti contentTemplate.csv.title=movieTitle

Il titolo dei contenuti è il campo di qualità di ricerca più alto.

Elevata qualità di ricerca per i campi dei contenuti contentTemplate.csv.quality.high=actors

Campi dei contenuti a cui è stato assegnato un valore elevato per la qualità della ricerca. Il valore predefinito è una stringa vuota.

Bassa qualità di ricerca per i campi dei contenuti contentTemplate.csv.quality.low=genre

Campi dei contenuti a cui è stato assegnato un valore basso per la qualità della ricerca. Il valore predefinito è una stringa vuota.

Qualità media della ricerca per i campi dei contenuti contentTemplate.csv.quality.medium=description

Campi dei contenuti a cui è stato assegnato un valore medio di qualità della ricerca. Il valore predefinito è una stringa vuota.

Campi di contenuti non specificati contentTemplate.csv.unmappedColumnsMode=IGNORE

In che modo il connettore gestisce i campi dei contenuti non specificati. I valori validi sono:

  • APPEND: accoda i campi di contenuti non specificati al modello
  • IGNORE: ignora i campi dei contenuti non specificati

    Il valore predefinito è APPEND.

8. Pianifica il traversale dei dati

La traversale è il processo del connettore per scoprire i contenuti dell'origine dati, in questo caso un file CSV. Durante l'esecuzione, il connettore CSV attraversa le righe di un file CSV e indicizza ogni riga in Cloud Search tramite l'API Indexing.

L'esplorazione completa indicizza tutte le colonne del file. L'esplorazione incrementale indicizza solo le colonne aggiunte o modificate dall'esplorazione precedente. Il connettore CSV esegue solo attraversamenti completi. Non esegue attraversamenti incrementali.

I parametri di pianificazione determinano la frequenza con cui il connettore attende tra le esplorazioni. Se il file di configurazione non contiene parametri di pianificazione, vengono utilizzati i valori predefiniti. La seguente tabella mostra questi parametri.

Impostazione Parametro
Percorso completo dopo un intervallo schedule.traversalIntervalSecs=7200

Il connettore esegue un attraversamento completo dopo un intervallo specificato. Specifica l'intervallo tra le esplorazioni in secondi. Il valore predefinito è 86400 (numero di secondi in un giorno).

Percorso completo all'avvio del connettore schedule.performTraversalOnStart=false

Il connettore esegue un attraversamento completo all'avvio, anziché attendere la scadenza del primo intervallo. Il valore predefinito è true.

9. Specifica le opzioni dell'elenco di controllo dell'accesso (ACL)

Il connettore CSV di Google Cloud Search supporta le autorizzazioni tramite ACL per controllare l'accesso ai contenuti del file CSV nei risultati di ricerca. Sono disponibili più opzioni di ACL per consentirti di proteggere l'accesso degli utenti ai record indicizzati.

Se il tuo repository ha informazioni ACL individuali associate a ciascun documento, carica tutte le informazioni ACL per controllare l'accesso ai documenti in Cloud Search. Se il tuo repository fornisce informazioni ACL parziali o nessuna, puoi fornire informazioni ACL predefinite nei seguenti parametri, che l'SDK fornisce al connettore.

Il connettore si basa sull'attivazione delle ACL predefinite nel file di configurazione. Per attivare gli ACL predefiniti, imposta 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 ignorare il nome del contenitore virtuale utilizzato dal connettore per configurare le ACL predefinite. 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 pubblico al dominio. 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
L'ACL comune ha negato i lettori di gruppo defaultAcl.denied.groups=group3
Lettori ACL con accesso negato comuni defaultAcl.denied.users=user4, user5
Accesso all'intero dominio Per specificare che ogni record indicizzato sia accessibile pubblicamente da ogni utente del dominio, imposta entrambe le seguenti opzioni con i valori:
  • defaultAcl.mode=fallback
  • defaultAcl.public=true
ACL definito comune Per specificare un'ACL per ogni record del repository di dati, imposta tutti i seguenti valori parametro:
  • defaultAcl.mode=fallback
  • defaultAcl.public=false
  • defaultAcl.readers.groups=google:group1, group2
  • defaultAcl.readers.users=user1, user2, google:user3
  • defaultAcl.denied.groups=group3
  • defaultAcl.denied.users=user4, user5

    Si presume che ogni utente e gruppo specificato sia un utente/gruppo definito dal dominio locale, a meno che non sia preceduto da "google:" (costante letterale).

    L'utente o il gruppo predefinito è una stringa vuota. Fornisci le opzioni utente e gruppo solo se defaultAcl.public è impostato su false. Per elencare più gruppi e utenti, utilizza un elenco separato da virgole.

    Se defaultAcl.mode è impostato su none, i record non sono disponibili per la ricerca senza singole ACL definite.

Definizione dello schema

Cloud Search consente l'indicizzazione e la pubblicazione di contenuti strutturati e non strutturati. Per supportare le query sui dati strutturati, devi configurare lo schema per la tua origine dati.

Una volta definito, il connettore CSV può fare riferimento allo schema definito per creare richieste di indicizzazione. Per fare un esempio pratico, prendiamo in considerazione un file CSV contenente informazioni sui film.

Supponiamo che il file CSV di input abbia i seguenti contenuti.

  1. movieId
  2. movieTitle
  3. descrizione
  4. anno
  5. releaseDate
  6. attori (più valori separati da virgola (,))
  7. genere (più valori)
  8. valutazioni

In base alla struttura dei dati riportata sopra, puoi definire lo schema per un'origine dati in cui vuoi indicizzare i dati del 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 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

Per descrizioni dettagliate di ciascun parametro, consulta la documentazione di riferimento relativa ai parametri di configurazione.

Esegui 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 registrare i log in file specificando logging.properties.