Criar um conector de conteúdo

Um conector de conteúdo é um programa de software que transfere dados em um repositório corporativo e preenche uma fonte de dados. O Google oferece as seguintes opções para desenvolver conectores de conteúdo:

Um conector de conteúdo típico desempenha as seguintes tarefas:

  1. Leitura e processamento de parâmetros de configuração.
  2. Extração de blocos distintos de dados indexáveis, chamados de itens, do repositório de terceiros.
  3. Combinação de listas de controle de acesso (ACLs, na sigla em inglês), metadados e dados de conteúdo em itens indexáveis.
  4. Indexação de itens com a origem de dados do Cloud Search.
  5. (Opcional) Escuta de notificações sobre alterações do repositório. As notificações de mudança são convertidas em solicitações de indexação para manter a fonte de dados do Cloud Search em sincronia. O conector só realiza essa tarefa se o repositório for compatível com a detecção de mudanças.

Criar um conector de conteúdo usando o SDK do Content Connector

Nas seções a seguir, você verá explicações sobre como criar um conector de conteúdo usando o SDK do Content Connector.

Configurar dependências

Inclua essas dependências no arquivo de build.

Maven

xml <dependency> <groupId>com.google.enterprise.cloudsearch</groupId> <artifactId>google-cloudsearch-indexing-connector-sdk</artifactId> <version>v1-0.0.3</version> </dependency>

Gradle

groovy compile group: 'com.google.enterprise.cloudsearch', name: 'google-cloudsearch-indexing-connector-sdk', version: 'v1-0.0.3'

Criar a configuração do conector

Cada conector usa um arquivo de configuração para parâmetros como o ID do repositório. Defina parâmetros como pares de chave-valor, como api.sourceId=1234567890abcdef.

O SDK do Google Cloud Search inclui parâmetros fornecidos pelo Google para todos os conectores. É necessário declarar o seguinte no arquivo de configuração:

  • Conector de conteúdo: declare api.sourceId e api.serviceAccountPrivateKeyFile. Eles identificam seu repositório e a chave privada necessária para acesso.
  • Conector de identidade: declare api.identitySourceId para identificar sua origem de identidade externa. Para a sincronização de usuários, declare também api.customerId (o ID exclusivo da sua conta do Google Workspace).

Declare outros parâmetros fornecidos pelo Google apenas para substituir os valores padrão. Para detalhes sobre como gerar IDs e chaves, consulte Parâmetros fornecidos pelo Google.

Também é possível definir parâmetros específicos do repositório no arquivo de configuração.

Transmitir o arquivo de configuração para o conector

Defina a propriedade do sistema config para transmitir o arquivo de configuração. Use o argumento -D ao iniciar o conector. Exemplo:

java -classpath myconnector.jar -Dconfig=MyConfig.properties MyConnector

Se você omitir esse argumento, o SDK tentará usar um arquivo chamado connector-config.properties no diretório local.

Determinar a estratégia de travessia

A principal função do conector de conteúdo é percorrer um repositório e indexar os dados nele. Implemente uma estratégia com base no tamanho e no layout do seu repositório. Crie sua própria estratégia ou escolha uma do SDK:

Estratégia de travessia completa
Verifica o repositório inteiro e indexa cada item. Essa estratégia é melhor para repositórios pequenos em que é possível arcar com a sobrecarga de uma travessia completa durante cada indexação. Use-a para repositórios pequenos com dados em sua maioria estáticos e não hierárquicos ou quando a detecção de alterações é difícil.
Estratégia de travessia de listas
Verifica o repositório inteiro para determinar o status de cada item e indexa apenas os itens novos ou atualizados. Use isso para atualizações incrementais em um índice grande e não hierárquico quando a detecção de mudanças não é compatível.
Travessia de gráficos
Verifica um nó pai para determinar o status dos itens e indexa os itens novos ou atualizados nesse nó. Em seguida, ele processa recursivamente os nós filhos. Use isso para repositórios hierárquicos em que não é prático listar todos os IDs, como estruturas de diretórios ou sites.

O SDK implementa essas estratégias em classes de conector modelo. Esses modelos podem acelerar seu desenvolvimento. Para usar um modelo, consulte a seção correspondente:

Criar um conector de travessia completa usando uma classe de modelo

Esta seção se refere ao código do FullTraversalSample.

Implementar o ponto de entrada do conector

O ponto de entrada é o método main(). Ele cria uma instância Application e chama start() para executar o conector.

Antes de chamar application.start(), use a classe IndexingApplication.Builder para instanciar o modelo FullTraversalConnector. Esse modelo aceita um objeto Repository.

FullTraversalSample.java
/**
 * This sample connector uses the Cloud Search SDK template class for a full
 * traversal connector.
 *
 * @param args program command line arguments
 * @throws InterruptedException thrown if an abort is issued during initialization
 */
public static void main(String[] args) throws InterruptedException {
  Repository repository = new SampleRepository();
  IndexingConnector connector = new FullTraversalConnector(repository);
  IndexingApplication application = new IndexingApplication.Builder(connector, args).build();
  application.start();
}

O SDK chama initConfig() depois que o método main() chama Application.build(). O método initConfig():

  1. Garante que o Configuration ainda não foi inicializado.
  2. Inicializa o objeto Configuration com pares de chave-valor fornecidos pelo Google.

Implementar a interface do repositório

O objeto Repository percorre e indexa itens do repositório. Ao usar um modelo, você só precisa modificar determinados métodos na interface Repository. Para FullTraversalConnector, substitua:

  • init(): para configuração e inicialização do repositório.
  • getAllDocs(): para percorrer e indexar todos os itens. Isso é chamado uma vez para cada travessia programada.
  • (Opcional) getChanges(): se o repositório for compatível com a detecção de mudanças, substitua esse método para recuperar e indexar itens modificados.
  • (Opcional) close(): para limpeza do repositório durante o desligamento.

Cada método retorna um objeto ApiOperation, que realiza a indexação usando IndexingService.indexItem().

Receber parâmetros de configuração personalizados

Para processar a configuração do conector, recupere todos os parâmetros personalizados do objeto Configuration. Realize essa tarefa no método init() da classe Repository.

A classe Configuration inclui métodos para recuperar diferentes tipos de dados. Cada método retorna um objeto ConfigValue. Use o método get() do objeto ConfigValue para extrair o valor. Este snippet de FullTraversalSample mostra como recuperar um valor inteiro personalizado:

FullTraversalSample.java
@Override
public void init(RepositoryContext context) {
  log.info("Initializing repository");
  numberOfDocuments = Configuration.getInteger("sample.documentCount", 10).get();
}

Para extrair e analisar parâmetros com vários valores, use um dos analisadores de tipo da classe Configuration. Este snippet do conector do tutorial usa getMultiValue para recuperar uma lista de nomes de repositório do GitHub:

GithubRepository.java
ConfigValue<List<String>> repos = Configuration.getMultiValue(
    "github.repos",
    Collections.emptyList(),
    Configuration.STRING_PARSER);

Realizar uma travessia completa

Substitua getAllDocs() para realizar uma travessia completa. Esse método aceita um checkpoint para retomar a indexação se ela for interrompida. Para cada item:

  1. Defina as permissões.
  2. Defina os metadados.
  3. Combine-os em um RepositoryDoc.
  4. Empacote cada item no iterador retornado por getAllDocs().

Se o conjunto de itens for muito grande para uma chamada, use um checkpoint e chame hasMore(true).

Definir as permissões para um item

Os repositórios usam listas de controle de acesso (ACLs) para identificar usuários ou grupos com acesso a um item. Uma ACL lista os IDs de usuários ou grupos autorizados.

Para garantir que os usuários vejam apenas os resultados da pesquisa que têm autorização para acessar, é necessário replicar as ACLs do repositório. Inclua a ACL ao indexar um item para que o Google Cloud Search possa fornecer o nível de acesso correto.

O SDK do Content Connector inclui classes e métodos para modelar as ACLs da maioria dos repositórios. Analise as ACLs do seu repositório e crie ACLs correspondentes para o Cloud Search durante a indexação. A modelagem de ACLs complexas, como as que usam herança, exige um planejamento cuidadoso. Para mais informações, consulte ACLs do Cloud Search.

Use a classe Acl.Builder para definir o acesso. Este snippet da amostra de travessia completa permite que todos os usuários do domínio (getCustomerPrincipal()) leiam todos os itens (setReaders()):

FullTraversalSample.java
// Make the document publicly readable within the domain
Acl acl = new Acl.Builder()
    .setReaders(Collections.singletonList(Acl.getCustomerPrincipal()))
    .build();

Para modelar corretamente as ACLs do repositório, principalmente aquelas que usam modelos de herança, é necessário ter as informações em ACLs do Cloud Search.

Definir os metadados de um item

Os metadados são armazenados em um objeto Item. Para criar um Item, é necessário ter um ID, um tipo de item, uma ACL, um URL e uma versão exclusivos. Use a classe auxiliar IndexingItemBuilder.

FullTraversalSample.java
// Url is required. Use google.com as a placeholder for this sample.
String viewUrl = "https://www.google.com";

// Version is required, set to current timestamp.
byte[] version = Longs.toByteArray(System.currentTimeMillis());

// Using the SDK item builder class to create the document with appropriate attributes
// (this can be expanded to include metadata fields etc.)
Item item = IndexingItemBuilder.fromConfiguration(Integer.toString(id))
    .setItemType(IndexingItemBuilder.ItemType.CONTENT_ITEM)
    .setAcl(acl)
    .setSourceRepositoryUrl(IndexingItemBuilder.FieldOrValue.withValue(viewUrl))
    .setVersion(version)
    .build();
Criar o item indexável

Use a classe RepositoryDoc.Builder.

FullTraversalSample.java
// For this sample, content is just plain text
String content = String.format("Hello world from sample doc %d", id);
ByteArrayContent byteContent = ByteArrayContent.fromString("text/plain", content);

// Create the fully formed document
RepositoryDoc doc = new RepositoryDoc.Builder()
    .setItem(item)
    .setContent(byteContent, IndexingService.ContentFormat.TEXT)
    .build();

Um RepositoryDoc é um ApiOperation que executa a solicitação IndexingService.indexItem().

Use o método setRequestMode() da classe RepositoryDoc.Builder para definir a solicitação de indexação como ASYNCHRONOUS ou SYNCHRONOUS:

ASYNCHRONOUS
Esse modo tem uma latência de indexação para exibição maior, mas acomoda uma cota de capacidade maior. Use o modo assíncrono para a indexação inicial (preenchimento) de um repositório inteiro.
SYNCHRONOUS
Esse modo tem uma latência de indexação para exibição menor, mas uma cota de capacidade menor. Use o modo síncrono para indexar atualizações e mudanças no repositório. Se não for especificado, o modo de solicitação será SYNCHRONOUS por padrão.
Empacotar cada item indexável em um iterador

O método getAllDocs() retorna um CheckpointCloseableIterable de objetos RepositoryDoc. Use a classe CheckpointCloseableIterableImpl.Builder.

FullTraversalSample.java
CheckpointCloseableIterable<ApiOperation> iterator =
  new CheckpointCloseableIterableImpl.Builder<>(allDocs).build();

Próximas etapas

Criar um conector de travessia de listas usando uma classe de modelo

A fila de indexação do Cloud Search armazena IDs e hashes opcionais para itens do repositório. Um conector de travessia de listas envia IDs a essa fila e os recupera para indexação. O Cloud Search mantém essas filas para determinar o status dos itens, como exclusões. Consulte A fila de indexação do Cloud Search.

Esta seção se refere ao ListTraversalSample.

Implementar o ponto de entrada do conector

O método main() cria uma instância Application e chama start(). Use IndexingApplication.Builder para instanciar o modelo ListingConnector.

ListTraversalSample.java
/**
 * This sample connector uses the Cloud Search SDK template class for a
 * list traversal connector.
 *
 * @param args program command line arguments
 * @throws InterruptedException thrown if an abort is issued during initialization
 */
public static void main(String[] args) throws InterruptedException {
  Repository repository = new SampleRepository();
  IndexingConnector connector = new ListingConnector(repository);
  IndexingApplication application = new IndexingApplication.Builder(connector, args).build();
  application.start();
}

Implementar a interface do repositório

Substitua os seguintes métodos para ListingConnector:

  • init(): para configuração do repositório.
  • getIds(): para recuperar IDs e hashes de todos os registros.
  • getDoc(): para adicionar, atualizar ou excluir itens do índice.
  • (Opcional) getChanges(): para atualizações incrementais usando detecção de mudanças.
  • (Opcional) close(): para limpeza do repositório.

Realizar a travessia de listas

Substitua getIds() para recuperar IDs e hashes. Substitua getDoc() para processar cada item na fila de indexação do Cloud Search.

Enviar IDs de itens e valores de hash

Substitua getIds() para buscar IDs e hashes de conteúdo. Empacote-os em uma solicitação PushItems para a fila de indexação.

ListTraversalSample.java
PushItems.Builder allIds = new PushItems.Builder();
for (Map.Entry<Integer, Long> entry : this.documents.entrySet()) {
  String documentId = Integer.toString(entry.getKey());
  String hash = this.calculateMetadataHash(entry.getKey());
  PushItem item = new PushItem().setMetadataHash(hash);
  log.info("Pushing " + documentId);
  allIds.addPushItem(documentId, item);
}

Use PushItems.Builder para empacotar os IDs e hashes.

ListTraversalSample.java
ApiOperation pushOperation = allIds.build();
CheckpointCloseableIterable<ApiOperation> iterator =
  new CheckpointCloseableIterableImpl.Builder<>(
      Collections.singletonList(pushOperation))
  .build();
return iterator;
Recuperar e processar os itens

Substitua getDoc() para processar itens na fila de indexação. Os itens podem ser novos, modificados, inalterados ou excluídos.

  1. Verifique se o ID do item existe no repositório. Caso contrário, exclua-o.
  2. Verifique o status do índice. Se não houver mudanças (ACCEPTED), não faça nada.
  3. No caso de índice alterado ou itens novos, defina permissões e metadados, combine em um RepositoryDoc e retorne.
Processar itens excluídos

Este snippet mostra como determinar se um item existe e excluí-lo se não existir.

ListTraversalSample.java
String resourceName = item.getName();
int documentId = Integer.parseInt(resourceName);

if (!documents.containsKey(documentId)) {
  // Document no longer exists -- delete it
  log.info(() -> String.format("Deleting document %s", item.getName()));
  return ApiOperations.deleteItem(resourceName);
}
Processar itens inalterados

Pesquise a fila de indexação para processar itens inalterados.

ListTraversalSample.java
String currentHash = this.calculateMetadataHash(documentId);
if (this.canSkipIndexing(item, currentHash)) {
  // Document neither modified nor deleted, ack the push
  log.info(() -> String.format("Document %s not modified", item.getName()));
  PushItem pushItem = new PushItem().setType("NOT_MODIFIED");
  return new PushItems.Builder().addPushItem(resourceName, pushItem).build();
}

O exemplo usa um hash para detectar mudanças.

ListTraversalSample.java
/**
 * Checks to see if an item is already up to date
 *
 * @param previousItem Polled item
 * @param currentHash  Metadata hash of the current github object
 * @return PushItem operation
 */
private boolean canSkipIndexing(Item previousItem, String currentHash) {
  if (previousItem.getStatus() == null || previousItem.getMetadata() == null) {
    return false;
  }
  String status = previousItem.getStatus().getCode();
  String previousHash = previousItem.getMetadata().getHash();
  return "ACCEPTED".equals(status)
      && previousHash != null
      && previousHash.equals(currentHash);
}
Definir as permissões para um item

Os repositórios usam listas de controle de acesso (ACLs) para identificar usuários ou grupos com acesso a um item. Uma ACL lista os IDs de usuários ou grupos autorizados.

Para garantir que os usuários vejam apenas os resultados da pesquisa que têm autorização para acessar, é necessário replicar as ACLs do repositório. Inclua a ACL ao indexar um item para que o Google Cloud Search possa fornecer o nível de acesso correto.

O SDK do Content Connector inclui classes e métodos para modelar as ACLs da maioria dos repositórios. Analise as ACLs do seu repositório e crie ACLs correspondentes para o Cloud Search durante a indexação. A modelagem de ACLs complexas, como as que usam herança, exige um planejamento cuidadoso. Para mais informações, consulte ACLs do Cloud Search.

Use a classe Acl.Builder para definir o acesso. Este snippet da amostra de travessia completa permite que todos os usuários do domínio (getCustomerPrincipal()) leiam todos os itens (setReaders()):

FullTraversalSample.java
// Make the document publicly readable within the domain
Acl acl = new Acl.Builder()
    .setReaders(Collections.singletonList(Acl.getCustomerPrincipal()))
    .build();

Para modelar corretamente as ACLs do repositório, principalmente aquelas que usam modelos de herança, é necessário ter as informações em ACLs do Cloud Search.

Definir os metadados de um item
ListTraversalSample.java
// Url is required. Use google.com as a placeholder for this sample.
String viewUrl = "https://www.google.com";

// Version is required, set to current timestamp.
byte[] version = Longs.toByteArray(System.currentTimeMillis());

// Set metadata hash so queue can detect changes
String metadataHash = this.calculateMetadataHash(documentId);

// Using the SDK item builder class to create the document with
// appropriate attributes. This can be expanded to include metadata
// fields etc.
Item item = IndexingItemBuilder.fromConfiguration(Integer.toString(documentId))
    .setItemType(IndexingItemBuilder.ItemType.CONTENT_ITEM)
    .setAcl(acl)
    .setSourceRepositoryUrl(IndexingItemBuilder.FieldOrValue.withValue(viewUrl))
    .setVersion(version)
    .setHash(metadataHash)
    .build();
Criar um item indexável
ListTraversalSample.java
// For this sample, content is just plain text
String content = String.format("Hello world from sample doc %d", documentId);
ByteArrayContent byteContent = ByteArrayContent.fromString("text/plain", content);

// Create the fully formed document
RepositoryDoc doc = new RepositoryDoc.Builder()
    .setItem(item)
    .setContent(byteContent, IndexingService.ContentFormat.TEXT)
    .build();

Use o método setRequestMode() da classe RepositoryDoc.Builder para definir a solicitação de indexação como ASYNCHRONOUS ou SYNCHRONOUS:

ASYNCHRONOUS
Esse modo tem uma latência de indexação para exibição maior, mas acomoda uma cota de capacidade maior. Use o modo assíncrono para a indexação inicial (preenchimento) de um repositório inteiro.
SYNCHRONOUS
Esse modo tem uma latência de indexação para exibição menor, mas uma cota de capacidade menor. Use o modo síncrono para indexar atualizações e mudanças no repositório. Se não for especificado, o modo de solicitação será SYNCHRONOUS por padrão.

Próximas etapas

Veja a seguir algumas das próximas etapas:

Criar um conector de travessia de grafos usando uma classe de modelo

A fila de indexação do Cloud Search armazena IDs e valores de hash opcionais para cada item no repositório. Um conector de travessia de grafos envia códigos de itens ao Google Cloud Search Indexing Queue e os recupera, um de cada vez, para realizar a indexação. O Google Cloud Search mantém filas e compara o conteúdo delas para determinar o status dos itens, como por exemplo, se um item foi excluído do repositório. Para mais informações sobre esse recurso, consulte Filas de indexação do Google Cloud Search.

Durante a indexação, o conteúdo do item é buscado no repositório de dados e todos os IDs de itens filhos são enviados para a fila. O conector processa de forma recursiva os IDs pai e filho até que todos os itens sejam tratados.

Implementar o ponto de entrada do conector

O ponto de entrada de um conector é o método main(). Esse método cria uma instância da classe Application e chama o método start() para executar o conector.

Antes de chamar application.start(), use a classe IndexingApplication.Builder para instanciar o modelo ListingConnector. O ListingConnector aceita um objeto Repository cujos métodos você implementa.

Implementar a interface do repositório

Substitua init(), getIds(), getDoc() e, opcionalmente, getChanges() ou close().

Realizar a travessia de gráficos

Substitua getIds() para recuperar os IDs iniciais e getDoc() para processar itens e enviar IDs filhos para a fila.

Enviar IDs de itens e valores de hash
GraphTraversalSample.java
PushItems.Builder allIds = new PushItems.Builder();
PushItem item = new PushItem();
allIds.addPushItem("root", item);
Recuperar e processar os itens
  1. Verifique se o ID existe no repositório. Se não, exclua o item.
  2. Para itens atuais, defina permissões e metadados e combine-os em um RepositoryDoc.
  3. Envie os IDs filhos para a fila de indexação.
  4. Retorne o RepositoryDoc.
Processar itens excluídos
GraphTraversalSample.java
String resourceName = item.getName();
if (documentExists(resourceName)) {
  return buildDocumentAndChildren(resourceName);
}
// Document doesn't exist, delete it
log.info(() -> String.format("Deleting document %s", resourceName));
return ApiOperations.deleteItem(resourceName);
Definir metadados e criar o item
GraphTraversalSample.java
// Url is required. Use google.com as a placeholder for this sample.
String viewUrl = "https://www.google.com";

// Version is required, set to current timestamp.
byte[] version = Longs.toByteArray(System.currentTimeMillis());

// Using the SDK item builder class to create the document with
// appropriate attributes. This can be expanded to include metadata
// fields etc.
Item item = IndexingItemBuilder.fromConfiguration(documentId)
    .setItemType(IndexingItemBuilder.ItemType.CONTENT_ITEM)
    .setAcl(acl)
    .setSourceRepositoryUrl(IndexingItemBuilder.FieldOrValue.withValue(viewUrl))
    .setVersion(version)
    .build();
GraphTraversalSample.java
// For this sample, content is just plain text
String content = String.format("Hello world from sample doc %s", documentId);
ByteArrayContent byteContent = ByteArrayContent.fromString("text/plain", content);

RepositoryDoc.Builder docBuilder = new RepositoryDoc.Builder()
    .setItem(item)
    .setContent(byteContent, IndexingService.ContentFormat.TEXT);
Colocar IDs filhos na fila de indexação
GraphTraversalSample.java
// Queue the child nodes to visit after indexing this document
Set<String> childIds = getChildItemNames(documentId);
for (String id : childIds) {
  log.info(() -> String.format("Pushing child node %s", id));
  PushItem pushItem = new PushItem();
  docBuilder.addChildId(id, pushItem);
}

RepositoryDoc doc = docBuilder.build();

Criar um conector de conteúdo usando a API REST

Nas seções a seguir, você aprenderá como criar um conector de conteúdo usando a API REST.

Determinar a estratégia de travessia

As estratégias (completa, lista e gráfico) são conceitualmente as mesmas do SDK. Implemente a estratégia escolhida usando a API REST.

Implementar a estratégia de travessia e indexar itens

Registre seu esquema e preencha o índice usando:

  1. (Opcional) items.upload para arquivos maiores que 100 KiB.
  2. (Opcional) media.upload para arquivos de mídia.

  3. items.index para indexar o item.

    Exemplo de solicitação de indexação:

    {
  "name": "datasource/<data_source_id>/items/titanic",
  "acl": {
    "readers": [
      {
        "gsuitePrincipal": {
          "gsuiteDomain": true
        }
      }
    ]
  },
  "metadata": {
    "title": "Titanic",
    "viewUrl": "http://www.imdb.com/title/tt2234155/",
    "objectType": "movie"
  },
  "structuredData": {
    "object": {
      "properties": [
        {
          "name": "movieTitle",
          "textValues": { "values": ["Titanic"] }
        }
      ]
    }
  },
  "content": {
    "inlineContent": "A seventeen-year-old aristocrat falls in love...",
    "contentFormat": "TEXT"
  },
  "version": "01",
  "itemType": "CONTENT_ITEM"
}

  4. (Opcional) Use items.get para verificar a indexação.

Processar alterações no repositório

Reindexe periodicamente o repositório inteiro para uma indexação completa. Para travessia de listas ou gráficos, use a fila de indexação do Google Cloud para rastrear mudanças e indexar apenas o que foi alterado. Use items.push para adicionar itens à fila.