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 de Google Workspace, archivos CSV y 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 texto de valores separados por comas (CSV) . Un archivo CSV almacena datos tabulares y cada línea del archivo es un dato registro.

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:

    Por lo general, el administrador de Google Workspace del dominio puede proporcionar estas credenciales por ti.

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. Cómo especificar 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 a los contenidos del archivo, como se describe a continuación. secciones.
  2. Guarda el archivo de configuración y asígnale un nombre.
    Google recomienda que asignes un nombre al archivo de configuración connector-config.properties para que no se pueda usar ningún parámetro de línea de comandos necesario 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 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 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.

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 Google Workspace, como se describe en Administra fuentes 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 Google Workspace.

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 grupo 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 botón de configuración de Terraform no contiene los parámetros que especifican los nombres de las columnas para indexar y a columnas de clave única, se usan los 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 no se establece csv.csvColumns, la primera fila del archivo CSV se usa como encabezado. Si se configura csv.csvColumns, tiene prioridad sobre la primera fila del CSV. Si configuraste csv.csvColumns y la primera fila del archivo CSV es una lista de nombres de columnas, debes configurar csv.skipHeaderRecord=true para evitar intentar 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 de los archivos CSV cuyos valores se usarán para generar el ID único de cada registro. Si no se especifica, se debe usar el hash del registro CSV 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, 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.

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 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:

Parámetro de 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/
Es 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

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

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

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 utilizado por 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.

Parámetro de configuración Parámetro
Formatos de fecha y hora adicionales structuredData.dateTimePatterns=MM/dd/uuuu HH:mm:ssXXX
Una lista de patrones java.time.formatDateTimeFormatter adicionales separados por signos de punto y coma. 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 utilizan los valores predeterminados. La siguiente tabla muestra 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 configuraste csv.csvColumns y el archivo CSV tiene una fila de encabezado, debes configurar skipHeaderRecord=true. Esto evita que se indexe la primera fila del archivo como datos. Si el archivo CSV no tiene una fila de encabezado, configura skipHeaderRecord=false. El valor predeterminado es 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 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:

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 dado 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:

  • ANEXO: agrega 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, 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:

Configuración Parámetro
Recorrido completo luego del intervalo schedule.traversalIntervalSecs=7200

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 habilita las LCA predeterminadas, establece 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.

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 Para especificar que cada registro indexado sea de acceso público para todos los usuarios del dominio, configura las siguientes opciones con 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 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 el comportamiento de un 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. Puedes registrar archivos especificando logging.properties.