Implantar um plug-in indexador para Apache Nutch

Este guia destina-se aos administradores do plug-in indexador do Google Cloud Search para Apache Nutch, ou seja, qualquer pessoa responsável por fazer o download, implantar, configurar e manter o plug-in indexador. Para usar este guia, é necessário ter familiaridade com os sistemas operacionais Linux, além de noções básicas de rastreamento da Web e do Apache Nutch (em inglês).

Este guia inclui instruções para realizar as principais tarefas relacionadas à implantação do plug-in indexador:

  • Fazer o download do software do plug-in indexador.
  • Configurar o Google Cloud Search.
  • Configurar o Apache Nutch e o rastreamento da Web.
  • Iniciar o rastreamento da Web e o upload de conteúdo.

As informações sobre as tarefas que o administrador do G Suite precisa executar para mapear o Google Cloud Search para o plug-in indexador para Nutch não estão presentes neste guia. Para mais informações sobre essas tarefas, consulte Gerenciar origens de dados de terceiros.

Visão geral do plug-in indexador do Google Cloud Search para Apache Nutch

Por padrão, o Google Cloud Search pode detectar, indexar e exibir conteúdo com base nos dados do G Suite, como o Documentos Google e o Gmail. É possível estender o alcance do Google Cloud Search para incluir a exibição de conteúdo da Web para seus usuários. Para fazer isso, implante o plug-in indexador para Apache Nutch (em inglês), um rastreador da Web de código aberto.

Arquivos de propriedades de configuração

Para permitir que o plug-in indexador realize rastreamentos da Web e faça upload do conteúdo para a API Indexing, o administrador do plug-in precisa fornecer informações específicas ao conector durante as etapas de configuração descritas neste documento em Etapas da implantação.

Para usar o plug-in indexador, é necessário definir as propriedades em três arquivos de configuração:

  • nutch-site.xml (em inglês): contém as configurações do rastreador da Web Apache Nutch
  • index-writers.xml: contém as configurações do plug-in indexador do Google Cloud Search
  • sdk-configuration.properties : contém as configurações do Google Cloud Search

As propriedades em cada arquivo permitem que o plug-in indexador do Google Cloud Search e o Apache Nutch se comuniquem entre si.

Rastreamento da Web e upload de conteúdo

Depois de preencher os arquivos de configuração, você terá as configurações necessárias para iniciar o rastreamento da Web. O Apache Nutch rastreia a Web, detectando o conteúdo de documento que pertence à configuração dele. Usando o plug-in indexador, Apache Nutch faz o upload de versões originais binárias (ou de texto) do conteúdo de documento para a API Indexing do Google Cloud Search, em que é indexado e exibido para os usuários.

Sistema operacional compatível

O plug-in indexador do Google Cloud Search para Apache Nutch precisa estar instalado no Linux.

Versão compatível do Apache Nutch

O plug-in indexador do Google Cloud Search para Apache Nutch é compatível com o Nutch versão 1.15. O software do plug-in indexador inclui essa versão do Nutch.

Tipos de documentos compatíveis com o Apache Tika

O Apache Nutch versão 1.15 depende do Apache Tika versão 1.18 para análise de conteúdo. Para uma lista dos tipos de documentos que podem ser indexados pelo plug-in indexador para Apache Nutch, consulte Formatos de documentos compatíveis com o Apache Tika (em inglês).

Compatibilidade com ACLs

O plug-in indexador é compatível com o controle de acesso a documentos no domínio do G Suite usando listas de controle de acesso (ACLs, na sigla em inglês).

Se as ACLs padrão estiverem ativadas na configuração do plug-in para Google Cloud Search (defaultAcl.mode definido como diferente de none e configurado com defaultAcl.*), o plug-in indexador primeiro tentará criar e aplicar uma ACL padrão.

Se as ACLs padrão não estiverem ativadas, o plug-in voltará a conceder permissão de leitura a todo o domínio do G Suite.

Para ver descrições detalhadas dos parâmetros de configuração de ACL, consulte Parâmetros de conector fornecidos pelo Google.

Pré-requisitos

Antes de implantar o plug-in indexador, verifique se você tem os componentes obrigatórios a seguir:

  • Java JRE 1.8 instalado em um computador que executa o plug-in indexador
  • Informações do G Suite necessárias para estabelecer relações entre o Google Cloud Search e o Apache Nutch:

    Normalmente, o administrador do G Suite no domínio pode fornecer essas credenciais para você.

Etapas da implantação

Para implantar o plug-in do indexador, siga estas etapas básicas:

  1. Instale o Apache Nutch e o software de plug-in do indexador.
  2. Configure o Google Cloud Search.
  3. Configure o Apache Nutch.
  4. Configure o rastreamento da Web.
  5. Inicie um rastreamento da Web e faça upload do conteúdo.

Etapa 1: crie e instalar o Apache Nutch e o software de plug-in indexador

  1. Clone o repositório do conector que está no GitHub.

    $ git clone https://github.com/google-cloudsearch/apache-nutch-indexer-plugin.git
        $ cd apache-nutch-indexer-plugin
  2. Confira se é a versão desejada do conector:

    $ git checkout tags/v1-0.0.5
  3. Crie o conector.

    $ mvn package

    Para pular os testes durante a criação do conector, use mvn package -DskipTests.

  4. Faça o download do Apache Nutch 1.15 e siga as instruções do Apache Nutch (ambos os links em inglês) para realizar a instalação.

  5. Extraia o target/google-cloudsearch-apache-nutch-indexer-plugin-v1.0.0.5.zip (criado na etapa 2) para uma pasta. Copie a pasta plugins/indexer-google-cloudsearch para a pasta de plug-ins de instalação do Apache Nutch (apache-nutch-1.15/plugins).

Para implantar um plug-in indexador para Apache Nutch, é necessário criar um arquivo de configuração do Google Cloud Search chamado sdk-configuration.properties. Esse arquivo precisa conter pares de chave/valor que definam as informações de configuração exigidas pelo conector.

O arquivo de configuração precisa especificar os parâmetros a seguir, que são obrigatórios para acessar a origem de dados do Google Cloud Search.

Configuração Parâmetro
Código da fonte de dados api.sourceId = 1234567890abcdef
Obrigatório. O ID da origem do Google Cloud Search configurado pelo administrador do G Suite.
Conta de serviço api.serviceAccountPrivateKeyFile = ./PrivateKey.json
Obrigatório. O arquivo da chave da conta de serviço do Google Cloud Search que foi criado pelo administrador do G Suite para que o plug-in do indexador tenha acesso.

O exemplo a seguir mostra um arquivo de configuração do Google Cloud Search.

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

O arquivo de configuração também pode conter vários outros parâmetros de configuração específicos do Google Cloud Search, o que pode afetar o modo como o plug-in indexador envia dados para a API do Google Cloud Search. Como exemplos desses parâmetros, temos defaultAcl.* e batch.*. Para ver descrições detalhadas de cada parâmetro, consulte Parâmetros de conector fornecidos pelo Google.

É possível configurar o plug-in indexador para preencher metadados e dados estruturados do conteúdo que está sendo indexado. Os valores a serem preenchidos nos campos de metadados e dados estruturados podem ser extraídos das metatags no conteúdo HTML que está sendo indexado. Como alternativa, especifique valores padrão no arquivo de configuração.

Configuração Parâmetro
Título itemMetadata.title.field=movieTitle
itemMetadata.title.defaultValue=Gone with the Wind
Por padrão, o plug-in usa o HTML title como título do documento que está sendo indexado. No caso de falta do título, consulte o atributo de metadados que contém o valor correspondente ao título do documento ou defina um valor padrão.
Carimbo de data/hora criado itemMetadata.createTime.field=releaseDate
itemMetadata.createTime.defaultValue=1940-01-17
O atributo de metadados que contém o valor do carimbo de data/hora da criação do documento.
Horário da última modificação itemMetadata.updateTime.field=releaseDate
itemMetadata.updateTime.defaultValue=1940-01-17
O atributo de metadados que contém o valor do carimbo de data/hora da modificação mais recente do documento.
Idioma do documento itemMetadata.contentLanguage.field=languageCode
itemMetadata.contentLanguage.defaultValue=en-US
O idioma do conteúdo dos documentos que estão sendo indexados.
Tipo de objeto de esquema itemMetadata.objectType=movie
O tipo de objeto usado pelo site, conforme definido nas definições de objeto de esquema da origem de dados. O conector não indexará nenhum dado estruturado se essa propriedade não for especificada.

Observação: essa propriedade de configuração indica um valor e não um atributo de metadados, e os sufixos .field e .defaultValue não são compatíveis.

Formatos de data e hora

Os formatos de data e hora especificam os formatos esperados nos atributos de metadados. Se o arquivo de configuração não contiver esse parâmetro, os valores padrão serão usados. Veja esse parâmetro na tabela a seguir.

Configuração Parâmetro
Outros padrões de data e hora structuredData.dateTimePatterns=MM/dd/uuuu HH:mm:ssXXX

Uma lista separada por ponto e vírgula de padrões extras de java.time.format.DateTimeFormatter. Os padrões são usados ao analisar valores de string de quaisquer campos de data ou data/hora nos metadados ou no esquema. O valor padrão é uma lista vazia, mas os formatos RFC 3339 e RFC 1123 são sempre aceitos.

Etapa 3: configure o Apache Nutch

Modificar os arquivos de configuração do Nutch

Abra conf/nutch-site.xml e adicione os seguintes parâmetros:

Configuração Parâmetro
Elementos inclusos no plug-in plugin.includes = text

Obrigatório. Lista de plug-ins a serem usados. Precisa incluir pelo menos os seguintes elementos:

  • index-basic
  • index-more
  • indexer-google-cloudsearch
O conf/nutch-default.xml fornece um valor padrão para essa propriedade, mas é necessário adicionar manualmente o indexer-google-cloudsearch a ela.
Nomes das metatags metatags.names = text

Opcional. Lista separada por vírgulas enumerando tags que mapeiam para propriedades no esquema da origem de dados correspondente. Esta página (em inglês) na documentação do Nutch contém mais informações sobre como configurar o rastreador para metatags.

O exemplo a seguir mostra a modificação necessária 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>
    

Modificar o arquivo de configuração de gravadores de indexação

Abra conf/index-writers.xml e adicione a seguinte seção:

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

A seção <writer> contém os seguintes parâmetros:

Configuração Parâmetro
Caminho para o arquivo de configuração do Google Cloud Search gcs.config.file = path

Obrigatório. O caminho (absoluto) completo para o arquivo de configuração do Google Cloud Search.

Formato de upload gcs.uploadFormat = text

Opcional. O formato que o plug-in do indexador usa para enviar o conteúdo do documento para a API do indexador do Google Cloud Search. Os valores válidos são:

  • raw: o plug-in do indexador envia o conteúdo original e não convertido do documento.
  • text: o plug-in do indexador envia o conteúdo textual extraído. O valor padrão é raw.

Etapa 4: configure o rastreamento da Web

Antes de iniciar um rastreamento da Web, configure-o para que ele inclua apenas as informações que sua organização quer disponibilizar nos resultados de pesquisa. Esta seção inclui informações básicas sobre os seguintes tópicos:

Para informações mais detalhadas sobre como configurar um rastreamento da Web, consulte o tutorial do Nutch (em inglês).

Configurar URLs iniciais

Os URLs iniciais controlam o local em que o rastreador da Web do Apache Nutch começa a rastrear o conteúdo. O rastreador da Web precisa ser capaz de acessar todo o conteúdo que você quer incluir em um determinado rastreamento. Para fazer isso, siga os links de um ou mais dos URLs iniciais. Esses URLs são obrigatórios.

Para configurar os URLs iniciais, siga estas etapas:

  1. Altere o diretório de trabalho para o diretório de instalação nutch:
    $ cd ~/nutch/apache-nutch-X.Y/
  2. Crie um diretório para URLs:
    $ mkdir urls
  3. Crie um arquivo chamado seed.txt e escreva URLs nele (um por linha):
    $ nano urls/seed.txt

Configurar regras de seguir e não seguir

As regras de seguir controlam quais URLs são rastreados e incluídos no índice do Google Cloud Search. Antes de rastrear URLs, o rastreador da Web os verifica quanto às regras de seguir de URL. Apenas os URLs que correspondem a essas regras são rastreados e indexados.

As regras de não seguir impedem que os URLs sejam rastreados e incluídos no índice do Google Cloud Search. Se um URL tiver um padrão de não rastreamento, o rastreador da Web não o rastreará.

Para configurar as regras de seguir e não seguir de URL, siga estas etapas:

  1. Altere o diretório de trabalho para o diretório de instalação nutch:
    $ cd ~/nutch/apache-nutch-X.Y/
  2. Edite conf/regex-urlfilter.txt para alterar as regras de seguir/não seguir:
    $ nano conf/regex-urlfilter.txt
  3. Coloque expressões regex (por exemplo, expressões abertas) com prefixo "+" ou "-" para seguir/não seguir extensões, padrões de URL e assim por diante, conforme mostrado nos exemplos a seguir.

Por exemplo:

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

Editar o script de rastreamento

Se o parâmetro gcs.uploadFormat estiver ausente ou definido como "raw", será necessário adicionar argumentos "-addBinaryContent -base64" para serem transmitidos ao comando nutch index. Esses argumentos enviam ao módulo de indexador do Nutch instruções para incluir o conteúdo binário em Base64 quando invocar o plug-in indexador. Por padrão, o script ./bin/crawl não tem esses argumentos.

Edite o script crawl.sh no apache-nutch-1.15/bin e adicione:

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

Etapa 5: inicie um rastreamento da Web e fazer upload do conteúdo

Depois de instalar e configurar o plug-in indexador, ele poderá ser executado por conta própria no modo local. Use os scripts de ./bin para executar um job de rastreamento ou comandos nutch individuais.

No exemplo a seguir, presume-se que os componentes necessários estão localizados no diretório local de um sistema Linux. Execute o nutch com o seguinte comando da pasta apache-nutch-1.15:

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

Os registros de rastreamento estão disponíveis na saída padrão (terminal) ou no diretório logs/. Para direcionar a saída de geração de registros ou para ver um registro mais detalhado, edite conf/log4j.properties.