Tworzenie łącznika treści

Oprogramowanie sprzęgające zawartości to program do przeglądania danych w repozytorium firmy i uzupełniania źródła danych. Google udostępnia te opcje tworzenia oprogramowania sprzęgającego treści:

Typowy łącznik treści wykonuje te zadania:

  1. Odczytuje i przetwarza parametry konfiguracji.
  2. Pobiera dyskretne fragmenty danych indeksowanych, zwanych „items”, z repozytorium treści innej firmy.
  3. Łączy listy kontroli dostępu, metadane i dane o treści w elementy możliwe do zindeksowania.
  4. Indeksuje elementy do źródła danych Cloud Search.
  5. (Opcjonalnie) Nasłuchiwanie zmian w powiadomieniach z zewnętrznego repozytorium treści. Powiadomienia o zmianach są konwertowane na żądania indeksowania, aby zapewnić synchronizację źródła danych Cloud Search z zewnętrznym repozytorium. 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 oprogramowania sprzęgającego zawartości

Poniższe sekcje zawierają informacje o tym, jak utworzyć oprogramowanie sprzęgające treści za pomocą pakietu SDK oprogramowania sprzęgającego zawartości.

Konfigurowanie zależności

Aby korzystać z pakietu SDK, musisz uwzględnić w pliku kompilacji określone zależności. Kliknij kartę poniżej, aby wyświetlić zależności ś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 zawiera plik konfiguracji zawierający parametry używane przez oprogramowanie sprzęgające, takie jak identyfikator repozytorium. Parametry definiuje się jako pary klucz-wartość, np. api.sourceId=1234567890abcdef.

Pakiet SDK Google Cloud Search zawiera kilka parametrów konfiguracyjnych udostępnionych przez Google. W pliku konfiguracji musisz zadeklarować te parametry podane przez Google:

  • W przypadku oprogramowania sprzęgającego zawartości musisz zadeklarować api.sourceId i api.serviceAccountPrivateKeyFile, ponieważ te parametry identyfikują lokalizację repozytorium i klucz prywatny, które są potrzebne, aby uzyskać dostęp do repozytorium.
  • W przypadku oprogramowania sprzęgającego tożsamości musisz zadeklarować api.identitySourceId, ponieważ ten parametr określa 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 Twojej firmy.

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

Możesz też definiować własne parametry repozytorium, które będą używane w pliku konfiguracji.

Przekaż plik konfiguracji do oprogramowania sprzęgającego

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

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

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

Określ strategię przemierzania

Podstawową funkcją oprogramowania sprzęgającego zawartości jest przemierzanie repozytorium i indeksowanie jego danych. Musisz wdrożyć strategię przemierzania w zależności od rozmiaru i układu danych w repozytorium. Możesz zaprojektować własną strategię lub wybrać jedną z tych strategii zaimplementowanych w pakiecie SDK:

Pełna strategia przemierzania

Pełna strategia przemierzania skanuje całe repozytorium i ślepo indeksuje każdy element. Ta strategia jest często wykorzystywana, gdy masz niewielkie repozytorium i możesz sobie pozwolić na całkowite przechodzenie całego procesu przy każdym indeksie.

Ta strategia przemierzania jest odpowiednia dla małych repozytoriów, których dane są głównie statyczne. Możesz używać tej strategii przemierzania także wtedy, gdy wykrywanie zmian jest trudne lub nie jest obsługiwane w repozytorium.

Lista strategii przemierzania

Strategia przemierzania listy skanuje całe repozytorium, w tym wszystkie węzły podrzędne, aby określić stan każdego elementu. Następnie oprogramowanie sprzęgające wykonuje drugi i indeksuje tylko nowe lub zaktualizowane od ostatniego indeksowania elementy. Strategia ta jest zwykle wykorzystywana do stopniowego aktualizowania istniejącego już indeksu (zamiast przeprowadzania pełnej migracji).

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

Omijanie wykresów

Strategia przemierzania wykresów skanuje cały węzeł nadrzędny, aby określić stan każdego elementu. W takim przypadku oprogramowanie sprzęgające przechodzi drugi i indeksuje tylko elementy w węźle głównym, które są nowe lub zostały zaktualizowane od ostatniego indeksowania. Oprogramowanie sprzęgające przekazuje też wszystkie identyfikatory podrzędne, a potem indeksuje elementy w węzłach podrzędnych, które są nowe lub zaktualizowane. Oprogramowanie sprzęgające jest rekurencyjne we wszystkich węzłach podrzędnych, dopóki nie zostaną rozwiązane. Takie omijanie jest zwykle używane w repozytoriach hierarchicznych, gdzie nie ma możliwości zastosowania listy wszystkich identyfikatorów.

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

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

Tworzenie pełnego oprogramowania sprzęgającego podczas przemierzania za pomocą klasy szablonu

Ta sekcja dokumentów zawiera fragmenty kodu z przykładu FullTraversalSample.

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

Punkt wejścia do oprogramowania sprzęgającego jest metodą 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, aby utworzyć instancję szablonu FullTraversalConnector. FullTraversalConnector akceptuje obiekt Repository, którego metody stosujesz. Z tego fragmentu kodu dowiesz się, jak wdrożyć metodę main():

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

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

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

Zaimplementuj interfejs Repository

Jedynym celem obiektu Repository jest omijanie i indeksowanie elementów repozytorium. Gdy tworzysz szablon oprogramowania sprzęgającego z użyciem szablonu, wystarczy, że zastąpisz tylko niektóre metody w interfejsie Repository. Metody, które zastępujesz, zależą od używanego szablonu i strategii przemierzania. W przypadku FullTraversalConnector zastąp te metody:

  • Metoda init(). Aby skonfigurować lub zainicjować 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 definicją 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 przejścia przyrostowego (zgodnie z definicją w konfiguracji), aby pobrać zmodyfikowane elementy i je zindeksować.

  • (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 pewien typ obiektu ApiOperation. Obiekt ApiOperation wykonuje działanie w postaci pojedynczego lub kilku wywołań IndexingService.indexItem() w celu przeprowadzenia rzeczywistego indeksowania repozytorium.

Pobierz niestandardowe parametry konfiguracji

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

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

FullTraversalSample.java
@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, aby przeanalizować dane jako odrębne fragmenty. Ten fragment z oprogramowania sprzęgającego samouczka wykorzystuje metodę getMultiValue, aby uzyskać listę nazw repozytoriów GitHub:

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

Pełna nawigacja

Zastąpienie getAllDocs() w celu przeprowadzenia pełnego przemierzania i indeksowania repozytorium. Metoda getAllDocs() akceptuje punkt kontrolny. Punkt kontrolny służy do wznowienia indeksowania określonego elementu, jeśli proces zostanie przerwany. W przypadku każdego elementu w repozytorium wykonaj te czynności w metodzie getAllDocs():

  1. Ustaw uprawnienia.
  2. Ustaw metadane indeksowanego elementu.
  3. Łączenie metadanych i elementów w jedno indeksowalne element RepositoryDoc
  4. Umieść każdy indeksowalny element w iteratorze zwróconym przez metodę getAllDocs(). Pamiętaj, że getAllDocs() zwraca CheckpointCloseableIterable, który jest powtarzaniem obiektów ApiOperation, a każdy obiekt reprezentujący żądanie do interfejsu API wykonano na RepositoryDoc, np. indeksował.

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

Ustawianie uprawnień elementu

Twoje repozytorium korzysta z listy kontroli dostępu (ACL) do identyfikowania użytkowników lub grup, które mają dostęp do danego elementu. Lista kontroli dostępu (ACL) to lista identyfikatorów grup lub użytkowników, którzy mają dostęp do elementu.

Musisz skopiować listę kontroli dostępu używaną przez repozytorium, aby mieć pewność, że tylko użytkownicy z dostępem do danego elementu będą mogli go zobaczyć w wynikach wyszukiwania. Podczas indeksowania elementu należy uwzględnić listę kontroli dostępu (ACL) dla elementu, aby umożliwić Google Cloud Search uzyskanie informacji potrzebnych do zapewnienia odpowiedniego poziomu dostępu do elementu.

Pakiet SDK oprogramowania sprzęgającego zawartości umożliwia udostępnienie bogatego zestawu klas i metod kontroli ACL w przypadku większości repozytoriów. Musisz przeanalizować listę kontroli dostępu dla każdego elementu w repozytorium i utworzyć odpowiednią listę kontroli dostępu dla Google Cloud Search podczas indeksowania elementu. Jeśli lista kontroli dostępu w repozytorium korzysta z takich pojęć jak dziedziczenie, ta funkcja może być trudna do modelowania. Więcej informacji na temat list kontroli dostępu Google Cloud Search znajdziesz w artykule Listy kontroli dostępu Google Cloud Search.

Uwaga: interfejs Cloud Search Indexing API obsługuje listy kontroli dostępu (ACL) z jedną domeną. Nie obsługuje ona list ACL dla wielu domen. Użyj klasy Acl.Builder, aby ustawić dostęp do każdego elementu za pomocą listy kontroli dostępu (ACL). Następujący fragment kodu pochodzący z pełnej próbki pokonywanej próby pozwala wszystkim użytkownikom lub „podmiotom zabezpieczeń” (getCustomerPrincipal()) na „odczytywanie” wszystkich elementów (.setReaders()) podczas wyszukiwania.

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

Aby prawidłowo modelować listy ACL dla repozytorium, musisz zrozumieć te zasady. Możesz na przykład zindeksować 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 podania dodatkowych informacji zawartych 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 ACL, adresu URL i wersji elementu. Fragment kodu poniżej pokazuje, jak utworzyć Item za pomocą klasy pomocniczej IndexingItemBuilder.

FullTraversalSample.java
// 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ć rzeczywisty element indeksowalny, korzystając z klasy RepositoryDoc.Builder. W poniższym przykładzie pokazano, jak utworzyć 1 element z możliwością indeksowania.

FullTraversalSample.java
// 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 ApiOperation, który przeprowadza właściwe żądanie IndexingService.indexItem().

Możesz też użyć metody setRequestMode() klasy RepositoryDoc.Builder, aby określić żądanie indeksowania jako ASYNCHRONOUS lub SYNCHRONOUS:

ASYNCHRONOUS
Tryb asynchroniczny powoduje wydłużenie czasu oczekiwania na indeksowanie i obsługuje duży limit przepustowości dla żądań indeksowania. W przypadku początkowego indeksowania (wypełnienia) całego repozytorium zaleca się tryb asynchroniczny.
SYNCHRONOUS
Tryb synchroniczny skraca czas oczekiwania na indeksowanie i wyświetlanie oraz ogranicza limit przepustowości. Do indeksowania aktualizacji i zmian w repozytorium zalecamy tryb synchroniczny. Jeśli nie określono inaczej, tryb żądania jest domyślnie ustawiony na SYNCHRONOUS.

Pakowanie każdego elementu możliwego do zindeksowania w iteracji

Metoda getAllDocs() zwraca obiekt Iterator, a zwłaszcza CheckpointCloseableIterable obiektów RepositoryDoc. Klasy CheckpointClosableIterableImpl.Builder możesz używać do tworzenia i zwracania iteratora. Ten fragment kodu pokazuje, jak utworzyć i zwrócić iterator.

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

SDK wykonuje każde wywołanie indeksowania wewnątrz iteratora.

Dalsze kroki

Oto co możesz zrobić:

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

Kolejka indeksowania Cloud Search jest używana do przechowywania identyfikatorów i opcjonalnych wartości skrótu każdego elementu w repozytorium. Oprogramowanie sprzęgające przemierzania listy przekazuje identyfikatory elementów do kolejki indeksowania Google Cloud Search i pobiera je pojedynczo do indeksowania. Google Cloud Search zarządza kolejkami i porównuje ich zawartość, aby ustalić, czy dany element został usunięty z repozytorium. Więcej informacji o kolejce indeksowania Cloud Search znajdziesz w sekcji Kolejka indeksowania Cloud Search.

Ta sekcja dokumentów zawiera fragmenty kodu z przykładu ListTraversalSample.

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

Punkt wejścia do oprogramowania sprzęgającego jest metodą 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, aby utworzyć instancję szablonu ListingConnector. ListingConnector akceptuje obiekt Repository, którego metody implementujesz. Ten fragment kodu instruuje, jak zintegrować ListingConnector i powiązane z nim Repository:

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

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

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

Zaimplementuj interfejs Repository

Jedynym celem obiektu Repository jest omijanie i indeksowanie elementów repozytorium. Aby utworzyć oprogramowanie sprzęgające zawartości, podczas korzystania z szablonu musisz zastąpić tylko niektóre metody w interfejsie Repository. Metody, które zastępujesz, zależą od używanego szablonu i strategii omijania. W przypadku ListingConnector zastąp te metody:

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

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

  • Metoda getDoc(). Aby dodać, zaktualizować, zmodyfikować lub usunąć elementy 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 przejścia przyrostowego (zgodnie z definicją w konfiguracji), aby pobrać zmodyfikowane elementy i je zindeksować.

  • (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 pewien typ obiektu ApiOperation. Obiekt ApiOperation wykonuje działanie w postaci pojedynczego lub kilku wywołań IndexingService.indexItem() w celu przeprowadzenia rzeczywistego indeksowania repozytorium.

Pobierz niestandardowe parametry konfiguracji

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

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

FullTraversalSample.java
@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, aby przeanalizować dane jako odrębne fragmenty. Ten fragment z oprogramowania sprzęgającego samouczka wykorzystuje metodę getMultiValue, aby uzyskać listę nazw repozytoriów GitHub:

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

Poruszanie się po liście

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

Następnie zastąp metodę getDoc() do obsługi każdego elementu w kolejce indeksowania Cloud Search.

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

Zastąp getIds(), aby pobrać identyfikatory elementów i powiązane z nimi wartości hash treści z repozytorium. Pary identyfikatorów i wartości hash są następnie pakowane w żądanie push do kolejki indeksowania Cloud Search. Zwykle najpierw są przekazywane identyfikatory nadrzędne lub nadrzędne, a potem identyfikatory podrzędne, dopóki nie zostanie przetworzona cała hierarchia elementów.

Metoda getIds() akceptuje punkt kontrolny, który reprezentuje ostatni element do zindeksowania. Punktu kontrolnego można użyć do wznowienia indeksowania określonego elementu, jeśli proces ten zostanie przerwany. Dla każdego elementu w repozytorium wykonaj te czynności w metodzie getIds():

  • Pobierz identyfikator każdego elementu i powiązane z nim wartości skrótu z repozytorium.
  • Umieść każdą parę identyfikatora i wartości skrótu w PushItems.
  • Połącz każdy element PushItems w iterator zwracany przez metodę getIds(). Pamiętaj, że getIds() zwraca błąd CheckpointCloseableIterable, który jest powtarzaniem obiektów ApiOperation, a każdy obiekt reprezentujący żądanie do interfejsu API wykonywane na RepositoryDoc, taki jak przekazywanie elementów do kolejki.

Następujący fragment kodu pokazuje, jak pobrać identyfikator każdego produktu oraz wartość skrótu i wstawić je do PushItems. PushItems to żądanie ApiOperation, które pozwala przenieść element do kolejki indeksowania Cloud Search.

ListaTraversalSample.java
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 użyć klasy PushItems.Builder do sparowania identyfikatorów i wartości skrótu w jednym żądaniu ApiOperation.

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

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

Pobieranie i pobieranie poszczególnych elementów

Zastąpienie getDoc() w celu obsługi każdego elementu w kolejce indeksowania Cloud Search. Element może być nowy, zmodyfikowany, niezmieniony lub nie może już istnieć w repozytorium źródłowym. Pobierz i zindeksuj każdy element, który jest nowy lub zmodyfikowany. Usuń z indeksu elementy, które nie istnieją już w repozytorium źródłowym.

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

  1. Sprawdź, czy identyfikator repozytorium znajduje się w kolejce indeksowania Cloud Search. Jeśli tak nie jest, usuń ten element z indeksu.

  2. Przeanalizuj indeks stanu elementu, a jeśli element nie został zmieniony (ACCEPTED), nie wykonuj żadnych działań.

  3. Indeks został zmieniony lub nowe elementy:

    1. Ustaw uprawnienia.
    2. Ustaw metadane indeksowanego elementu.
    3. Łączenie metadanych i elementów w jedno indeksowalne element RepositoryDoc
    4. Zwróć urządzenie RepositoryDoc.

Uwaga: szablon ListingConnector nie obsługuje zwracania null w metodzie getDoc(). Zwracanie wyników (null) w: NullPointerException.

Obsługa usuniętych elementów

Z tego fragmentu kodu dowiesz się, jak sprawdzić, czy element występuje w repozytorium, a jeśli tak, usuń go.

ListaTraversalSample.java
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 documents nie znajduje się w polu documentID, wróć do elementu APIOperations.deleteItem(resourceName), aby usunąć element z indeksu.

Obsługa niezmienionych elementów

Ten fragment kodu pokazuje, jak sprawdzać stan elementu w kolejce indeksowania Cloud Search i obsługiwać niezmieniony element.

ListaTraversalSample.java
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 hasz metadanych jest używany do określenia, czy element został zmieniony.

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

Ustawianie uprawnień elementu

Twoje repozytorium korzysta z listy kontroli dostępu (ACL) do identyfikowania użytkowników lub grup, które mają dostęp do danego elementu. Lista kontroli dostępu (ACL) to lista identyfikatorów grup lub użytkowników, którzy mają dostęp do elementu.

Musisz skopiować listę kontroli dostępu używaną przez repozytorium, aby mieć pewność, że tylko użytkownicy z dostępem do danego elementu będą mogli go zobaczyć w wynikach wyszukiwania. Podczas indeksowania elementu należy uwzględnić listę kontroli dostępu (ACL) dla elementu, aby umożliwić Google Cloud Search uzyskanie informacji potrzebnych do zapewnienia odpowiedniego poziomu dostępu do elementu.

Pakiet SDK oprogramowania sprzęgającego zawartości umożliwia udostępnienie bogatego zestawu klas i metod kontroli ACL w przypadku większości repozytoriów. Musisz przeanalizować listę kontroli dostępu dla każdego elementu w repozytorium i utworzyć odpowiednią listę kontroli dostępu dla Google Cloud Search podczas indeksowania elementu. Jeśli lista kontroli dostępu w repozytorium korzysta z takich pojęć jak dziedziczenie, ta funkcja może być trudna do modelowania. Więcej informacji na temat list kontroli dostępu Google Cloud Search znajdziesz w artykule Listy kontroli dostępu Google Cloud Search.

Uwaga: interfejs Cloud Search Indexing API obsługuje listy kontroli dostępu (ACL) z jedną domeną. Nie obsługuje ona list ACL dla wielu domen. Użyj klasy Acl.Builder, aby ustawić dostęp do każdego elementu za pomocą listy kontroli dostępu (ACL). Następujący fragment kodu pochodzący z pełnej próbki pokonywanej próby pozwala wszystkim użytkownikom lub „podmiotom zabezpieczeń” (getCustomerPrincipal()) na „odczytywanie” wszystkich elementów (.setReaders()) podczas wyszukiwania.

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

Aby prawidłowo modelować listy ACL dla repozytorium, musisz zrozumieć te zasady. Możesz na przykład zindeksować 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 podania dodatkowych informacji zawartych 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 ACL, adresu URL i wersji elementu. Fragment kodu poniżej pokazuje, jak utworzyć Item za pomocą klasy pomocniczej IndexingItemBuilder.

ListaTraversalSample.java
// 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ć rzeczywisty element, który można zindeksować, korzystając z RepositoryDoc.Builder. W poniższym przykładzie pokazano, jak utworzyć 1 element z możliwością indeksowania.

ListaTraversalSample.java
// 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 ApiOperation, który przeprowadza właściwe żądanie IndexingService.indexItem().

Możesz też użyć metody setRequestMode() klasy RepositoryDoc.Builder, aby określić żądanie indeksowania jako ASYNCHRONOUS lub SYNCHRONOUS:

ASYNCHRONOUS
Tryb asynchroniczny powoduje wydłużenie czasu oczekiwania na indeksowanie i obsługuje duży limit przepustowości dla żądań indeksowania. W przypadku początkowego indeksowania (wypełnienia) całego repozytorium zaleca się tryb asynchroniczny.
SYNCHRONOUS
Tryb synchroniczny skraca czas oczekiwania na indeksowanie i wyświetlanie oraz ogranicza limit przepustowości. Do indeksowania aktualizacji i zmian w repozytorium zalecamy tryb synchroniczny. Jeśli nie określono inaczej, tryb żądania jest domyślnie ustawiony na SYNCHRONOUS.

Dalsze kroki

Oto co możesz zrobić:

Utwórz oprogramowanie sprzęgające omijanie wykresów przy użyciu klasy szablonu

Kolejka indeksowania Cloud Search jest używana do przechowywania identyfikatorów i opcjonalnych wartości skrótu każdego elementu w repozytorium. Oprogramowanie sprzęgające do przemierzania wykresów przekazuje identyfikatory elementów do kolejki indeksowania Google Cloud Search i pobiera je pojedynczo do indeksowania. Google Cloud Search zarządza kolejkami i porównuje ich zawartość, aby określić stan elementu, na przykład to, czy element został usunięty z repozytorium. Więcej informacji o kolejce do indeksowania Cloud Search znajdziesz w artykule Kolejka indeksowania 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 nadrzędne i podrzędne, dopóki nie zostaną przetworzone wszystkie elementy.

Ta sekcja dokumentów zawiera fragmenty kodu z przykładu GraphTraversalSample.

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

Punkt wejścia do oprogramowania sprzęgającego jest metodą 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, aby utworzyć instancję szablonu ListingConnector. ListingConnector akceptuje obiekt Repository, którego metody stosujesz.

Ten fragment kodu instruuje, jak zintegrować ListingConnector i powiązane z nim Repository:

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

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

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

Zaimplementuj interfejs Repository

Jedynym celem obiektu Repository jest omijanie i indeksowanie elementów repozytorium. Aby utworzyć oprogramowanie sprzęgające treści, musisz zastąpić tylko niektóre metody w interfejsie Repository. Metody, które zastępujesz, zależą od używanego szablonu i strategii przemierzania. W przypadku instancji ListingConnector zastępujesz te metody:

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

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

  • Metoda getDoc(). Aby dodać, zaktualizować, zmodyfikować lub usunąć elementy 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 przejścia przyrostowego (zgodnie z definicją w konfiguracji), aby pobrać zmodyfikowane elementy i je zindeksować.

  • (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 pewien typ obiektu ApiOperation. Obiekt ApiOperation wykonuje działanie w postaci pojedynczego lub kilku wywołań IndexingService.indexItem() w celu przeprowadzenia rzeczywistego indeksowania repozytorium.

Pobierz niestandardowe parametry konfiguracji

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

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

FullTraversalSample.java
@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, aby przeanalizować dane jako odrębne fragmenty. Ten fragment z oprogramowania sprzęgającego samouczka wykorzystuje metodę getMultiValue, aby uzyskać listę nazw repozytoriów GitHub:

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

Poruszanie się po wykresie

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

Następnie zastąp metodę getDoc() do obsługi każdego elementu w kolejce indeksowania Cloud Search.

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

Zastąp getIds(), aby pobrać identyfikatory elementów i powiązane z nimi wartości hash treści z repozytorium. Pary identyfikatorów i wartości hash są następnie pakowane w żądanie push do kolejki indeksowania Cloud Search. Zwykle najpierw są przekazywane identyfikatory nadrzędne lub nadrzędne, a potem identyfikatory podrzędne, dopóki nie zostanie przetworzona cała hierarchia elementów.

Metoda getIds() akceptuje punkt kontrolny, który reprezentuje ostatni element do zindeksowania. Punktu kontrolnego można użyć do wznowienia indeksowania określonego elementu, jeśli proces ten zostanie przerwany. Dla każdego elementu w repozytorium wykonaj te czynności w metodzie getIds():

  • Pobierz identyfikator każdego elementu i powiązane z nim wartości skrótu z repozytorium.
  • Umieść każdą parę identyfikatora i wartości skrótu w PushItems.
  • Połącz każdy element PushItems w iterator zwracany za pomocą metody getIds(). Pamiętaj, że getIds() zwraca błąd CheckpointCloseableIterable, który jest powtarzaniem obiektów ApiOperation, a każdy obiekt reprezentujący żądanie do interfejsu API wykonywane na RepositoryDoc, taki jak przekazywanie elementów do kolejki.

Ten fragment kodu pokazuje, jak pobrać identyfikator każdego produktu oraz wartość skrótu i wstawić je do PushItems. PushItems to żądanie ApiOperation, które pozwala przenieść element do kolejki indeksowania Cloud Search.

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

Poniższy fragment kodu pokazuje, jak użyć klasy PushItems.Builder do sparowania identyfikatorów i wartości skrótu w jednym żądaniu ApiOperation.

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

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

Pobieranie i pobieranie poszczególnych elementów

Zastąpienie getDoc() w celu obsługi każdego elementu w kolejce indeksowania Cloud Search. Element może być nowy, zmodyfikowany, niezmieniony lub nie może już istnieć w repozytorium źródłowym. Pobierz i zindeksuj każdy element, który jest nowy lub zmodyfikowany. Usuń z indeksu elementy, które nie istnieją już w repozytorium źródłowym.

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

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

  2. Indeks został zmieniony lub nowe elementy:

    1. Ustaw uprawnienia.
    2. Ustaw metadane indeksowanego elementu.
    3. Łączenie metadanych i elementów w jedno indeksowalne element RepositoryDoc
    4. Umieść identyfikatory podrzędne w kolejce indeksowania Cloud Search do dalszego przetworzenia.
    5. Zwróć urządzenie RepositoryDoc.

Obsługa usuniętych elementów

Ten fragment kodu pokazuje, jak sprawdzić, czy element występuje w indeksie, i czy go nie usuwa.

WykresTraversalSample.java
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);

Ustawianie uprawnień elementu

Twoje repozytorium korzysta z listy kontroli dostępu (ACL) do identyfikowania użytkowników lub grup, które mają dostęp do danego elementu. Lista kontroli dostępu (ACL) to lista identyfikatorów grup lub użytkowników, którzy mają dostęp do elementu.

Musisz skopiować listę kontroli dostępu używaną przez repozytorium, aby mieć pewność, że tylko użytkownicy z dostępem do danego elementu będą mogli go zobaczyć w wynikach wyszukiwania. Podczas indeksowania elementu należy uwzględnić listę kontroli dostępu (ACL) dla elementu, aby umożliwić Google Cloud Search uzyskanie informacji potrzebnych do zapewnienia odpowiedniego poziomu dostępu do elementu.

Pakiet SDK oprogramowania sprzęgającego zawartości umożliwia udostępnienie bogatego zestawu klas i metod kontroli ACL w przypadku większości repozytoriów. Musisz przeanalizować listę kontroli dostępu dla każdego elementu w repozytorium i utworzyć odpowiednią listę kontroli dostępu dla Google Cloud Search podczas indeksowania elementu. Jeśli lista kontroli dostępu w repozytorium korzysta z takich pojęć jak dziedziczenie, ta funkcja może być trudna do modelowania. Więcej informacji na temat list kontroli dostępu Google Cloud Search znajdziesz w artykule Listy kontroli dostępu Google Cloud Search.

Uwaga: interfejs Cloud Search Indexing API obsługuje listy kontroli dostępu (ACL) z jedną domeną. Nie obsługuje ona list ACL dla wielu domen. Użyj klasy Acl.Builder, aby ustawić dostęp do każdego elementu za pomocą listy kontroli dostępu (ACL). Następujący fragment kodu pochodzący z pełnej próbki pokonywanej próby pozwala wszystkim użytkownikom lub „podmiotom zabezpieczeń” (getCustomerPrincipal()) na „odczytywanie” wszystkich elementów (.setReaders()) podczas wyszukiwania.

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

Aby prawidłowo modelować listy ACL dla repozytorium, musisz zrozumieć te zasady. Możesz na przykład zindeksować 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 podania dodatkowych informacji zawartych 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 ACL, adresu URL i wersji elementu. Fragment kodu poniżej pokazuje, jak utworzyć Item za pomocą klasy pomocniczej IndexingItemBuilder.

WykresTraversalSample.java
// 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ć rzeczywisty element, który można zindeksować, korzystając z RepositoryDoc.Builder. W poniższym przykładzie pokazano, jak utworzyć 1 element z możliwością indeksowania.

WykresTraversalSample.java
// 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 ApiOperation, który przeprowadza właściwe żądanie IndexingService.indexItem().

Możesz też użyć metody setRequestMode() klasy RepositoryDoc.Builder, aby określić żądanie indeksowania jako ASYNCHRONOUS lub SYNCHRONOUS:

ASYNCHRONOUS
Tryb asynchroniczny powoduje wydłużenie czasu oczekiwania na indeksowanie i obsługuje duży limit przepustowości dla żądań indeksowania. W przypadku początkowego indeksowania (wypełnienia) całego repozytorium zaleca się tryb asynchroniczny.
SYNCHRONOUS
Tryb synchroniczny skraca czas oczekiwania na indeksowanie i wyświetlanie oraz ogranicza limit przepustowości. Do indeksowania aktualizacji i zmian w repozytorium zalecamy tryb synchroniczny. Jeśli nie określono inaczej, tryb żądania jest domyślnie ustawiony na SYNCHRONOUS.

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

Następujący fragment kodu pokazuje, jak dołączyć identyfikatory podrzędne dla aktualnie przetwarzanego elementu nadrzędnego do przetwarzania. Identyfikatory są przetwarzane po zindeksowaniu elementu nadrzędnego.

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

Dalsze kroki

Oto co możesz zrobić:

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

Z poniższych sekcji dowiesz się, jak utworzyć oprogramowanie sprzęgające treści za pomocą interfejsu API REST.

Określ strategię przemierzania

Podstawową funkcją oprogramowania sprzęgającego zawartości jest przemierzanie repozytorium i indeksowanie jego danych. Musisz wdrożyć strategię przemierzania w zależności od rozmiaru i układu danych w repozytorium. Oto trzy typowe strategie przemierzania:

Pełna strategia przemierzania

Pełna strategia przemierzania skanuje całe repozytorium i ślepo indeksuje każdy element. Ta strategia jest często wykorzystywana, gdy masz niewielkie repozytorium i możesz sobie pozwolić na całkowite przechodzenie całego procesu przy każdym indeksie.

Ta strategia przemierzania jest odpowiednia dla małych repozytoriów, których dane są głównie statyczne. Możesz używać tej strategii przemierzania także wtedy, gdy wykrywanie zmian jest trudne lub nie jest obsługiwane w repozytorium.

Lista strategii przemierzania

Strategia przemierzania listy skanuje całe repozytorium, w tym wszystkie węzły podrzędne, aby określić stan każdego elementu. Następnie oprogramowanie sprzęgające wykonuje drugi i indeksuje tylko nowe lub zaktualizowane od ostatniego indeksowania elementy. Strategia ta jest zwykle wykorzystywana do stopniowego aktualizowania istniejącego już indeksu (zamiast przeprowadzania pełnej migracji).

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

Omijanie wykresów

Strategia przemierzania wykresów skanuje cały węzeł nadrzędny, aby określić stan każdego elementu. W takim przypadku oprogramowanie sprzęgające przechodzi drugi i indeksuje tylko elementy w węźle głównym, które są nowe lub zostały zaktualizowane od ostatniego indeksowania. Oprogramowanie sprzęgające przekazuje też wszystkie identyfikatory podrzędne, a potem indeksuje elementy w węzłach podrzędnych, które są nowe lub zaktualizowane. Oprogramowanie sprzęgające jest rekurencyjne we wszystkich węzłach podrzędnych, dopóki nie zostaną rozwiązane. Takie omijanie jest zwykle używane w repozytoriach hierarchicznych, gdzie nie ma możliwości zastosowania listy wszystkich identyfikatorów.

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

Wdrażanie strategii przemierzania i indeksowanie elementów

Każdy indeksowalny element w Cloud Search jest określany w Cloud Search API jako element. Elementem może być plik, folder, wiersz w pliku CSV lub rekord bazy danych.

Po zarejestrowaniu schematu możesz uzupełnić indeks według:

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

  2. (Opcjonalnie) Używanie media.upload do przesyłania plików multimedialnych na potrzeby indeksowania.

  3. Aby zindeksować element, użyj narzędzia items.index. Jeśli na przykład Twój schemat używa definicji obiektu w schemacie filmowym, żądanie indeksowania 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) Aby sprawdzić, czy element item został zindeksowany, użyj wywołań items.get.

Aby przeprowadzić pełne ominięcie, musisz okresowo indeksować całe repozytorium. Aby korzystać z list lub wykresów, musisz zaimplementować kod, by obsługiwać zmiany w repozytorium.

Obsługa zmian w repozytorium

Możesz okresowo gromadzić i indeksować każdy element z repozytorium, aby przeprowadzić pełne indeksowanie. Chociaż indeksowanie jest aktualne, pełne indeksowanie może być kosztowne w przypadku dużych i hierarchicznych repozytoriów.

Zamiast korzystać z wywołań indeksowania do indeksowania całego repozytorium, możesz też użyć kolejki indeksowania Google Cloud jako mechanizmu do śledzenia zmian i indeksowania tylko tych zmienionych elementów. Za pomocą żądań items.push możesz przekazywać elementy do kolejki w celu późniejszego sondowania i aktualizowania. Więcej informacji o kolejce do indeksowania Google Cloud znajdziesz w tym artykule.

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