Implementa un conector de archivos CSV

Esta guía está orientada a los administradores del conector de archivos CSV (valores separados por comas) de Google Cloud Search, es decir, a todos aquellos responsables de descargar, configurar, ejecutar y supervisar el conector.

En esta guía se incluyen instrucciones para realizar las siguientes tareas clave relacionadas con la implementación del conector de archivos CSV:

• Descargar el software del conector de archivos CSV de Google Cloud Search
• Configurar el conector para utilizarlo con la fuente de datos específica de archivos CSV
• Implementar y ejecutar el conector

Para comprender los conceptos de este documento, debes estar familiarizado con los aspectos básicos de Google Workspace, los archivos CSV y las listas de control de acceso (LCA).

Descripción general del conector de archivos CSV de Google Cloud Search

El conector de archivos CSV de Cloud Search funciona con cualquier archivo de texto de valores separados por comas (CSV). Un archivo CSV almacena datos tabulares y cada línea del archivo es un registro de datos.

El conector de archivos CSV de Google Cloud Search extrae filas individuales de un archivo CSV y luego las indexa en Cloud Search a través de la API de indexación de Cloud Search. Una vez que se completó la indexación correctamente, se puede buscar contenido en las filas individuales de los archivos CSV a través de los clientes o la API de búsqueda de Cloud Search. El conector de archivos CSV también admite el control del acceso de los usuarios al contenido en los resultados de la búsqueda mediante el uso de LCA.

El conector de archivos CSV de Google Cloud Search se puede instalar en Linux o en Windows. Antes de que implementes el conector de archivos CSV de Google Cloud Search, asegúrate de contar con los siguientes componentes obligatorios:

• Java JRE 1.8 instalado en una computadora que ejecuta el conector de archivos CSV de Google Cloud Search

• La información de Google Workspace necesaria para establecer relaciones entre Google Cloud Search y la fuente de datos:

  • Clave privada de Google Workspace (que contiene el ID de cuenta de servicio)
  • ID de la fuente de datos de Google Workspace

  Por lo general, el administrador de Google Workspace del dominio puede proporcionarte estas credenciales.

Pasos para la implementación

Para implementar el conector de archivos CSV de Google Cloud Search, sigue estos pasos:

1. Instala el software del conector de archivos CSV de Google Cloud Search
2. Especifica la configuración del conector de archivos CSV
3. Configura el acceso a la fuente de datos de Google Cloud Search
4. Cómo configurar el acceso a archivos CSV
5. Especifica nombres de columnas para indexar, columnas de clave única y columnas de fecha y hora
6. Especifica columnas para usar en URLs de resultados de la búsqueda en los que se puede hacer clic
7. Especifica información de metadatos y formatos de columna
8. Programa el recorrido de los datos
9. Especifica opciones de lista de control de acceso (LCA)

1. Instala el SDK

Instala el SDK en tu repositorio local de Maven.

1. Clona el repositorio del SDK desde GitHub.

   $ git clone https://github.com/google-cloudsearch/connector-sdk.git
   $ cd connector-sdk/csv

2. Cambia a la versión deseada del SDK:

   $ git checkout tags/v1-0.0.3

3. Compila el conector:

   $ mvn package

4. Copia el archivo ZIP del conector en el directorio de instalación local:

   $ 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. Especifica la configuración del conector de archivos CSV

Como administrador del conector, controlas el comportamiento y los atributos del conector de archivos CSV mediante la definición de parámetros en el archivo de configuración del conector. Algunos de los parámetros que se pueden configurar son los siguientes:

• Acceso a una fuente de datos
• Ubicación del archivo CSV
• Definiciones de columna del archivo CSV
• Columnas que definen un ID único
• Opciones de recorrido
• Opciones de LCA para restringir el acceso a los datos

Para que el conector acceda correctamente a un archivo CSV y luego indexe el contenido, primero debes crear tu archivo de configuración.

Para crear un archivo de configuración, haz lo siguiente:

1. Abre el editor de texto que prefieras y asigna un nombre al archivo de configuración.
   Agrega pares de clave=valor al contenido del archivo, como se describe en las siguientes secciones.
2. Guarda el archivo de configuración y asígnale un nombre.
   Google recomienda que al archivo de configuración le pongas el nombre connector-config.properties para que no se necesiten parámetros de línea de comandos adicionales para ejecutar el conector.

Dado que puedes especificar la ruta de acceso al archivo de configuración en la línea de comandos, no es necesaria una ubicación de archivo estándar. Sin embargo, mantén el archivo de configuración en el mismo directorio que el conector para simplificar el seguimiento y la ejecución del conector.

Para asegurarte de que el conector reconozca tu archivo de configuración, especifica su ruta de acceso en la línea de comandos. De lo contrario, el conector usa connector-config.properties en tu directorio local como nombre de archivo predeterminado. Para obtener información sobre cómo especificar la ruta de configuración en la línea de comandos, consulta Ejecuta el conector de archivos CSV de Cloud Search.

3. Configura el acceso a la fuente de datos de Google Cloud Search

Los primeros parámetros que se deben especificar en cada archivo de configuración son los necesarios para acceder a la fuente de datos de Cloud Search, como se muestra en la siguiente tabla. Normalmente, necesitarás el ID de la fuente de datos, el ID de la cuenta de servicio y la ruta de acceso al archivo de claves privadas de la cuenta de servicio para configurar el acceso del conector a Cloud Search. Los pasos necesarios para configurar una fuente de datos se describen en Administra fuente de datos de terceros.

4. Configura los parámetros de archivos CSV

Antes de que un conector pueda desviar un archivo CSV y extraer datos para su indexación, debes identificar la ruta de acceso al archivo. También puede especificar el formato de archivo y el tipo de codificación de archivo. Agrega los siguientes parámetros para especificar las propiedades del archivo CSV en el archivo de configuración.

5. Especifica nombres de columnas para indexar y columnas de clave únicas

Para que el conector acceda y luego indexe los archivos CSV, debes proporcionar información sobre las definiciones de columna en el archivo de configuración. Si el archivo de configuración no contiene los parámetros que especifican los nombres de columna a indexar y las columnas de clave únicas, se usan valores predeterminados.

6. Especifica columnas para usar en URL de resultados de la búsqueda en los que se puede hacer clic

Cuando un usuario realiza una búsqueda con Google Cloud Search, este responde mostrando una página de resultados que incluye URL para cada resultado. A fin de habilitar esta función, debes agregar el parámetro que se muestra en la siguiente tabla al archivo de configuración.

7. Especifica información de metadatos, formatos de columna y calidad de búsqueda

Puedes agregar parámetros al archivo de configuración que especifiquen lo siguiente:

• Parámetros de configuración de metadatos
• Formatos de columna
• Calidad de la Búsqueda

Parámetros de configuración de metadatos

Los parámetros de configuración de metadatos describen las columnas del archivo CSV utilizadas para propagar metadatos de elementos. Si el archivo de configuración no contiene estos parámetros, se utilizan los valores predeterminados. La siguiente tabla muestra estos parámetros:

Formatos de fecha y hora

Los formatos de fecha y hora especifican los esperados en los atributos de metadatos. Si el archivo de configuración no contiene este parámetro, se utilizan los valores predeterminados. La siguiente tabla muestra este parámetro.

Formatos de columna

Los formatos de columna especifican información sobre las columnas que deben formar parte del contenido de búsqueda. Si el archivo de configuración no contiene estos parámetros, se utilizan los valores predeterminados. La siguiente tabla muestra estos parámetros:

Calidad de búsqueda

El conector de archivos CSV de Cloud Search permite el formato HTML automático para los campos de datos. Tu conector define los campos de datos al comienzo de la ejecución del conector, y luego utiliza una plantilla de contenido para formatear cada registro de datos antes de subirlo en Cloud Search.

La plantilla de contenido define la importancia de cada valor de campo para la búsqueda. El campo de título es obligatorio y se define como la prioridad más alta. Puedes designar los niveles de importancia de calidad de búsqueda alto, medio o bajo para todos los demás campos de contenido. Cualquier campo de contenido no definido en una categoría específica se establece con una prioridad baja de forma predeterminada. La siguiente tabla muestra estos parámetros:

8. Programa el recorrido de los datos

El proceso de recorrido del conector permite descubrir contenido de la fuente de datos, en este caso, un archivo CSV. A medida que se ejecute el conector de archivos CSV, el conector atravesará las filas de un archivo CSV y luego indexará cada fila para Cloud Search a través de la API de indexación.

El recorrido completo indexa todas las columnas en el archivo. El recorrido incremental solo indexa las columnas que se agregan o modifican desde el recorrido anterior. El conector de archivos CSV solo realiza recorridos completos. No realiza recorridos incrementales.

Los parámetros de programación determinan la frecuencia con la que el conector espera entre recorridos. Si el archivo de configuración no contiene parámetros de programación, se utilizan los valores predeterminados. La siguiente tabla muestra estos parámetros:

9. Especifica opciones de lista de control de acceso (LCA)

El conector de archivos CSV de Google Cloud Search admite permisos a través de LCA para controlar el acceso al contenido del archivo CSV en los resultados de la búsqueda. Existen múltiples opciones de LCA disponibles para permitirte proteger el acceso de los usuarios a los registros indexados.

Si tu repositorio tiene información de LCA individuales asociada con cada documento, sube toda la información de LCA para controlar el acceso a los documentos dentro de Cloud Search. Si tu repositorio proporciona información parcial o nula de LCA, puedes proporcionar información predeterminada de LCA en los siguientes parámetros, que el SDK proporciona al conector.

El conector se basa en que las LCA predeterminadas estén habilitadas en el archivo de configuración. Para habilitar las LCA predeterminadas, configura defaultAcl.mode en cualquier modo que no sea none y configúralo con defaultAcl.*.

Definición de esquema

Cloud Search permite la indexación y la entrega de contenido estructurado y no estructurado. A fin de poder admitir consultas de datos estructurados en sus datos, debes configurar el esquema para tu fuente de datos.

Una vez definido, el conector de archivos CSV puede hacer referencia al esquema definido para generar solicitudes de indexación. Para proporcionar un ejemplo ilustrativo, consideremos un archivo CSV que contiene información sobre películas.

Supongamos que el archivo CSV de entrada tiene el siguiente contenido.

1. movieId
2. movieTitle
3. description
4. year
5. releaseDate
6. actors (valores múltiples separados por coma [,])
7. genre (valores múltiples)
8. ratings

Sobre la base de la estructura de datos anterior, puedes definir un esquema para una fuente de datos en la que quieres indexar datos desde un archivo 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"
            }
          }
        }
      ]
    }
  ]
}

Archivo de configuración de ejemplo

En el siguiente ejemplo de archivo de configuración, se muestran los pares de parámetros key=value que definen un comportamiento del conector de ejemplo.

# 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

Para obtener descripciones detalladas de cada parámetro, consulta Parámetros de configuración.

Ejecuta el conector de archivos CSV de Cloud Search

Para ejecutar el conector desde la línea de comandos, escribe el siguiente comando:

$ java -jar google-cloudsearch-csv-connector-v1-0.0.3.jar -Dconfig=my.config

De forma predeterminada, los registros del conector están disponibles en la salida estándar. Para registrar archivos, especifica logging.properties.