Ce guide est destiné aux fichiers CSV (valeurs séparées par une virgule) de Google Cloud Search les administrateurs du connecteur, c'est-à-dire toute personne chargée du téléchargement, la configuration, l'exécution et la surveillance du connecteur.
Ce guide comprend des instructions pour effectuer des tâches clés liées aux fichiers CSV déploiement du connecteur:
- 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 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 texte CSV (valeurs séparées par une virgule). . Un fichier CSV stocke des données tabulaires, et chaque ligne du fichier est un enregistrer.
Le connecteur CSV de Google Cloud Search extrait des lignes individuelles d'un fichier CSV. les indexe dans Cloud Search via l'API d'indexation de Cloud Search. Une fois sont correctement indexées, les lignes individuelles des fichiers CSV peuvent faire l'objet de recherches les clients de Cloud Search ou l'API Query de Cloud Search. Le connecteur CSV contient aussi permet de contrôler l'expérience utilisateur l'accès au contenu des résultats de recherche, en utilisant les listes de contrôle d'accès.
Le connecteur CSV de Google Cloud Search peut être installé sous Linux ou sous Windows. Avant vous déployez le connecteur CSV de Google Cloud Search, assurez-vous de disposer les composants obligatoires suivants:
- Java JRE 1.8 installé sur un ordinateur qui exécute le fichier CSV de Google Cloud Search connecteur
Informations Google Workspace requises pour établir des relations entre Google Cloud Search et la source de données:
- Clé privée Google Workspace (qui contient 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 fournir ces identifiants pour vous.
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 le comportement du connecteur CSV qui définissent les paramètres dans le fichier de configuration du connecteur. 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 au contenu du fichier, comme décrit ci-dessous. . - Enregistrez et nommez le fichier de configuration.
Google vous recommande de nommer le fichier de configurationconnector-config.propertiespour qu'aucun paramètre de ligne de commande supplémentaire nécessaires pour exécuter le connecteur.
Comme vous pouvez spécifier le chemin d'accès au fichier de configuration dans la ligne de commande, l'emplacement standard du fichier 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 le connecteur d'alimentation.
Pour vous assurer que le connecteur reconnaît votre fichier de configuration, spécifiez son chemin d'accès sur
la ligne de commande. Sinon, le connecteur utilise
connector-config.properties dans votre répertoire local en tant que
nom de fichier par défaut. Pour plus d'informations sur la spécification du chemin de configuration
à l'aide de la ligne de commande, consultez l'article 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 suivants : nécessaire pour accéder à la source de données Cloud Search, comme illustré ci-dessous tableau. 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 afin de configurer l'accès du connecteur à Cloud Search. Étapes à suivre pour configurer une source de données sont décrits dans Gérer les 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 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 l'indexation, vous devez identifier le chemin d'accès au 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ètre |
| 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 gère 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. Si aucune valeur n'est spécifiée, 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 indiquer des informations sur les définitions des colonnes dans le fichier de configuration. Si le ne contient pas les paramètres spécifiant les noms de colonnes à indexer et à 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 à 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 un résultat. incluant des URL cliquables pour chaque résultat. Pour activer cette fonctionnalité, vous devez doit 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 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 des métadonnées de l'élément. 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 les 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 qui doivent faire partie de 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. 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 à 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 Indiquez les niveaux d'importance de 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ètre |
| 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 valides sont les suivantes :
|
8. Planifier le balayage des données
Le balayage est le processus utilisé par le connecteur pour découvrir du contenu à partir des données source (dans ce cas, un fichier CSV). Pendant son exécution, le connecteur CSV balaie les lignes d'un fichier CSV, puis indexez chacune d'elles dans Cloud Search via le champ API.
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 les balayages d'écrans. 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 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 accepte les autorisations via des LCA pour contrôler au contenu du fichier CSV dans les résultats de recherche. Il existe plusieurs LCA options disponibles pour vous permettre de protéger l’accès des utilisateurs aux enregistrements indexés.
Si votre référentiel contient des informations de LCA individuelles associées à chaque document, importer toutes les informations des 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, voire aucune, vous pouvez fournir des informations de la LCA dans les paramètres suivants, que le SDK fournit au le connecteur d'alimentation.
Le connecteur repose sur l'activation des LCA par défaut dans le fichier de configuration. À
activer les LCA par défaut, définissez defaultAcl.mode sur un mode autre que none, puis
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 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 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'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. Pour vous donner un exemple, prenons l'exemple d'un fichier CSV contenant des informations sur les films.
Supposons que le fichier CSV d'entrée présente le contenu suivant.
- movieId
- movieTitle
- description
- année
- 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 un schéma pour une source de données dans dont vous voulez indexer les données à partir 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 montre les paires de paramètres key=value
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 une description détaillée de chaque paramètre, reportez-vous à la section Paramètres de configuration référence.
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. Vous pouvez consigner dans des fichiers
en spécifiant logging.properties.