Implementa un complemento indexador para Apache Nutch

Esta guía está orientada a los administradores del complemento indexador de Google Cloud Search para Apache Nutch, es decir, cualquier persona responsable de descargar, implementar, configurar y mantener el complemento indexador. En esta guía, se presupone que estás familiarizado con los sistemas operativos Linux, los aspectos básicos del rastreo web y Apache Nutch.

La guía también incluye instrucciones para realizar tareas clave relacionadas con la implementación del complemento indexador:

Descargar el software del complemento indexador.
Configurar Google Cloud Search.
Configurar Apache Nutch y el rastreo web.
Iniciar el rastreo web y la carga de contenido.

La información sobre las tareas que debe realizar el administrador de G Suite para asignar Google Cloud Search al complemento indexador para Nutch no aparece en esta guía. Para obtener información sobre esas tareas, consulta la página sobre cómo administrar fuentes de datos de terceros.

Descripción general del complemento indexador de Google Cloud Search para Apache Nutch

De forma predeterminada, Google Cloud Search puede detectar, indexar y entregar contenido a partir de los datos de G Suite, como los correspondientes a Documentos de Google y Gmail. Puedes ampliar el alcance de Google Cloud Search de modo de incluir la entrega de contenido web activo a tus usuarios mediante la implementación del complemento indexador para Apache Nutch, un rastreador web de código abierto.

Archivos de propiedades de configuración

Como administrador del complemento indexador, para permitir que este realice rastreos web y cargue contenido a la API de indexación, debes proporcionar información específica al conector durante los pasos de configuración que se describen en este documento en Pasos para la implementación.

Para usar el complemento indexador, debes configurar las propiedades en tres archivos de configuración:

nutch-site.xml: contiene la configuración del rastreador web Apache Nutch
index-writers.xml: contiene la configuración del complemento indexador de Google Cloud Search
sdk-configuration.properties : contiene la configuración de Google Cloud Search

Las propiedades de cada archivo habilitan la comunicación entre el complemento indexador de Google Cloud Search y Apache Nutch.

Rastreo web y carga de contenido

Una vez que hayas propagado los archivos de configuración, tendrás los ajustes necesarios para iniciar el rastreo web. Apache Nutch rastrea la Web y detecta contenido de documentos relacionado con su configuración. Si usas el complemento indexador, carga versiones binarias (o de texto) originales de contenido de documentos a la API de indexación de Google Cloud Search donde se indexa y, posteriormente, se entrega a tus usuarios.

Sistema operativo compatible

El complemento indexador de Google Cloud Search para Apache Nutch debe instalarse en Linux.

Versión compatible de Apache Nutch

El complemento indexador de Google Cloud Search para Apache Nutch es compatible con la versión 1.15 de Nutch. El software del complemento indexador incluye esa versión de Nutch.

Tipos de documentos compatibles con Apache Tika

La versión 1.15 de Apache Nutch emplea la versión 1.18 de Apache Tika para el análisis del contenido. Si deseas obtener una lista de los tipos de documentos indexables mediante el complemento indexador para Apache Nutch, consulta Formatos de documento compatibles con Apache Tika.

Compatibilidad de LCA

El complemento indexador es compatible con el control de acceso a documentos en el dominio de G Suite mediante el uso de Listas de control de acceso (LCA).

Si se habilitan las LCA predeterminadas en la configuración del complemento de Google Cloud Search (defaultAcl.mode configurado en un valor distinto de none y con defaultAcl.*), el complemento indexador primero intenta crear y aplicar una LCA predeterminada.

Si no se habilitan las LCA predeterminadas, el complemento recurre a dar permiso de lectura a todo el dominio de G Suite.

Para obtener descripciones detalladas de los parámetros de configuración de LCA, consulta Parámetros de conectores que proporciona Google.

Requisitos previos

Antes de implementar el complemento indexador, asegúrate de contar con los siguientes componentes necesarios:

Java JRE 1.8 instalado en una computadora que ejecute el complemento indexador
La información de G Suite necesaria para establecer relaciones entre Google Cloud Search y Apache Nutch:
- Clave privada de G Suite (que contiene el ID de cuenta de servicio)
- ID de la fuente de datos de G Suite
Por lo general, el administrador de G Suite del dominio puede proporcionarte estas credenciales.

Pasos para la implementación

Para implementar el complemento indexador, sigue estos pasos básicos:

Instala Apache Nutch y el software del complemento indexador.
Configura Google Cloud Search.
Configura Apache Nutch.
Configura el rastreo web.
Inicia un rastreo web y carga de contenido.

Paso 1: Compila e instala Apache Nutch y el software del complemento indexador

Clona el repositorio del conector desde GitHub.

$ git clone https://github.com/google-cloudsearch/apache-nutch-indexer-plugin.git
    $ cd apache-nutch-indexer-plugin

Consulta la versión deseada del conector:
```
$ git checkout tags/v1-0.0.5
```
Compila el conector.
```
$ mvn package
```
Para omitir las pruebas durante la compilación, usa mvn package -DskipTests.
Descarga Apache Nutch 1.15 y sigue las instrucciones de Apache Nutch para instalarlo.
Extrae el archivo target/google-cloudsearch-apache-nutch-indexer-plugin-v1.0.0.5.zip (compilado en el paso 2) a una carpeta. Copia la carpeta plugins/indexer-google-cloudsearch y pégala en la carpeta de complementos de instalación de Apache Nutch (apache-nutch-1.15/plugins).

Paso 2: Configura Google Cloud Search

Si deseas implementar un complemento indexador para Apache Nutch, necesitas crear un archivo de configuración de Google Cloud Search llamado sdk-configuration.properties. Ese archivo debe contener pares clave-valor que definan la información de configuración que requiere el conector.

En el archivo de configuración, se deben especificar los siguientes parámetros, que son necesarios para acceder a la fuente de datos de Google Cloud Search.

Configuración	Parámetro
ID de la fuente de datos	`api.sourceId = 1234567890abcdef` Obligatorio. ID de la fuente de Google Cloud Search configurado por el administrador de G Suite
Cuenta de servicio	`api.serviceAccountPrivateKeyFile = ./PrivateKey.json` Obligatorio. Archivo de claves de la cuenta de servicio de Google Cloud Search que creó el administrador de G Suite para la accesibilidad del complemento indexador

En el siguiente ejemplo, se muestra un archivo de configuración de Google Cloud Search.

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

Es posible que el archivo de configuración también contenga otros parámetros de configuración específicos de Google Cloud Search, que pueden afectar la manera en la que el complemento indexador envía datos a la API de Google Cloud Search. Entre esos parámetros, se incluyen defaultAcl.* y batch.* Para acceder a descripciones detalladas de cada parámetro, consulta Parámetros de conectores que proporciona Google.

Puedes configurar el complemento indexador a fin de propagar metadatos y datos estructurados para el contenido que se indexa. Los valores que se propagarán para los campos de datos estructurados y metadatos se pueden extraer de las metaetiquetas del contenido HTML que se indexa, o bien pueden especificarse valores predeterminados en el archivo de configuración.

Configuración	Parámetro
Título	`itemMetadata.title.field=movieTitle` `itemMetadata.title.defaultValue=Gone with the Wind` De forma predeterminada, el complemento usa `HTML title` como título del documento que se indexa. En el caso de que falte un título, puedes consultar el atributo de metadatos que contiene el valor correspondiente al título del documento o configurar un valor predeterminado.
Marca de tiempo de creación	`itemMetadata.createTime.field=releaseDate` `itemMetadata.createTime.defaultValue=1940-01-17` Atributo de metadatos que contiene el valor correspondiente a la marca de tiempo de creación del documento.
Hora de la última modificación	`itemMetadata.updateTime.field=releaseDate` `itemMetadata.updateTime.defaultValue=1940-01-17` Atributo de metadatos que contiene el valor correspondiente a la marca de tiempo de la última modificación del documento.
Idioma del documento	`itemMetadata.contentLanguage.field=languageCode` `itemMetadata.contentLanguage.defaultValue=en-US` Idioma del contenido para los documentos que se indexan.
Tipo de objeto de esquema	`itemMetadata.objectType=movie` Tipo de objeto que usa el sitio, según se establece en las definiciones del objeto de esquema de la fuente de datos. El conector no indexará ningún dato estructurado si no se especifica esta propiedad. Nota: Esta propiedad de configuración hace referencia a un valor y no a un atributo de metadatos, y no se admiten los sufijos `.field` ni `.defaultValue`.

Formatos de fecha y hora

Los formatos de fecha y hora especifican los formatos esperados en los atributos de metadatos. Si el archivo de configuración no contiene este parámetro, se usan los valores predeterminados. La siguiente tabla muestra este parámetro.

Configuración	Parámetro
Patrones de fecha y hora adicionales	`structuredData.dateTimePatterns=MM/dd/uuuu HH:mm:ssXXX` Lista de patrones java.time.format.DateTimeFormatter adicionales separada por puntos y comas. Los patrones se usan cuando se analizan valores de string para cualquier campo de fecha o de fecha y hora de metadatos o de esquema. El valor predeterminado es una lista vacía, pero siempre se admiten los formatos RFC 3339 y RFC 1123.

Paso 3: Configura Apache Nutch

Modifica los archivos de configuración de Nutch

Abre conf/nutch-site.xml y agrega los siguientes parámetros:

Configuración Parámetro

El complemento incluye

plugin.includes = text

Obligatorio. Lista de complementos que se usan. Por lo menos, debe incluir:

index-basic
index-more
indexer-google-cloudsearch

conf/nutch-default.xml proporciona un valor predeterminado para esta propiedad, pero es necesario agregarle indexer-google-cloudsearch de forma manual.

Nombres de metaetiquetas

metatags.names = text

Opcional. Lista de etiquetas separadas por comas que se asignan a propiedades en el esquema de fuente de datos correspondiente. Esta página de la documentación de Nutch contiene más información sobre cómo configurar el rastreador para metaetiquetas.

El siguiente ejemplo muestra la modificación necesaria para nutch-site.xml.

<property>
      <name>plugin.includes</name>
      <value>protocol-(http|httpclient)|urlfilter-regex|index-(basic|more| metadata)|query-(basic|site|url|lang)|indexer-google-cloudsearch|nutch-extensionpoints|parse-(text|html|msexcel|msword|mspowerpoint|pdf|metatags)|summary-basic|scoring-opic|urlnormalizer-(pass|regex|basic)|parse-(html|tika|metatags)|index-(basic|anchor|more|metadata)</value>
    </property>

Modifica el archivo de configuración de escritores de índices

Abre conf/index-writers.xml y agrega la siguiente sección:

<writer id="indexer_google_cloud_search_1" class="org.apache.nutch.indexwriter.gcs.GoogleCloudSearchIndexWriter">
          <parameters>
              <param name="gcs.config.file" value="path/to/config.properties"/>
          </parameters>
      </writer>

La sección <writer> contiene los siguientes parámetros:

Configuración Parámetro

Ruta al archivo de configuración de Google Cloud Search

gcs.config.file = path

Obligatorio. Ruta completa (absoluta) al archivo de configuración de Google Cloud Search.

Formato de carga

gcs.uploadFormat = text

Opcional. Formato en el que el complemento indexador envía contenido de documentos a la API del indexador de Google Cloud Search. Los valores válidos son los siguientes:

raw: el complemento indexador envía contenido original de documentos sin convertir.
text: el complemento indexador envía contenido textual extraído. El valor predeterminado es raw.

Paso 4: Configura el rastreo web

Antes de iniciar un rastreo web, debes configurar el rastreo para que solo incluya la información que tu organización quiere que esté disponible en los resultados de la búsqueda. Esta sección incluye información básica sobre lo siguiente:

Configurar URL de inicio
Configurar reglas de seguimiento y de no seguimiento
Editar la secuencia de comandos de rastreo

Para obtener información más detallada sobre cómo configurar un rastreo web, consulta el instructivo de Nutch.

Configura URL de inicio

Las URL de inicio controlan dónde comienza a rastrear tu contenido el rastreador web de Apache Nutch. El rastreador web debería poder llegar a todo el contenido que desees incluir en un rastreo particular mediante el seguimiento de los vínculos de una o más URL de inicio. Las URL de inicio son obligatorias.

Para configurar las URL de inicio, sigue estos pasos:

Cambia el directorio de trabajo al directorio de instalación de Nutch:
$ cd ~/nutch/apache-nutch-X.Y/
Crea un directorio para las URL:
$ mkdir urls
Crea un archivo llamado seed.txt y escribe allí las URL (1 por línea):
$ nano urls/seed.txt

Configura reglas de seguimiento y de no seguimiento

Las reglas de seguimiento de URL controlan qué URL se rastrean y se incluyen en el índice de Google Cloud Search. Antes de rastrear cualquier URL, el rastreador web las verifica en función de las reglas de seguimiento de URL. Solo se rastrean y se indexan las URL que coinciden con estas reglas.

Las reglas de no seguimiento evitan que las URL se rastreen y se incluyan en el índice de Google Cloud Search. Si una URL contiene un patrón de no rastreo, el rastreador web no la rastrea.

Para configurar reglas de seguimiento y de no seguimiento de URL, sigue estos pasos:

Cambia el directorio de trabajo al directorio de instalación de Nutch:
$ cd ~/nutch/apache-nutch-X.Y/
Edita conf/regex-urlfilter.txt para cambiar las reglas de seguimiento o no seguimiento:
$ nano conf/regex-urlfilter.txt
Coloca expresiones regex (pueden ser abiertas) con el prefijo “+” o “-” para seguir o no seguir patrones de URL, extensiones, etc., como se muestra en los ejemplos a continuación.

Ejemplos:

# 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)
    #+.

Edita la secuencia de comandos de rastreo

Si falta el parámetro gcs.uploadFormat o está configurado como “raw”, debes agregar argumentos “-addBinaryContent -base64” que se pasen al comando nutch index. Estos argumentos le dicen al módulo del indexador para Nutch que incluya contenido binario en Base64 cuando invoque el complemento indexador. La secuencia de comandos ./bin/crawl no tiene estos argumentos de forma predeterminada.

Edita la secuencia de comandos crawl.sh en apache-nutch-1.15/bin y agrega lo siguiente:

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

Paso 5: Inicia un rastreo web y carga de contenido

Una vez que instalaste y configuraste el complemento indexador, puedes ejecutarlo de manera independiente en modo local. Usa las secuencias de comandos de ./bin para ejecutar un trabajo de rastreo o comandos de Nutch individuales.

En el siguiente ejemplo, se presupone que los componentes obligatorios están ubicados en el directorio local de un sistema Linux. Ejecuta Nutch con el siguiente comando desde la carpeta apache-nutch-1.15:

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

Los registros de rastreo están disponibles en el resultado estándar (terminal) o en el directorio logs/. Para dirigir el resultado de registro o acceder a registros más detallados, edita conf/log4j.properties.