Filas de indexação do Google Cloud Search

Com o SDK do Connector e a API Google Cloud Search, é possível criar filas de indexação do Cloud Search, que são usadas para realizar as seguintes tarefas:

• Manter o estado por documento (status, valores de hash etc.), que pode ser usado para manter o índice em sincronia com o repositório.

• Manter uma lista de itens a serem indexados conforme detectados durante o processo de travessia.

• Priorizar os itens nas filas com base no status deles.

• Manter informações extras sobre o estado para uma integração eficiente, como checkpoints, tokens de alteração etc.

Uma fila é um rótulo atribuído a um item indexado, como "padrão" para a fila padrão ou "B" para a fila B.

Status e prioridade

A prioridade de um documento na fila é baseada no código ItemStatus. Confira a seguir os possíveis códigos ItemStatus em ordem de prioridade, dos primeiros aos últimos a serem processados:

• ERROR: item que encontrou um erro assíncrono durante o processo de indexação e precisa ser indexado novamente.

• MODIFIED: item que foi indexado anteriormente e foi modificado no repositório desde a última indexação.

• NEW_ITEM: item que ainda não foi indexado.

• ACCEPTED: documento que foi indexado anteriormente e não foi alterado no repositório desde a última indexação.

Quando dois itens em uma fila têm o mesmo status, a prioridade mais alta é dada aos itens que estão na fila há mais tempo.

Visão geral do uso de filas de indexação para indexar um item novo ou alterado

A Figura 1 mostra as etapas para indexar um item novo ou alterado usando uma fila de indexação. Estas etapas mostram chamadas da API REST. Para chamadas de SDK equivalentes, consulte Operações de fila (SDK do Connector).

Figura 1. Etapas de indexação para adicionar ou atualizar um item

1. O conector de conteúdo usa items.push para enviar itens (metadados e hash) para uma fila de indexação a fim de estabelecer o status do item (MODIFIED, NEW_ITEM, DELETED). Especificamente:

   • Ao enviar, o conector inclui explicitamente um push type ou contentHash.
   • Se o conector não incluir o type, o Cloud Search usará automaticamente o contentHash para determinar o status do item.
   • Se o item for desconhecido, o status será definido como NEW_ITEM.
   • Se o item existir e os valores de hash corresponderem, o status será mantido como ACCEPTED.
   • Se o item existir e os hashes forem diferentes, o status será MODIFIED.

   Para mais informações sobre como o status do item é estabelecido, consulte o exemplo de código Como registrar os repositórios do GitHub no tutorial de primeiros passos do Cloud Search.

   Geralmente, o push está associado a processos de detecção de mudanças e/ou de passagem de conteúdo no conector.

2. O conector de conteúdo usa items.poll para consultar a fila e determinar os itens a serem indexados. O Cloud Search informa ao conector quais itens mais precisam de indexação, classificados primeiro por código de status e depois por tempo na fila.

3. O conector recupera esses itens do repositório e cria solicitações de API de índice.

4. O conector usa items.index para indexar os itens. O item só entra no estado ACCEPTED depois que o Cloud Search conclui o processamento do item.

Um conector também pode excluir um item se ele não existir mais no repositório ou enviar um item novamente se ele não tiver sido modificado ou se houver um erro no repositório de origem. Para mais informações sobre exclusões de itens, consulte a próxima seção.

Observação: algumas estratégias de travessia, como a travessia completa, usam mais de uma fila de indexação. Para conferir um exemplo de como duas filas podem ser usadas, consulte a próxima seção.

Visão geral do uso de filas de indexação para excluir um item

A estratégia de travessia completa usa um processo de duas filas para indexar itens e detectar exclusões. A Figura 2 mostra as etapas para excluir um item usando duas filas de indexação. Especificamente, a Figura 2 mostra a segunda travessia realizada com uma estratégia de travessia completa. Estas etapas usam as chamadas da API REST. Para chamadas equivalentes do SDK, consulte Operações de fila (SDK do conector).

Figura 2. Excluir itens

Observação: na lista de etapas a seguir, as etapas de 1 a 4 não são mostradas na Figura 2 porque são iguais às do diagrama anterior e não estão no escopo desta seção. A etapa 5 não é mostrada porque chamar deleteQueueItems em uma fila vazia não está no escopo desta seção. Este diagrama se concentra na segunda travessia.

1. Na travessia inicial, o conector de conteúdo usa items.push para enviar itens (metadados e hash) para uma fila de indexação, "fila A" como NEW_ITEM, porque não existe na fila. Cada item recebe o rótulo "A" para "fila A". O conteúdo é indexado no Cloud Search.

   Observação: o conector pode atribuir um rótulo de fila, usando o campo queue do item, a um item durante uma operação item.push ou item.index. Esse rótulo pode ser modificado sempre que o item for enviado novamente ou reindexado.

2. O conector de conteúdo usa items.poll para consultar a fila A e determinar os itens a serem indexados. O Cloud Search informa ao conector quais itens mais precisam de indexação, classificados primeiro por código de status e depois por tempo na fila.

3. O conector recupera esses itens do repositório e cria solicitações de API de índice.

4. O conector usa items.index para indexar os itens. O item só entra no estado ACCEPTED depois que o Cloud Search conclui o processamento do item.

5. O método deleteQueueItems é chamado na "fila B". No entanto, nenhum item foi enviado para a fila B, então nada pode ser excluído.

6. Na segunda travessia completa, o conector de conteúdo usa items.push para enviar itens (metadados e hash) para a fila B:

   • Ao enviar, o conector inclui explicitamente um push type ou contentHash.
   • Se o conector não incluir o type, o Cloud Search usará automaticamente o contentHash para determinar o status do item.
   • Se o item for desconhecido, o status dele será definido como NEW_ITEM e o rótulo da fila será alterado para "B".
   • Se o item existir e os valores de hash corresponderem, o status será mantido como ACCEPTED e o rótulo da fila será alterado para "B".
   • Se o item existir e os hashes forem diferentes, o status vai se tornar MODIFIED, e o rótulo da fila será alterado para "B".

7. O conector de conteúdo usa items.poll para consultar a fila e determinar os itens a serem indexados. O Cloud Search informa ao conector quais itens mais precisam de indexação, classificados primeiro por código de status e depois por tempo na fila.

8. O conector recupera esses itens do repositório e cria solicitações de API de índice.

9. O conector usa items.index para indexar os itens. O item só entra no estado ACCEPTED depois que o Cloud Search termina o processamento.

10. Por fim, deleteQueueItems é chamado na fila A para excluir todos os itens indexados anteriormente da CCloud Search que ainda têm um rótulo "A".

11. Com as transições completas subsequentes, a fila usada para indexação e a fila usada para exclusão são trocadas.

Operações de fila (SDK do Connector)

O SDK do conector de conteúdo fornece as operações para enviar itens para um fila, bem como extraí-los dela.

Para empacotar e enviar um item para uma fila, use a classe Builder pushItems.

Não é necessário realizar qualquer ação específica para extrair itens de uma fila para processamento. Em vez disso, o SDK extrai automaticamente os itens da fila, na ordem de prioridade, usando o método getDoc da classe Repository.

Operações de fila (API REST)

A API REST fornece os dois métodos a seguir para enviar itens para uma fila e extraí-los dela.

• Para enviar um item para uma fila, use Items.push.
• Para pesquisar itens na fila, use Items.poll.

Também é possível usar Items.index para enviar itens para a fila durante a indexação. Os itens enviados para a fila durante a indexação não exigem um type e recebem automaticamente um status de ACCEPTED.

Items.push

O método Items.push adiciona IDs à fila. Esse método pode ser chamado com um valor type específico que determina o resultado da operação de envio. Para uma lista de valores type, consulte o campo item.type no método Items.push.

Enviar um ID novo resulta na inclusão de uma nova entrada com um código NEW_ITEM ItemStatus.

O payload opcional sempre é armazenado, tratado como um valor opaco e retornado de Items.poll.

Quando um item é pesquisado, ele é reservado. Isso significa que ele não pode ser retornado por outra chamada para Items.poll. Usando Items.push com type como NOT_MODIFIED, REPOSITORY_ERROR ou REQUEUE, não reserva entradas pesquisadas. Para mais informações sobre entradas reservadas ou não, consulte a seção Items.poll.

Items.push com hashes

A API Google Cloud Search é compatível com a especificação de valores de hash de metadados e conteúdo em solicitações Items.index. Em vez de especificar type, especifique os valores de hash de metadados e/ou conteúdo com uma solicitação de envio. A fila de indexação do Cloud Search compara os valores de hash fornecidos com os valores armazenados disponíveis com o item na origem de dados. Se não houver correspondência, a entrada será marcada como MODIFIED. Se um item correspondente não existir no índice, o status será NEW_ITEM.

Observação: os valores de hash fornecidos com solicitações Items.push não são salvos com o item. Esses valores são usados apenas para determinar se o item foi modificado.

Items.poll

O método Items.poll recupera as entradas de prioridade mais alta da fila. Os valores de status solicitados e retornados indicam os status das filas de prioridade solicitadas ou os status dos IDs retornados.

Por padrão, podem ser retornadas entradas de qualquer seção da fila, com base na prioridade. Cada entrada retornada é reservada e não é retornada por outras chamadas para Items.poll até que um dos seguintes casos ocorra:

• A reserva expire.
• A entrada seja enfileirada novamente por Items.index.
• Items.push é chamado com um valor type de NOT_MODIFIED, REPOSITORY_ERROR ou REQUEUE.