Очереди индексирования Google Cloud Search

Connector SDK и API Google Cloud Search позволяют создавать очереди индексации Cloud Search, используемые для выполнения следующих задач:

  • Сохраняйте состояние каждого документа (статус, хэш-значения и т. д.), которое можно использовать для синхронизации индекса с вашим репозиторием.

  • Ведите список элементов, которые необходимо индексировать по мере их обнаружения в процессе обхода.

  • Распределите приоритеты элементов в очередях на основе их статуса.

  • Поддерживайте дополнительную информацию о состоянии для эффективной интеграции, такую как контрольные точки, токены изменений и т. д.

Очередь — это метка, назначенная индексированному элементу, например «default» для очереди по умолчанию или «B» для очереди B.

Статус и приоритет

Приоритет документа в очереди определяется его кодом ItemStatus . Ниже приведены возможные коды ItemStatus в порядке приоритета (от первого к последнему):

  • ERROR - В процессе индексации элемента произошла асинхронная ошибка, его необходимо переиндексировать.

  • MODIFIED - Элемент, который был ранее проиндексирован и с тех пор был изменен в репозитории с момента последней индексации.

  • NEW_ITEM — элемент, который не индексирован.

  • ACCEPTED - Документ, который был ранее проиндексирован и не изменялся в репозитории с момента последней индексации.

Если два элемента в очереди имеют одинаковый статус, более высокий приоритет отдается элементам, которые находятся в очереди дольше всего.

Обзор использования очередей индексации для индексации нового или измененного элемента

На рисунке 1 показаны этапы индексации нового или изменённого элемента с использованием очереди индексации. Эти этапы демонстрируют вызовы REST API. Аналогичные вызовы SDK см. в разделе «Операции с очередями» (Connector SDK) .

Обзор индексации Google Cloud Search
Рисунок 1. Шаги индексации для добавления или обновления элемента

  1. Коннектор контента использует items.push для помещения элементов (метаданные и хэш) в очередь индексации для определения их статуса ( MODIFIED , NEW_ITEM , DELETED ). В частности:

    • При отправке соединитель явно включает type отправки или contentHash .
    • Если соединитель не включает type , то Cloud Search автоматически использует contentHash для определения статуса элемента.
    • Если элемент неизвестен, статус элемента устанавливается на NEW_ITEM .
    • Если элемент существует и значения хеша совпадают, статус сохраняется как ACCEPTED .
    • Если элемент существует и хеши различаются, статус становится MODIFIED .

    Дополнительную информацию об определении статуса элемента см. в примере кода «Обход репозиториев GitHub» в руководстве по началу работы с Cloud Search .

    Обычно push-уведомление связано с процессами обхода контента и/или обнаружения изменений в коннекторе.

  2. Коннектор контента использует items.poll для опроса очереди и определения элементов для индексации. Cloud Search сообщает коннектору, какие элементы больше всего нуждаются в индексации, сортируя их сначала по коду статуса, а затем по времени нахождения в очереди.

  3. Коннектор извлекает эти элементы из репозитория и формирует запросы API индекса.

  4. Коннектор использует items.index для индексации элементов. Элемент переходит в состояние ACCEPTED только после того, как Cloud Search успешно завершит его обработку.

Коннектор также может удалить элемент, если его больше нет в репозитории, или повторно отправить элемент, если он не был изменён или возникла ошибка в исходном репозитории. Информация об удалении элементов приведена в следующем разделе.

Обзор использования очередей индексации для удаления элемента

Стратегия полного обхода использует двухочередной процесс для индексации элементов и обнаружения удалений. На рисунке 2 показаны шаги удаления элемента с использованием двух очередей индексации. В частности, на рисунке 2 показан второй обход, выполняемый с использованием стратегии полного обхода. Эти шаги используют вызовы REST API. Эквивалентные вызовы SDK см. в разделе «Операции с очередями» (Connector SDK) .

Обзор индексации Google Cloud Search
Рисунок 2. Удаление элементов

  1. При первом обходе коннектор контента использует items.push для помещения элементов (метаданные и хэш) в очередь индексации, «очередь A» с пометкой NEW_ITEM , поскольку элемент отсутствует в очереди. Каждому элементу присваивается метка «A» для «очереди A». Контент индексируется в Cloud Search.

  2. Коннектор контента использует items.poll для опроса очереди A и определения элементов для индексации. Cloud Search сообщает коннектору, какие элементы больше всего нуждаются в индексации, сортируя их сначала по коду статуса, а затем по времени нахождения в очереди.

  3. Коннектор извлекает эти элементы из репозитория и формирует запросы API индекса.

  4. Коннектор использует items.index для индексации элементов. Элемент переходит в состояние ACCEPTED только после того, как Cloud Search успешно завершит его обработку.

  5. Метод deleteQueueItems вызывается для «очереди B». Однако в очередь B не было помещено ни одного элемента, поэтому удалить ничего нельзя.

  6. При втором полном обходе соединитель контента использует items.push для помещения элементов (метаданные и хэш) в очередь B:

    • При отправке соединитель явно включает type отправки или contentHash .
    • Если соединитель не включает type , то Cloud Search автоматически использует contentHash для определения статуса элемента.
    • Если элемент неизвестен, статус элемента устанавливается на NEW_ITEM , а метка очереди меняется на «B».
    • Если элемент существует и значения хеша совпадают, статус сохраняется как ACCEPTED , а метка очереди изменяется на «B».
    • Если элемент существует и хеши различаются, статус становится MODIFIED , а метка очереди меняется на «B».

  7. Коннектор контента использует items.poll для опроса очереди и определения элементов для индексации. Cloud Search сообщает коннектору, какие элементы больше всего нуждаются в индексации, сортируя их сначала по коду статуса, а затем по времени нахождения в очереди.

  8. Коннектор извлекает эти элементы из репозитория и формирует запросы API индекса.

  9. Коннектор использует items.index для индексации элементов. Элемент переходит в состояние ACCEPTED только после того, как Cloud Search успешно завершит его обработку.

  10. Наконец, deleteQueueItems вызывается для очереди A, чтобы удалить все ранее проиндексированные элементы CCloud Search, которые все еще имеют метку очереди «A».

  11. При последующих полных обходах очередь, используемая для индексации, и очередь, используемая для удаления, меняются местами.

Операции с очередями (Connector SDK)

Content Connector SDK предоставляет операции по добавлению элементов в очередь и извлечению элементов из нее.

Чтобы упаковать и поместить элемент в очередь, используйте класс-конструктор pushItems .

Вам не нужно выполнять никаких специальных действий, чтобы извлечь элементы из очереди для обработки. Вместо этого SDK автоматически извлекает элементы из очереди в порядке приоритета, используя метод getDoc класса Repository .

Операции с очередями (REST API)

REST API предоставляет следующие два метода для помещения элементов в очередь и извлечения элементов из очереди:

  • Чтобы поместить элемент в очередь, используйте Items.push .
  • Для опроса элементов в очереди используйте Items.poll .

Вы также можете использовать Items.index для добавления элементов в очередь во время индексации. Элементам, помещенным в очередь во время индексации, не требуется type , и им автоматически присваивается статус ACCEPTED .

Items.push

Метод Items.push добавляет идентификаторы в очередь. Этот метод можно вызвать с определённым значением type , определяющим результат операции push. Список значений type см. в поле item.type метода Items.push .

Ввод нового идентификатора приводит к добавлению новой записи с кодом NEW_ITEM ItemStatus .

Необязательная полезная нагрузка всегда сохраняется, рассматривается как непрозрачное значение и возвращается из Items.poll .

При опросе элемент зарезервирован , то есть его нельзя вернуть другим вызовом Items.poll . Использование Items.push с type NOT_MODIFIED , REPOSITORY_ERROR или REQUEUE снимает резервирование опрашиваемых записей. Подробнее о зарезервированных и незарезервированных записях см. в разделе Items.poll .

Items.push с хэшами

API Google Cloud Search поддерживает указание метаданных и хеш-значений контента в запросах Items.index . Вместо указания type метаданные и/или хеш-значения контента можно указать в push-запросе. Очередь индексирования Cloud Search сравнивает предоставленные хеш-значения с сохранёнными значениями, доступными для элемента в источнике данных. В случае несоответствия запись помечается как MODIFIED . Если соответствующий элемент отсутствует в индексе, статус — NEW_ITEM .

Items.poll

Метод Items.poll извлекает записи с наивысшим приоритетом из очереди. Запрошенные и возвращенные значения статуса указывают статус(ы) запрошенной(ых) приоритетной(ых) очереди(ей) или статус возвращенных идентификаторов.

По умолчанию записи из любого раздела очереди могут быть возвращены в зависимости от приоритета. Каждая возвращаемая запись зарезервирована и не возвращается другими вызовами Items.poll , пока не наступит одно из следующих событий:

  • Срок действия бронирования истек.
  • Запись снова ставится в очередь с помощью Items.index .
  • Items.push вызывается со значением type NOT_MODIFIED , REPOSITORY_ERROR или REQUEUE .