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 conceptos generales de G Suite, 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 valores separados por comas (CSV), es decir, cualquier archivo de texto delimitado que usa una coma para separar los valores. 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 de forma correcta, se puede buscar contenido en las filas individuales de los archivos CSV a través de los clientes o la API de consulta 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 G Suite requerida para establecer relaciones entre Google Cloud Search y la fuente de datos:

    Por lo general, el administrador de G Suite 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. Configura 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 URL 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 de manera correcta a un archivo CSV y, luego, indexe el contenido, primero debes crear el archivo de configuración.

Para crear un archivo de configuración, sigue estos pasos:

  1. Abre el editor de texto que prefieras y asigna un nombre al archivo de configuración.
    Agrega pares de clave=valor a los contenidos 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 lo nombres connector-config.properties a fin de que no se necesiten parámetros de línea de comandos adicionales para ejecutar el conector.

Dado que puedes especificar la ruta del archivo de configuración en la línea de comandos, no es necesario proporcionar 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 en la línea de comandos. De lo contrario, el conector usará 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 la página sobre cómo ejecutar 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. Por lo general, necesitarás el ID de la fuente de datos, el ID de la cuenta de servicio y la ruta de acceso al archivo de clave privada 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 la página sobre cómo administrar fuentes de datos de terceros.

Configuración Parámetro
ID de la fuente de datos api.sourceId=1234567890abcdef

Obligatorio. El ID de la fuente de datos de Google Cloud Search que configura el administrador de G Suite, como se describe en Administra fuente de datos de terceros.

Ruta de acceso al archivo de claves privadas de la cuenta de servicio api.serviceAccountPrivateKeyFile=./PrivateKey.json

Obligatorio. El archivo de claves de la cuenta de servicio de Google Cloud Search para la accesibilidad del conector de archivos CSV de Google Cloud Search.

ID de la fuente de identidad api.identitySourceId=x0987654321

Obligatorio si se utilizan usuarios y grupos externos. El ID de la fuente de identidad de Google Cloud Search que configura el administrador de G Suite.

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.

Configuración Parámetro
Ruta de acceso al archivo CSV csv.filePath=./movie_content.csv

Obligatorio. La ruta de acceso al archivo CSV del que se debe extraer contenido para la indexación.

Formato de archivo csv.format=DEFAULT

El formato del archivo. Los valores posibles son de la clase CSVFormat de Apache Commons CSV.

Los valores de formato incluyen los siguientes: DEFAULT, EXCEL, INFORMIX_UNLOAD, INFORMIX_UNLOAD_CSV, MYSQL, RFC4180, ORACLE, POSTGRESQL_CSV, POSTGRESQL_TEXT y TDF. Si no se especifica, Cloud Search usa DEFAULT.

Modificador de formato de archivo csv.format.withMethod=value

Una modificación en la forma en la que Cloud Search maneja el archivo. Los métodos posibles son de la clase CSVFormat de Apache Commons CSV y se incluyen aquellos que toman un solo carácter, string o valor booleano.

Por ejemplo, para especificar un punto y coma como delimitador, usa csv.format.withDelimiter=;. Para ignorar líneas vacías, usa csv.format.withIgnoreEmptyLines=true.

Tipo de codificación de archivo csv.fileEncoding=UTF-8

El conjunto de caracteres Java que se usará cuando Cloud Search lea el archivo. Si no se especifica, Cloud Search usa el conjunto de caracteres predeterminado de la plataforma.

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.

Configuración Parámetro
Columnas para indexar csv.csvColumns=movieId,movieTitle,description,actors,releaseDate,year,userratings...

Los nombres de columna para indexar desde el archivo CSV. Si csv.csvColumns no se configura, entonces la primera fila del archivo CSV se usa como encabezado. Si csv.csvColumns se configura, entonces tiene prioridad sobre la primera fila del archivo CSV. Si se configuró csv.csvColumns y la primera fila del archivo CSV es una lista de nombres de columna, entonces necesitas configurar csv.skipHeaderRecord=true para evitar indexar la primera fila como datos. Los valores predeterminados son las columnas en la fila del encabezado del archivo.

Columnas de clave única csv.uniqueKeyColumns=movieId

Las columnas del archivo CSV cuyos valores se utilizarán para generar el ID único de cada registro. Si no se especifica, el hash del registro CSV debe usarse como su clave única. El valor predeterminado es el código hash del registro.

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, la respuesta de este es mostrar una página de resultados que incluye URL en las que se puede hacer clic 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.

Configuración Parámetro
Formato de URL de resultados de la búsqueda url.format=https://mymoviesite.com/movies/{0}

Obligatorio. El formato que permite construir URL de vista para contenido del archivo CSV.

Parámetros de URL de resultados de la búsqueda. url.columns=movieId

Obligatorio. Los nombres de columna del archivo CSV cuyos valores se utilizarán para generar URL de vista del registro.

Parámetros de URL de los resultados de la búsqueda para escapar url.columnsToEscape=movieId

Opcional. Los nombres de columna del archivo CSV cuyos valores serán URL con caracteres de escape para generar URL de vista válidas.

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

Los parámetros de configuración de metadatos describen las columnas del archivo CSV usadas para propagar metadatos de elementos. Si el archivo de configuración no contiene estos parámetros, se usan los valores predeterminados. En la siguiente tabla, se muestran estos parámetros:

Configuración Parámetro
Título itemMetadata.title.field=movieTitle
itemMetadata.title.defaultValue=Gone with the Wind

El atributo de metadatos que contiene el valor correspondiente al título del documento. El valor predeterminado es una string vacía.

URL itemMetadata.sourceRepositoryUrl.field=url
itemMetadata.sourceRepositoryUrl.defaultValue=https://www.imdb.com/title/tt0031381/
El atributo de metadatos que contiene el valor de la URL del documento para los resultados de la búsqueda.
Marca de tiempo de creación itemMetadata.createTime.field=releaseDate
itemMetadata.createTime.defaultValue=1940-01-17

El atributo de metadatos que contiene el valor correspondiente a la marca de tiempo de creación del documento

Hora de la última modificación itemMetadata.updateTime.field=releaseDate
itemMetadata.updateTime.defaultValue=1940-01-17

El atributo de metadatos que contiene el valor correspondiente a la marca de tiempo de la última modificación del documento

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

El idioma del contenido para los documentos que se indexan

Tipo de objeto de esquema itemMetadata.objectType.field=type
itemMetadata.objectType.defaultValue=movie

El tipo de objeto que usa el conector, como se define en el esquema. El conector no indexará ningún dato estructurado si no se especifica esta propiedad.

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.

Configuración Parámetro
Formatos de fecha y hora adicionales structuredData.dateTimePatterns=MM/dd/uuuu HH:mm:ssXXX
Una lista separada por puntos y comas de patrones java.time.formatDateTimeFormatter adicionales. Los patrones se utilizan cuando se analizan valores de string para cualquier fecha o campos de fecha y hora en los metadatos o el esquema. El valor predeterminado es una lista vacía, pero los formatos RFC 3339 y RFC 1123 siempre son compatibles.

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 usan los valores predeterminados. En la siguiente tabla, se muestran estos parámetros:

Configuración Parámetro
Omitir encabezado csv.skipHeaderRecord=true

Booleano. Ignora el registro del encabezado (primera línea) en el archivo CSV. Si has configurado csv.csvColumns y el archivo CSV posee una fila de encabezado, entonces debes definir skipHeaderRecord=true. Esto evita que se indexe la primera fila del archivo como datos. Si el archivo CSV no tiene una fila de encabezado, define skipHeaderRecord=false. El valor predeterminado es "false" (falso).

Columnas de valores múltiples csv.multiValueColumns=genre,actors

Los nombres de columna en el archivo CSV que tienen valores múltiples. El valor predeterminado es una string vacía.

Delimitador para columnas de valores múltiples csv.multiValue.genre=;

El delimitador para columnas de valores múltiples. El delimitador predeterminado es una coma.

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, usa 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 como 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. En la siguiente tabla, se muestran estos parámetros:

Configuración Parámetro
Título del contenido contentTemplate.csv.title=movieTitle

El título del contenido es el campo de mayor calidad de búsqueda.

Alta calidad de búsqueda para los campos de contenido contentTemplate.csv.quality.high=actors

Campos de contenido dado un alto valor de calidad de búsqueda. El valor predeterminado es una string vacía.

Baja calidad de búsqueda para los campos de contenido contentTemplate.csv.quality.low=genre

Campos de contenido con un bajo valor de calidad de búsqueda. El valor predeterminado es una string vacía.

Calidad media de búsqueda para los campos de contenido contentTemplate.csv.quality.medium=description

Campos de contenido dado un valor medio de calidad de búsqueda. El valor predeterminado es una string vacía.

Campos de contenido sin especificar contentTemplate.csv.unmappedColumnsMode=IGNORE

Cómo maneja el conector los campos de contenido no especificados. Estos son los valores posibles:

  • APPEND anexa campos de contenido sin especificar a la plantilla.
  • IGNORE ignora campos de contenido sin especificar.

    El valor predeterminado es APPEND.

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, este desviará 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 usan los valores predeterminados. En la siguiente tabla, se muestran estos parámetros:

Configuración Parámetro
Recorrido completo luego del intervalo schedule.traversalIntervalSecs=7,200

El conector realiza un recorrido completo después de un intervalo especificado. Especifica el intervalo entre recorridos en segundos. El valor predeterminado es 86,400 (número de segundos en un día).

Recorrido completo al inicio del conector schedule.performTraversalOnStart=false

El conector realiza un recorrido completo en el inicio del conector, en lugar de esperar a que venza el primer intervalo. El valor predeterminado es true (verdadero).

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.*

Configuración Parámetro
Modo de LCA defaultAcl.mode=fallback

Obligatorio. El conector de archivos CSV depende de la funcionalidad de LCA predeterminada. El conector solo admite el modo de resguardo.

Nombre de LCA predeterminado defaultAcl.name=VIRTUAL_CONTAINER_FOR_CONNECTOR_1

Opcional. Permite anular el nombre del contenedor virtual utilizado por el conector para configurar las LCA predeterminadas. El valor predeterminado es "DEFAULT_ACL_VIRTUAL_CONTAINER". Es posible que quieras anular este valor si varios conectores están indexando el contenido en la misma fuente de datos.

LCA pública predeterminada defaultAcl.public=true

La LCA predeterminada utilizada para todo el repositorio se establece en el acceso de dominio público. El valor predeterminado es false (falso).

Lectores comunes del grupo de LCA defaultAcl.readers.groups=google:group1, group2
Lectores comunes de LCA defaultAcl.readers.users=user1, user2, google:user3
Lectores comunes del grupo de LCA denegadas defaultAcl.denied.groups=group3
Lectores comunes de LCA denegadas defaultAcl.denied.users=user4, user5
Acceso de dominio completo Si quieres especificar que los registros indexados sean de acceso público para todos los usuarios del dominio, configura las opciones que se muestran a continuación con los siguientes valores:
  • defaultAcl.mode=fallback
  • defaultAcl.public=true
LCA comunes definidas A fin de especificar una LCA para cada registro del repositorio de datos, configura todos los valores de parámetros siguientes:
  • 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

    Se supone que cada usuario y grupo especificado es un usuario o grupo definido por el dominio local, a menos que tenga el prefijo "google: " (constante literal).

    El usuario o grupo predeterminado es una string vacía. Proporciona opciones de usuario y grupo solo si defaultAcl.public está configurado como false. Para enumerar varios grupos y usuarios, usa una lista delimitada por comas.

    Si defaultAcl.mode se configura como none, no se podrá buscar en los registros sin LCA individuales definidas.

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 tus 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 compilar 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

Si te basas en la estructura de datos anterior, puedes definir un esquema para una fuente de datos en la que quieras 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": "Documentry"
                  },
                  {
                    "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"
                }
              }
            }
          ]
        }
      ]
    }

    

Ejemplo: Archivo de configuración

En el siguiente ejemplo de archivo de configuración, se muestran los pares key=value de parámetros 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 la referencia sobre 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.