Ce guide est destiné aux administrateurs des connecteurs CSV (valeurs séparées par des virgules) 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 du connecteur.
Ce guide contient des instructions permettant de réaliser les principales tâches lié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 connaître 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 les lignes individuelles d'un fichier CSV et les indexe dans Cloud Search via l'API d'indexation de Cloud Search. Une fois l'indexation réussie, les lignes individuelles des fichiers CSV peuvent faire l'objet d'une recherche 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 LCA.
Le connecteur CSV de Google Cloud Search peut être installé sous Linux ou 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 (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 souhaitée du SDK:
$ git checkout tags/v1-0.0.3Créez 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 contrôlez le comportement et les attributs du connecteur CSV, qui définissent les paramètres figurant dans son fichier de configuration. Les paramètres configurables incluent les suivants:
- Accès à une source de données
- Emplacement du fichier CSV
- Définitions des colonnes d'un fichier CSV
- Colonne(s) définissant un identifiant unique
- Options de balayage
- Options de LCA pour restreindre l'accès aux données
Pour que le connecteur puisse accéder correctement à un fichier CSV et indexer les contenus pertinents, vous devez d'abord créer son fichier de configuration.
Pour créer un fichier de configuration:
- Ouvrez l'éditeur de texte de votre choix et attribuez un nom au fichier de configuration.
Ajoutez des paires clé=valeur aux contenus des fichiers comme décrit dans les sections suivantes. - Enregistrez le fichier de configuration et nommez-le.
Google vous recommande de nommer ce fichierconnector-config.propertiespour pouvoir exécuter le connecteur sans aucun paramètre de ligne de commande supplémentaire.
Étant donné que vous pouvez spécifier le chemin d'accès au fichier de configuration sur la ligne de commande, il n'est pas nécessaire d'utiliser un emplacement de fichier standard. Toutefois, vous devez conserver le fichier de configuration dans le même répertoire que le connecteur pour simplifier le suivi et l'exécution du connecteur.
Pour vous assurer que le connecteur reconnaît votre fichier de configuration, spécifiez son chemin d'accès dans la ligne de commande. Sinon, le connecteur utilisera le nom de fichier par défaut connector-config.properties présent dans votre répertoire local. Pour savoir comment spécifier le chemin d'accès à la 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 que chaque fichier de configuration doit spécifier sont ceux nécessaires pour accéder à 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 de clé privée du compte de service pour configurer l'accès du connecteur à Cloud Search. La procédure de configuration d'une source de données est décrite dans Gérer des sources de données tierces.
| Paramètre | Paramètres |
| 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 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 pour l'accessibilité du connecteur CSV de Google Cloud Search. |
| ID de la source d'identité | api.identitySourceId=x0987654321
Obligatoire si vous utilisez des utilisateurs et des 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 que le connecteur puisse balayer un fichier CSV et en extraire des données à indexer, vous devez identifier le chemin d'accès au 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ètres |
| Chemin d'accès au fichier CSV | csv.filePath=./movie_content.csv
Obligatoire. Chemin d'accès au fichier CSV dont le contenu est extrait pour l'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 de format de fichier | csv.format.withMethod=value
Modification de la façon dont Cloud Search gère le fichier. Les méthodes possibles proviennent de la classe CSVFormat CSV d'Apache Commons et incluent celles qui utilisent un seul caractère, une chaîne ou une valeur booléenne. Par exemple, pour spécifier un point-virgule comme délimiteur, utilisez |
| Type d'encodage de fichier | csv.fileEncoding=UTF-8
Jeu de caractères Java à utiliser lorsque Cloud Search lit le fichier. S'il n'est pas spécifié, Cloud Search utilise le jeu de caractères 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 accéder aux fichiers CSV et les indexer, vous devez fournir des informations sur les définitions des colonnes dans le fichier de configuration. Si le fichier de configuration ne contient pas les paramètres indiquant les noms des colonnes à indexer et les colonnes à clé unique, des valeurs par défaut sont utilisées.
| Paramètre | Paramètres |
| 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
Colonne(s) 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 de résultats de recherche cliquables
Lorsqu'un utilisateur effectue une recherche à l'aide de Google Cloud Search, une page de résultats s'affiche avec des URL cliquables pour chaque résultat. Pour activer cette fonctionnalité, vous devez ajouter le paramètre indiqué dans le tableau suivant au fichier de configuration.
| Paramètre | Paramètres |
| 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 CSV. |
| Paramètres d'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 d'URL des résultats de recherche à échapper | url.columnsToEscape=movieId
Facultatif. Noms des colonnes du fichier CSV dont les valeurs seront échappées via l'URL pour générer une URL d'affichage valide. |
7. Spécifier les informations sur les métadonnées, les formats des colonnes et la qualité de la recherche
Vous pouvez ajouter au fichier de configuration des paramètres qui spécifient les éléments suivants:
Paramètres de configuration des métadonnées
Les paramètres de configuration des métadonnées décrivent les colonnes CSV utilisées pour 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. Le tableau suivant présente ces paramètres.
| 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 de l'URL du document pour 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 qui contient la valeur du code temporel 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 valeur de 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. Si cette propriété n'est pas spécifiée, 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 sont utilisés lors de l'analyse des valeurs de chaîne pour tous les champs de date ou de date/heure dans les métadonnées ou 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
Les formats de colonnes spécifient des informations sur la ou les colonnes qui doivent faire partie du contenu interrogeable. Si le fichier de configuration ne contient pas ces paramètres, des valeurs par défaut sont utilisées. Le tableau suivant présente ces paramètres.
| Paramètre | Paramètres |
| Ignorer l'en-tête | csv.skipHeaderRecord=true
Valeur booléenne. Ignorez l'enregistrement d'en-tête (première ligne) du fichier CSV. Si vous avez défini |
| Colonnes à plusieurs valeurs | csv.multiValueColumns=genre,actors
Noms des colonnes du fichier CSV qui ont plusieurs valeurs. La valeur par défaut est une chaîne vide. |
| Délimiteur pour les colonnes à plusieurs valeurs | csv.multiValue.genre=;
Délimiteur des colonnes à valeurs multiples. Le délimiteur par défaut est une virgule. |
Qualité de la recherche
Le connecteur CSV de Cloud Search permet de mettre en forme 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 met en forme chaque enregistrement de données à l'aide d'un modèle de contenu avant de l'importer dans Cloud Search.
Le modèle de contenu définit l'importance de chaque valeur de champ pour la recherche. Le champ de titre est obligatoire et a la priorité la plus élevée. Vous pouvez attribuer des niveaux d'importance à la qualité de la recherche pour tous les autres champs de contenu : élevé, moyen ou faible. Tout champ de contenu non défini dans une catégorie spécifique est associé par défaut à une priorité faible. Le tableau suivant présente ces paramètres.
| Paramètre | Paramètres |
| Titre du contenu | contentTemplate.csv.title=movieTitle
Le titre du contenu est le champ de recherche présentant la meilleure qualité de recherche. |
| 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. |
| Faible qualité de recherche 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 traite les champs de contenu non spécifiés Les valeurs possibles sont les suivantes :
|
8. Planifier le balayage des données
Le balayage est le processus du connecteur permettant de découvrir du contenu à partir de la source de données, dans ce cas un fichier CSV. Lors de son exécution, le connecteur CSV balaie les lignes d'un 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 effectue uniquement des balayages complets. Il n'effectue pas de balayages incrémentiels.
Les paramètres de planification déterminent la fréquence à laquelle le connecteur attend entre deux balayages. Si le fichier de configuration ne contient pas de paramètres de planification, des valeurs par défaut sont utilisées. Le tableau suivant présente ces paramètres.
| Paramètre | Paramètres |
| Balayage complet après un intervalle | schedule.traversalIntervalSecs=7200
Le connecteur effectue un balayage complet après un intervalle défini. Indiquez l'intervalle entre les balayages, en secondes. La valeur par défaut est 86400 (soit le nombre de secondes dans une journée). |
| Balayage complet au démarrage du connecteur | schedule.performTraversalOnStart=false
Le connecteur effectue un balayage complet au démarrage du connecteur, sans attendre l'expiration du premier intervalle. La valeur par défaut est true. |
9. Spécifier les options de la liste de contrôle d'accès (LCA)
Le connecteur CSV de Google Cloud Search accepte les autorisations via des LCA pour contrôler l'accès au contenu du fichier CSV dans les résultats de recherche. Plusieurs options de LCA sont disponibles pour vous permettre de protéger l'accès des utilisateurs aux enregistrements indexés.
Si votre dépôt contient des informations de LCA individuelles associées à chaque document, importez toutes les informations de LCA pour contrôler l'accès aux documents dans Cloud Search. Si votre dépôt ne fournit pas d'informations de LCA partielles ou aucune, vous pouvez fournir des informations de LCA par défaut dans les paramètres suivants, qui seront fournis par le SDK au connecteur.
Le connecteur s'appuie sur l'activation des LCA par défaut dans le fichier de configuration. 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ètres |
| Mode LCA | defaultAcl.mode=fallback
Obligatoire. Le connecteur CSV repose sur la fonctionnalité LCA par défaut. Le connecteur n'est compatible qu'avec le mode de remplacement. |
| Nom de 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". Vous pouvez remplacer cette valeur si plusieurs connecteurs indexent du contenu dans la 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 est définie sur l'accès au 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 publiquement par tous les utilisateurs du domaine, définissez les valeurs des deux options suivantes:
|
| LCA commune définie | Pour spécifier une LCA pour chaque enregistrement du référentiel de données, définissez toutes les valeurs de paramètres suivantes:
|
Définition du schéma
Cloud Search permet d'indexer et de diffuser du contenu structuré et non structuré. Pour 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 à celui-ci pour créer des demandes d'indexation. À titre d'exemple, prenons un fichier CSV contenant des informations sur des films.
Supposons que le fichier CSV d'entrée comporte le contenu suivant.
- movieId
- movieTitle
- description
- year
- releaseDate
- acteurs (plusieurs valeurs séparées par une virgule (,))
- genre (plusieurs valeurs)
- notes
Sur la base de la structure de données ci-dessus, vous pouvez définir un schéma pour une source de données sous laquelle vous souhaitez indexer les données d'un 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 de 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, consultez la documentation de référence sur les 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.