Коннектор контента — это программа, используемая для перемещения данных в корпоративном репозитории и заполнения источника данных. Google предоставляет следующие возможности для разработки коннекторов контента:
SDK Content Connector. Это хороший вариант, если вы программируете на Java. Content Connector SDK — это оболочка REST API, позволяющая быстро создавать соединители. Чтобы создать соединитель контента с помощью SDK, см. раздел Создание соединителя контента с помощью SDK Content Connector .
Низкоуровневый REST API или библиотеки API. Используйте эти параметры, если вы не программируете на Java или если ваша кодовая база лучше подходит для REST API или библиотеки. Чтобы создать соединитель контента с помощью REST API, см. раздел Создание соединителя контента с помощью REST API .
Типичный соединитель контента выполняет следующие задачи:
- Считывает и обрабатывает параметры конфигурации.
- Извлекает отдельные фрагменты индексируемых данных, называемые « элементами », из стороннего репозитория контента.
- Объединяет списки управления доступом, метаданные и данные контента в индексируемые элементы.
- Индексирует элементы в источник данных Cloud Search.
- (необязательно) Прослушивает уведомления об изменениях из стороннего репозитория контента. Уведомления об изменениях преобразуются в запросы на индексирование, чтобы обеспечить синхронизацию источника данных Cloud Search со сторонним репозиторием. Соединитель выполняет эту задачу только в том случае, если репозиторий поддерживает обнаружение изменений.
Создайте соединитель контента с помощью Content Connector SDK.
В следующих разделах объясняется, как создать соединитель контента с помощью Content Connector SDK.
Настройка зависимостей
Чтобы использовать SDK, вы должны включить определенные зависимости в файл сборки. Нажмите на вкладку ниже, чтобы просмотреть зависимости для вашей среды сборки:
Мавен
<dependency>
<groupId>com.google.enterprise.cloudsearch</groupId>
<artifactId>google-cloudsearch-indexing-connector-sdk</artifactId>
<version>v1-0.0.3</version>
</dependency>
Градл
compile group: 'com.google.enterprise.cloudsearch',
name: 'google-cloudsearch-indexing-connector-sdk',
version: 'v1-0.0.3'
Создайте конфигурацию соединителя
У каждого соединителя есть файл конфигурации, содержащий параметры, используемые соединителем, например идентификатор вашего репозитория. Параметры определяются как пары ключ-значение , например api.sourceId= 1234567890abcdef
.
SDK Google Cloud Search содержит несколько предоставленных Google параметров конфигурации, используемых всеми соединителями. Вы должны объявить следующие параметры, предоставленные Google, в вашем файле конфигурации:
- Для соединителя контента необходимо объявить
api.sourceId
иapi.serviceAccountPrivateKeyFile
поскольку эти параметры определяют расположение вашего репозитория и закрытый ключ, необходимый для доступа к репозиторию.
- Для соединителя удостоверений необходимо объявить
api.identitySourceId
поскольку этот параметр определяет расположение вашего внешнего источника удостоверений. Если вы синхронизируете пользователей, вы также должны объявитьapi.customerId
в качестве уникального идентификатора учетной записи Google Workspace вашего предприятия.
Если вы не хотите переопределить значения по умолчанию для других параметров, предоставленных Google, вам не нужно объявлять их в файле конфигурации. Дополнительную информацию о параметрах конфигурации, предоставляемых Google, например о том, как генерировать определенные идентификаторы и ключи, см. в разделе Параметры конфигурации, предоставляемые Google .
Вы также можете определить свои собственные параметры, специфичные для репозитория, для использования в файле конфигурации.
Передайте файл конфигурации в коннектор
Настройте системное свойство config
для передачи файла конфигурации в соединитель. Вы можете установить это свойство, используя аргумент -D
при запуске коннектора. Например, следующая команда запускает соединитель с файлом конфигурации MyConfig.properties
:
java -classpath myconnector.jar;... -Dconfig=MyConfig.properties MyConnector
Если этот аргумент отсутствует, SDK пытается получить доступ к файлу конфигурации по умолчанию с именем connector-config.properties
.
Определите свою стратегию обхода
Основная функция соединителя контента — перемещение по репозиторию и индексирование его данных. Вы должны реализовать стратегию обхода, основанную на размере и расположении данных в вашем репозитории. Вы можете разработать собственную стратегию или выбрать одну из следующих стратегий, реализованных в SDK:
- Полная стратегия обхода
Стратегия полного обхода сканирует весь репозиторий и слепо индексирует каждый элемент. Эта стратегия обычно используется, когда у вас небольшой репозиторий и вы можете позволить себе полный обход при каждом индексировании.
Эта стратегия обхода подходит для небольших репозиториев, в основном содержащих статичные, неиерархические данные. Вы также можете использовать эту стратегию обхода, когда обнаружение изменений затруднено или не поддерживается репозиторием.
- Стратегия обхода списка
Стратегия обхода списка сканирует весь репозиторий, включая все дочерние узлы, определяя статус каждого элемента. Затем соединитель выполняет второй проход и индексирует только те элементы, которые являются новыми или были обновлены с момента последней индексации. Эта стратегия обычно используется для выполнения дополнительных обновлений существующего индекса (вместо необходимости выполнять полный обход каждый раз при обновлении индекса).
Эта стратегия обхода подходит, когда обнаружение изменений затруднено или не поддерживается репозиторием, у вас есть неиерархические данные и вы работаете с очень большими наборами данных.
- Обход графа
Стратегия обхода графа сканирует весь родительский узел, определяя статус каждого элемента. Затем соединитель выполняет второй проход и индексирует только элементы в корневом узле, которые являются новыми или были обновлены с момента последней индексации. Наконец, соединитель передает все дочерние идентификаторы, а затем индексирует новые или обновленные элементы в дочерних узлах. Соединитель продолжает рекурсивно проходить через все дочерние узлы, пока все элементы не будут адресованы. Такой обход обычно используется для иерархических репозиториев, где перечисление всех идентификаторов нецелесообразно.
Эта стратегия подходит, если у вас есть иерархические данные, которые необходимо сканировать, например ряд каталогов или веб-страниц.
Каждая из этих стратегий обхода реализуется классом соединителя шаблонов в SDK. Хотя вы можете реализовать свою собственную стратегию обхода, эти шаблоны значительно ускоряют разработку вашего соединителя. Чтобы создать коннектор по шаблону, перейдите в раздел, соответствующий вашей стратегии обхода:
- Создайте соединитель полного обхода, используя класс шаблона.
- Создайте соединитель обхода списка, используя класс шаблона.
- Создайте соединитель обхода графа, используя класс шаблона.
Создайте соединитель полного обхода, используя класс шаблона.
Этот раздел документации относится к фрагментам кода из примера FullTraversalSample .
Реализация точки входа соединителя
Точкой входа в коннектор является метод main()
. Основная задача этого метода — создать экземпляр класса Application
и вызвать его метод start()
для запуска соединителя.
Прежде чем вызывать application.start()
, используйте класс IndexingApplication.Builder
для создания экземпляра шаблона FullTraversalConnector
. FullTraversalConnector
принимает объект Repository
, методы которого вы реализуете. Следующий фрагмент кода показывает, как реализовать метод main()
:
За кулисами SDK вызывает метод initConfig()
после того, как метод main()
вашего соединителя вызывает Application.build
. Метод initConfig()
выполняет следующие задачи:
- Вызывает метод
Configuation.isInitialized()
, чтобы убедиться, чтоConfiguration
не была инициализирована. - Инициализирует объект
Configuration
с помощью пар ключ-значение, предоставленных Google. Каждая пара ключ-значение хранится в объектеConfigValue
внутри объектаConfiguration
.
Реализовать интерфейс Repository
Единственная цель объекта Repository
— выполнять обход и индексацию элементов репозитория. При использовании шаблона вам нужно только переопределить определенные методы в интерфейсе Repository
, чтобы создать соединитель контента. Методы, которые вы переопределяете, зависят от используемого вами шаблона и стратегии обхода. Для FullTraversalConnector
переопределите следующие методы:
Метод
init()
. Чтобы выполнить настройку и инициализацию хранилища данных, переопределите методinit()
.Метод
getAllDocs()
. Чтобы просмотреть и индексировать все элементы в репозитории данных, переопределите методgetAllDocs()
. Этот метод вызывается один раз для каждого запланированного обхода (как определено вашей конфигурацией).(необязательно) Метод
getChanges()
. Если ваш репозиторий поддерживает обнаружение изменений, переопределите методgetChanges()
. Этот метод вызывается один раз для каждого запланированного инкрементального обхода (как определено вашей конфигурацией) для получения измененных элементов и их индексации.(необязательно) Метод
close()
. Если вам нужно выполнить очистку репозитория, переопределите методclose()
. Этот метод вызывается один раз во время завершения работы коннектора.
Каждый из методов объекта Repository
возвращает объект ApiOperation
определенного типа. Объект ApiOperation
выполняет действие в форме одного или, возможно, нескольких вызовов IndexingService.indexItem()
для фактического индексирования вашего репозитория.
Получить пользовательские параметры конфигурации
В рамках обработки конфигурации вашего соединителя вам потребуется получить любые пользовательские параметры из объекта Configuration
. Эта задача обычно выполняется в методе init()
класса Repository
.
Класс Configuration
имеет несколько методов для получения различных типов данных из конфигурации. Каждый метод возвращает объект ConfigValue
. Затем вы будете использовать метод get()
объекта ConfigValue
для получения фактического значения. В следующем фрагменте из FullTraversalSample
показано, как получить одно пользовательское целочисленное значение из объекта Configuration
:
Чтобы получить и проанализировать параметр, содержащий несколько значений, используйте один из анализаторов типов класса Configuration
для анализа данных на отдельные фрагменты. В следующем фрагменте из соединителя учебника используется метод getMultiValue
для получения списка имен репозиториев GitHub:
Выполнить полный обход
Переопределите getAllDocs()
, чтобы выполнить полный обход и индексацию вашего репозитория. Метод getAllDocs()
принимает контрольную точку. Контрольная точка используется для возобновления индексации определенного элемента в случае прерывания процесса. Для каждого элемента в вашем репозитории выполните следующие шаги в методе getAllDocs()
:
- Установите разрешения.
- Задайте метаданные для индексируемого элемента.
- Объедините метаданные и элемент в один индексируемый
RepositoryDoc
. - Упакуйте каждый индексируемый элемент в итератор, возвращаемый методом
getAllDocs()
. Обратите внимание, чтоgetAllDocs()
фактически возвращаетCheckpointCloseableIterable
, который представляет собой итерацию объектовApiOperation
, причем каждый объект представляет собой запрос API, выполненный вRepositoryDoc
, например, его индексацию.
Если набор элементов слишком велик для обработки за один вызов, включите контрольную точку и установите hasMore(true)
чтобы указать, что для индексации доступно больше элементов.
Установите разрешения для элемента
В вашем репозитории используется список контроля доступа (ACL) для идентификации пользователей или групп, имеющих доступ к элементу. ACL — это список идентификаторов групп или пользователей, которые могут получить доступ к элементу.
Вы должны дублировать ACL, используемый вашим репозиторием, чтобы гарантировать, что только те пользователи, у которых есть доступ к элементу, смогут видеть этот элемент в результатах поиска. ACL для элемента должен быть включен при индексировании элемента, чтобы Google Cloud Search имел информацию, необходимую для обеспечения правильного уровня доступа к элементу.
Content Connector SDK предоставляет богатый набор классов и методов ACL для моделирования списков ACL большинства репозиториев. Вы должны проанализировать ACL для каждого элемента в вашем репозитории и создать соответствующий ACL для Google Cloud Search при индексировании элемента. Если в ACL вашего репозитория используются такие концепции, как наследование ACL, моделирование этого ACL может оказаться сложной задачей. Дополнительную информацию о списках ACL Google Cloud Search см. в разделе ACL Google Cloud Search .
Примечание. API индексирования Cloud Search поддерживает однодоменные списки управления доступом. Он не поддерживает междоменные списки управления доступом. Используйте класс Acl.Builder
чтобы настроить доступ к каждому элементу с помощью ACL. Следующий фрагмент кода, взятый из полного примера обхода, позволяет всем пользователям или «принципалам» ( getCustomerPrincipal()
) быть «читателями» всех элементов ( .setReaders()
) при выполнении поиска.
Вам необходимо понимать ACL, чтобы правильно моделировать ACL для репозитория. Например, вы можете индексировать файлы в файловой системе, использующей какую-то модель наследования, при которой дочерние папки наследуют разрешения от родительских папок. Для моделирования наследования ACL требуется дополнительная информация, описанная в ACL Google Cloud Search.
Установите метаданные для элемента
Метаданные хранятся в объекте Item
. Чтобы создать Item
, вам потребуется как минимум уникальный строковый идентификатор, тип элемента, список управления доступом, URL-адрес и версия элемента. В следующем фрагменте кода показано, как создать Item
с помощью вспомогательного класса IndexingItemBuilder
.
Создайте индексируемый элемент
После того как вы установили метаданные для элемента, вы можете создать фактический индексируемый элемент, используя класс RepositoryDoc.Builder
. В следующем примере показано, как создать один индексируемый элемент.
RepositoryDoc
— это тип ApiOperation
, который выполняет фактический запрос IndexingService.indexItem()
.
Вы также можете использовать метод setRequestMode()
класса RepositoryDoc.Builder
, чтобы определить запрос на индексацию как ASYNCHRONOUS
или SYNCHRONOUS
:
-
ASYNCHRONOUS
- Асинхронный режим приводит к увеличению задержки между индексированием и обслуживанием и обеспечивает большую квоту пропускной способности для запросов индексирования. Асинхронный режим рекомендуется для первоначальной индексации (засыпки) всего репозитория.
-
SYNCHRONOUS
- Синхронный режим приводит к сокращению задержки между индексированием и обслуживанием и обеспечивает ограниченную квоту пропускной способности. Синхронный режим рекомендуется для индексации обновлений и изменений в репозитории. Если не указано, режим запроса по умолчанию
SYNCHRONOUS
.
Упакуйте каждый индексируемый элемент в итератор
Метод getAllDocs()
возвращает Iterator
, в частности CheckpointCloseableIterable
, объектов RepositoryDoc
. Вы можете использовать класс CheckpointClosableIterableImpl.Builder
для создания и возврата итератора. В следующем фрагменте кода показано, как создать и вернуть итератор.
SDK выполняет каждый вызов индексации, заключенный в итераторе.
Следующие шаги
Вот несколько следующих шагов, которые вы можете предпринять:
- (необязательно) Если скорость индексирования кажется низкой, см. раздел Увеличение скорости индексирования для
FullTraversalConnector
. - (необязательно) Реализуйте метод
close()
, чтобы освободить все ресурсы перед завершением работы. - (необязательно) Создайте соединитель удостоверений с помощью Content Connector SDK.
Создайте соединитель обхода списка, используя класс шаблона.
Очередь индексирования Cloud Search используется для хранения идентификаторов и дополнительных хеш-значений для каждого элемента в репозитории. Соединитель обхода списка помещает идентификаторы элементов в очередь индексирования Google Cloud Search и извлекает их по одному для индексации. Google Cloud Search поддерживает очереди и сравнивает их содержимое, чтобы определить статус элемента, например, был ли элемент удален из хранилища. Дополнительную информацию об очереди индексирования Cloud Search см. в разделе Очередь индексирования Cloud Search .
Этот раздел документации относится к фрагментам кода из примера ListTraversalSample .
Реализация точки входа соединителя
Точкой входа в коннектор является метод main()
. Основная задача этого метода — создать экземпляр класса Application
и вызвать его метод start()
для запуска соединителя.
Прежде чем вызывать application.start()
, используйте класс IndexingApplication.Builder
для создания экземпляра шаблона ListingConnector
. ListingConnector
принимает объект Repository
, методы которого вы реализуете. В следующем фрагменте показано, как создать экземпляр ListingConnector
и связанного с ним Repository
:
За кулисами SDK вызывает метод initConfig()
после того, как метод main()
вашего соединителя вызывает Application.build
. Метод initConfig()
:
- Вызывает метод
Configuation.isInitialized()
, чтобы убедиться, чтоConfiguration
не была инициализирована. - Инициализирует объект
Configuration
с помощью пар ключ-значение, предоставленных Google. Каждая пара ключ-значение хранится в объектеConfigValue
внутри объектаConfiguration
.
Реализовать интерфейс Repository
Единственная цель объекта Repository
— выполнять обход и индексацию элементов репозитория. При использовании шаблона вам нужно только переопределить определенные методы в интерфейсе Repository
, чтобы создать соединитель контента. Методы, которые вы переопределяете, зависят от используемого вами шаблона и стратегии обхода. Для ListingConnector
переопределите следующие методы:
Метод
init()
. Чтобы выполнить настройку и инициализацию хранилища данных, переопределите методinit()
.Метод
getIds()
. Чтобы получить идентификаторы и хеш-значения для всех записей в репозитории, переопределите методgetIds()
.Метод
getDoc()
. Чтобы добавить новые, обновить, изменить или удалить элементы из индекса, переопределите методgetDoc()
.(необязательно) Метод
getChanges()
. Если ваш репозиторий поддерживает обнаружение изменений, переопределите методgetChanges()
. Этот метод вызывается один раз для каждого запланированного инкрементного обхода (как определено вашей конфигурацией) для получения измененных элементов и их индексации.(необязательно) Метод
close()
. Если вам нужно выполнить очистку репозитория, переопределите методclose()
. Этот метод вызывается один раз во время завершения работы коннектора.
Каждый из методов объекта Repository
возвращает объект ApiOperation
определенного типа. Объект ApiOperation
выполняет действие в форме одного или, возможно, нескольких вызовов IndexingService.indexItem()
для фактического индексирования вашего репозитория.
Получить пользовательские параметры конфигурации
В рамках обработки конфигурации вашего соединителя вам потребуется получить любые пользовательские параметры из объекта Configuration
. Эта задача обычно выполняется в методе init()
класса Repository
.
Класс Configuration
имеет несколько методов для получения различных типов данных из конфигурации. Каждый метод возвращает объект ConfigValue
. Затем вы будете использовать метод get()
объекта ConfigValue
для получения фактического значения. В следующем фрагменте из FullTraversalSample
показано, как получить одно пользовательское целочисленное значение из объекта Configuration
:
Чтобы получить и проанализировать параметр, содержащий несколько значений, используйте один из анализаторов типов класса Configuration
для анализа данных на отдельные фрагменты. В следующем фрагменте из соединителя учебника используется метод getMultiValue
для получения списка имен репозиториев GitHub:
Выполнить обход списка
Переопределить метод getIds()
для получения идентификаторов и хеш-значений для всех записей в репозитории. Метод getIds()
принимает контрольную точку. Контрольная точка используется для возобновления индексации определенного элемента в случае прерывания процесса.
Затем переопределите метод getDoc()
для обработки каждого элемента в очереди индексирования Cloud Search.
Отправка идентификаторов элементов и хэш-значений
Переопределите getIds()
для получения идентификаторов элементов и связанных с ними хеш-значений контента из репозитория. Пары идентификаторов и хеш-значений затем упаковываются в запрос операции push в очередь индексирования Cloud Search. Корневые или родительские идентификаторы обычно передаются первыми, а затем дочерние идентификаторы, пока не будет обработана вся иерархия элементов.
Метод getIds()
принимает контрольную точку, представляющую последний индексируемый элемент. Контрольную точку можно использовать для возобновления индексации определенного элемента, если процесс будет прерван. Для каждого элемента в вашем репозитории выполните следующие шаги в методе getIds()
:
- Получите идентификатор каждого элемента и связанное с ним значение хеш-функции из репозитория.
- Упакуйте каждую пару идентификаторов и хеш-значений в
PushItems
. - Объедините каждый
PushItems
в итератор, возвращаемый методомgetIds()
. Обратите внимание, чтоgetIds()
фактически возвращаетCheckpointCloseableIterable
, который представляет собой итерацию объектовApiOperation
, каждый объект представляет собой запрос API, выполняемый вRepositoryDoc
, например, помещает элементы в очередь.
В следующем фрагменте кода показано, как получить идентификатор каждого элемента и значение хеш-функции и вставить их в PushItems
. PushItems
— это запрос ApiOperation
для отправки элемента в очередь индексирования Cloud Search.
В следующем фрагменте кода показано, как использовать класс PushItems.Builder
для упаковки идентификаторов и хэш-значений в одну операцию push ApiOperation
.
Элементы помещаются в очередь индексирования Cloud Search для дальнейшей обработки.
Извлекайте и обрабатывайте каждый элемент
Переопределите getDoc()
для обработки каждого элемента в очереди индексирования Cloud Search. Элемент может быть новым, измененным, неизмененным или больше не существовать в исходном репозитории. Извлекайте и индексируйте каждый новый или измененный элемент. Удалите из индекса элементы, которых больше нет в исходном репозитории.
Метод getDoc()
принимает элемент из очереди индексирования Google Cloud Search. Для каждого элемента в очереди выполните следующие шаги в методе getDoc()
:
Проверьте, существует ли в репозитории идентификатор элемента в очереди индексирования Cloud Search. Если нет, удалите элемент из индекса.
Опросите индекс на предмет статуса элемента и, если элемент не изменился (
ACCEPTED
), ничего не делайте.Индекс изменен или добавлены элементы:
- Установите разрешения.
- Задайте метаданные для индексируемого элемента.
- Объедините метаданные и элемент в один индексируемый
RepositoryDoc
. - Верните
RepositoryDoc
.
Примечание. Шаблон ListingConnector
не поддерживает возврат null
в методе getDoc()
. Возврат null
результатов приводит к NullPointerException.
Обработка удаленных элементов
В следующем фрагменте кода показано, как определить, существует ли элемент в репозитории, и если нет, удалить его.
Обратите внимание, что documents
— это структура данных, представляющая репозиторий. Если documentID
не найден в documents
, верните APIOperations.deleteItem(resourceName)
чтобы удалить элемент из индекса.
Обработка неизмененных элементов
В следующем фрагменте кода показано, как опросить статус элемента в очереди индексирования Cloud Search и обработать неизмененный элемент.
Чтобы определить, является ли элемент неизмененным, проверьте статус элемента, а также другие метаданные, которые могут указывать на изменение. В этом примере хэш метаданных используется для определения того, был ли изменен элемент.
Установите разрешения для элемента
В вашем репозитории используется список контроля доступа (ACL) для идентификации пользователей или групп, имеющих доступ к элементу. ACL — это список идентификаторов групп или пользователей, которые могут получить доступ к элементу.
Вы должны дублировать ACL, используемый вашим репозиторием, чтобы гарантировать, что только те пользователи, у которых есть доступ к элементу, смогут видеть этот элемент в результатах поиска. ACL для элемента должен быть включен при индексировании элемента, чтобы Google Cloud Search имел информацию, необходимую для обеспечения правильного уровня доступа к элементу.
Content Connector SDK предоставляет богатый набор классов и методов ACL для моделирования списков ACL большинства репозиториев. Вы должны проанализировать ACL для каждого элемента в вашем репозитории и создать соответствующий ACL для Google Cloud Search при индексировании элемента. Если в ACL вашего репозитория используются такие концепции, как наследование ACL, моделирование этого ACL может оказаться сложной задачей. Дополнительную информацию о списках ACL Google Cloud Search см. в разделе ACL Google Cloud Search .
Примечание. API индексирования Cloud Search поддерживает однодоменные списки управления доступом. Он не поддерживает междоменные списки управления доступом. Используйте класс Acl.Builder
чтобы настроить доступ к каждому элементу с помощью ACL. Следующий фрагмент кода, взятый из полного примера обхода, позволяет всем пользователям или «принципалам» ( getCustomerPrincipal()
) быть «читателями» всех элементов ( .setReaders()
) при выполнении поиска.
Вам необходимо понимать ACL, чтобы правильно моделировать ACL для репозитория. Например, вы можете индексировать файлы в файловой системе, использующей какую-то модель наследования, при которой дочерние папки наследуют разрешения от родительских папок. Для моделирования наследования ACL требуется дополнительная информация, описанная в ACL Google Cloud Search.
Установите метаданные для элемента
Метаданные хранятся в объекте Item
. Чтобы создать Item
, вам необходим как минимум уникальный строковый идентификатор, тип элемента, ACL, URL-адрес и версия элемента. В следующем фрагменте кода показано, как создать Item
с помощью вспомогательного класса IndexingItemBuilder
.
Создать индексируемый элемент
После того как вы установили метаданные для элемента, вы можете создать фактический индексируемый элемент с помощью RepositoryDoc.Builder
. В следующем примере показано, как создать один индексируемый элемент.
RepositoryDoc
— это тип ApiOperation
, который выполняет фактический запрос IndexingService.indexItem()
.
Вы также можете использовать метод setRequestMode()
класса RepositoryDoc.Builder
, чтобы определить запрос на индексацию как ASYNCHRONOUS
или SYNCHRONOUS
:
-
ASYNCHRONOUS
- Асинхронный режим приводит к увеличению задержки между индексированием и обслуживанием и обеспечивает большую квоту пропускной способности для запросов индексирования. Асинхронный режим рекомендуется для первоначальной индексации (засыпки) всего репозитория.
-
SYNCHRONOUS
- Синхронный режим приводит к сокращению задержки между индексированием и обслуживанием и обеспечивает ограниченную квоту пропускной способности. Синхронный режим рекомендуется для индексации обновлений и изменений в репозитории. Если не указано, режим запроса по умолчанию
SYNCHRONOUS
.
Следующие шаги
Вот несколько следующих шагов, которые вы можете предпринять:
- (необязательно) Реализуйте метод
close()
, чтобы освободить все ресурсы перед завершением работы. - (необязательно) Создайте соединитель удостоверений с помощью Content Connector SDK.
Создайте соединитель обхода графа, используя класс шаблона.
Очередь индексирования Cloud Search используется для хранения идентификаторов и дополнительных хеш-значений для каждого элемента в репозитории. Соединитель обхода графа передает идентификаторы элементов в очередь индексирования Google Cloud Search и извлекает их по одному для индексации. Google Cloud Search поддерживает очереди и сравнивает их содержимое, чтобы определить статус элемента, например, был ли элемент удален из хранилища. Дополнительную информацию об очереди индексирования Cloud Search см. в разделе Очередь индексирования Google Cloud Search .
Во время индексирования содержимое элемента извлекается из хранилища данных, а идентификаторы всех дочерних элементов помещаются в очередь. Соединитель продолжает рекурсивно обрабатывать родительские и дочерние идентификаторы, пока не будут обработаны все элементы.
Этот раздел документации относится к фрагментам кода из примера GraphTraversalSample .
Реализация точки входа соединителя
Точкой входа в коннектор является метод main()
. Основная задача этого метода — создать экземпляр класса Application
и вызвать его метод start()
для запуска соединителя.
Прежде чем вызывать application.start()
, используйте класс IndexingApplication.Builder
для создания экземпляра шаблона ListingConnector
. ListingConnector
принимает объект Repository
, методы которого вы реализуете.
В следующем фрагменте показано, как создать экземпляр ListingConnector
и связанного с ним Repository
:
За кулисами SDK вызывает метод initConfig()
после того, как метод main()
вашего соединителя вызывает Application.build
. Метод initConfig()
:
- Вызывает метод
Configuation.isInitialized()
, чтобы убедиться, чтоConfiguration
не была инициализирована. - Инициализирует объект
Configuration
с помощью пар ключ-значение, предоставленных Google. Каждая пара ключ-значение хранится в объектеConfigValue
внутри объектаConfiguration
.
Реализовать интерфейс Repository
Единственная цель объекта Repository
— выполнять обход и индексацию элементов репозитория. При использовании шаблона вам нужно только переопределить определенные методы в интерфейсе Repository
, чтобы создать соединитель контента. Методы, которые вы переопределяете, зависят от используемого вами шаблона и стратегии обхода. Для ListingConnector
вы переопределяете следующие методы:
Метод
init()
. Чтобы выполнить настройку и инициализацию хранилища данных, переопределите методinit()
.Метод
getIds()
. Чтобы получить идентификаторы и хеш-значения для всех записей в репозитории, переопределите методgetIds()
.Метод
getDoc()
. Чтобы добавить новые, обновить, изменить или удалить элементы из индекса, переопределите методgetDoc()
.(необязательно) Метод
getChanges()
. Если ваш репозиторий поддерживает обнаружение изменений, переопределите методgetChanges()
. Этот метод вызывается один раз для каждого запланированного инкрементального обхода (как определено вашей конфигурацией) для получения измененных элементов и их индексации.(необязательно) Метод
close()
. Если вам нужно выполнить очистку репозитория, переопределите методclose()
. Этот метод вызывается один раз во время завершения работы коннектора.
Каждый из методов объекта Repository
возвращает объект ApiOperation
определенного типа. Объект ApiOperation
выполняет действие в форме одного или, возможно, нескольких вызовов IndexingService.indexItem()
для фактического индексирования вашего репозитория.
Получить пользовательские параметры конфигурации
В рамках обработки конфигурации вашего соединителя вам потребуется получить любые пользовательские параметры из объекта Configuration
. Эта задача обычно выполняется в методе init()
класса Repository
.
Класс Configuration
имеет несколько методов для получения различных типов данных из конфигурации. Каждый метод возвращает объект ConfigValue
. Затем вы будете использовать метод get()
объекта ConfigValue
для получения фактического значения. В следующем фрагменте из FullTraversalSample
показано, как получить одно пользовательское целочисленное значение из объекта Configuration
:
Чтобы получить и проанализировать параметр, содержащий несколько значений, используйте один из анализаторов типов класса Configuration
для анализа данных на отдельные фрагменты. В следующем фрагменте из соединителя учебника используется метод getMultiValue
для получения списка имен репозиториев GitHub:
Выполнить обход графа
Переопределить метод getIds()
для получения идентификаторов и хеш-значений для всех записей в репозитории. Метод getIds()
принимает контрольную точку. Контрольная точка используется для возобновления индексации определенного элемента в случае прерывания процесса.
Затем переопределите метод getDoc()
для обработки каждого элемента в очереди индексирования Cloud Search.
Отправка идентификаторов элементов и хэш-значений
Переопределите getIds()
для получения идентификаторов элементов и связанных с ними хеш-значений контента из репозитория. Пары идентификаторов и хэш-значений затем упаковываются в запрос операции push в очередь индексирования Cloud Search. Корневые или родительские идентификаторы обычно передаются первыми, а затем дочерние идентификаторы, пока не будет обработана вся иерархия элементов.
Метод getIds()
принимает контрольную точку, представляющую последний индексируемый элемент. Контрольную точку можно использовать для возобновления индексации определенного элемента, если процесс будет прерван. Для каждого элемента в вашем репозитории выполните следующие шаги в методе getIds()
:
- Получите идентификатор каждого элемента и связанное с ним значение хеш-функции из репозитория.
- Упакуйте каждый идентификатор и хэш -значение в
PushItems
. - Объедините все
PushItems
в итератор, возвращаемый методомgetIds()
. Обратите внимание, чтоgetIds()
фактически возвращаетCheckpointCloseableIterable
, которая является итерацией объектовApiOperation
, каждый объект, представляющий запрос API, выполняемый вRepositoryDoc
, например, подтолкнуть элементы в очередь.
Следующий фрагмент кода показывает, как получить каждый идентификатор элемента и значение хэша, и вставить их в PushItems
. PushItems
- это запрос ApiOperation
, чтобы выдвинуть элемент в очередь индексации поиска в облачном поиске.
Следующий фрагмент кода показывает, как использовать класс PushItems.Builder
для упаковки идентификаторов и значений хэша в единое push ApiOperation
.
Элементы выдвигаются в очередь индексации по поиску облачного поиска для дальнейшей обработки.
Получить и обрабатывать каждый элемент
Переопределите getDoc()
, чтобы обрабатывать каждый элемент в очереди индексации поиска в облаке. Предмет может быть новым, измененным, неизменным или больше не может существовать в хранилище источника. Получить и индексировать каждый элемент, который является новым или измененным. Удалите элементы из индекса, которые больше не существуют в хранилище источника.
Метод getDoc()
принимает элемент из очереди индексации поиска. Для каждого элемента в очереди выполните эти шаги в методе getDoc()
:
Проверьте, существует ли идентификатор элемента в очереди индексации поиска, существует в репозитории. Если нет, удалите элемент из индекса. Если предмет существует, продолжайте следующий шаг.
Индекс изменился или новые элементы:
- Установите разрешения.
- Установите метаданные для предмета, который вы индексируете.
- Объедините метаданные и элемент в один индексируемый
RepositoryDoc
. - Поместите идентификаторы детей в очередь индексации поиска в облаке для дальнейшей обработки.
- Вернуть
RepositoryDoc
.
Обрабатывать удаленные предметы
Следующий фрагмент кода показывает, как определить, существует ли элемент в индексе, а не удалить его.
Установите разрешения на элемент
Ваш репозиторий использует список контроля доступа (ACL) для идентификации пользователей или групп, которые имеют доступ к элементу. ACL - это список идентификаторов для групп или пользователей, которые могут получить доступ к элементу.
Вы должны дублировать ACL, используемый вашим хранилищем, чтобы гарантировать, что только те пользователи, имеющие доступ к элементу, могут увидеть этот элемент в результате поиска. ACL для элемента должен быть включен при индексации элемента, так что Google Cloud Search имеет информацию, необходимую для предоставления правильного уровня доступа к элементу.
Content Connector SDK предоставляет богатый набор классов ACL и методов для моделирования ACL большинства репозиториев. Вы должны проанализировать ACL для каждого элемента в вашем репозитории и создать соответствующий ACL для поиска Google Cloud, когда вы индексируете элемент. Если ACL вашего репозитория использует такие понятия, как наследование ACL, моделирование этого ACL может быть сложным. Для получения дополнительной информации о Google Cloud Search ACL см. ACLS Google Cloud Search.
ПРИМЕЧАНИЕ. API индексации облачного поиска поддерживает однодоменные ACLS. Он не поддерживает междоменные ACL. Используйте класс Acl.Builder
чтобы установить доступ к каждому элементу, используя ACL. Следующий фрагмент кода, взятый из полной выборки, позволяет всем пользователям или «принципалам» ( getCustomerPrincipal()
) быть «читателями» всех элементов ( .setReaders()
) при выполнении поиска.
Вы должны понимать ACL для правильного моделирования ACL для репозитория. Например, вы можете индексировать файлы в файловой системе, которая использует какую -то модель наследования, в которой дочерние папки наследуют разрешения от родительских папок. Моделирование наследования ACL требует дополнительной информации, описанной в Google Cloud Search ACLS
Установите метаданные для предмета
Метаданные хранятся в Item
. Чтобы создать Item
, вам нужен как минимум уникальный идентификатор строки, тип элемента, ACL, URL и версия для элемента. Следующий фрагмент кода показывает, как создать Item
используя класс Helper IndexingItemBuilder
.
Создать индексируемый элемент
После того, как вы установили метаданные для элемента, вы можете создать фактический индексируемый элемент, используя RepositoryDoc.Builder
. В следующем примере показано, как создать один индексируемый элемент.
RepositoryDoc
- это тип ApiOperation
, который выполняет фактический запрос IndexingService.indexItem()
.
Вы также можете использовать метод setRequestMode()
класса RepositoryDoc.Builder
для определения запроса индексации как ASYNCHRONOUS
или SYNCHRONOUS
:
-
ASYNCHRONOUS
- Асинхронный режим приводит к более длинной задержке индексации к проведению и вмещает большую квоту пропускной способности для запросов индексации. Асинхронный режим рекомендуется для начальной индексации (засыпания) всего репозитория.
-
SYNCHRONOUS
- Синхронный режим приводит к более короткой задержке индексации к проведению и вмещает ограниченную квоту пропускной способности. Синхронный режим рекомендуется для индексации обновлений и изменений в хранилище. В случае неопределенности режим запроса по умолчанию
SYNCHRONOUS
.
Поместите идентификаторы детей в очередь индексации поиска в облаке
Следующий фрагмент кода показывает, как включить идентификаторы дочерних идентификаторов для в настоящее время обработки родительского элемента в очередь для обработки. Эти идентификаторы обрабатываются после того, как родительский элемент проиндексирован.
Следующие шаги
Вот несколько следующих шагов, которые вы можете предпринять:
- (Необязательно) Реализуйте метод
close()
для выпуска любых ресурсов перед выключением. - (Необязательно) Создайте идентификационный разъем, используя SDK идентификационного разъема.
Создайте контент -разъем, используя API REST
В следующих разделах объясняется, как создать контент -разъем, используя API REST.
Определите свою стратегию обхода
Основная функция контента -разъема состоит в том, чтобы пересечь репозиторий и индексировать его данные. Вы должны реализовать стратегию обхода в зависимости от размера и макета данных в вашем репозитории. Ниже приведены три общие стратегии обхода:
- Полная стратегия обхода
Полная стратегия обхода сканирует весь репозиторий и слепо индексирует каждый элемент. Эта стратегия обычно используется, когда у вас есть небольшой репозиторий и может позволить себе накладные расходы на полное прохождение каждый раз, когда вы индексируете.
Эта стратегия обхода подходит для небольших репозиториев с в основном статическими, не иерархическими данными. Вы также можете использовать эту стратегию обхода, когда обнаружение изменений затруднено или не поддерживается репозиторием.
- Список стратегии обхода
Стратегия пересечения списка сканирует весь репозиторий, включая все узлы дочерних узлов, определяя статус каждого элемента. Затем разъем берет второй проход и только индексирует новые элементы, которые являются новыми или были обновлены с момента последней индексации. Эта стратегия обычно используется для выполнения инкрементных обновлений существующего индекса (вместо того, чтобы делать полное прохождение каждый раз, когда вы обновляете индекс).
Эта стратегия обхода подходит, когда обнаружение изменений затруднено или не поддерживается репозиторием, у вас есть не иерархические данные, и вы работаете с очень большими наборами данных.
- График обход
Стратегия обхода графика сканирует весь родительский узел, определяющий статус каждого элемента. Затем разъем берет второй проход, и только элементы индексов в корневом узле являются новыми или были обновлены с момента последней индексации. Наконец, разъем проходит любые идентификаторы дочерних идентификаторов, а затем индексирует элементы в узлах дочерних узлов, которые являются новыми или были обновлены. Разъем продолжает рекурсивно через все дочерние узлы, пока все элементы не будут рассмотрены. Такое обход обычно используется для иерархических репозиториев, где список всех идентификаторов не является практичным.
Эта стратегия подходит, если у вас есть иерархические данные, которые необходимо заполнить, такие как серийные каталоги или веб -страницы.
Реализуйте свою стратегию обхода и индексы
Каждый индексируемый элемент для облачного поиска называется элементом в облачном поиске API. Элемент может быть файлом, папкой, строкой в файле CSV или записи базы данных.
Как только ваша схема зарегистрирована, вы можете заполнить индекс:
(необязательно) Использование
items.upload
для загрузки файлов более 100 киб для индексации. Для небольших файлов встройте контент как InlineContent с использованиемitems.index
.(необязательно) Использование
media.upload
для загрузки медиа -файлов для индексации.Использование
items.index
для индексации элемента. Например, если ваша схема использует определение объекта в схеме фильма , запрос индексации на один элемент будет выглядеть так:{ "name": "datasource/<data_source_id>/items/titanic", "acl": { "readers": [ { "gsuitePrincipal": { "gsuiteDomain": true } } ] }, "metadata": { "title": "Titanic", "viewUrl": "http://www.imdb.com/title/tt2234155/?ref_=nv_sr_1", "objectType": "movie" }, "structuredData": { "object": { "properties": [ { "name": "movieTitle", "textValues": { "values": [ "Titanic" ] } }, { "name": "releaseDate", "dateValues": { "values": [ { "year": 1997, "month": 12, "day": 19 } ] } }, { "name": "actorName", "textValues": { "values": [ "Leonardo DiCaprio", "Kate Winslet", "Billy Zane" ] } }, { "name": "genre", "enumValues": { "values": [ "Drama", "Action" ] } }, { "name": "userRating", "integerValues": { "values": [ 8 ] } }, { "name": "mpaaRating", "textValues": { "values": [ "PG-13" ] } }, { "name": "duration", "textValues": { "values": [ "3 h 14 min" ] } } ] } }, "content": { "inlineContent": "A seventeen-year-old aristocrat falls in love with a kind but poor artist aboard the luxurious, ill-fated R.M.S. Titanic.", "contentFormat": "TEXT" }, "version": "01", "itemType": "CONTENT_ITEM" }
(Необязательно) Использование элементов. Получить вызовы для проверки элемента был проиндексирован.
Чтобы выполнить полное обход, вы периодически переоцените весь репозиторий. Чтобы выполнить список или график, вам необходимо внедрить код для обработки изменений репозитория .
Обрабатывать изменения репозитория
Вы можете периодически собирать и индексировать каждый элемент из репозитория для выполнения полной индексации. Несмотря на то, что он эффективен в обеспечении актуального индекса, полная индексация может быть дорогостоящей при работе с более крупными или иерархическими репозиториями.
Вместо того, чтобы использовать индексные вызовы для индексации всего репозитория, вы также можете использовать очередь индексации Cloud Google в качестве механизма для отслеживания изменений и индексации только те элементы, которые изменились. Вы можете использовать ements.push Запросы, чтобы выдвигать элементы в очередь для последующего опроса и обновления. Для получения дополнительной информации о очереди индексации Google Cloud, см. В очереди индексации облака Google .
Для получения дополнительной информации об API поиска Google Cloud, см. API облачного поиска .