Esta guía está destinada a los administradores del conector de archivos CSV (valores separados por comas) de Google Cloud Search responsables de descargar, configurar, ejecutar y supervisar el conector.
En esta guía, se incluyen instrucciones para realizar las siguientes tareas clave:
- Descarga el software del conector de archivos CSV de Cloud Search.
- Configura el conector para una fuente de datos CSV específica.
- Implementa y ejecuta el conector.
Para comprender los conceptos de este documento, debes estar familiarizado con Google Workspace, los archivos CSV y las listas de control de acceso (LCA).
Descripción general del conector de archivos CSV de 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, en el que cada línea es un registro de datos.
El conector extrae filas de un archivo CSV y las indexa en Cloud Search con la API de Indexing. Una vez indexadas, las filas se pueden buscar a través de los clientes de Cloud Search o la API de Query. El conector también admite LCA para controlar el acceso de los usuarios al contenido.
Puedes instalar el conector en Linux o Windows. Antes de la implementación, asegúrate de tener los siguientes componentes:
- Java JRE 1.8 instalado en la computadora que ejecuta el conector.
- Información de Google Workspace para establecer conexiones:
- 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 proporciona estas credenciales.
Pasos para la implementación
Sigue estos pasos para implementar el conector de archivos CSV de Cloud Search:
- Instala el software del conector
- Especifica la configuración del conector
- Configura el acceso a la fuente de datos de Cloud Search
- Configura el acceso a archivos CSV
- Especifica nombres de columnas, claves únicas y columnas de fecha y hora
- Especifica columnas para las URLs de los resultados de la búsqueda en los que se puede hacer clic
- Especifica metadatos y formatos de columna
- Programa el recorrido de los datos
- Especifica opciones de LCA
1. Instala el SDK
Instala el SDK en tu repositorio local de Maven.
Clona el repositorio del SDK desde GitHub.
$ git clone https://github.com/google-cloudsearch/connector-sdk.git $ cd connector-sdk/csv
Consulta la versión seleccionada:
$ git checkout tags/v1-0.0.3
Compila el conector:
$ mvn package
Extrae e instala el conector:
$ 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
Controlas el comportamiento del conector a través de parámetros en su archivo de configuración. Algunos de los parámetros que se pueden configurar son los siguientes:
- Acceso a la fuente de datos
- Ubicación y definiciones del archivo CSV
- Columnas de ID único
- Opciones de recorrido y de LCA
Para crear un archivo de configuración, sigue estos pasos:
- Abre un editor de texto y asigna el nombre
connector-config.propertiesal archivo. - Agrega parámetros de configuración como pares
key=value, con cada par en una línea nueva. Para ver un ejemplo de un archivo de configuración, consulta Ejemplo de archivo de configuración.
Mantén el archivo de configuración en el mismo directorio que el conector para simplificar el seguimiento. Para asegurarte de que el conector reconozca tu archivo, especifica su ruta en la línea de comandos. De lo contrario, el conector usará connector-config.properties en tu directorio local de forma predeterminada. Consulta Ejecución del conector.
3. Configura el acceso a la fuente de datos de Cloud Search
El archivo de configuración debe especificar parámetros para acceder a la fuente de datos de Cloud Search. Necesitas 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.
| Configuración | Parámetro |
| ID de la fuente de datos | api.sourceId=1234567890abcdef
Obligatorio. El ID de la fuente de Cloud Search que configura el administrador de Google Workspace. |
| Ruta de acceso a la clave privada de la cuenta de servicio | api.serviceAccountPrivateKeyFile=./PrivateKey.json
Obligatorio. Es el archivo de claves de la cuenta de servicio para la accesibilidad del conector. |
| ID de la fuente de identidad | api.identitySourceId=x0987654321
Obligatorio si se utilizan usuarios y grupos externos. ID de la fuente de identidad configurado por el administrador de Google Workspace. |
4. Configura los parámetros de archivos CSV
Identifica la ruta de acceso, el formato y la codificación del archivo.
| Configuración | Parámetro |
| Ruta de acceso al archivo CSV | csv.filePath=./movie_content.csv
Obligatorio. Es la ruta de acceso al archivo 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: |
| 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 |
| Tipo de codificación de archivo | csv.fileEncoding=UTF-8
Es el conjunto de caracteres Java que se usará. El valor predeterminado es el conjunto de caracteres de la plataforma. |
5. Especifica nombres de columnas para indexar y columnas de clave únicas
Proporciona información de las columnas en el archivo de configuración.
| 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. De forma predeterminada, la primera fila del CSV se usa como encabezado. Si se especifica |
| Columnas de clave única | csv.uniqueKeyColumns=movieId
Son las columnas que se usan para generar un ID único. El valor predeterminado es el código hash del registro. |
6. Especifica columnas para las URLs de los resultados de la búsqueda en los que se puede hacer clic
Habilita las URLs en las que se puede hacer clic para los resultados de la búsqueda.
| Configuración | Parámetro |
| Formato de URL de resultados de la búsqueda | url.format=https://mymoviesite.com/movies/{0}
Obligatorio. Es el formato que se usa para construir la URL de vista. |
| Parámetros de URL | url.columns=movieId
Obligatorio. Son los nombres de las columnas del archivo CSV cuyos valores se utilizarán para generar la 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 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
Estos parámetros describen las columnas para propagar metadatos de elementos.
| Parámetro de configuración | Parámetro |
| Título | itemMetadata.title.field=movieTitle
itemMetadata.title.defaultValue=Gone with the Wind
Es el atributo de metadatos para el 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 para la URL del documento en 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 para la marca de tiempo de creación del documento. |
| Hora de última modificación | itemMetadata.updateTime.field=releaseDate
itemMetadata.updateTime.defaultValue=1940-01-17
Atributo de metadatos para 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=typeitemMetadata.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
Este parámetro especifica formatos de fecha y hora adicionales para analizar valores de cadena en campos de fecha o fecha y hora.
| Parámetro de configuración | 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 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
Estos parámetros especifican cómo analizar las columnas en el archivo CSV.
| Configuración | Parámetro |
| Omitir encabezado | csv.skipHeaderRecord=true
Ignora la primera línea. El valor predeterminado es falso. |
| Columnas de valores múltiples | csv.multiValueColumns=genre,actors
Nombres de columna con varios valores. |
| Delimitador para columnas de valores múltiples | csv.multiValue.genre=;
Es el delimitador para las columnas de valores múltiples. El delimitador predeterminado es una coma. |
Calidad de búsqueda
El conector usa una plantilla de contenido para formatear los registros. El campo de título tiene la prioridad más alta. Puedes asignar niveles de prioridad (alta, media o baja) a otros campos.
| 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:
El valor predeterminado es APPEND. |
8. Programa el recorrido de los datos
El recorrido es el proceso de descubrir contenido. El conector recorre las filas de CSV y las indexa con la API de Indexing. El conector de archivos CSV solo realiza recorridos completos.
| Configuración | Parámetro |
| Intervalo de recorrido | schedule.traversalIntervalSecs=7200
Intervalo entre recorridos completos en segundos. El valor predeterminado es 86,400 (un día). |
| Recorrido al inicio | schedule.performTraversalOnStart=false
El conector realiza un recorrido en el inicio del conector, en lugar de esperar a que venza el primer intervalo. La cantidad predeterminada es |
9. Especifica opciones de LCA
El conector usa LCA para controlar el acceso. Si tu repositorio proporciona LCA, cárgalas. De lo contrario, configura las LCA predeterminadas. Establece defaultAcl.mode en un valor distinto de none.
| Configuración | Parámetro |
| Modo de LCA | defaultAcl.mode=fallback
Obligatorio. El conector solo admite el modo de resguardo. |
| Nombre de LCA predeterminado | defaultAcl.name=VIRTUAL_CONTAINER_FOR_CONNECTOR_1
Opcional. Anula el nombre del contenedor virtual que usa el conector para las LCA predeterminadas. El valor predeterminado es |
| LCA pública predeterminada | defaultAcl.public=true
Establece todo el repositorio en acceso de dominio público. El valor predeterminado es 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:
|
| LCA común definida | Para definir una LCA común para cada registro, configura los siguientes parámetros:
Se supone que los usuarios y los grupos están definidos por el dominio local, a menos que tengan el prefijo " El usuario o grupo predeterminado es una string vacía. Solo proporciona opciones de usuario y grupo si Si |
Definición de esquema
Para admitir consultas de datos estructurados, configura un esquema para tu fuente de datos.
Por ejemplo, considera un archivo CSV con la siguiente información sobre películas:
- movieId
- movieTitle
- description
- year
- releaseDate
- actors (valores múltiples separados por coma [,])
- genre (valores múltiples)
- calificaciones
Según esta estructura, puedes definir el siguiente esquema para tu fuente de datos:
{
"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
Ejecución del conector
Para ejecutar el conector desde la línea de comandos, haz lo siguiente:
$ 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.