Ce guide est destiné aux administrateurs des connecteurs CSV (valeurs séparées par une virgule) de Google Cloud Search, c'est-à-dire toute personne chargée du téléchargement, de la configuration, de l'exécution et de la surveillance de ce type de connecteur.
Ce guide contient des instructions permettant de réaliser les principales tâches associées au déploiement d'un connecteur CSV:
- Télécharger le logiciel du connecteur CSV de Google Cloud Search
- Configurer le connecteur pour une source de données CSV spécifique
- Déployer et exécuter le connecteur
Pour comprendre les concepts présentés dans ce document, vous devez être familiarisé avec les principes fondamentaux de Google Workspace, des fichiers CSV et des listes de contrôle d'accès (LCA).
Présentation du connecteur CSV de Google 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, et chaque ligne du fichier constitue un enregistrement de données.
Le connecteur CSV de Google Cloud Search extrait des lignes individuelles d'un fichier CSV et les indexe dans Cloud Search via l'API d'indexation de Cloud Search. Une fois l'indexation terminée, les lignes individuelles des fichiers CSV peuvent être recherchées via les clients de Cloud Search ou l'API Query de Cloud Search. Le connecteur CSV permet également de contrôler l'accès des utilisateurs au contenu des résultats de recherche à l'aide de listes de contrôle d'accès.
Le connecteur CSV de Google Cloud Search peut être installé sous Linux ou sous Windows. Avant de déployer le connecteur CSV de Google Cloud Search, assurez-vous que vous disposez de la configuration requise suivante:
- Java JRE 1.8 installé sur un ordinateur qui exécute le connecteur CSV de Google Cloud Search
Informations Google Workspace requises pour établir des relations entre Google Cloud Search et la source de données:
- 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 est généralement en mesure de vous fournir ces identifiants.
Procédure de déploiement
Pour déployer le connecteur CSV de Google Cloud Search, procédez comme suit:
- Installer le logiciel du connecteur CSV de Google Cloud Search
- Spécifier la configuration du connecteur CSV
- Configurer l'accès à la source de données Google Cloud Search
- Configurer l'accès au fichier CSV
- Spécifier les noms des colonnes à indexer, les colonnes à clé unique et les colonnes contenant la date et l'heure
- Spécifier les colonnes à utiliser dans les URL des résultats de recherche cliquables
- Spécifier les informations sur les métadonnées, les formats des colonnes
- Planifier le balayage des données
- Spécifier les options de la liste de contrôle d'accès
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 souhaitée du SDK:
$ git checkout tags/v1-0.0.3Compilez le connecteur:
$ mvn packageCopiez le fichier ZIP du connecteur dans votre répertoire d'installation 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. Spécifier la configuration du connecteur CSV
En tant qu'administrateur du connecteur, vous pouvez contrôler le comportement et les attributs du connecteur CSV à l'aide de paramètres définis dans son fichier de configuration. Les paramètres configurables comprennent:
- Accès à une source de données
- Emplacement du fichier CSV
- les définitions des colonnes CSV ;
- la ou les colonnes qui définissent un identifiant unique ;
- Options de balayage
- les options de la LCA qui restreignent l'accès aux données.
Pour que le connecteur puisse accéder à un fichier CSV et indexer les contenus pertinents, vous devez au préalable créer son fichier de configuration.
Pour créer un fichier de configuration:
- Ouvrez un éditeur de texte de votre choix et attribuez un nom au fichier de configuration.
Ajoutez des paires clé=valeur au contenu du fichier comme indiqué dans les sections suivantes. - Attribuez un nom au fichier de configuration et enregistrez-le.
Google vous recommande de nommer ce fichierconnector-config.propertiespour pouvoir exécuter le connecteur via la ligne de commande sans aucun paramètre supplémentaire.
Il n'y a pas d'emplacement standard dans lequel enregistrer le fichier de configuration, car vous pouvez spécifier son chemin d'accès dans la ligne de commande. Cependant, nous vous invitons à l'enregistrer dans le même répertoire que le connecteur afin de simplifier le suivi et l'exécution du connecteur.
Pour vous assurer que le connecteur reconnaît votre fichier de configuration, indiquez son chemin d'accès dans la ligne de commande. Sinon, le connecteur utilisera le nom de fichier par défaut connector-config.properties dans votre répertoire local. Pour savoir comment spécifier le chemin d'accès au fichier de configuration dans la ligne de commande, consultez la section Exécuter le connecteur CSV de Cloud Search.
3. Configurer l'accès à la source de données Google Cloud Search
Les premiers paramètres à spécifier dans chaque fichier de configuration sont les paramètres d'accès à la source de données Cloud Search, comme indiqué dans le tableau suivant. En règle générale, 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 pour configurer l'accès du connecteur à Cloud Search. La procédure à suivre pour configurer une source de données est décrite dans la page Gérer des sources de données tierces.
| Paramètre | Paramètre |
| ID de la source de données | api.sourceId=1234567890abcdef
Obligatoire. ID de la source Google Cloud Search configuré par l'administrateur Google Workspace, comme décrit dans l'article Gérer des sources de données tierces. |
| Chemin d'accès au fichier contenant la clé privée du compte de service | api.serviceAccountPrivateKeyFile=./PrivateKey.json
Obligatoire. Fichier contenant la clé du compte de service Google Cloud Search nécessaire à l'accessibilité du connecteur CSV. |
| 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é Google Cloud Search configuré par l'administrateur Google Workspace. |
4. Configurer les paramètres du fichier CSV
Pour permettre au connecteur de balayer un fichier CSV et d'en extraire les données à indexer, vous devez identifier le chemin d'accès à ce fichier. Vous pouvez également spécifier le format et le type d'encodage du fichier. Ajoutez les paramètres suivants pour spécifier les propriétés du fichier CSV dans le fichier de configuration.
| Paramètre | Paramètre |
| Chemin d'accès au fichier CSV | csv.filePath=./movie_content.csv
Obligatoire. Chemin d'accès au fichier CSV dont le contenu doit être extrait pour indexation. |
| 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 lorsque Cloud Search lit le fichier. En l'absence de configuration, Cloud Search utilise le caractère par défaut de la plate-forme. |
5. Spécifier les noms des colonnes à indexer et les colonnes à clé unique
Pour que le connecteur puisse consulter et indexer les fichiers CSV, vous devez lui fournir les définitions des colonnes spécifiées dans le fichier de configuration. Si le fichier de configuration ne contient pas les paramètres indiquant le nom des colonnes à indexer et les colonnes à clé unique, des valeurs par défaut sont utilisées.
| Paramètre | Paramètre |
| Colonnes à indexer | csv.csvColumns=movieId,movieTitle,description,actors,releaseDate,year,userratings...
Noms des colonnes du fichier CSV à indexer. Si |
| Colonnes à clé unique | csv.uniqueKeyColumns=movieId
La ou les colonnes du fichier CSV dont les valeurs seront utilisées pour générer l'identifiant unique de chaque enregistrement. S'il n'est pas spécifié, le hachage de l'enregistrement CSV doit être utilisé comme clé unique. La valeur par défaut est le code de hachage de l'enregistrement. |
6. Spécifier les colonnes à utiliser dans les URL des résultats de recherche cliquables
Lorsqu'un utilisateur effectue une recherche à l'aide de Google Cloud Search, chaque résultat de recherche est associé à une URL cliquable. Pour activer cette fonctionnalité, vous devez ajouter le paramètre indiqué dans le tableau suivant au fichier de configuration.
| Paramètre | Paramètre |
| Format de l'URL des résultats de recherche | url.format=https://mymoviesite.com/movies/{0}
Obligatoire. Format de l'URL d'affichage pour le contenu du fichier CSV. |
| Paramètres de l'URL des résultats de recherche | 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 informations sur les métadonnées, les formats des colonnes, 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
Les paramètres de configuration des métadonnées décrivent les colonnes du fichier CSV qui serviront à renseigner les métadonnées des éléments. Si le fichier de configuration ne contient pas ces paramètres, des valeurs par défaut sont utilisées. Ces paramètres sont présentés dans le tableau suivant.
| Paramètre | Paramètre |
| Titre | itemMetadata.title.field=movieTitle
itemMetadata.title.defaultValue=Gone with the Wind
Attribut de métadonnées qui contient la valeur correspondant au 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 qui contient la valeur correspondant à l'URL de la page de résultats. |
| Code temporel de création | itemMetadata.createTime.field=releaseDate
itemMetadata.createTime.defaultValue=1940-01-17
Attribut de métadonnées qui contient 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 qui contient la date et l'heure 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 du 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
Les formats de date et d'heure spécifient les formats attendus dans les attributs de métadonnées. Si le fichier de configuration ne contient pas ce paramètre, des valeurs par défaut sont utilisées. Le tableau suivant présente ce paramètre.
| 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 contiennent des informations sur les colonnes à inclure dans le contenu interrogeable. Si le fichier de configuration ne contient pas ces paramètres, des valeurs par défaut sont utilisées. Ces paramètres sont présentés dans le tableau suivant.
| Paramètre | Paramètre |
| Ignorer l'en-tête | csv.skipHeaderRecord=true
Valeur booléenne. Ignore l'enregistrement d'en-tête (première ligne) dans le fichier CSV. Si vous avez défini |
| Colonnes à plusieurs valeurs | csv.multiValueColumns=genre,actors
Noms des colonnes du fichier CSV qui contiennent plusieurs valeurs. La valeur par défaut est une chaîne vide. |
| 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 CSV de Cloud Search permet de formater automatiquement les champs de données au format HTML. Le connecteur définit les champs de données au début de son exécution, puis utilise un modèle de contenu pour formater chaque enregistrement de données avant de le télécharger dans Cloud Search.
Le modèle de contenu attribue à chaque valeur de champ une priorité dans le cadre de la recherche. Le champ de titre est obligatoire et associé à la plus haute priorité. Vous pouvez attribuer à tous les autres champs de contenu une priorité élevée, moyenne ou faible pour la qualité de recherche. Tout champ de contenu non défini dans une catégorie spécifique est associé par défaut à une priorité faible. Ces paramètres sont présentés dans le tableau suivant.
| 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 :
|
8. Planifier le balayage des données
Le balayage permet au connecteur d'explorer le contenu de la source de données, qui est dans notre cas un fichier CSV. Une fois exécuté, le connecteur CSV balaie les lignes du fichier CSV et les indexe dans Cloud Search via l'API d'indexation.
Le balayage complet indexe toutes les colonnes du fichier. Le balayage incrémentiel n'indexe que les colonnes ajoutées ou modifiées depuis le précédent balayage. Le connecteur CSV se limite aux balayages complets. Il n'effectue pas de balayages incrémentiels.
Les paramètres de planification déterminent la fréquence des balayages effectués par le connecteur. Si le fichier de configuration ne contient pas de paramètres de planification, des valeurs par défaut sont utilisées. Ces paramètres sont présentés dans le tableau suivant.
| Paramètre | Paramètre |
| Balayage complet après un intervalle | schedule.traversalIntervalSecs=7200
Le connecteur effectue un balayage complet après un intervalle défini. Spécifiez l'intervalle entre les balayages en secondes. La valeur par défaut est 86 400 (soit le nombre de secondes dans une journée). |
| Balayage complet au démarrage du connecteur | schedule.performTraversalOnStart=false
Au lieu d'attendre l'expiration du premier intervalle, le connecteur effectue un balayage complet au démarrage. La valeur par défaut est true. |
9. Spécifier les options de la liste de contrôle d'accès
Le connecteur CSV de Google Cloud Search peut contrôler l'accès au contenu du fichier CSV dans les résultats de recherche à l'aide de listes de contrôle d'accès (LCA). Les LCA offrent de nombreuses options permettant de protéger l'accès des utilisateurs aux enregistrements indexés.
Si chaque document est associé à ses propres informations de LCA dans votre dépôt, importez toutes les informations de LCA pour contrôler l'accès aux documents dans Cloud Search. Si votre dépôt ne contient aucune information de LCA ou seulement des informations partielles, vous pouvez fournir des informations de LCA par défaut dans les paramètres suivants, qui seront transmis au connecteur par le SDK.
Les LCA par défaut doivent être activées dans le fichier de configuration pour que le connecteur fonctionne correctement. Pour activer les LCA par défaut, définissez defaultAcl.mode sur un mode autre que none et configurez-le avec defaultAcl.*.
| Paramètre | Paramètre |
| Mode LCA | defaultAcl.mode=fallback
Obligatoire. Le connecteur CSV s'appuie sur la fonctionnalité de LCA par défaut. Le connecteur n'est compatible qu'avec le mode "fallback". |
| Nom des LCA par défaut | defaultAcl.name=VIRTUAL_CONTAINER_FOR_CONNECTOR_1
Facultatif. Permet de remplacer le nom du conteneur virtuel utilisé par le connecteur pour configurer des LCA par défaut. La valeur par défaut est "DEFAULT_ACL_VIRTUAL_CONTAINER". Il peut être utile de remplacer cette valeur quand plusieurs connecteurs sont chargés d'indexer du contenu dans une même source de données. |
| LCA publique par défaut | defaultAcl.public=true
La LCA par défaut utilisée pour l'ensemble du dépôt correspond à un accès de type 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 à l'ensemble 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 associer une LCA à chaque enregistrement du dépôt de données, configurez les paramètres suivants avec les valeurs spécifiées:
|
Définition du schéma
Cloud Search permet d'indexer et de diffuser des contenus structurés et non structurés. Afin d'autoriser les requêtes de données structurées sur vos données, vous devez configurer un schéma pour votre source de données.
Une fois le schéma défini, le connecteur CSV peut faire référence à ce schéma pour générer des demandes d'indexation. À titre d'exemple, prenons un fichier CSV contenant des informations sur des films.
Le fichier CSV d'entrée contient les informations suivantes :
- movieId
- movieTitle
- description
- année
- releaseDate
- actors (plusieurs valeurs séparées par une virgule (,))
- genre (plusieurs valeurs)
- notes
En vous basant sur la structure de ces données, vous pouvez définir un schéma pour la source de données avec laquelle vous souhaitez indexer les données provenant du fichier 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"
}
}
}
]
}
]
}
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
Pour obtenir une description détaillée de chaque paramètre, reportez-vous au guide de référence des paramètres de configuration.
Exécuter le connecteur CSV de Cloud Search
Pour exécuter le connecteur à partir de la ligne de commande, saisissez la commande suivante:
$ 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.