Ce guide est destiné aux administrateurs du connecteur CSV (valeurs séparées par une virgule) de Google Cloud Search, qui sont chargés de télécharger, de configurer, d'exécuter et de surveiller le connecteur.
Ce guide contient des instructions pour les tâches clés suivantes :
- Téléchargez le logiciel du connecteur CSV de Cloud Search.
- Configurez le connecteur pour une source de données CSV spécifique.
- Déployez et exécutez le connecteur.
Pour comprendre les concepts présentés dans ce document, vous devez être familiarisé avec Google Workspace, les fichiers CSV et les listes de contrôle d'accès (LCA).
Présentation du connecteur CSV de Cloud Search
Le connecteur CSV de Cloud Search est compatible avec tout fichier texte CSV (valeurs séparées par une virgule). Un fichier CSV stocke des données tabulaires, où chaque ligne est un enregistrement de données.
Le connecteur extrait les lignes d'un fichier CSV et les indexe dans Cloud Search à l'aide de l'API Indexing. Une fois les lignes indexées, il est possible d'effectuer des recherches dans les clients Cloud Search ou l'API Query. Le connecteur est également compatible avec les LCA pour contrôler l'accès des utilisateurs au contenu.
Vous pouvez installer le connecteur sous Linux ou Windows. Avant le déploiement, assurez-vous de disposer des composants suivants :
- Java JRE 1.8 installé sur l'ordinateur qui exécute le connecteur
- Informations Google Workspace pour établir des connexions :
- Clé privée Google Workspace (contenant l'ID du compte de service).
- ID de la source de données Google Workspace.
L'administrateur Google Workspace du domaine fournit généralement ces identifiants.
Procédure de déploiement
Pour déployer le connecteur CSV de Cloud Search, procédez comme suit :
- Installer le logiciel du connecteur
- Spécifier la configuration du connecteur
- Configurer l'accès à la source de données Cloud Search
- Configurer l'accès au fichier CSV
- Spécifier les noms de colonnes, les clés uniques et les colonnes contenant la date et l'heure
- Spécifier les colonnes pour les URL des résultats de recherche cliquables
- Spécifier les métadonnées et les formats des colonnes
- Planifier le balayage des données
- Spécifier les options de la LCA
1. Installer le SDK
Installez le SDK dans votre dépôt Maven local.
Clonez le dépôt du SDK à partir de GitHub.
$ git clone https://github.com/google-cloudsearch/connector-sdk.git $ cd connector-sdk/csv
Vérifiez la version sélectionnée :
$ git checkout tags/v1-0.0.3
Compilez le connecteur :
$ mvn package
Extrayez et installez le connecteur :
$ 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. Spécifier la configuration du connecteur CSV
Vous pouvez contrôler le comportement du connecteur à l'aide de paramètres définis dans son fichier de configuration. Les paramètres configurables comprennent :
- Accès à la source de données.
- Emplacement et définitions du fichier CSV.
- Colonnes d'ID uniques.
- Options de parcours et de LCA.
Pour créer un fichier de configuration :
- Ouvrez un éditeur de texte et nommez le fichier
connector-config.properties. - Ajoutez des paramètres de configuration sous forme de paires
key=value, chaque paire étant sur une nouvelle ligne. Pour obtenir un exemple de fichier de configuration, consultez Exemple de fichier de configuration.
Conservez le fichier de configuration dans le même répertoire que le connecteur pour simplifier le suivi. Pour vous assurer que le connecteur reconnaît votre fichier, indiquez son chemin d'accès dans la ligne de commande. Sinon, le connecteur utilisera par défaut connector-config.properties dans votre répertoire local. Consultez Exécuter le connecteur.
3. Configurer l'accès à la source de données Cloud Search
Le fichier de configuration doit spécifier les paramètres permettant d'accéder à la source de données Cloud Search. Vous avez besoin de l'ID de la source de données, de l'ID du compte de service et du chemin d'accès au fichier contenant la clé privée du compte de service.
| Paramètre | Paramètre |
| ID de la source de données | api.sourceId=1234567890abcdef
Obligatoire. ID de la source Cloud Search défini par l'administrateur Google Workspace. |
| Chemin d'accès à la clé privée du compte de service | api.serviceAccountPrivateKeyFile=./PrivateKey.json
Obligatoire. Fichier contenant la clé du compte de service pour l'accessibilité du connecteur. |
| ID de la source d'identité | api.identitySourceId=x0987654321
Obligatoire en présence d'utilisateurs et de groupes externes. ID de la source d'identité configuré par l'administrateur Google Workspace. |
4. Configurer les paramètres du fichier CSV
Identifiez le chemin d'accès, le format et l'encodage du fichier.
| Paramètre | Paramètre |
| Chemin d'accès au fichier CSV | csv.filePath=./movie_content.csv
Obligatoire. Chemin d'accès au fichier à indexer. |
| Format de fichier | csv.format=DEFAULT
Format du fichier. Les valeurs possibles proviennent de la classe CSVFormat du fichier CSV Apache Commons. Les valeurs de format incluent : |
| Modificateur du format de fichier | csv.format.withMethod=value
Modification apportée à la façon dont Cloud Search traite le fichier. Les méthodes possibles proviennent de la classe CSVFormat du fichier CSV Apache Commons et incluent celles qui utilisent un caractère, une chaîne ou une valeur booléenne unique. Par exemple, spécifiez |
| Type d'encodage de fichier | csv.fileEncoding=UTF-8
Jeu de caractères Java à utiliser. La valeur par défaut est le jeu de caractères de la plate-forme. |
5. Spécifier les noms des colonnes à indexer et les colonnes à clé unique
Fournissez des informations sur les colonnes dans le fichier de configuration.
| Paramètre | Paramètre |
| Colonnes à indexer | csv.csvColumns=movieId,movieTitle,description,actors,releaseDate,year,userratings...
Noms des colonnes du fichier CSV à indexer. Par défaut, la première ligne du fichier CSV est utilisée comme en-tête. Si |
| Colonnes à clé unique | csv.uniqueKeyColumns=movieId
Colonnes utilisées pour générer un identifiant unique. La valeur par défaut est le code de hachage de l'enregistrement. |
6. Spécifier les colonnes pour les URL des résultats de recherche cliquables
Activez les URL cliquables pour les résultats de recherche.
| Paramètre | Paramètre |
| Format de l'URL des résultats de recherche | url.format=https://mymoviesite.com/movies/{0}
Obligatoire. Format utilisé pour créer l'URL d'affichage. |
| Paramètres d'URL | url.columns=movieId
Obligatoire. Noms des colonnes du fichier CSV dont les valeurs seront utilisées pour générer l'URL d'affichage de l'enregistrement. |
| Paramètres de l'URL des résultats de recherche à échapper | url.columnsToEscape=movieId
Facultatif. Noms des colonnes du fichier CSV dont les valeurs comprendront une séquence d'échappement pour générer une URL d'affichage valide. |
7. Spécifier les métadonnées, les formats des colonnes et la qualité de la recherche
Vous pouvez ajouter des paramètres au fichier de configuration pour spécifier :
Paramètres de configuration des métadonnées
Ces paramètres décrivent les colonnes permettant de renseigner les métadonnées des éléments.
| Paramètre | Paramètre |
| Titre | itemMetadata.title.field=movieTitle
itemMetadata.title.defaultValue=Gone with the Wind
Attribut de métadonnées pour le titre du document. La valeur par défaut est une chaîne vide. |
| URL | itemMetadata.sourceRepositoryUrl.field=url
itemMetadata.sourceRepositoryUrl.defaultValue=https://www.imdb.com/title/tt0031381/
Attribut de métadonnées pour l'URL du document dans les résultats de recherche. |
| Date et heure de création | itemMetadata.createTime.field=releaseDate
itemMetadata.createTime.defaultValue=1940-01-17
Attribut de métadonnées pour la date et l'heure de création du document. |
| Date et heure de la dernière modification | itemMetadata.updateTime.field=releaseDate
itemMetadata.updateTime.defaultValue=1940-01-17
Attribut de métadonnées pour l'horodatage de la dernière modification du document. |
| Langue du document | itemMetadata.contentLanguage.field=languageCode
itemMetadata.contentLanguage.defaultValue=en-US
Langue du contenu des documents indexés. |
| Type d'objet de schéma | itemMetadata.objectType.field=typeitemMetadata.objectType.defaultValue=movie
Type d'objet utilisé par le connecteur, tel que défini dans le schéma. Lorsque cette propriété n'est pas définie, le connecteur n'indexe aucune donnée structurée. |
Formats de date et d'heure
Ce paramètre spécifie des formats de date et d'heure supplémentaires pour analyser les valeurs de chaîne dans les champs de date ou de date et d'heure.
| Paramètre | Paramètre |
| Autres formats de date et d'heure | structuredData.dateTimePatterns=MM/dd/uuuu HH:mm:ssXXX
Liste de formats java.time.format.DateTimeFormatter supplémentaires séparés par un point-virgule. Ces formats permettront d'analyser les valeurs de chaîne de tous les champs de date, ou de date et d'heure, contenus dans les métadonnées ou dans le schéma. La valeur par défaut est une liste vide, mais les formats RFC 3339 et RFC 1123 sont toujours acceptés.
|
Formats de colonnes
Ces paramètres spécifient comment analyser les colonnes du fichier CSV.
| Paramètre | Paramètre |
| Ignorer l'en-tête | csv.skipHeaderRecord=true
Ignorez la première ligne. La valeur par défaut est "false". |
| Colonnes à valeurs multiples | csv.multiValueColumns=genre,actors
Noms des colonnes comportant plusieurs valeurs. |
| Délimiteur des colonnes à plusieurs valeurs | csv.multiValue.genre=;
Délimiteur pour les colonnes à plusieurs valeurs. Le délimiteur par défaut est une virgule. |
Qualité de la recherche
Le connecteur utilise un modèle de contenu pour mettre en forme les enregistrements. Le champ de titre a la priorité la plus élevée. Vous pouvez attribuer des niveaux de priorité (élevé, moyen, faible) à d'autres champs.
| Paramètre | Paramètre |
| Titre du contenu |
contentTemplate.csv.title=movieTitle
Le titre du contenu est le champ de recherche associé à la qualité la plus élevée. |
| Qualité de recherche élevée pour les champs de contenu |
contentTemplate.csv.quality.high=actors
Champs de contenu associés à une qualité de recherche élevée. La valeur par défaut est une chaîne vide. |
| Qualité de recherche faible pour les champs de contenu |
contentTemplate.csv.quality.low=genre
Champs de contenu associés à une qualité de recherche faible. La valeur par défaut est une chaîne vide. |
| Qualité de recherche moyenne pour les champs de contenu |
contentTemplate.csv.quality.medium=description
Champs de contenu associés à une qualité de recherche moyenne. La valeur par défaut est une chaîne vide. |
| Champs de contenu non spécifiés |
contentTemplate.csv.unmappedColumnsMode=IGNORE
Façon dont le connecteur gère les champs de contenu non spécifiés. Les valeurs valides sont les suivantes :
La valeur par défaut est APPEND. |
8. Planifier le balayage des données
Le balayage est le processus de découverte de contenu. Le connecteur parcourt les lignes CSV et les indexe à l'aide de l'API d'indexation. Le connecteur CSV se limite aux balayages complets.
| Paramètre | Paramètre |
| Intervalle de déplacement | schedule.traversalIntervalSecs=7200
Intervalle entre les balayages complets, en secondes. La valeur par défaut est 86 400 (un jour). |
| Balayage au démarrage | schedule.performTraversalOnStart=false
Au lieu d'attendre l'expiration du premier intervalle, le connecteur effectue un balayage au démarrage. La valeur par défaut est |
9. Spécifier les options de la LCA
Le connecteur utilise des ACL pour contrôler l'accès. Si votre dépôt fournit des LCA, importez-les. Sinon, configurez les LCA par défaut. Définissez defaultAcl.mode sur une valeur autre que none.
| Paramètre | Paramètre |
| Mode des LCA | defaultAcl.mode=fallback
Obligatoire. Le connecteur n'accepte que le mode "fallback". |
| Nom des LCA par défaut | defaultAcl.name=VIRTUAL_CONTAINER_FOR_CONNECTOR_1
Facultatif. Remplace le nom du conteneur virtuel utilisé par le connecteur pour les LCA par défaut. La valeur par défaut est |
| LCA publique par défaut | defaultAcl.public=true
Définit l'accès à l'ensemble du dépôt sur le domaine public. La valeur par défaut est "false". |
| Lecteurs de groupe de la LCA commune | defaultAcl.readers.groups=google:group1, group2
|
| Lecteurs de la LCA commune | defaultAcl.readers.users=user1, user2, google:user3
|
| Lecteurs de groupe refusés de la LCA commune | defaultAcl.denied.groups=group3
|
| Lecteurs refusés de la LCA commune | defaultAcl.denied.users=user4, user5
|
| Accès à la totalité du domaine | Pour indiquer que chaque enregistrement indexé doit être accessible à tous les utilisateurs du domaine, configurez les options suivantes avec les valeurs spécifiées :
|
| LCA commune définie | Pour définir une LCA commune pour chaque enregistrement, définissez les paramètres suivants :
Les utilisateurs et les groupes sont considérés comme définis par le domaine local, à moins qu'ils portent le préfixe " La valeur par défaut pour l'utilisateur ou le groupe est une chaîne vide. Renseignez les options des utilisateurs et des groupes uniquement si Si |
Définition du schéma
Pour autoriser les requêtes de données structurées, configurez un schéma pour votre source de données.
Prenons l'exemple d'un fichier CSV contenant les informations suivantes sur des films :
- movieId
- movieTitle
- description
- année
- releaseDate
- actors (plusieurs valeurs séparées par une virgule (,))
- genre (plusieurs valeurs)
- notes
En vous basant sur cette structure, vous pouvez définir le schéma suivant pour votre source de données :
{
"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"
}
}
}
]
}
]
}
Exemple de fichier de configuration
L'exemple de fichier de configuration suivant indique les paires key=value des paramètres définissant le comportement d'un connecteur.
# 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
Exécuter le connecteur
Pour exécuter le connecteur à partir de la ligne de commande :
$ java -jar google-cloudsearch-csv-connector-v1-0.0.3.jar -Dconfig=my.config
Par défaut, les journaux du connecteur sont disponibles sur la sortie standard. Pour consigner les données dans des fichiers, spécifiez logging.properties.