Déployer un connecteur CSV

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 du 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 G Suite, 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 CSV (valeurs séparées par une virgule), c'est-à-dire un fichier texte délimité dans lequel les valeurs sont 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, puis les indexe dans Cloud Search via l'API d'indexation associée. Une fois indexées, les lignes individuelles des fichiers CSV sont interrogeables via les clients ou l'API Query de Cloud Search. Le connecteur CSV peut également contrôler l'accès des utilisateurs au contenu présenté dans les résultats de recherche à l'aide de listes de contrôle d'accès (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 de la configuration requise suivante :

  • Java JRE 1.8 installé sur un ordinateur qui exécute le connecteur CSV de Google Cloud Search
  • Informations G Suite requises pour établir des relations entre Google Cloud Search et la source de données :

    En règle générale, l'administrateur G Suite du domaine peut vous fournir ces identifiants.

Procédure de déploiement

Pour déployer le connecteur CSV de Google Cloud Search, suivez les étapes ci-dessous :

  1. Installer le logiciel du connecteur CSV de Google Cloud Search
  2. Spécifier la configuration du connecteur CSV
  3. Configurer l'accès à la source de données Google Cloud Search
  4. Configurer l'accès au fichier CSV
  5. Spécifier les noms des colonnes à indexer, les colonnes à clé unique et les colonnes contenant la date et l'heure
  6. Spécifier les colonnes à utiliser dans les URL des résultats de recherche cliquables
  7. Spécifier les informations sur les métadonnées, les formats des colonnes
  8. Planifier le balayage des données
  9. Spécifier les options de la liste de contrôle d'accès

1. Installer le connecteur CSV de Google Cloud Search

Google fournit le logiciel d'installation du connecteur dans le fichier suivant :

google-cloudsearch-csv-connector-v1-0.0.2.zip

Téléchargez le connecteur CSV et extrayez-le dans le répertoire de travail local où il s'exécutera. Ce répertoire peut également contenir tous les fichiers nécessaires à l'exécution du connecteur, y compris le fichier de configuration et le fichier contenant la clé du compte de service.

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 :

  • l'accès à une source de données ;
  • l'emplacement du fichier CSV ;
  • les définitions des colonnes CSV ;
  • la ou les colonnes qui définissent un identifiant unique ;
  • les 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 :

  1. Ouvrez l'éditeur de texte de votre choix et attribuez un nom au fichier de configuration.
    Ajoutez des paires clé=valeur dans le fichier, comme expliqué dans les sections suivantes.
  2. Attribuez un nom au fichier de configuration et enregistrez-le.
    Google vous recommande de nommer ce fichier connector-config.properties pour 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 de ce dernier.

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 obtenir plus d'informations sur la spécification du chemin d'accès au fichier de configuration dans la ligne de commande, reportez-vous à la section Exécuter le connecteur CSV.

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 relative à la gestion de sources de données tierces.

Paramètre Définition
ID de la source de données api.sourceId=1234567890abcdef

Obligatoire. ID de la source Google Cloud Search défini par l'administrateur G Suite, comme décrit dans l'article relatif à la gestion de 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é Cloud Search défini par l'administrateur G Suite.

4. Configurer l'accès au 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. Le paramètre suivant permet d'ajouter des informations d'accès dans le fichier de configuration.

Paramètre Définition
Chemin du fichier CSV csv.filePath=./movie_content.csv

Obligatoire. Chemin d'accès au fichier CSV dont le contenu doit être extrait pour indexation.

5. Spécifier les noms des colonnes à indexer, les colonnes à clé unique et les colonnes contenant la date et l'heure

L'intérêt de l'indexation des fichiers CSV dans Cloud Search est qu'elle permet d'effectuer des recherches dans leurs contenus. Pour que le connecteur puisse consulter et indexer les fichiers CSV, vous devez 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, les colonnes à clé unique et les colonnes contenant la date et l'heure, des valeurs par défaut sont utilisées. Ces paramètres sont présentés dans le tableau suivant.

Paramètre Définition
Colonnes à indexer csv.csvColumns=movieId,movieTitle,description,actors,releaseDate,year,userratings...

Noms des colonnes du fichier CSV à indexer. Si csv.csvColumns n'est pas défini, la première ligne du fichier CSV est utilisée comme en-tête. Si csv.csvColumns est défini, il est prioritaire sur la première ligne du fichier CSV. Si vous avez défini csv.csvColumns et que la première ligne du fichier CSV est une liste de noms de colonnes, vous devez ajouter csv.skipHeaderRecord=true pour éviter que la première ligne soit indexée sous forme de données. Les valeurs par défaut sont les colonnes de la ligne d'en-tête du fichier.

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.

Colonnes contenant la date et l'heure csv.dateTimeColumns=releaseDate

Noms des colonnes du fichier CSV qui contiennent la date ou l'heure. La valeur par défaut est une liste vide.

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 Définition
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

Obligatoires. 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

Facultatifs. 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 Définition
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 de cet attribut est une chaîne vide.
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=movie
Type d'objet utilisé par le connecteur, tel que défini durant la procédure permettant de créer et d'enregistrer un schéma. Lorsque cette propriété n'est pas définie, le connecteur n'indexe aucune donnée structurée.

Remarque : Cette propriété de configuration renvoie à une valeur plutôt qu'à un attribut de métadonnées, et les suffixes .field et .defaultValue ne sont pas compatibles.

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 Définition
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 compatibles.

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 Définition
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 csv.csvColumns et que le fichier CSV comporte une ligne d'en-tête, vous devez ajouter skipHeaderRecord=true pour éviter que la première ligne du fichier soit indexée sous forme de données. Si le fichier CSV ne comporte pas de ligne d'en-tête, utilisez skipHeaderRecord=false. La valeur par défaut est "false".

Colonnes à plusieurs valeurs csv.multiValueColumns=genre,actors

Noms des colonnes du fichier CSV qui contiennent plusieurs valeurs. La valeur par défaut de cet attribut 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 Définition
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=

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 :

  • APPEND : ajoute les champs de contenu non spécifiés au modèle
  • IGNORE : ignore les champs de contenu non spécifiés

    La valeur par défaut est APPEND.

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.

Il existe deux types de balayages : le balayage complet, qui indexe toutes les colonnes du fichier, et le balayage incrémentiel, qui indexe uniquement 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 Définition
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 86400 (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 Définition
Mode des LCA defaultAcl.mode=fallback

Obligatoire. Le connecteur CSV s'appuie sur la fonctionnalité de LCA par défaut. Le connecteur accepte uniquement 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 à 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 :
  • defaultAcl.mode=fallback
  • defaultAcl.public=true
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 :
  • defaultAcl.mode=fallback
  • defaultAcl.public=false
  • defaultAcl.readers.groups=google:group1, group2
  • defaultAcl.readers.users=user1, user2, google:user3
  • defaultAcl.denied.groups=group3
  • defaultAcl.denied.users=user4, user5

    Chacun des utilisateurs et groupes spécifiés est considéré comme un utilisateur/groupe défini par le domaine local, à moins qu'il porte le préfixe "google:" (constante littérale).

    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 defaultAcl.public est défini sur false. Pour spécifier plusieurs groupes et utilisateurs, délimitez chaque élément par une virgule.

    Si defaultAcl.mode est défini sur none, les enregistrements peuvent faire l'objet d'une recherche uniquement si des LCA individuelles sont définies.

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 :

  1. movieId
  2. movieTitle
  3. description
  4. year
  5. releaseDate
  6. actors (plusieurs valeurs séparées par une virgule (,))
  7. genre (plusieurs valeurs)
  8. ratings

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": "HIGHEST",
            "operatorOptions": {
              "operatorName": "title"
            }
          }
        },
        {
          "name": "genre",
          "isReturnable": true,
          "isRepeatable": true,
          "isFacetable": true,
          "enumPropertyOptions": {
            "operatorOptions": {
              "operatorName": "genre"
            },
            "possibleValues": [
              {
                "stringValue": "Action"
              },
              {
                "stringValue": "Documentry"
              },
              {
                "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 (clé/valeur) 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=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

Après avoir installé et configuré le connecteur CSV de Cloud Search,

Pour exécuter le connecteur à partir de la ligne de commande, saisissez la commande suivante :

java -Djava.util.logging.config.file=logging.properties -cp google-cloudsearch-csv-connector-v1-0.0.1-withlib.jar com.google.enterprise.cloudsearch.csvconnector.CSVConnector

Vous pouvez également spécifier le chemin d'accès au fichier de configuration sous la forme -Dconfig=path_to_configfile si le connecteur utilise un fichier de configuration autre que connector-config.properties.

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.