Tworzenie łącznika treści

Łącznik treści to program służący do przeglądania danych w repozytorium firmy i wypełniania źródła danych. Google oferuje następujące opcje tworzenia oprogramowania sprzęgającego treści:

• Pakiet SDK Content Connector. Jest to dobra opcja, jeśli programujesz w języku Java. Pakiet Content Connector SDK to otoka interfejsu API REST, która umożliwia szybkie tworzenie oprogramowania sprzęgającego. Informacje o tym, jak utworzyć łącznik treści za pomocą pakietu SDK, znajdziesz w sekcji Tworzenie oprogramowania sprzęgającego treści za pomocą pakietu SDK Content Connector.

• interfejsu API typu REST lub bibliotek interfejsów API niskiego poziomu; Użyj tych opcji, jeśli nie programujesz w języku Java albo jeśli Twoja baza kodu lepiej obsługuje interfejs API REST lub bibliotekę. Aby utworzyć oprogramowanie sprzęgające treści za pomocą interfejsu API REST, zapoznaj się z sekcją Tworzenie oprogramowania sprzęgającego treści za pomocą interfejsu API REST.

Typowy łącznik treści wykonuje te zadania:

1. Odczytuje i przetwarza parametry konfiguracji.
2. Pobiera dyskretne fragmenty danych dostępnych do indeksowania, tzw. „items”, z zewnętrznego repozytorium treści.
3. Łączy listy kontroli dostępu, metadane i dane o treści w elementy możliwe do indeksowania.
4. Indeksuje elementy do źródła danych Cloud Search.
5. (opcjonalnie) Nasłuchuje zmian powiadomień z repozytorium treści innych firm. Powiadomienia o zmianach są konwertowane na żądania indeksowania, aby zapewnić synchronizację źródła danych Cloud Search z repozytorium innej firmy. Oprogramowanie sprzęgające wykonuje to zadanie tylko wtedy, gdy repozytorium obsługuje wykrywanie zmian.

Utwórz oprogramowanie sprzęgające treści za pomocą pakietu SDK Content Connector.

W poniższych sekcjach znajdziesz informacje o tym, jak utworzyć oprogramowanie sprzęgające treści za pomocą pakietu SDK Content Connector.

Skonfiguruj zależności

Aby korzystać z pakietu SDK, musisz umieścić w pliku kompilacji pewne zależności. Kliknij kartę poniżej, aby wyświetlić zależności swojego środowiska kompilacji:

Maven

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

Gradle

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

Tworzenie konfiguracji oprogramowania sprzęgającego

Każde oprogramowanie sprzęgające ma plik konfiguracji zawierający parametry używane przez oprogramowanie sprzęgające, takie jak identyfikator repozytorium. Parametry są definiowane jako pary klucz-wartość, np. api.sourceId=1234567890abcdef.

Pakiet Google Cloud Search SDK zawiera kilka parametrów konfiguracyjnych dostarczonych przez Google, które są używane przez wszystkie oprogramowanie sprzęgające. W pliku konfiguracji musisz zadeklarować te parametry Google:

• W przypadku oprogramowania sprzęgającego treści musisz zadeklarować api.sourceId i api.serviceAccountPrivateKeyFile, ponieważ te parametry identyfikują lokalizację repozytorium i klucz prywatny niezbędny do uzyskania dostępu do repozytorium.

Uwaga: jeśli plik z kluczem prywatnym nie jest kluczem JSON, musisz też zastąpić api.serviceAccountId.

• W przypadku oprogramowania sprzęgającego tożsamości musisz zadeklarować api.identitySourceId, ponieważ ten parametr identyfikuje lokalizację zewnętrznego źródła tożsamości. Jeśli synchronizujesz użytkowników, musisz też zadeklarować api.customerId jako unikalny identyfikator konta Google Workspace swojej firmy.

Jeśli nie chcesz zastąpić domyślnych wartości innych parametrów dostarczonych przez Google, nie musisz ich deklarować w pliku konfiguracji. Więcej informacji o parametrach konfiguracyjnych dostarczonych przez Google, np. o sposobie generowania określonych identyfikatorów i kluczy, znajdziesz w sekcji Parametry konfiguracji dostarczone przez Google.

Możesz też zdefiniować własne parametry repozytorium do użycia w pliku konfiguracji.

Uwaga: nie ma rygorystycznych wymagań dotyczących nazewnictwa pliku właściwości oprogramowania sprzęgającego, ale zalecamy zapisanie go jako rozszerzenia .properties lub .config.

Przekaż plik konfiguracji do oprogramowania sprzęgającego

Ustaw właściwość systemową config, aby przekazywać plik konfiguracji do oprogramowania sprzęgającego. Możesz ustawić właściwość za pomocą argumentu -D podczas uruchamiania oprogramowania sprzęgającego. Na przykład to polecenie uruchamia oprogramowanie sprzęgające od pliku konfiguracji MyConfig.properties:

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

Jeśli nie ma tego argumentu, pakiet SDK próbuje uzyskać dostęp do domyślnego pliku konfiguracji o nazwie connector-config.properties.

Określanie strategii przemierzania

Podstawową funkcją oprogramowania sprzęgającego treści jest przemierzanie repozytorium i zindeksowanie jego danych. Musisz wdrożyć strategię przemierzania na podstawie rozmiaru i układu danych w repozytorium. Możesz opracować własną strategię lub wybrać jedną z poniższych strategii wdrożonych w pakiecie SDK:

Strategia przemierzania wszystkich stron

Strategia pełnego przemierzania skanuje całe repozytorium i ślepo indeksuje każdy element. Ta strategia jest zwykle używana w przypadku małego repozytorium i kosztu pełnego przemierzania za każdym razem podczas indeksowania.

Ta strategia przemierzania sprawdza się w przypadku małych repozytoriów zawierających głównie statyczne, niehierarchiczne dane. Tej strategii możesz też użyć, gdy wykrywanie zmian jest trudne lub nie jest obsługiwane przez repozytorium.

Strategia przemierzania listy

Strategia przemierzania listy skanuje całe repozytorium, w tym wszystkie węzły podrzędne, sprawdzając stan każdego elementu. Następnie oprogramowanie sprzęgające przechodzi drugi etap i indeksuje tylko te elementy, które są nowe lub zostały zaktualizowane od ostatniego indeksowania. Ta strategia jest zwykle używana do wykonywania przyrostowych aktualizacji istniejącego indeksu (zamiast wykonywania pełnego przemierzania za każdym razem, gdy aktualizujesz indeks).

Ta strategia przemierzania jest odpowiednia, gdy wykrywanie zmian jest trudne lub nie jest obsługiwane przez repozytorium, masz dane niehierarchiczne i pracujesz z bardzo dużymi zbiorami danych.

Poruszanie się po wykresie

Strategia przemierzania wykresu skanuje cały węzeł nadrzędny, sprawdzając stan każdego elementu. Następnie oprogramowanie sprzęgające sprawdza drugi przebieg i indeksuje tylko elementy w węźle głównym, które są nowe lub zostały zaktualizowane od ostatniego indeksowania. Na koniec oprogramowanie sprzęgające przekazuje wszystkie identyfikatory podrzędne, a następnie indeksuje elementy w węzłach podrzędnych, które są nowe lub zostały zaktualizowane. Oprogramowanie sprzęgające jest kontynuowane rekurencyjnie po wszystkich węzłach podrzędnych, aż do rozwiązania wszystkich problemów. Takie przemierzanie jest zwykle stosowane w repozytoriach hierarchicznych, w których wyświetlanie wszystkich identyfikatorów nie jest praktyczne.

Ta strategia jest odpowiednia, jeśli masz dane hierarchiczne, które trzeba zindeksować, takie jak seria katalogów lub stron internetowych.

Uwaga: terminy „produkt” i „dokument” są synonimami w tym dokumencie i przykładowym kodzie.

Każda z tych strategii przemierzania jest implementowana przez klasę oprogramowania sprzęgającego szablonu w pakiecie SDK. Możesz wdrożyć własną strategię przemierzania, ale szablony te znacznie przyspieszają tworzenie oprogramowania sprzęgającego. Aby utworzyć oprogramowanie sprzęgające za pomocą szablonu, przejdź do sekcji odpowiadającej Twojej strategii przemierzania:

• Tworzenie oprogramowania sprzęgającego pełnego przemierzania za pomocą klasy szablonu
• Tworzenie oprogramowania sprzęgającego przemierzania listy za pomocą klasy szablonu
• Tworzenie oprogramowania sprzęgającego przemierzania wykresu za pomocą klasy szablonu

Utwórz oprogramowanie sprzęgające pełnego przemierzania za pomocą klasy szablonu

W tej sekcji dokumentacji opisujemy fragmenty kodu z przykładu FullTraversalSample.

Wdróż punkt wejścia oprogramowania sprzęgającego

Punktem wejścia do oprogramowania sprzęgającego jest metoda main(). Głównym zadaniem tej metody jest utworzenie instancji klasy Application i wywołanie jej metody start() w celu uruchomienia oprogramowania sprzęgającego.

Przed wywołaniem application.start() użyj klasy IndexingApplication.Builder do utworzenia instancji szablonu FullTraversalConnector. FullTraversalConnector akceptuje obiekt Repository, których metody implementujesz. Ten fragment kodu pokazuje, jak wdrożyć metodę main():

FullTraversalSample.java

Wyświetl w GitHubie

/**
 * 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();
}

W tle pakiet SDK wywołuje metodę initConfig() po wywołaniu metody main() oprogramowania sprzęgającego Application.build. Metoda initConfig() wykonuje te zadania:

1. Wywołuje metodę Configuation.isInitialized(), aby mieć pewność, że element Configuration nie został zainicjowany.
2. Inicjuje obiekt Configuration za pomocą par klucz-wartość udostępnionych przez Google. Każda para klucz-wartość jest przechowywana w obiekcie ConfigValue w obiekcie Configuration.

Implementowanie interfejsu Repository

Jedynym przeznaczeniem obiektu Repository jest przemierzanie i indeksowanie elementów repozytorium. Podczas korzystania z szablonu wystarczy zastąpić tylko niektóre metody w interfejsie Repository, aby utworzyć łącznik treści. Zastępowane metody zależą od stosowanego szablonu i strategii przemierzania. W przypadku FullTraversalConnector zastąp te metody:

• Metoda init(). Aby skonfigurować lub zainicjować dowolne repozytorium danych, zastąp metodę init().

• Metoda getAllDocs(). Aby przeglądać i indeksować wszystkie elementy w repozytorium danych, zastąp metodę getAllDocs(). Ta metoda jest wywoływana raz dla każdego zaplanowanego przemierzania (zgodnie z ustawieniami w konfiguracji).

• (opcjonalnie) Metoda getChanges(). Jeśli repozytorium obsługuje wykrywanie zmian, zastąp metodę getChanges(). Ta metoda jest wywoływana raz dla każdego zaplanowanego przemierzania przyrostowego (zgodnie z definicją w konfiguracji) w celu pobrania i zindeksowania zmodyfikowanych elementów.

• (opcjonalnie) Metoda close(). Jeśli musisz wyczyścić repozytorium, zastąp metodę close(). Ta metoda jest wywoływana raz podczas wyłączania oprogramowania sprzęgającego.

Każda z metod obiektu Repository zwraca jakiś typ obiektu ApiOperation. Obiekt ApiOperation wykonuje działanie w postaci pojedynczego lub wielu wywołań IndexingService.indexItem(), które wykonują rzeczywiste indeksowanie repozytorium.

Pobierz niestandardowe parametry konfiguracji

W ramach obsługi konfiguracji oprogramowania sprzęgającego musisz uzyskać z obiektu Configuration wszelkie parametry niestandardowe. To zadanie jest zwykle wykonywane w metodzie init() klasy Repository.

Klasa Configuration ma kilka metod pobierania różnych typów danych z konfiguracji. Każda metoda zwraca obiekt ConfigValue. Następnie użyj metody get() obiektu ConfigValue, aby pobrać rzeczywistą wartość. Ten fragment kodu z FullTraversalSample pokazuje, jak pobrać niestandardową wartość całkowitą z obiektu Configuration:

FullTraversalSample.java

Wyświetl w GitHubie

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

Aby pobrać i przeanalizować parametr zawierający kilka wartości, użyj jednego z parserów typu Configuration w celu przeanalizowania danych na osobne fragmenty. Ten fragment kodu z oprogramowania sprzęgającego samouczka korzysta z metody getMultiValue, aby uzyskać listę nazw repozytoriów GitHub:

GithubRepository.java

Wyświetl w GitHubie

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

Wykonaj pełne przemierzanie

Zastąp getAllDocs(), aby wykonać pełne przemierzanie i indeksowanie repozytorium. Metoda getAllDocs() akceptuje punkt kontrolny. Punkt kontrolny służy do wznowienia indeksowania przy określonym elemencie w przypadku przerwania tego procesu. W przypadku każdego elementu w repozytorium wykonaj te czynności w metodzie getAllDocs():

1. Ustaw uprawnienia.
2. Ustaw metadane indeksowanego elementu.
3. Połącz metadane i element w jeden możliwy do zindeksowania element RepositoryDoc.
4. Spakuj każdy element możliwy do zindeksowania do iteratora zwróconego przez metodę getAllDocs(). Pamiętaj, że getAllDocs() tak naprawdę zwraca CheckpointCloseableIterable, który jest iteracją obiektów ApiOperation, a każdy obiekt reprezentujący żądanie do interfejsu API wykonane w RepositoryDoc, na przykład jego zindeksowanie.

Jeśli zbiór elementów jest zbyt duży, aby można go było przetworzyć w jednym wywołaniu, dodaj punkt kontrolny i ustaw hasMore(true), aby wskazać, że więcej elementów jest dostępnych do indeksowania.

Ustaw uprawnienia dla elementu

Repozytorium używa listy kontroli dostępu (ACL) do identyfikowania użytkowników lub grup mających dostęp do danego elementu. Jest to lista identyfikatorów grup lub użytkowników, którzy mają dostęp do elementu.

Musisz zduplikować listę kontroli dostępu używaną przez repozytorium, aby mieć pewność, że tylko użytkownicy z dostępem do danego elementu zobaczą go w wynikach wyszukiwania. Lista kontroli dostępu elementu musi być uwzględniona podczas indeksowania elementu, aby usługa Google Cloud Search miała informacje niezbędne do zapewnienia prawidłowego poziomu dostępu do elementu.

Pakiet Content Connector SDK udostępnia bogaty zestaw klas i metod ACL do modelowania list kontroli dostępu większości repozytoriów. Podczas indeksowania elementu musisz przeanalizować listę kontroli dostępu (ACL) dla każdego elementu w repozytorium i utworzyć odpowiednią listę kontroli dostępu na potrzeby Google Cloud Search. Jeśli na liście kontroli dostępu (ACL) są stosowane pojęcia takie jak dziedziczenie ACL, modelowanie jej może być trudne. Więcej informacji o listach kontroli dostępu (ACL) Google Cloud Search znajdziesz w artykule Listy kontroli dostępu Google Cloud Search.

Uwaga: interfejs Cloud Search Crawl API obsługuje listy kontroli dostępu dla jednej domeny. Nie obsługuje list kontroli dostępu dla wielu domen. Użyj klasy Acl.Builder, aby ustawić dostęp do każdego elementu za pomocą listy kontroli dostępu. Poniższy fragment kodu, pochodzący z próbki pełnego przemierzania, pozwala na „odczytywanie” wszystkich elementów (.setReaders()) wszystkim użytkownikom lub „podmiotom zabezpieczeń” (getCustomerPrincipal()).

FullTraversalSample.java

Wyświetl w GitHubie

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

Aby prawidłowo modelować listy kontroli dostępu dla repozytorium, musisz poznać listy kontroli dostępu. Na przykład możesz indeksować pliki w systemie plików, który korzysta z modelu dziedziczenia, w którym foldery podrzędne dziedziczą uprawnienia z folderów nadrzędnych. Modelowanie dziedziczenia ACL wymaga dodatkowych informacji omówionych w listach kontroli dostępu Google Cloud Search.

Ustawianie metadanych elementu

Metadane są przechowywane w obiekcie Item. Aby utworzyć Item, potrzebujesz co najmniej unikalnego identyfikatora ciągu znaków, typu elementu, listy kontroli dostępu, adresu URL i wersji elementu. Poniższy fragment kodu pokazuje, jak utworzyć Item za pomocą klasy pomocniczej IndexingItemBuilder.

FullTraversalSample.java

Wyświetl w GitHubie

// 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();

Tworzenie elementu możliwego do zindeksowania

Po ustawieniu metadanych elementu możesz utworzyć element możliwy do zindeksowania za pomocą klasy RepositoryDoc.Builder. Przykład poniżej pokazuje, jak utworzyć jeden element możliwy do zindeksowania.

FullTraversalSample.java

Wyświetl w GitHubie

// 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();

RepositoryDoc to typ elementu ApiOperation, który wykonuje właściwe żądanie IndexingService.indexItem().

Możesz też użyć metody setRequestMode() klasy RepositoryDoc.Builder, aby określić prośbę o zindeksowanie jako ASYNCHRONOUS lub SYNCHRONOUS:

ASYNCHRONOUS

Tryb asynchroniczny skutkuje dłuższym czasem oczekiwania na indeksowanie i udostępnianiem oraz umożliwia obsługę dużego limitu przepustowości żądań indeksowania. Zalecamy korzystanie z trybu asynchronicznego do początkowego indeksowania (uzupełniania) całego repozytorium.

SYNCHRONOUS

Tryb synchroniczny skraca czas oczekiwania na indeksowanie i udostępnia i reaguje na ograniczony limit przepustowości. Tryb synchroniczny jest zalecany w przypadku indeksowania aktualizacji i zmian w repozytorium. Jeśli nie określono tego ustawienia, domyślnie używany jest tryb żądania SYNCHRONOUS.

Umieść każdy element możliwy do zindeksowania w iteratorze

Metoda getAllDocs() zwraca element Iterator, a konkretnie CheckpointCloseableIterable, spośród obiektów RepositoryDoc. Klasy CheckpointClosableIterableImpl.Builder możesz użyć do utworzenia i zwrócenia iteratora. Poniższy fragment kodu pokazuje, jak utworzyć i zwrócić iterator.

FullTraversalSample.java

Wyświetl w GitHubie

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

Pakiet SDK wykonuje każde wywołanie indeksowania zawarte w iteratorze.

Uwaga: Cloud Search indeksuje metadane wszystkich plików. W zależności od typu pliku elementu Cloud Search indeksuje też zawartość tekstową, w tym z użyciem optycznego rozpoznawania znaków (OCR) na zdjęciach i innych plikach. Listę typów plików obsługujących wyodrębnianie tekstu znajdziesz w artykule Obsługiwane typy plików umożliwiające wyodrębnianie tekstu.

Dalsze kroki

Oto kilka dalszych kroków, które możesz podjąć:

• (opcjonalnie) Jeśli szybkość indeksowania wydaje się niska, zapoznaj się z artykułem Zwiększanie szybkości indeksowania witryny FullTraversalConnector.
• (Opcjonalnie) Zaimplementuj metodę close(), aby zwolnić wszystkie zasoby przed wyłączeniem.
• (Opcjonalnie) Utwórz oprogramowanie sprzęgające tożsamości za pomocą pakietu SDK Content Connector.

Tworzenie oprogramowania sprzęgającego przemierzania listy za pomocą klasy szablonu

Kolejka indeksowania w Cloud Search służy do przechowywania identyfikatorów i opcjonalnych wartości skrótu każdego elementu w repozytorium. Oprogramowanie sprzęgające do przemierzania listy przekazuje identyfikatory elementów do kolejki indeksowania w Google Cloud Search i pobiera je pojedynczo na potrzeby indeksowania. Google Cloud Search utrzymuje kolejki i porównuje ich zawartość, aby określić stan elementów – na przykład czy element został usunięty z repozytorium. Więcej informacji o kolejce indeksowania w Cloud Search znajdziesz w artykule Kolejka indeksowania w Cloud Search.

W tej sekcji dokumentacji opisujemy fragmenty kodu z przykładu ListTraversalSample.

Wdróż punkt wejścia oprogramowania sprzęgającego

Punktem wejścia do oprogramowania sprzęgającego jest metoda main(). Głównym zadaniem tej metody jest utworzenie instancji klasy Application i wywołanie jej metody start() w celu uruchomienia oprogramowania sprzęgającego.

Przed wywołaniem application.start() użyj klasy IndexingApplication.Builder do utworzenia instancji szablonu ListingConnector. ListingConnector akceptuje obiekt Repository, których metody zaimplementowane przez Ciebie. Ten fragment kodu pokazuje, jak uruchomić funkcję ListingConnector i powiązaną z nią właściwość Repository:

ListTraversalSample.java

Wyświetl w GitHubie

/**
 * 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();
}

W tle pakiet SDK wywołuje metodę initConfig() po wywołaniu metody main() oprogramowania sprzęgającego Application.build. Metoda initConfig():

1. Wywołuje metodę Configuation.isInitialized(), aby mieć pewność, że element Configuration nie został zainicjowany.
2. Inicjuje obiekt Configuration za pomocą par klucz-wartość udostępnionych przez Google. Każda para klucz-wartość jest przechowywana w obiekcie ConfigValue w obiekcie Configuration.

Implementowanie interfejsu Repository

Jedynym przeznaczeniem obiektu Repository jest przemierzanie i indeksowanie elementów repozytorium. Podczas korzystania z szablonu wystarczy zastąpić tylko niektóre metody w interfejsie Repository, aby utworzyć oprogramowanie sprzęgające treści. Zastępowane metody zależą od używanych przez Ciebie szablonów i strategii przemierzania. W przypadku ListingConnector zastąp te metody:

• Metoda init(). Aby skonfigurować lub zainicjować dowolne repozytorium danych, zastąp metodę init().

• Metoda getIds(). Aby pobrać identyfikatory i wartości skrótu dla wszystkich rekordów w repozytorium, zastąp metodę getIds().

• Metoda getDoc(). Aby dodawać nowe elementy do indeksu, aktualizować je, modyfikować i usuwać z indeksu, zastąp metodę getDoc().

• (opcjonalnie) Metoda getChanges(). Jeśli repozytorium obsługuje wykrywanie zmian, zastąp metodę getChanges(). Ta metoda jest wywoływana raz dla każdego zaplanowanego przemierzania przyrostowego (zgodnie z definicją w konfiguracji) w celu pobrania i zindeksowania zmodyfikowanych elementów.

• (opcjonalnie) Metoda close(). Jeśli musisz wyczyścić repozytorium, zastąp metodę close(). Ta metoda jest wywoływana raz podczas wyłączania oprogramowania sprzęgającego.

Każda z metod obiektu Repository zwraca jakiś typ obiektu ApiOperation. Obiekt ApiOperation wykonuje działanie w postaci pojedynczego lub wielu wywołań IndexingService.indexItem(), które wykonują rzeczywiste indeksowanie repozytorium.

Pobierz niestandardowe parametry konfiguracji

W ramach obsługi konfiguracji oprogramowania sprzęgającego musisz uzyskać z obiektu Configuration wszelkie parametry niestandardowe. To zadanie jest zwykle wykonywane w metodzie init() klasy Repository.

Klasa Configuration ma kilka metod pobierania różnych typów danych z konfiguracji. Każda metoda zwraca obiekt ConfigValue. Następnie użyj metody get() obiektu ConfigValue, aby pobrać rzeczywistą wartość. Ten fragment kodu z FullTraversalSample pokazuje, jak pobrać niestandardową wartość całkowitą z obiektu Configuration:

FullTraversalSample.java

Wyświetl w GitHubie

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

Aby pobrać i przeanalizować parametr zawierający kilka wartości, użyj jednego z parserów typu Configuration w celu przeanalizowania danych na osobne fragmenty. Ten fragment kodu z oprogramowania sprzęgającego samouczka korzysta z metody getMultiValue, aby uzyskać listę nazw repozytoriów GitHub:

GithubRepository.java

Wyświetl w GitHubie

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

Poruszaj się po liście

Zastąp metodę getIds(), aby pobrać identyfikatory i wartości skrótu dla wszystkich rekordów w repozytorium. Metoda getIds() akceptuje punkt kontrolny. Punkt kontrolny służy do wznowienia indeksowania w przypadku konkretnego elementu, jeśli proces ten zostanie przerwany.

Następnie zastąp metodę getDoc(), aby obsługiwać każdy element w kolejce indeksowania Cloud Search.

Przekaż identyfikatory elementów i wartości skrótu

Zastąp getIds(), aby pobrać z repozytorium identyfikatory elementów i powiązane z nimi wartości skrótu treści. Pary identyfikatorów i wartości skrótu są następnie łączone w żądanie operacji push do kolejki indeksowania Cloud Search. Identyfikatory główne i nadrzędne są zwykle przekazywane jako pierwsze, a po nich identyfikatory podrzędne, aż do przetworzenia całej hierarchii elementów.

Metoda getIds() akceptuje punkt kontrolny reprezentujący ostatni element do zindeksowania. Możesz użyć punktu kontrolnego, aby wznowić indeksowanie określonego elementu, jeśli proces ten zostanie przerwany. Dla każdego elementu w repozytorium wykonaj te czynności w metodzie getIds():

• Pobierz z repozytorium każdy identyfikator elementu i powiązaną wartość skrótu.
• Spakuj każdą parę identyfikator i wartość skrótu do PushItems.
• Połącz poszczególne PushItems w iterator zwracany przez metodę getIds(). Pamiętaj, że getIds() tak naprawdę zwraca CheckpointCloseableIterable, który jest iteracją obiektów ApiOperation, a każdy obiekt reprezentujący żądanie API wykonane w RepositoryDoc, np. wypchnięcie elementów do kolejki.

Poniższy fragment kodu pokazuje, jak uzyskać identyfikator elementu i wartość skrótu oraz wstawić je w elemencie PushItems. PushItems to żądanie ApiOperation, które powoduje przekazanie elementu do kolejki indeksowania Cloud Search.

ListTraversalSample.java

Wyświetl w GitHubie

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);
}

Poniższy fragment kodu pokazuje, jak za pomocą klasy PushItems.Builder spakować identyfikatory i wartości haszowania w jednoczesne ApiOperation.

ListTraversalSample.java

Wyświetl w GitHubie

ApiOperation pushOperation = allIds.build();
CheckpointCloseableIterable<ApiOperation> iterator =
  new CheckpointCloseableIterableImpl.Builder<>(
      Collections.singletonList(pushOperation))
  .build();
return iterator;

Elementy są przekazywane do kolejki indeksowania w Cloud Search w celu dalszego przetworzenia.

Pobieranie i obsługa każdego produktu

Zastąp getDoc(), aby obsługiwać każdy element w kolejce indeksowania Cloud Search. Element może być nowy, zmodyfikowany, niezmieniony lub nie może już istnieć w repozytorium źródłowym. Pobieranie i indeksowanie każdego nowego lub zmodyfikowanego elementu. Usuń z indeksu elementy, których już nie ma w repozytorium źródłowym.

Metoda getDoc() akceptuje element z kolejki indeksowania Google Cloud Search. W przypadku każdego elementu w kolejce wykonaj te czynności w metodzie getDoc():

1. Sprawdź, czy w repozytorium znajduje się identyfikator elementu znajdujący się w kolejce indeksowania Cloud Search. Jeśli nie, usuń element z indeksu.

2. Przejrzyj indeks pod kątem stanu elementu i jeśli element nie zostanie zmieniony (ACCEPTED), nic nie rób.

3. Indeks zmieniony lub nowe elementy:

   1. Ustaw uprawnienia.
   2. Ustaw metadane indeksowanego elementu.
   3. Połącz metadane i element w jeden możliwy do zindeksowania element RepositoryDoc.
   4. Zwróć RepositoryDoc.

Uwaga: szablon ListingConnector nie obsługuje zwracania null za pomocą metody getDoc(). Zwracanie null wyników w postaci NullPointerException.

Obsługa usuniętych elementów

Poniższy fragment kodu pokazuje, jak sprawdzić, czy element istnieje w repozytorium, i usunąć go, jeśli nie jest.

ListTraversalSample.java

Wyświetl w GitHubie

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);
}

Pamiętaj, że documents to struktura danych reprezentująca repozytorium. Jeśli w regule documents nie znaleziono elementu documentID, wróć do APIOperations.deleteItem(resourceName), aby usunąć element z indeksu.

Obsługa niezmienionych elementów

Poniższy fragment kodu pokazuje, jak odpytywać stan elementu w kolejce indeksowania Cloud Search i obsługiwać niezmieniony element.

ListTraversalSample.java

Wyświetl w GitHubie

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();
}

Aby ustalić, czy element jest niezmodyfikowany, sprawdź jego stan i inne metadane, które mogą wskazywać na zmianę. W tym przykładzie do określenia, czy element został zmieniony, służy szyfr metadanych.

ListTraversalSample.java

Wyświetl w GitHubie

/**
 * 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);
}

Ustaw uprawnienia dla elementu

Repozytorium używa listy kontroli dostępu (ACL) do identyfikowania użytkowników lub grup mających dostęp do danego elementu. Jest to lista identyfikatorów grup lub użytkowników, którzy mają dostęp do elementu.

Musisz zduplikować listę kontroli dostępu używaną przez repozytorium, aby mieć pewność, że tylko użytkownicy z dostępem do danego elementu zobaczą go w wynikach wyszukiwania. Lista kontroli dostępu elementu musi być uwzględniona podczas indeksowania elementu, aby usługa Google Cloud Search miała informacje niezbędne do zapewnienia prawidłowego poziomu dostępu do elementu.

Pakiet Content Connector SDK udostępnia bogaty zestaw klas i metod ACL do modelowania list kontroli dostępu większości repozytoriów. Podczas indeksowania elementu musisz przeanalizować listę kontroli dostępu (ACL) dla każdego elementu w repozytorium i utworzyć odpowiednią listę kontroli dostępu na potrzeby Google Cloud Search. Jeśli na liście kontroli dostępu (ACL) są stosowane pojęcia takie jak dziedziczenie ACL, modelowanie jej może być trudne. Więcej informacji o listach kontroli dostępu (ACL) Google Cloud Search znajdziesz w artykule Listy kontroli dostępu Google Cloud Search.

Uwaga: interfejs Cloud Search Crawl API obsługuje listy kontroli dostępu dla jednej domeny. Nie obsługuje list kontroli dostępu dla wielu domen. Użyj klasy Acl.Builder, aby ustawić dostęp do każdego elementu za pomocą listy kontroli dostępu. Poniższy fragment kodu, pochodzący z próbki pełnego przemierzania, pozwala na „odczytywanie” wszystkich elementów (.setReaders()) wszystkim użytkownikom lub „podmiotom zabezpieczeń” (getCustomerPrincipal()).

FullTraversalSample.java

Wyświetl w GitHubie

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

Aby prawidłowo modelować listy kontroli dostępu dla repozytorium, musisz poznać listy kontroli dostępu. Na przykład możesz indeksować pliki w systemie plików, który korzysta z modelu dziedziczenia, w którym foldery podrzędne dziedziczą uprawnienia z folderów nadrzędnych. Modelowanie dziedziczenia ACL wymaga dodatkowych informacji omówionych w listach kontroli dostępu Google Cloud Search.

Ustawianie metadanych elementu

Metadane są przechowywane w obiekcie Item. Aby utworzyć Item, potrzebujesz co najmniej unikalnego identyfikatora ciągu znaków, typu elementu, listy kontroli dostępu, adresu URL i wersji elementu. Poniższy fragment kodu pokazuje, jak utworzyć Item za pomocą klasy pomocniczej IndexingItemBuilder.

ListTraversalSample.java

Wyświetl w GitHubie

// 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();

Tworzenie elementu możliwego do zindeksowania

Po ustawieniu metadanych elementu możesz utworzyć element możliwy do zindeksowania, korzystając z metody RepositoryDoc.Builder. Przykład poniżej pokazuje, jak utworzyć jeden element możliwy do zindeksowania.

ListTraversalSample.java

Wyświetl w GitHubie

// 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();

RepositoryDoc to typ elementu ApiOperation, który wykonuje rzeczywiste żądanie IndexingService.indexItem().

Możesz też użyć metody setRequestMode() klasy RepositoryDoc.Builder, aby określić prośbę o zindeksowanie jako ASYNCHRONOUS lub SYNCHRONOUS:

ASYNCHRONOUS

Tryb asynchroniczny skutkuje dłuższym czasem oczekiwania na indeksowanie i udostępnianiem oraz umożliwia obsługę dużego limitu przepustowości żądań indeksowania. Zalecamy korzystanie z trybu asynchronicznego do początkowego indeksowania (uzupełniania) całego repozytorium.

SYNCHRONOUS

Tryb synchroniczny skraca czas oczekiwania na indeksowanie i udostępnia i reaguje na ograniczony limit przepustowości. Tryb synchroniczny jest zalecany w przypadku indeksowania aktualizacji i zmian w repozytorium. Jeśli nie określono tego ustawienia, domyślnie używany jest tryb żądania SYNCHRONOUS.

Uwaga: Cloud Search indeksuje metadane dla wszystkich plików. W zależności od typu pliku elementu Cloud Search indeksuje też zawartość tekstową, m.in. z użyciem optycznego rozpoznawania znaków (OCR) na treściach pisanych odręcznie. Listę typów plików obsługujących wyodrębnianie tekstu znajdziesz w artykule Obsługiwane typy plików umożliwiające wyodrębnianie tekstu.

Dalsze kroki

Oto kilka dalszych kroków, które możesz podjąć:

• (Opcjonalnie) Zaimplementuj metodę close(), aby zwolnić wszystkie zasoby przed wyłączeniem.
• (Opcjonalnie) Utwórz oprogramowanie sprzęgające tożsamości za pomocą pakietu SDK Content Connector.

Utwórz oprogramowanie sprzęgające przemierzania wykresu za pomocą klasy szablonu

Kolejka indeksowania w Cloud Search służy do przechowywania identyfikatorów i opcjonalnych wartości skrótu każdego elementu w repozytorium. Oprogramowanie sprzęgające do przemierzania wykresu przekazuje identyfikatory elementów do kolejki indeksowania w Google Cloud Search i pobiera je pojedynczo na potrzeby indeksowania. Google Cloud Search przechowuje kolejki i porównuje ich zawartość, aby określić stan elementów (np. czy element został usunięty z repozytorium). Więcej informacji o kolejce indeksowania w Cloud Search znajdziesz w artykule Kolejka indeksowania w Google Cloud Search.

Podczas indeksowania zawartość elementu jest pobierana z repozytorium danych, a wszystkie identyfikatory elementów podrzędnych są przekazywane do kolejki. Oprogramowanie sprzęgające przetwarza rekurencyjnie identyfikatory elementów nadrzędnych i podrzędnych tak długo, aż wszystkie elementy zostaną przetworzone.

W tej sekcji dokumentacji opisujemy fragmenty kodu z przykładu GraphTraversalSample.

Wdróż punkt wejścia oprogramowania sprzęgającego

Punktem wejścia do oprogramowania sprzęgającego jest metoda main(). Głównym zadaniem tej metody jest utworzenie instancji klasy Application i wywołanie jej metody start() w celu uruchomienia oprogramowania sprzęgającego.

Zanim wywołasz application.start(), użyj klasy IndexingApplication.Builder do utworzenia instancji szablonu ListingConnector. ListingConnector akceptuje obiekt Repository, których metody implementujesz.

Uwaga: strategia przemierzania wykresu używa tej samej klasy szablonu (ListingConnector) co strategia przemierzania listy.

Ten fragment kodu pokazuje, jak uruchomić funkcję ListingConnector i powiązaną z nią właściwość Repository:

GraphTraversalSample.java

Wyświetl w GitHubie

/**
 * This sample connector uses the Cloud Search SDK template class for a graph
 * 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();
}

W tle pakiet SDK wywołuje metodę initConfig() po wywołaniu metody main() oprogramowania sprzęgającego Application.build. Metoda initConfig():

1. Wywołuje metodę Configuation.isInitialized(), aby mieć pewność, że element Configuration nie został zainicjowany.
2. Inicjuje obiekt Configuration za pomocą par klucz-wartość udostępnionych przez Google. Każda para klucz-wartość jest przechowywana w obiekcie ConfigValue w obiekcie Configuration.

Implementowanie interfejsu Repository

Jedynym przeznaczeniem obiektu Repository jest przemierzanie i indeksowanie elementów repozytorium. Podczas korzystania z szablonu wystarczy zastąpić tylko niektóre metody w interfejsie Repository, aby utworzyć łącznik treści. Zastępowane metody zależą od użytego szablonu i strategii przemierzania. W przypadku ListingConnector zastępujesz te metody:

• Metoda init(). Aby skonfigurować lub zainicjować dowolne repozytorium danych, zastąp metodę init().

• Metoda getIds(). Aby pobrać identyfikatory i wartości skrótu dla wszystkich rekordów w repozytorium, zastąp metodę getIds().

• Metoda getDoc(). Aby dodawać nowe elementy do indeksu, aktualizować je, modyfikować i usuwać z indeksu, zastąp metodę getDoc().

• (opcjonalnie) Metoda getChanges(). Jeśli repozytorium obsługuje wykrywanie zmian, zastąp metodę getChanges(). Ta metoda jest wywoływana raz dla każdego zaplanowanego przemierzania przyrostowego (zgodnie z definicją w konfiguracji) w celu pobrania i zindeksowania zmodyfikowanych elementów.

• (opcjonalnie) Metoda close(). Jeśli musisz wyczyścić repozytorium, zastąp metodę close(). Ta metoda jest wywoływana raz podczas wyłączania oprogramowania sprzęgającego.

Każda metoda obiektu Repository zwraca jakiś typ obiektu ApiOperation. Obiekt ApiOperation wykonuje działanie w formie pojedynczego lub wielu wywołań IndexingService.indexItem(), które wykonują rzeczywiste indeksowanie repozytorium.

Pobierz niestandardowe parametry konfiguracji

W ramach obsługi konfiguracji oprogramowania sprzęgającego musisz uzyskać z obiektu Configuration wszelkie parametry niestandardowe. To zadanie jest zwykle wykonywane w metodzie init() klasy Repository.

Klasa Configuration ma kilka metod pobierania różnych typów danych z konfiguracji. Każda metoda zwraca obiekt ConfigValue. Następnie użyj metody get() obiektu ConfigValue, aby pobrać rzeczywistą wartość. Ten fragment kodu z FullTraversalSample pokazuje, jak pobrać niestandardową wartość całkowitą z obiektu Configuration:

FullTraversalSample.java

Wyświetl w GitHubie

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

Aby pobrać i przeanalizować parametr zawierający kilka wartości, użyj jednego z parserów typu Configuration w celu przeanalizowania danych na osobne fragmenty. Ten fragment kodu z oprogramowania sprzęgającego samouczka korzysta z metody getMultiValue, aby uzyskać listę nazw repozytoriów GitHub:

GithubRepository.java

Wyświetl w GitHubie

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

Poruszaj się po wykresie

Zastąp metodę getIds(), aby pobrać identyfikatory i wartości skrótu dla wszystkich rekordów w repozytorium. Metoda getIds() akceptuje punkt kontrolny. Punkt kontrolny służy do wznowienia indeksowania w przypadku konkretnego elementu, jeśli proces ten zostanie przerwany.

Następnie zastąp metodę getDoc(), aby obsługiwać każdy element w kolejce indeksowania Cloud Search.

Przekaż identyfikatory elementów i wartości skrótu

Zastąp getIds(), aby pobrać z repozytorium identyfikatory elementów i powiązane z nimi wartości skrótu treści. Pary identyfikatorów i wartości skrótu są następnie łączone w żądanie operacji push do kolejki indeksowania Cloud Search. Identyfikatory główne i nadrzędne są zwykle przekazywane jako pierwsze, a po nich identyfikatory podrzędne, aż do przetworzenia całej hierarchii elementów.

Metoda getIds() akceptuje punkt kontrolny reprezentujący ostatni element do zindeksowania. Możesz użyć punktu kontrolnego, aby wznowić indeksowanie określonego elementu, jeśli proces ten zostanie przerwany. Dla każdego elementu w repozytorium wykonaj te czynności w metodzie getIds():

• Pobierz z repozytorium każdy identyfikator elementu i powiązaną wartość skrótu.
• Spakuj każdą parę identyfikator i wartość skrótu do PushItems.
• Połącz poszczególne PushItems w iterator zwracany przez metodę getIds(). Pamiętaj, że getIds() tak naprawdę zwraca CheckpointCloseableIterable, który jest iteracją obiektów ApiOperation, a każdy obiekt reprezentujący żądanie API wykonane w RepositoryDoc, np. wypchnięcie elementów do kolejki.

Poniższy fragment kodu pokazuje, jak uzyskać identyfikator elementu i wartość skrótu oraz wstawić je w elemencie PushItems. PushItems to żądanie ApiOperation przesyłające element do kolejki indeksowania w Cloud Search.

GraphTraversalSample.java

Wyświetl w GitHubie

PushItems.Builder allIds = new PushItems.Builder();
PushItem item = new PushItem();
allIds.addPushItem("root", item);

Poniższy fragment kodu pokazuje, jak za pomocą klasy PushItems.Builder spakować identyfikatory i wartości haszowania w jednoczesne ApiOperation.

GraphTraversalSample.java

Wyświetl w GitHubie

ApiOperation pushOperation = allIds.build();
CheckpointCloseableIterable<ApiOperation> iterator =
  new CheckpointCloseableIterableImpl.Builder<>(
      Collections.singletonList(pushOperation))
  .build();

Elementy są przekazywane do kolejki indeksowania w Cloud Search w celu dalszego przetworzenia.

Pobieranie i obsługa każdego produktu

Zastąp getDoc(), aby obsługiwać każdy element w kolejce indeksowania Cloud Search. Element może być nowy, zmodyfikowany, niezmieniony lub nie może już istnieć w repozytorium źródłowym. Pobieranie i indeksowanie każdego nowego lub zmodyfikowanego elementu. Usuń z indeksu elementy, których już nie ma w repozytorium źródłowym.

Metoda getDoc() akceptuje element z kolejki indeksowania w Cloud Search. W przypadku każdego elementu w kolejce wykonaj te czynności w metodzie getDoc():

1. Sprawdź, czy w repozytorium znajduje się identyfikator elementu znajdujący się w kolejce indeksowania Cloud Search. Jeśli nie, usuń element z indeksu. Jeśli element istnieje, przejdź do następnego kroku.

2. Indeks zmieniony lub nowe elementy:

   1. Ustaw uprawnienia.
   2. Ustaw metadane indeksowanego elementu.
   3. Połącz metadane i element w jeden możliwy do zindeksowania element RepositoryDoc.
   4. Umieść identyfikatory podrzędne w kolejce indeksowania w Cloud Search do dalszego przetworzenia.
   5. Zwróć RepositoryDoc.

Obsługa usuniętych elementów

Poniższy fragment kodu pokazuje, jak ustalić, czy element istnieje w indeksie, i usunąć go.

GraphTraversalSample.java

Wyświetl w GitHubie

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);

Ustaw uprawnienia dla elementu

Repozytorium używa listy kontroli dostępu (ACL) do identyfikowania użytkowników lub grup mających dostęp do danego elementu. Jest to lista identyfikatorów grup lub użytkowników, którzy mają dostęp do elementu.

Musisz zduplikować listę kontroli dostępu używaną przez repozytorium, aby mieć pewność, że tylko użytkownicy z dostępem do danego elementu zobaczą go w wynikach wyszukiwania. Lista kontroli dostępu elementu musi być uwzględniona podczas indeksowania elementu, aby usługa Google Cloud Search miała informacje niezbędne do zapewnienia prawidłowego poziomu dostępu do elementu.

Pakiet Content Connector SDK udostępnia bogaty zestaw klas i metod ACL do modelowania list kontroli dostępu większości repozytoriów. Podczas indeksowania elementu musisz przeanalizować listę kontroli dostępu (ACL) dla każdego elementu w repozytorium i utworzyć odpowiednią listę kontroli dostępu na potrzeby Google Cloud Search. Jeśli na liście kontroli dostępu (ACL) są stosowane pojęcia takie jak dziedziczenie ACL, modelowanie jej może być trudne. Więcej informacji o listach kontroli dostępu (ACL) Google Cloud Search znajdziesz w artykule Listy kontroli dostępu Google Cloud Search.

Uwaga: interfejs Cloud Search Crawl API obsługuje listy kontroli dostępu dla jednej domeny. Nie obsługuje list kontroli dostępu dla wielu domen. Użyj klasy Acl.Builder, aby ustawić dostęp do każdego elementu za pomocą listy kontroli dostępu. Poniższy fragment kodu, pochodzący z próbki pełnego przemierzania, pozwala na „odczytywanie” wszystkich elementów (.setReaders()) wszystkim użytkownikom lub „podmiotom zabezpieczeń” (getCustomerPrincipal()).

FullTraversalSample.java

Wyświetl w GitHubie

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

Aby prawidłowo modelować listy kontroli dostępu dla repozytorium, musisz poznać listy kontroli dostępu. Na przykład możesz indeksować pliki w systemie plików, który korzysta z modelu dziedziczenia, w którym foldery podrzędne dziedziczą uprawnienia z folderów nadrzędnych. Modelowanie dziedziczenia ACL wymaga dodatkowych informacji omówionych w listach kontroli dostępu Google Cloud Search.

Ustawianie metadanych elementu

Metadane są przechowywane w obiekcie Item. Aby utworzyć Item, potrzebujesz co najmniej unikalnego identyfikatora ciągu znaków, typu elementu, listy kontroli dostępu, adresu URL i wersji elementu. Poniższy fragment kodu pokazuje, jak utworzyć Item za pomocą klasy pomocniczej IndexingItemBuilder.

GraphTraversalSample.java

Wyświetl w GitHubie

// 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();

Tworzenie elementu możliwego do zindeksowania

Po ustawieniu metadanych elementu możesz utworzyć element możliwy do zindeksowania, korzystając z metody RepositoryDoc.Builder. Przykład poniżej pokazuje, jak utworzyć jeden element możliwy do zindeksowania.

GraphTraversalSample.java

Wyświetl w GitHubie

// 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);

RepositoryDoc to typ elementu ApiOperation, który wykonuje właściwe żądanie IndexingService.indexItem().

Możesz też użyć metody setRequestMode() klasy RepositoryDoc.Builder, aby określić prośbę o zindeksowanie jako ASYNCHRONOUS lub SYNCHRONOUS:

ASYNCHRONOUS

Tryb asynchroniczny skutkuje dłuższym czasem oczekiwania na indeksowanie i udostępnianiem oraz umożliwia obsługę dużego limitu przepustowości żądań indeksowania. Zalecamy korzystanie z trybu asynchronicznego do początkowego indeksowania (uzupełniania) całego repozytorium.

SYNCHRONOUS

Tryb synchroniczny skraca czas oczekiwania na indeksowanie i udostępnia i reaguje na ograniczony limit przepustowości. Tryb synchroniczny jest zalecany w przypadku indeksowania aktualizacji i zmian w repozytorium. Jeśli nie określono tego ustawienia, domyślnie używany jest tryb żądania SYNCHRONOUS.

Umieść identyfikatory podrzędne w kolejce indeksowania w Cloud Search

Poniższy fragment kodu pokazuje, jak uwzględnić identyfikatory podrzędne w aktualnie przetwarzanym elemencie nadrzędnym w kolejce do przetworzenia. Identyfikatory te są przetwarzane po zindeksowaniu elementu nadrzędnego.

GraphTraversalSample.java

Wyświetl w GitHubie

// 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();

Uwaga: Cloud Search indeksuje metadane wszystkich plików. W zależności od typu pliku elementu Cloud Search indeksuje też zawartość tekstową, m.in. z użyciem optycznego rozpoznawania znaków (OCR) na treściach pisanych odręcznie. Listę typów plików obsługujących wyodrębnianie tekstu znajdziesz w artykule Obsługiwane typy plików umożliwiające wyodrębnianie tekstu.

Dalsze kroki

Oto kilka dalszych kroków, które możesz podjąć:

• (Opcjonalnie) Zaimplementuj metodę close(), aby zwolnić wszystkie zasoby przed wyłączeniem.
• (Opcjonalnie) Utwórz oprogramowanie sprzęgające tożsamości za pomocą pakietu SDK Identity Connector.

Tworzenie oprogramowania sprzęgającego treści za pomocą interfejsu API REST

Poniżej dowiesz się, jak utworzyć oprogramowanie sprzęgające treści za pomocą interfejsu API typu REST.

Określanie strategii przemierzania

Podstawową funkcją oprogramowania sprzęgającego treści jest przemierzanie repozytorium i zindeksowanie jego danych. Musisz wdrożyć strategię przemierzania na podstawie rozmiaru i układu danych w repozytorium. Oto 3 często używane strategie przemierzania tych zasobów:

Strategia przemierzania wszystkich stron

Strategia pełnego przemierzania skanuje całe repozytorium i ślepo indeksuje każdy element. Ta strategia jest zwykle używana w przypadku małego repozytorium i kosztu pełnego przemierzania za każdym razem podczas indeksowania.

Ta strategia przemierzania sprawdza się w przypadku małych repozytoriów zawierających głównie statyczne, niehierarchiczne dane. Tej strategii możesz też użyć, gdy wykrywanie zmian jest trudne lub nie jest obsługiwane przez repozytorium.

Strategia przemierzania listy

Strategia przemierzania listy skanuje całe repozytorium, w tym wszystkie węzły podrzędne, sprawdzając stan każdego elementu. Następnie oprogramowanie sprzęgające przechodzi drugi etap i indeksuje tylko te elementy, które są nowe lub zostały zaktualizowane od ostatniego indeksowania. Ta strategia jest zwykle używana do wykonywania przyrostowych aktualizacji istniejącego indeksu (zamiast wykonywania pełnego przemierzania za każdym razem, gdy aktualizujesz indeks).

Ta strategia przemierzania jest odpowiednia, gdy wykrywanie zmian jest trudne lub nie jest obsługiwane przez repozytorium, masz dane niehierarchiczne i pracujesz z bardzo dużymi zbiorami danych.

Poruszanie się po wykresie

Strategia przemierzania wykresu skanuje cały węzeł nadrzędny, sprawdzając stan każdego elementu. Następnie oprogramowanie sprzęgające sprawdza drugi przebieg i indeksuje tylko elementy w węźle głównym, które są nowe lub zostały zaktualizowane od ostatniego indeksowania. Na koniec oprogramowanie sprzęgające przekazuje wszystkie identyfikatory podrzędne, a następnie indeksuje elementy w węzłach podrzędnych, które są nowe lub zostały zaktualizowane. Oprogramowanie sprzęgające jest kontynuowane rekurencyjnie po wszystkich węzłach podrzędnych, aż do rozwiązania wszystkich problemów. Takie przemierzanie jest zwykle stosowane w repozytoriach hierarchicznych, w których wyświetlanie wszystkich identyfikatorów nie jest praktyczne.

Ta strategia jest odpowiednia, jeśli masz dane hierarchiczne, które trzeba zindeksować, takie jak katalogi serii lub strony internetowe.

Uwaga: terminy „produkt” i „dokument” są synonimami w tym dokumencie i przykładowym kodzie.

Wdrażanie strategii przemierzania i elementów indeksu

W interfejsie Cloud Search API każdy element możliwy do indeksowania jest określany jako item. Elementem może być plik, folder, wiersz w pliku CSV lub rekord bazy danych.

Po zarejestrowaniu schematu możesz wypełnić indeks według tych kryteriów:

1. (opcjonalnie) Używanie items.upload do przesyłania na potrzeby indeksowania plików większych niż 100 KiB. W przypadku mniejszych plików umieść treść jako inlineContent za pomocą items.index.

2. (opcjonalnie) korzystanie z media.upload w celu przesyłania plików multimedialnych do zindeksowania.

3. Indeksowanie elementu za pomocą narzędzia items.index. Jeśli na przykład schemat korzysta z definicji obiektu w schemacie filmów, prośba o zindeksowanie pojedynczego elementu będzie wyglądać tak:

   {
     "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"
   }
   

4. (Opcjonalnie) Za pomocą wywołań items.get możesz sprawdzić, czy element item został zindeksowany.

Aby wykonać pełne przemierzanie, musisz co jakiś czas ponownie zindeksować całe repozytorium. Aby móc poruszać się po liście lub wykresie, musisz zaimplementować kod do obsługi zmian w repozytorium.

Uwaga: pole objectType w tabeli ItemMetadata powinno być zgodne z nazwą definicji obiektu w schemacie. Dzięki temu Cloud Search identyfikuje oczekiwaną strukturę obiektu w żądaniu indeksowania. Jeśli w prośbie o zindeksowanie wyślesz uporządkowane dane zawierające właściwości, które nie są zarejestrowane w bieżącym schemacie, albo podasz typ obiektu, który nie odpowiada nazwie jednej z definicji obiektu w schemacie, obiekt lub właściwość będą ignorowane. Poza tym, jeśli wysyłasz właściwości innego typu niż zarejestrowany w schemacie, Cloud Search zwraca odpowiedź o błędzie w momencie indeksowania.

Uwaga: każde połączenie HTTP realizowane przez klienta skutkuje narzutem. Aby zmniejszyć narzut, możesz zgrupować kilka wywołań interfejsu API w jednym żądaniu HTTP. Aby dowiedzieć się, jak zmniejszyć obciążenie połączeń HTTP, przeczytaj artykuł Grupowanie żądań. Aby dowiedzieć się, jak obsłużyć duże pliki multimedialne, przeczytaj artykuł Przesyłanie bezpośrednie i wznawiane przesyłanie multimediów.

Obsługuj zmiany w repozytorium

Możesz okresowo gromadzić i indeksować każdy element z repozytorium, aby wykonać pełne indeksowanie. Chociaż w ten sposób zapewniasz aktualność indeksu, pełne indeksowanie może być kosztowne w przypadku większych lub hierarchicznych repozytoriów.

Zamiast co często wywoływać całe repozytorium do indeksowania całego repozytorium, możesz użyć kolejki indeksowania w Google Cloud jako mechanizmu do śledzenia zmian i indeksowania tylko tych elementów, które się zmieniły. Za pomocą żądań items.push możesz przenosić elementy do kolejki w celu późniejszego odpytywania i aktualizowania. Więcej informacji o kolejce indeksowania w Google Cloud znajdziesz w artykule Kolejka indeksowania w Google Cloud.

Więcej informacji o interfejsie Google Cloud Search API znajdziesz w artykule Cloud Search API.