Esegui il deployment di un connettore CSV

Questa guida è destinata agli amministratori del connettore CSV (comma-separated values) 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 le attività chiave relative al deployment del connettore CSV:

• Scaricare il software del connettore CSV di Google Cloud Search
• Configurare il connettore per l'utilizzo con un'origine dati CSV specifica
• Esegui il deployment del connettore ed eseguilo

Per comprendere i concetti descritti in questo documento, devi avere familiarità con le nozioni di base di Google Workspace, i file CSV e le liste di controllo degli accessi (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 tabellari e ogni riga del file è un record di dati.

Il connettore CSV di Google Cloud Search estrae singole righe da un file CSV e le indicizza in Cloud Search tramite l'API Indexing di Cloud Search. Una volta indicizzate correttamente, le singole righe dei file CSV sono ricercabili tramite i client di Cloud Search o l'API Cloud Search Query. Il connettore CSV supporta anche il controllo dell'accesso degli utenti ai contenuti nei risultati di ricerca tramite 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 che esegue il connettore CSV di Google Cloud Search

• Informazioni di Google Workspace necessarie per stabilire relazioni tra Google Cloud Search e l'origine dati:

  • Chiave privata di Google Workspace (che contiene l'ID account di servizio)
  • ID origine dati di Google Workspace

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

Passi per il deployment

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

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 Google Cloud Search
4. Configurare l'accesso al file CSV
5. Specifica i nomi delle colonne da indicizzare, le colonne delle chiavi univoche e le colonne di data e ora
6. Specificare le colonne da utilizzare negli URL dei risultati di ricerca cliccabili
7. Specificare le informazioni sui metadati e i formati delle colonne
8. Pianificare l'attraversamento 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 dell'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, controlli 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
• Colonna o 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 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 denominare il file di configurazione connector-config.properties in modo che non siano necessari parametri della riga di comando aggiuntivi per eseguire il connettore.

Poiché puoi specificare il percorso del file di configurazione sulla riga di comando, non è necessaria una posizione standard del file. 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 percorso nella riga di comando. In caso contrario, il connettore utilizza connector-config.properties nella directory locale come nome file predefinito. Per informazioni su come specificare il percorso di configurazione nella riga di comando, vedi Esegui 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 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 service account e il percorso del file della chiave privata del service account. I passaggi necessari per configurare un'origine dati sono descritti in Gestire le origini dati di terze parti

4. Configurare i parametri del file CSV

Prima che il connettore possa attraversare un file CSV ed estrarre i dati per l'indicizzazione, devi identificare il percorso del file. Puoi anche specificare il formato del file e il tipo di codifica. Aggiungi i seguenti parametri per specificare le proprietà del file CSV nel file di configurazione.

5. Specifica i nomi delle colonne da indicizzare e le colonne delle chiavi univoche

Affinché il connettore possa accedere ai file CSV e indicizzarli, devi fornire informazioni sulle definizioni delle colonne nel file di configurazione. Se il file di configurazione non contiene i parametri che specificano i nomi delle colonne da indicizzare e le colonne delle chiavi univoche, vengono utilizzati i valori predefiniti.

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

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

7. Specifica le informazioni sui metadati, i formati delle colonne e la qualità della ricerca

Puoi aggiungere parametri al file di configurazione che specificano:

• Parametri di configurazione dei metadati
• Formati delle colonne
• Qualità della ricerca

Parametri di configurazione dei metadati

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 tabella seguente mostra questi parametri.

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 seguente tabella mostra questo parametro.

Formati delle colonne

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

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 e poi 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 ogni valore del campo per la ricerca. Il campo del titolo è obbligatorio ed è definito come la priorità più alta. Puoi assegnare livelli di importanza della qualità della ricerca a tutti gli altri campi dei contenuti: alta, media o bassa. Qualsiasi campo dei contenuti non definito in una categoria specifica viene impostato su priorità bassa. La tabella seguente mostra questi parametri.

8. Pianificare l'attraversamento dei dati

L'attraversamento è il processo del connettore per scoprire i contenuti dell'origine dati, in questo caso un file CSV. Quando viene eseguito, il connettore CSV attraversa le righe di un file CSV e indicizza ogni riga in Cloud Search tramite l'API Indexing.

L'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 con cui il connettore attende tra le traversals. Se il file di configurazione non contiene parametri di pianificazione, vengono utilizzati i valori predefiniti. La tabella seguente mostra questi parametri.

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 ACL per consentirti di proteggere l'accesso degli utenti ai record indicizzati.

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

Il connettore si basa sull'abilitazione degli ACL predefiniti nel file di configurazione. Per attivare gli ACL predefiniti, imposta defaultAcl.mode su una modalità diversa da none e configurala con defaultAcl.*

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 l'origine dati.

Una volta definito, il connettore CSV può fare riferimento allo schema definito per creare richieste di indicizzazione. Per fornire un esempio illustrativo, 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 virgole (,)).
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 ogni parametro, consulta il riferimento ai parametri di configurazione.

Esegui il connettore CSV di Cloud Search

Per eseguire il connettore dalla riga di comando, digita questo 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 dati nei file specificando logging.properties.