Implementar un conector CSV

Esta guía está destinada a los administradores del conector CSV (valores separados por comas) de Google Cloud Search, es decir, cualquier persona responsable de descargar, configurar, ejecutar y monitorear el conector.

Esta guía incluye instrucciones para realizar tareas clave relacionadas con la implementación del conector CSV:

  • Descarga el software del conector CSV de Google Cloud Search
  • Configure el conector para usarlo con una fuente de datos CSV específica
  • Implementar y ejecutar el conector

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

Descripción general del conector CSV de Google Cloud Search

El conector 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 CSV de Google Cloud Search extrae filas individuales de un archivo CSV y las indexa en Cloud Search a través de la API de indexación de Cloud Search. Una vez indexadas correctamente, las filas individuales de los archivos CSV se pueden buscar a través de los clientes de Cloud Search o la API de consultas de Cloud Search. El conector CSV también admite el control del acceso de los usuarios al contenido de los resultados de búsqueda mediante el uso de ACL.

El conector CSV de Google Cloud Search se puede instalar en Linux o Windows. Antes de implementar el conector CSV de Google Cloud Search, asegúrese de tener los siguientes componentes necesarios:

  • Java JRE 1.8 instalado en una computadora que ejecuta el conector CSV de Google Cloud Search
  • Información de Google Workspace requerida para establecer relaciones entre Google Cloud Search y la fuente de datos:

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

Pasos de implementación

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

  1. Instalar el software del conector CSV de Google Cloud Search
  2. Especificar la configuración del conector CSV
  3. Configurar el acceso a la fuente de datos de Google Cloud Search
  4. Configurar el acceso a archivos CSV
  5. Especifique nombres de columnas para indexar, columnas de clave única y columnas de fecha y hora
  6. Especificar columnas para usar en las URL de resultados de búsqueda en las que se puede hacer clic
  7. Especificar información de metadatos, formatos de columna
  8. Programar el cruce de datos
  9. Especificar las opciones de la lista de control de acceso (ACL)

1. Instale el SDK

Instale el SDK en su repositorio Maven local.

  1. Clone el repositorio SDK de GitHub.

    $ git clone https://github.com/google-cloudsearch/connector-sdk.git
    $ cd connector-sdk/csv
  2. Consulte la versión deseada del SDK:

    $ git checkout tags/v1-0.0.3
  3. Construya el conector:

    $ mvn package
  4. Copie el archivo zip del conector en su 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. Especifique la configuración del conector CSV

Como administrador del conector, usted controla el comportamiento y los atributos del conector CSV que definen los parámetros en el archivo de configuración del conector. Los parámetros configurables incluyen:

  • Acceso a una fuente de datos
  • Ubicación del archivo CSV
  • Definiciones de columnas CSV
  • Columna(s) que definen una identificación única
  • Opciones transversales
  • Opciones de ACL para restringir el acceso a datos

Para que el conector acceda correctamente a un archivo CSV e indexe el contenido relevante, primero debe crear su archivo de configuración.

Para crear un archivo de configuración:

  1. Abra un editor de texto de su elección y asigne un nombre al archivo de configuración.
    Agregue pares clave = valor al contenido del archivo como se describe en las siguientes secciones.
  2. Guarde y asigne un nombre al archivo de configuración.
    Google recomienda que asigne al archivo de configuración el nombre connector-config.properties para que no se requieran parámetros de línea de comandos adicionales para ejecutar el conector.

Debido a que puede especificar la ruta del archivo de configuración en la línea de comandos, no es necesaria una ubicación de archivo estándar. Sin embargo, mantenga el archivo de configuración en el mismo directorio que el conector para simplificar el seguimiento y la ejecución del conector.

Para asegurarse de que el conector reconozca su archivo de configuración, especifique su ruta en la línea de comando. De lo contrario, el conector usa connector-config.properties en su 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, consulte Ejecutar el conector CSV de Cloud Search .

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

Los primeros parámetros que debe especificar 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á el ID de la fuente de datos, el ID de la cuenta de servicio y la ruta 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 Administrar fuentes de datos de terceros

Entorno Parámetro
ID de la fuente de datos api.sourceId= 1234567890abcdef

Requerido. El ID de fuente de Google Cloud Search configurado por el administrador de Google Workspace, como se describe en Administrar fuentes de datos de terceros.

Ruta al archivo de clave privada de la cuenta de servicio api.serviceAccountPrivateKeyFile= ./PrivateKey.json

Requerido. El archivo de clave de la cuenta de servicio de Google Cloud Search para la accesibilidad del conector CSV de Google Cloud Search.

ID de fuente de identidad api.identitySourceId= x0987654321

Obligatorio si se utilizan usuarios y grupos externos. El ID de fuente de identidad de Cloud Search configurado por el administrador de Google Workspace.

4. Configurar los parámetros del archivo CSV

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

Entorno Parámetro
Ruta al archivo CSV csv.filePath= ./movie_content.csv

Requerido. La ruta al archivo CSV al que se accederá y extraerá el contenido para la indexación.

Formato de archivo csv.format= DEFAULT

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

Los valores de formato incluyen: 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 de cómo Cloud Search maneja el archivo. Los métodos posibles son de la clase Apache Commons CSV CSVFormat e incluyen aquellos que toman un solo carácter, cadena o valor booleano.

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

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

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

5. Especifique nombres de columna para indexar y columnas de clave única

Para que el conector acceda e indexe los archivos CSV, debe 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 para indexar y las columnas de clave única, se utilizan los valores predeterminados.

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

Los nombres de las columnas que se indexarán desde el archivo CSV. Si csv.csvColumns no está configurado, la primera fila del archivo CSV se usa como encabezado. Si se establece csv.csvColumns , entonces tiene prioridad sobre la primera fila del CSV. Si configuró csv.csvColumns y la primera fila del archivo CSV es una lista de nombres de columnas, debe configurar csv.skipHeaderRecord=true para evitar intentar indexar la primera fila como datos. Los valores predeterminados son las columnas de la fila de encabezado del archivo.

Columnas clave únicas csv.uniqueKeyColumns= movieId

La(s) columna(s) 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. Especifique columnas para usar en las URL de resultados de búsqueda en las que se puede hacer clic

Cuando un usuario busca con Google Cloud Search, responde mostrando una página de resultados que incluye direcciones URL en las que se puede hacer clic para cada resultado. Para habilitar esta función, debe agregar el parámetro que se muestra en la siguiente tabla al archivo de configuración.

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

Requerido. El formato para construir la URL de vista para contenido CSV.

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

Requerido. Los nombres de las columnas CSV cuyos valores se utilizarán para generar la URL de vista del registro.

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

Opcional. Los nombres de las columnas CSV cuyos valores se escaparán de la URL para generar una URL de vista válida.

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

Puede agregar parámetros al archivo de configuración que especifican:

Parámetros de configuración de metadatos

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

Entorno 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 cadena 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 búsqueda.
Marca de tiempo creada itemMetadata.createTime.field= releaseDate
itemMetadata.createTime.defaultValue= 1940-01-17

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

Última hora de modificación itemMetadata.updateTime.field= releaseDate
itemMetadata.updateTime.defaultValue= 1940-01-17

El atributo de metadatos que contiene el valor de 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 de 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, tal 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 formatos 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.

Entorno Parámetro
Formatos de fecha y hora adicionales structuredData.dateTimePatterns= MM/dd/uuuu HH:mm:ssXXX
Una lista separada por punto y coma de patrones java.time.format.DateTimeFormatter adicionales. Los patrones se utilizan al analizar valores de cadena para cualquier campo de fecha o de fecha y hora en los metadatos o el esquema. El valor predeterminado es una lista vacía, pero siempre se admiten los formatos RFC 3339 y RFC 1123.

Formatos de columna

Los formatos de columna especifican información sobre la(s) columna(s) que debe(n) ser parte del contenido buscable. Si el archivo de configuración no contiene estos parámetros, se utilizan los valores predeterminados. La siguiente tabla muestra estos parámetros.

Entorno Parámetro
Saltar encabezado csv.skipHeaderRecord=true

booleano. Ignore el registro de encabezado (primera línea) en el archivo CSV. Si configuró csv.csvColumns y el archivo CSV tiene una fila de encabezado, debe configurar skipHeaderRecord=true . Esto evita indexar la primera fila del archivo como datos. Si el archivo CSV no tiene una fila de encabezado, establezca skipHeaderRecord=false . El valor predeterminado es falso.

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

Los nombres de las columnas en el archivo CSV que tienen varios valores. El valor predeterminado es una cadena vacía.

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

El delimitador de las columnas de varios valores. El delimitador predeterminado es una coma.

Calidad de búsqueda

El conector CSV de Cloud Search permite el formato HTML automático para los campos de datos. Su 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 cargarlo 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 el de mayor prioridad. Puede designar niveles de importancia de calidad de búsqueda para todos los demás campos de contenido: alto, medio o bajo. Cualquier campo de contenido no definido en una categoría específica tiene prioridad baja por defecto. La siguiente tabla muestra estos parámetros.

Entorno 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 campos de contenido contentTemplate.csv.quality.high = actors

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

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

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

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

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

Campos de contenido no especificado contentTemplate.csv.unmappedColumnsMode = IGNORE

Cómo maneja el conector los campos de contenido no especificado. Los valores válidos son:

  • APPEND —añade campos de contenido no especificados a la plantilla
  • IGNORE —ignorar campos de contenido no especificados

    El valor predeterminado es AÑADIR.

8. Programar el cruce de datos

El recorrido es el proceso del conector para descubrir contenido del origen de datos, en este caso, un archivo CSV. A medida que se ejecuta el conector CSV, recorrerá las filas de un archivo CSV e indexará cada fila en Cloud Search a través de la API de indexación.

El recorrido completo indexa todas las columnas del archivo. El recorrido incremental solo indexa las columnas que se agregaron o modificaron desde el recorrido anterior. El conector 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.

Entorno Parámetro
Recorrido completo después de un intervalo horario.traversalIntervalSecs = 7200

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

Recorrido completo al inicio del conector horario.performTraversalOnStart = false

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

9. Especificar las opciones de la Lista de control de acceso (ACL)

El conector CSV de Google Cloud Search admite permisos a través de ACL para controlar el acceso al contenido del archivo CSV en los resultados de búsqueda. Hay varias opciones de ACL disponibles que le permiten proteger el acceso de los usuarios a los registros indexados.

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

El conector depende de que las ACL predeterminadas estén habilitadas en el archivo de configuración. Para habilitar las ACL predeterminadas, establezca defaultAcl.mode en cualquier modo que no sea none y configúrelo con defaultAcl.*

Entorno Parámetro
modo LCA defaultAcl.mode =retroceso

Requerido. El conector CSV se basa en la funcionalidad ACL predeterminada. El conector solo admite el modo de respaldo.

Nombre de ACL predeterminado defaultAcl.name = VIRTUAL_CONTAINER_FOR_CONNECTOR_1

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

ACL pública predeterminada defaultAcl.público = true

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

Lectores de grupo ACL comunes defaultAcl.readers.groups = google: group1, group2
Lectores comunes de ACL defaultAcl.lectores.usuarios = usuario1 user1, user2, google: user3
Lectores comunes de grupos denegados de ACL defaultAcl.denied.groups = group3
Lectores comunes denegados de Acl defaultAcl.denegado.usuarios = user4, user5
Acceso a todo el dominio Para especificar que todos los usuarios del dominio puedan acceder públicamente a todos los registros indexados, establezca las dos opciones siguientes con valores:
  • defaultAcl.mode =retroceso
  • defaultAcl.public =true
ACL definida común Para especificar una ACL para cada registro del repositorio de datos, establezca todos los siguientes valores de parámetros:
  • defaultAcl.mode =retroceso
  • defaultAcl.público =falso
  • defaultAcl.readers.groups = google: group1, group2
  • defaultAcl.lectores.usuarios = usuario1 user1, user2, google: user3
  • defaultAcl.denied.groups = group3
  • defaultAcl.denegado.usuarios = user4, user5

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

    El usuario o grupo predeterminado es una cadena vacía. Proporcione las opciones de usuario y grupo solo si defaultAcl.public se establece en false . Para enumerar varios grupos y usuarios, utilice la lista delimitada por comas.

    Si defaultAcl.mode se establece en none , los registros no se pueden buscar sin ACL individuales definidas.

Definición de esquema

Cloud Search permite la indexación y el servicio de contenido estructurado y no estructurado. Para admitir consultas de datos estructurados en sus datos, debe configurar Schema para su fuente de datos .

Una vez definido, CSV Connector puede hacer referencia al esquema definido para crear 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. ID de la película
  2. título de la película
  3. descripción
  4. año
  5. fecha de lanzamiento
  6. actores (múltiples valores separados por coma (,))
  7. género (múltiples valores)
  8. calificaciones

Según la estructura de datos anterior, puede definir el esquema para una fuente de datos bajo la cual desea indexar datos del 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

El siguiente archivo de configuración de ejemplo muestra los pares key=value de parámetro 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, consulte la referencia de parámetros de configuración.

Ejecute el conector CSV de Cloud Search

Para ejecutar el conector desde la línea de comandos, escriba 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. Puede iniciar sesión en archivos especificando logging.properties .