Déployer un plug-in d'indexation pour Apache Nutch

Ce guide est destiné aux administrateurs du plug-in d'indexation pour Apache Nutch de Google Cloud Search, c'est-à-dire à toute personne chargée du téléchargement, du déploiement, de la configuration et de la maintenance de ce plug-in. Il nécessite de connaître les systèmes d'exploitation Linux, les principes de base de l'exploration du Web, ainsi qu'Apache Nutch.

Ce guide contient des instructions permettant de réaliser les principales tâches associées au déploiement du plug-in d'indexation :

  • Télécharger le logiciel du plug-in d'indexation
  • Configurer Google Cloud Search
  • Configurer Apache Nutch et l'exploration du Web
  • Démarrer l'exploration du Web et importer du contenu

Ce guide ne fournit pas d'informations sur les tâches que l'administrateur G Suite doit effectuer pour mapper Google Cloud Search sur le plug-in d'indexation pour Nutch. Pour plus d'informations sur ces tâches, reportez-vous à la page relative à la gestion de sources de données tierces.

Présentation du plug-in d'indexation Google Cloud Search pour Apache Nutch

Par défaut, Google Cloud Search peut explorer, indexer et diffuser du contenu à partir de données G Suite (Google Docs, Gmail, etc.). En déployant le plug-in d'indexation pour Apache Nutch (robot d'exploration Open Source), vous pouvez proposer du contenu Web à vos utilisateurs via Google Cloud Search.

Fichiers de propriétés de configuration

Pour pouvoir explorer le Web et importer du contenu dans l'API d'indexation avec le plug-in d'indexation, le connecteur aura besoin d'informations spécifiques. En tant qu'administrateur du plug-in, il vous appartient de transmettre au connecteur ces informations lors des étapes de configuration décrites dans ce document (à la section Procédure de déploiement).

L'utilisation du plug-in d'indexation nécessite de définir des propriétés dans deux fichiers de configuration :

  • nutch-site.xml : paramètres du robot d'exploration Apache Nutch.
  • sdk-configuration.properties : paramètres de Google Cloud Search.

Ces propriétés permettent au plug-in d'indexation de Google Cloud Search et à Apache Nutch de communiquer entre eux.

Exploration du Web et importation de contenu

Une fois les fichiers de configuration renseignés, vous disposez des paramètres nécessaires pour démarrer l'exploration du Web. Apache Nutch explore le Web et détecte le contenu des documents correspondant à sa configuration. À l'aide du plug-in d'indexation, il importe les versions binaires (ou texte) originales de ces contenus dans l'API d'indexation de Google Cloud Search. Cette API indexe alors les contenus et les diffuse à vos utilisateurs.

Système d'exploitation compatible

Le plug-in d'indexation pour Apache Nutch de Google Cloud Search doit être installé sur Linux.

Version d'Apache Nutch compatible

Le plug-in d'indexation pour Apache Nutch de Google Cloud Search fonctionne avec la version 1.14 de Nutch. Cette version de Nutch est d'ailleurs incluse dans le logiciel du plug-in.

Types de documents acceptés par Apache Tika

Apache Nutch 1.14 utilise Apache Tika 1.17 pour analyser le contenu. Pour accéder à la liste des types de documents que le plug-in d'indexation pour Apache Nutch peut indexer, consultez l'article relatif aux formats de documents acceptés par Apache Tika.

Compatibilité avec les listes de contrôle d'accès

Le plug-in d'indexation permet de contrôler l'accès des utilisateurs aux documents du domaine G Suite à l'aide de listes de contrôle d'accès (LCA).

Si les LCA par défaut sont activées dans la configuration du plug-in Google Cloud Search (defaultAcl.mode défini sur une valeur autre que none et configuré avec defaultAcl.*), le plug-in d'indexation essaie d'abord de créer une LCA par défaut et de l'appliquer.

Si les LCA ne sont pas activées, le plug-in accorde une autorisation de lecture pour l'ensemble du domaine G Suite.

Pour obtenir une description détaillée des paramètres de configuration des LCA, consultez l'article Paramètres de connecteur fournis par Google.

Conditions préalables

Avant de déployer le plug-in d'indexation, assurez-vous que vous disposez de la configuration requise suivante :

  • Java JRE 1.8 installé sur l'ordinateur qui exécute le plug-in d'indexation
  • Informations G Suite requises pour établir des relations entre Google Cloud Search et Apache Nutch :

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

Procédure de déploiement

Le déploiement du plug-in d'indexation se déroule en cinq étapes simples :

  1. Installer Apache Nutch et le logiciel du plug-in d'indexation
  2. Configurer Google Cloud Search
  3. Configurer Apache Nutch
  4. Configurer l'exploration du Web
  5. Démarrer l'exploration du Web et importer du contenu

Étape 1 : Installer Apache Nutch et le logiciel du plug-in d'indexation

Le logiciel du plug-in d'indexation de Google Cloud Search doit être installé sur une machine hôte. Vous le trouverez dans la distribution binaire pré-intégrée suivante :

apache-nutch-1.14-v1-0.0.2-bin.tar.gz

La distribution binaire comprend également le SDK Connector Google Cloud Search.

Pour installer Apache Nutch et le plug-in d'indexation de Google Cloud Search, procédez comme suit :

  1. Téléchargez le plug-in d'indexation pour Apache Nutch.

  2. Décompressez le fichier apache-nutch-1.14-v1-0.0.2-bin.tar.gz.
    Cette action crée le dossier "apache-nutch-1.14-SNAPSHOT", qui contient à la fois Apache Nutch et le plug-in d'indexation de Google Cloud Search.

Pour déployer un plug-in d'indexation pour Apache Nutch, vous devez créer un fichier de configuration de Google Cloud Search intitulé sdk-configuration.properties. Ce fichier doit contenir des paires clé/valeur qui définissent les informations de configuration dont le connecteur a besoin.

Il doit inclure les paramètres suivants, indispensables pour accéder à la source de données Google Cloud Search.

Paramètre Définition
ID de la source de données api.sourceId = 1234567890abcdef
Obligatoire. Identifiant de la source Google Cloud Search créée par l'administrateur G Suite.
Compte de service api.serviceAccountPrivateKeyFile = ./PrivateKey.json
Obligatoire. Fichier contenant la clé du compte de service Google Cloud Search créé par l'administrateur G Suite pour assurer l'accessibilité du plug-in d'indexation.

L'exemple suivant présente un fichier de configuration de Google Cloud Search.

#
# data source access
api.sourceId=1234567890abcdef
api.serviceAccountPrivateKeyFile=./PrivateKey.json
#

Le fichier de configuration peut également contenir d'autres paramètres propres à Google Cloud Search, qui sont susceptibles d'affecter la manière dont le plug-in d'indexation transmet les données à l'API Google Cloud Search. Exemple : defaultAcl.* et batch.* Pour obtenir une description détaillée de chaque paramètre, consultez l'article Paramètres de connecteur fournis par Google.

Vous pouvez configurer le plug-in d'indexation pour qu'il insère les métadonnées et les données structurées du contenu indexé. Ces valeurs peuvent être extraites des balises Meta incluses dans le contenu HTML indexé, ou des valeurs par défaut peuvent être définies dans le fichier de configuration.

Paramètre Définition
Titre itemMetadata.title.field=movieTitle
itemMetadata.title.defaultValue=Gone with the Wind
Par défaut, le plug-in utilise la valeur HTML title comme titre du document indexé. En l'absence de titre, vous pouvez faire référence à l'attribut de métadonnées qui contient la valeur correspondant au titre du document, ou bien définir une valeur par défaut.
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 site, tel qu'indiqué dans les définitions d'objet de schéma des sources de données. Lorsque cette propriété fait défaut, 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 séparés par un point-virgule (semicolon) répertoriant les formats supplémentaires java.time.format.DateTimeFormatter. Ces formats permettront d'analyser les valeurs de chaîne de tous les champs de date, ou de date et d'heure, contenus dans les métadonnées ou dans le schéma. La valeur par défaut est une liste vide, mais les formats RFC 3339 et RFC 1123 sont toujours acceptés.

Étape 3 : Configurer Apache Nutch

Le fichier d'archive tar apache-nutch-1.14-SNAPSHOT-bin.tar.gz comprend le fichier de configuration d'Apache Nutch, nutch-site.xml.

Ce fichier contient les valeurs requises pour la propriété plugin.includes :

index-basic
index-more
indexer-google-cloud-search

nutch-site.xml doit inclure les paramètres suivants, indispensables pour interagir avec Google Cloud Search.

Paramètre Définition
Chemin d'accès au fichier de configuration de Google Cloud Search gcs.config.file = TBS Obligatoire. Chemin (absolu) complet du fichier de configuration de Google Cloud Search.
Format d'importation gcs.uploadFormat = text Facultatif. Format dans lequel le plug-in d'indexation transmet le contenu du document à l'API d'indexation de Google Cloud Search. Les valeurs suivantes sont valides :
  • raw : le plug-in d'indexation transmet le contenu original du document, sans conversion.
  • text : le plug-in d'indexation transmet le contenu extrait, au format texte. La valeur par défaut est raw.

L'exemple suivant montre la modification à apporter dans le fichier nutch-site.xml.

<property>
  <name>gcs.config.file</name>
  <value>/path/to/sdk-configuration.properties</value>
  <description>Location of GCS Connector SDK configuration file.</description>
</property>

Étape 4 : Configurer l'exploration du Web

L'exploration du Web doit d'abord être configurée pour n'inclure que les informations que votre organisation souhaite proposer aux utilisateurs dans les résultats de recherche. Cette section contient des informations de base sur :

Pour en savoir plus sur la configuration d'une exploration du Web, consultez le tutoriel de Nutch.

Configurer les URL de début

Les URL de début indiquent à Apache Nutch où commencer l'exploration de votre contenu. Le robot doit pouvoir accéder à l'ensemble du contenu que vous souhaitez explorer en suivant les liens d'une ou de plusieurs URL de début, lesquelles sont obligatoires.

Pour configurer les URL de début, procédez comme suit :

  1. Remplacez le répertoire de travail par le répertoire d'installation de Nutch :
    $ cd ~/nutch/apache-nutch-X.Y/
  2. Créez un répertoire pour les URL :
    $ mkdir urls
  3. Créez un fichier intitulé seed.txt et inscrivez-y les URL, à raison d'une par ligne :
    $ nano urls/seed.txt

Configurer des règles relatives aux URL à suivre et à ne pas suivre

Les règles des URL à suivre définissent les URL qui seront explorées et incluses dans l'index de Google Cloud Search. Le robot consulte ces règles avant d'explorer les URL. Seules les URL qui respectent ces règles sont explorées et indexées.

Les règles des URL à ne pas suivre définissent les URL qui ne seront ni explorées, ni incluses dans l'index de Google Cloud Search. Les URL dont le format d'exploration répond aux critères de ces règles ne sont pas explorées par le robot.

Pour configurer des règles relatives aux URL à suivre et à ne pas suivre, procédez comme suit :

  1. Remplacez le répertoire de travail par le répertoire d'installation de Nutch :
    $ cd ~/nutch/apache-nutch-X.Y/
  2. Modifiez les règles des URL à suivre/à ne pas suivre dans le fichier conf/regex-urlfilter.txt :
    $ nano conf/regex-urlfilter.txt
  3. Ajoutez des expressions régulières (les expressions ouvertes sont acceptées) avec le préfixe "+" ou "-" pour suivre ou ne pas suivre des formats d'URL et des extensions, entre autres, comme dans les exemples ci-dessous.

Exemples :

# skip file extensions
-\.(gif|GIF|jpg|JPG|png|PNG|ico)

# skip protocols (file: ftp: and mailto:)
    -^(file|ftp|mailto):

# allow urls starting with https://support.google.com/gsa/
+^https://support.google.com/gsa/

# accept anything else
# (commented out due to the single url-prefix allowed above)
#+.

Modifier le script d'exploration

En l'absence de paramètre gcs.uploadFormat ou si la valeur définie est "raw", vous devez ajouter les arguments "-addBinaryContent -base64" à transmettre à la commande nutch index. Ces arguments indiquent au module d'indexation de Nutch d'inclure du contenu binaire en base64 au moment d'appeler le plug-in d'indexation. Ces arguments ne sont pas présents par défaut dans le script ./bin/crawl.

Modifiez le script crawl.sh dans apache-nutch-1.14-SNAPSHOT/bin, puis ajoutez :

      if $INDEXFLAG; then
          echo "Indexing $SEGMENT to index"
          __bin_nutch index $JAVA_PROPERTIES "$CRAWL_PATH"/crawldb  -addBinaryContent -base64 -linkdb "$CRAWL_PATH"/linkdb "$CRAWL_PATH"/segments/$SEGMENT

          echo "Cleaning up index if possible"
          __bin_nutch clean $JAVA_PROPERTIES "$CRAWL_PATH"/crawldb
      else
          echo "Skipping indexing ..."

Étape 5 : Démarrer l'exploration du Web et importer du contenu

Une fois que vous avez installé et configuré le plug-in d'indexation, vous pouvez l'exécuter de façon autonome en mode local. Utilisez les scripts de ./bin pour exécuter une tâche d'exploration ou des commandes Nutch individuelles.

Dans l'exemple suivant, les composants obligatoires se trouvent dans un répertoire local d'un système Linux. À partir du dossier apache-nutch-1.14-SNAPSHOT, exécutez Nutch avec la commande suivante :

bin/crawl -i -s urls/ crawl-test/ 5

Les journaux d'exploration sont disponibles sur la sortie standard (terminal) ou dans le répertoire logs/. Pour rediriger les journaux de sortie ou pour configurer une journalisation plus détaillée, modifiez conf/log4j.properties.