Ce guide est destiné aux administrateurs des connecteurs CSV (valeurs séparées par des virgules) 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 du connecteur.
Ce guide contient des instructions pour effectuer 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 l'utiliser avec 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 de base 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 fonctionne 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 est 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 indexées, 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 sous Windows. Avant de déployer le connecteur CSV de Google Cloud Search, assurez-vous que vous disposez des composants requis suivants:
- 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
En règle générale, l'administrateur Google Workspace du domaine peut 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 aux fichiers 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 et 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 son comportement et ses attributs en définissant des paramètres dans son fichier de configuration. Les paramètres configurables sont 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 la LCA pour restreindre l'accès aux données
Pour que le connecteur puisse accéder correctement à un fichier CSV et indexer le contenu pertinent, 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 nommez le fichier de configuration.
Ajoutez des paires clé=valeur dans le fichier, comme décrit dans les sections suivantes. - Enregistrez et nommez le fichier de configuration.
Google vous recommande de nommer le fichier de configurationconnector-config.propertiesafin qu'aucun paramètre de ligne de commande supplémentaire ne soit nécessaire pour exécuter le connecteur.
Étant donné que vous pouvez spécifier le chemin d'accès au fichier de configuration dans la ligne de commande, un emplacement de fichier standard n'est pas nécessaire. Toutefois, conservez 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 connector-config.properties dans votre répertoire local comme nom de fichier par défaut. Pour plus d'informations sur la spécification du chemin d'accès de 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 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 de 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 section 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 l'article Gérer des sources de données tierces. |
| Chemin d'accès au fichier de 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 les données à indexer, vous devez identifier le chemin d'accès à ce fichier. Vous pouvez également spécifier le format de fichier et le type d'encodage de 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 auquel 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 de format de fichier | csv.format.withMethod=value
Modification de 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 acceptent un caractère, une chaîne ou une valeur booléenne unique. 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 figurant dans le fichier de configuration. Si le fichier de configuration ne contient pas les paramètres spécifiant 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 à indexer à partir du fichier CSV. 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 des résultats de recherche cliquables
Lorsqu'un utilisateur effectue une recherche à l'aide de Google Cloud Search, il répond en affichant une page de résultats qui inclut 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 construction 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 au format URL afin de générer une URL d'affichage valide. |
7. Spécifiez 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:
Paramètres de configuration des métadonnées
Les paramètres de configuration des métadonnées décrivent les colonnes du fichier 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. 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 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 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. Si cette propriété n'est pas spécifiée, le connecteur n'indexera 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. Les formats sont utilisés lors de l'analyse des valeurs de chaîne des 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 des colonnes
Les formats de colonne fournissent des informations sur la ou les colonnes à inclure dans le contenu inclus dans l'index de recherche. 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ètres |
| Ignorer l'en-tête | csv.skipHeaderRecord=true
Valeur booléenne. Ignorez 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 comportent plusieurs valeurs. La valeur par défaut est une chaîne vide. |
| Délimiteur pour les 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 mettre en forme automatiquement les champs de données en HTML. Votre connecteur définit les champs de données au début de son exécution, puis utilise un modèle de contenu pour mettre en forme chaque enregistrement de données 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 défini par défaut sur une priorité faible. Ces paramètres sont présentés dans le tableau suivant.
| Paramètre | Paramètres |
| Titre du contenu | contentTemplate.csv.title=movieTitle
Le titre du contenu est le champ de recherche offrant la meilleure qualité. |
| 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. |
| Mauvaise 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 gère 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 utilisé par le connecteur pour découvrir le contenu 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 indexe uniquement les colonnes ajoutées ou modifiées depuis le précédent balayage. Le connecteur CSV n'effectue que les balayages complets. Il n'effectue pas de balayages incrémentiels.
Les paramètres de planification déterminent la fréquence d'attente du connecteur entre les balayages. 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ètres |
| Balayage complet après un intervalle | schedule.traversalIntervalSecs=7200
Le connecteur effectue un balayage complet après un intervalle spécifié. Spécifiez 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 prend en charge 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 vous permettent 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 que des informations de LCA partielles ou aucune, vous pouvez fournir des informations de LCA par défaut dans les paramètres suivants, que le SDK fournit au connecteur.
Le connecteur repose 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 s'appuie sur la fonctionnalité de LCA par défaut. Le connecteur n'est compatible qu'avec le mode de remplacement. |
| 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 les 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 groupes 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'intégralité du domaine | Pour spécifier que chaque enregistrement indexé doit être accessible à tous les utilisateurs du domaine, définissez les deux options suivantes avec des valeurs:
|
| 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 des contenus structurés et non structurés. Pour pouvoir exécuter des 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 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 présente le contenu suivant.
- movieId
- movieTitle
- description
- year
- releaseDate
- acteurs (plusieurs valeurs séparées par une virgule (,))
- genre (plusieurs valeurs)
- notes
En vous basant sur la structure de données ci-dessus, vous pouvez définir le schéma d'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 des paramètres qui définissent 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 des données dans des fichiers, spécifiez logging.properties.