Esta guía está orientada a los administradores del conector de archivos CSV (valores separados por comas) de Google Cloud Search, es decir, a todos aquellos responsables de descargar, configurar, ejecutar y supervisar el conector.
En esta guía se incluyen instrucciones para realizar las siguientes tareas clave relacionadas con la implementación del conector de archivos CSV:
- Descargar el software del conector de archivos CSV de Google Cloud Search
- Configurar el conector para utilizarlo con la fuente de datos específica de archivos CSV
- Implementar y ejecutar el conector
Para comprender los conceptos de este documento, debes estar familiarizado con los aspectos básicos de Google Workspace, los archivos CSV y las listas de control de acceso (LCA).
Descripción general del conector de archivos CSV de Google Cloud Search
El conector de archivos CSV de Cloud Search funciona con cualquier archivo de texto de valores separados por comas (CSV). Un archivo CSV almacena datos tabulares y cada línea del archivo es un registro de datos.
El conector de archivos CSV de Google Cloud Search extrae filas individuales de un archivo CSV y luego las indexa en Cloud Search a través de la API de indexación de Cloud Search. Una vez que se completó la indexación correctamente, se puede buscar contenido en las filas individuales de los archivos CSV a través de los clientes o la API de búsqueda de Cloud Search. El conector de archivos CSV también admite el control del acceso de los usuarios al contenido en los resultados de la búsqueda mediante el uso de LCA.
El conector de archivos CSV de Google Cloud Search se puede instalar en Linux o en Windows. Antes de que implementes el conector de archivos CSV de Google Cloud Search, asegúrate de contar con los siguientes componentes obligatorios:
- Java JRE 1.8 instalado en una computadora que ejecuta el conector de archivos CSV de Google Cloud Search
La información de Google Workspace necesaria para establecer relaciones entre Google Cloud Search y la fuente de datos:
- Clave privada de Google Workspace (que contiene el ID de cuenta de servicio)
- ID de fuente de datos de Google Workspace
Por lo general, el administrador de Google Workspace del dominio puede proporcionarte estas credenciales.
Pasos para la implementación
Para implementar el conector de archivos CSV de Google Cloud Search, sigue estos pasos:
- Instala el software del conector de archivos CSV de Google Cloud Search
- Especifica la configuración del conector de archivos CSV
- Configura el acceso a la fuente de datos de Google Cloud Search
- Cómo configurar el acceso a archivos CSV
- Especifica nombres de columnas para indexar, columnas de clave única y columnas de fecha y hora
- Especifica columnas para usar en URLs de resultados de la búsqueda en los que se puede hacer clic
- Especifica información de metadatos y formatos de columna
- Programa el recorrido de los datos
- Especifica opciones de lista de control de acceso (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
Cambia a la versión deseada del SDK:
$ git checkout tags/v1-0.0.3
Compila el conector:
$ mvn package
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:
- Abre el editor de texto que prefieras y asigna un nombre al archivo de configuración.
Agrega pares de clave=valor al contenido del archivo, como se describe en las siguientes secciones. - Guarda el archivo de configuración y asígnale un nombre.
Google recomienda que al archivo de configuración le pongas el nombreconnector-config.propertiespara que no se necesiten parámetros de línea de comandos adicionales para ejecutar el conector.
Dado que puedes especificar la ruta de acceso al archivo de configuración en la línea de comandos, no es necesaria una ubicación de archivo estándar. Sin embargo, mantén el archivo de configuración en el mismo directorio que el conector para simplificar el seguimiento y la ejecución del conector.
Para asegurarte de que el conector reconozca tu archivo de configuración, especifica su ruta de acceso en la línea de comandos. De lo contrario, el conector usa connector-config.properties en tu directorio local como nombre de archivo predeterminado. Para obtener información sobre cómo especificar la ruta de configuración en la línea de comandos, consulta Ejecuta el conector de archivos CSV de Cloud Search.
3. Configura el acceso a la fuente de datos de Google Cloud Search
Los primeros parámetros que se deben especificar en cada archivo de configuración son los necesarios para acceder a la fuente de datos de Cloud Search, como se muestra en la siguiente tabla. Normalmente, necesitarás el ID de la fuente de datos, el ID de la cuenta de servicio y la ruta de acceso al archivo de claves privadas de la cuenta de servicio para configurar el acceso del conector a Cloud Search. Los pasos necesarios para configurar una fuente de datos se describen en Administra fuente de datos de terceros.
| 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: |
| 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
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 no se configura |
| 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, 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=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
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
Es una lista de patrones java.time.format.DateTimeFormatter adicionales separados por puntos y comas. 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 |
| 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:
|
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 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. |
| 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 comunes definidas | Para especificar una LCA para cada registro del repositorio de datos, configura todos los valores de parámetros siguientes:
|
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.
- movieId
- movieTitle
- description
- year
- releaseDate
- actors (valores múltiples separados por coma [,])
- genre (valores múltiples)
- ratings
Sobre la base de la estructura de datos anterior, puedes definir un esquema para una fuente de datos en la que quieres indexar datos desde un archivo CSV.
{
"objectDefinitions": [
{
"name": "movie",
"propertyDefinitions": [
{
"name": "actors",
"isReturnable": true,
"isRepeatable": true,
"isFacetable": true,
"textPropertyOptions": {
"operatorOptions": {
"operatorName": "actor"
}
}
},
{
"name": "releaseDate",
"isReturnable": true,
"isRepeatable": false,
"isFacetable": false,
"datePropertyOptions": {
"operatorOptions": {
"operatorName": "released",
"lessThanOperatorName": "releasedbefore",
"greaterThanOperatorName": "releasedafter"
}
}
},
{
"name": "movieTitle",
"isReturnable": true,
"isRepeatable": false,
"isFacetable": false,
"textPropertyOptions": {
"retrievalImportance": {
"importance": "HIGHEST"
},
"operatorOptions": {
"operatorName": "title"
}
}
},
{
"name": "genre",
"isReturnable": true,
"isRepeatable": true,
"isFacetable": true,
"enumPropertyOptions": {
"operatorOptions": {
"operatorName": "genre"
},
"possibleValues": [
{
"stringValue": "Action"
},
{
"stringValue": "Documentary"
},
{
"stringValue": "Drama"
},
{
"stringValue": "Crime"
},
{
"stringValue": "Sci-fi"
}
]
}
},
{
"name": "userRating",
"isReturnable": true,
"isRepeatable": false,
"isFacetable": true,
"integerPropertyOptions": {
"orderedRanking": "ASCENDING",
"maximumValue": "10",
"operatorOptions": {
"operatorName": "score",
"lessThanOperatorName": "scorebelow",
"greaterThanOperatorName": "scoreabove"
}
}
}
]
}
]
}
Archivo de configuración de ejemplo
En el siguiente ejemplo de archivo de configuración, se muestran los pares de parámetros key=value que definen un comportamiento del conector de ejemplo.
# data source access
api.sourceId=1234567890abcd
api.serviceAccountPrivateKeyFile=./PrivateKey.json
# CSV data structure
csv.filePath=./movie_content.csv
csv.csvColumns=movieId,movieTitle,description,releaseYear,genre,actors,ratings,releaseDate
csv.skipHeaderRecord=true
url.format=https://mymoviesite.com/movies/{0}
url.columns=movieId
csv.datetimeFormat.releaseDate=yyyy-mm-dd
csv.multiValueColumns=genre,actors
csv.multiValue.genre=;
contentTemplate.csv.title=movieTitle
# metadata structured data and content
itemMetadata.title.field=movieTitle
itemMetadata.createTime.field=releaseDate
itemMetadata.contentLanguage.defaultValue=en-US
itemMetadata.objectType.defaultValue=movie
contentTemplate.csv.quality.medium=description
contentTemplate.csv.unmappedColumnsMode=IGNORE
#ACLs
defaultAcl.mode=fallback
defaultAcl.public=true
Para obtener descripciones detalladas de cada parámetro, consulta Parámetros de configuración.
Ejecuta el conector de archivos CSV de Cloud Search
Para ejecutar el conector desde la línea de comandos, escribe el siguiente comando:
$ java -jar google-cloudsearch-csv-connector-v1-0.0.3.jar -Dconfig=my.config
De forma predeterminada, los registros del conector están disponibles en la salida estándar. Para registrar archivos, especifica logging.properties.