Colas de indexación de Google Cloud Search

El SDK de Connector y la API de Google Cloud Search permiten la creación de colas de indexación de Cloud Search que se usan para realizar las siguientes tareas:

• Conservar el estado por documento (estado, valores de hash, etc.) que se pueden usar para mantener el índice sincronizado con tu repositorio

• Conservar una lista de elementos para indexar descubiertos durante el proceso transversal

• Priorizar los elementos en colas según el estado del elemento

• Conservar información de estado adicional para una integración eficiente, como puntos de control, tokens de cambio, etcétera

Una cola es una etiqueta asignada a un elemento indexado, como "predeterminada" para la cola predeterminada o "B" para la cola B.

Estado y prioridad

La prioridad de un documento en una cola se basa en su código de ItemStatus. A continuación, se muestran los códigos de ItemStatus posibles en orden de prioridad (cuáles deben manejarse primero):

• ERROR: un elemento que encontró un error asíncrono durante el proceso de indexación y debe volver a indexarse.

• MODIFIED: un elemento que ya fue indexado y se modificó en el repositorio tras la última indexación.

• NEW_ITEM: Es el elemento que no está indexado.

• ACCEPTED: Documento que ya se indexó y no se modificó en el repositorio desde la última indexación.

Cuando dos elementos en una cola tienen el mismo estado, se otorga mayor prioridad a los elementos que han estado en la cola durante un período más largo.

Descripción general del uso de las colas de indexación para indexar un elemento nuevo o modificado

En la figura 1, se muestran los pasos para indexar un elemento nuevo o modificado con una cola de indexación. En estos pasos, se muestran llamadas a la API de REST. Para ver las llamadas equivalentes al SDK, consulta Operaciones de cola (SDK de conector).

Figura 1: Pasos de indexación para agregar o actualizar un elemento

1. El conector de contenido usa items.push para enviar elementos (metadatos y hash) a una cola de indexación y establecer el estado del elemento (MODIFIED, NEW_ITEM, DELETED). Específicamente:

   • Cuando se realiza una inserción, el conector incluye de forma explícita un type o contentHash de inserción.
   • Si el conector no incluye el type, Cloud Search usa automáticamente el contentHash para determinar el estado del elemento.
   • Si el elemento es desconocido, el estado se establece en NEW_ITEM.
   • Si el elemento existe y los valores de hash coinciden, el estado se mantiene como ACCEPTED.
   • Si el elemento existe y los hashes difieren, el estado cambia a MODIFIED.

   Para obtener más información sobre cómo se establece el estado del elemento, consulta el código de ejemplo Cómo recorrer los repositorios de GitHub en el instructivo de introducción a Cloud Search.

   Por lo general, la inserción se asocia con procesos de detección de cambios o de recorrido de contenido en el conector.

2. El conector de contenido usa items.poll para sondear la cola y determinar los elementos que se deben indexar. Cloud Search le indica al conector qué elementos necesitan más indexación, ordenados primero por código de estado y, luego, por tiempo en la cola.

3. El conector recupera estos elementos del repositorio y compila solicitudes a la API de Index.

4. El conector usa items.index para indexar los elementos. El elemento solo ingresa al estado ACCEPTED después de que Cloud Search finaliza correctamente el procesamiento del elemento.

Un conector también puede borrar un elemento si ya no existe en el repositorio o volver a enviar un elemento si no se modificó o si hay un error en el repositorio de origen. Para obtener información sobre las eliminaciones de elementos, consulta la siguiente sección.

Nota: Algunas estrategias de recorrido, como el recorrido completo, usan más de una cola de indexación. Para ver un ejemplo de cómo se podrían usar dos colas, consulta la siguiente sección.

Descripción general del uso de las colas de indexación para borrar un elemento

La estrategia de recorrido completo usa un proceso de dos colas para indexar elementos y detectar eliminaciones. En la figura 2, se muestran los pasos para borrar un elemento con dos colas de indexación. Específicamente, en la Figura 2, se muestra el segundo recorrido realizado con una estrategia de recorrido completo. En estos pasos, se usan las llamadas a la API de REST. Para ver las llamadas al SDK equivalentes, consulta Operaciones de cola (SDK de conector).

Figura 2: Cómo borrar elementos

Nota: En la siguiente lista de pasos, los pasos del 1 al 4 no se muestran en la figura 2, ya que son los mismos que los pasos del 1 al 4 del diagrama anterior y no se incluyen en el alcance de esta sección. No se muestra el paso 5 porque llamar a deleteQueueItems en una cola vacía no está dentro del alcance de esta sección. Este diagrama se centra en el segundo recorrido.

1. En el recorrido inicial, el conector de contenido usa items.push para enviar elementos (metadatos y hash) a una cola de indexación, "cola A", como NEW_ITEM, ya que no existe en la cola. A cada elemento se le asigna la etiqueta "A" para la "fila A". El contenido se indexa en Cloud Search.

   Nota: El conector puede asignar una etiqueta de cola, usando el campo queue del elemento, a un elemento durante una operación item.push o item.index. Esta etiqueta se puede modificar cada vez que se vuelve a enviar o indexar el elemento.

2. El conector de contenido usa items.poll para sondear la cola A y determinar los elementos que se deben indexar. Cloud Search le indica al conector qué elementos necesitan más indexación, ordenados primero por código de estado y, luego, por tiempo en la cola.

3. El conector recupera estos elementos del repositorio y compila solicitudes a la API de Index.

4. El conector usa items.index para indexar los elementos. El elemento solo ingresa al estado ACCEPTED después de que Cloud Search finaliza correctamente el procesamiento del elemento.

5. Se llama al método deleteQueueItems en la "fila B". Sin embargo, no se envió ningún elemento a la cola B, por lo que no se puede borrar nada.

6. En el segundo recorrido completo, el conector de contenido usa items.push para enviar elementos (metadatos y hash) a la cola B:

   • Cuando se realiza una inserción, el conector incluye de forma explícita un type o contentHash de inserción.
   • Si el conector no incluye el type, Cloud Search usa automáticamente el contentHash para determinar el estado del elemento.
   • Si el elemento es desconocido, el estado se establece en NEW_ITEM y la etiqueta de la fila cambia a "B".
   • Si el elemento existe y los valores de hash coinciden, el estado se mantiene como ACCEPTED y la etiqueta de la cola cambia a "B".
   • Si el elemento existe y los hashes son diferentes, el estado cambia a MODIFIED y la etiqueta de la fila cambia a "B".

7. El conector de contenido usa items.poll para sondear la cola y determinar los elementos que se deben indexar. Cloud Search le indica al conector qué elementos necesitan más indexación, ordenados primero por código de estado y, luego, por tiempo en la cola.

8. El conector recupera estos elementos del repositorio y compila solicitudes a la API de Index.

9. El conector usa items.index para indexar los elementos. El elemento solo ingresa al estado ACCEPTED después de que Cloud Search finaliza correctamente el procesamiento del elemento.

10. Por último, se llama a deleteQueueItems en la cola A para borrar todos los elementos de CCloud Search indexados previamente que aún tienen una etiqueta de cola "A".

11. En los recorridos completos posteriores, se intercambian la cola que se usa para la indexación y la que se usa para el borrado.

Operaciones de cola (SDK de conector)

El SDK de Content Connector proporciona operaciones para enviar elementos a una cola y extraerlos de ella.

Para agrupar y enviar un elemento a una cola, usa la clase de compilador pushItems.

No necesitas hacer nada específico si quieres extraer elementos de una cola para procesarlos. En su lugar, el SDK extrae automáticamente elementos de la cola, en orden de prioridad, con el método getDoc de la clase Repository.

Operaciones de cola (API de REST)

La API de REST proporciona los dos métodos siguientes para enviar elementos a una cola y extraerlos de ella:

• Para enviar un elemento a una cola, usa Items.push.
• Para consultar elementos en la cola, usa Items.poll.

También puedes usar Items.index para enviar elementos a la cola durante la indexación. Los elementos que se envían a la cola durante la indexación no requieren un type y se les asigna automáticamente el estado ACCEPTED.

Items.push

El método Items.push agrega varios IDs a la cola. Se puede llamar a este método con un valor de type específico que determina el resultado de la operación de envío. Para obtener una lista de los valores de type, consulta el campo item.type en el método Items.push.

Cuando se envía un ID nuevo, se agrega una entrada nueva con un código NEW_ITEM ItemStatus.

La carga útil opcional siempre se almacena, se trata como un valor opaco y se devuelve desde Items.poll.

Cuando se consulta un elemento, se lo reserva, lo que significa que no se puede mostrar con otra llamada a Items.poll. Usar Items.push con type como NOT_MODIFIED, REPOSITORY_ERROR o REQUEUE cancela la reserva de las entradas consultadas. Para obtener más información sobre las entradas reservadas y no reservadas, consulta la sección Items.poll.

Items.push con hashes

La API de Google Cloud Search admite la especificación de metadatos y valores de hash de contenido en las solicitudes de Items.index. En lugar de especificar type, los metadatos o los valores de hash de contenido se pueden especificar con una solicitud de envío. La cola de indexación de Cloud Search compara los valores de hash proporcionados con los valores almacenados disponibles y con el elemento en la fuente de datos. Si no coinciden, esa entrada se marca como MODIFIED. Si no existe un elemento correspondiente en el índice, el estado es NEW_ITEM.

Nota: Los valores de hash proporcionados con las solicitudes de Items.push no se guardan con el elemento. Estos elementos solo se usan para determinar si el elemento se modificó.

Items.poll

El método Items.poll recupera los datos de entrada de más alta prioridad de la cola. Los valores de estado solicitados y devueltos indican los estados de las colas de prioridad solicitadas o el estado de los IDs devueltos.

De forma predeterminada, los datos de entradas de una sección de la cola se pueden mostrar, según la prioridad. Cada entrada que se muestra se reserva, y otras llamadas a Items.poll no la muestran hasta que se cumpla una de las siguientes condiciones:

• Que se agote el tiempo de la reserva.
• Que Items.index vuelva a colocar la entrada en la cola.
• Items.push se llama con un valor de type de NOT_MODIFIED, REPOSITORY_ERROR o REQUEUE.