Tworzenie łącznika treści

Oprogramowanie sprzęgające treści to program służący do przeglądania danych w repozytorium firmy i wypełniania źródeł danych. Google udostępnia te opcje tworzenia oprogramowania sprzęgającego treści:

• SDK Content Connector. To dobre rozwiązanie, jeśli programujesz w języku Java. Content Connector SDK to otoka interfejsu API REST, która umożliwia szybkie tworzenie oprogramowania sprzęgającego. Aby utworzyć łącznik treści za pomocą pakietu SDK, zapoznaj się z sekcją Tworzenie oprogramowania sprzęgającego treści za pomocą pakietu SDK Content Connector.

• Niskopoziomowego interfejsu API typu REST lub bibliotek API. Użyj tych opcji, jeśli nie programujesz w Javie albo jeśli Twoja baza kodu lepiej pasuje do interfejsu API typu REST lub biblioteki. Aby utworzyć łącznik treści za pomocą interfejsu API REST, zapoznaj się z artykułem Tworzenie łącznika treści za pomocą interfejsu API REST.

Typowy łącznik treści wykonuje te zadania:

1. Odczyt i przetwarzanie parametrów konfiguracji.
2. Pobiera z repozytorium treści innej firmy określone fragmenty danych do indeksowania, nazywane „elementami”.
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 powiadomień o zmianach z repozytorium treści innej firmy. Powiadomienia o zmianach są konwertowane na prośby o indeksowanie, aby zapewnić synchronizację źródła danych Cloud Search z repozytorium zewnętrznym. Łącznik wykonuje to zadanie tylko wtedy, gdy repozytorium obsługuje wykrywanie zmian.

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

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

Skonfiguruj zależności

Aby korzystać z pakietu SDK, musisz w pliku kompilacji uwzględnić określone zależności. Kliknij kartę poniżej, aby wyświetlić zależności dotyczące środowiska kompilacji:

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

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

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ą zdefiniowane w postaci par klucz-wartość, np. api.sourceId=1234567890abcdef.

Pakiet Google Cloud Search SDK zawiera kilka parametrów konfiguracyjnych dostarczanych przez Google, które są używane przez wszystkie oprogramowanie sprzęgające. W pliku konfiguracji musisz zadeklarować te parametry dostarczone przez 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 potrzebny do uzyskania dostępu 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ąpić wartości domyślnych innych parametrów dostarczonych przez Google, nie musisz deklarować ich w pliku konfiguracji. Więcej informacji o parametrach konfiguracji dostarczonych przez Google, na przykład o generowaniu określonych identyfikatorów i kluczy, znajdziesz w artykule o parametrach konfiguracyjnych udostępnionych przez Google.

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

Przekaż plik konfiguracji do oprogramowania sprzęgającego

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

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

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

Określ strategię przemierzania

Główną funkcją łącznika treści jest przemierzanie repozytorium i indeksowanie jego danych. Musisz wdrożyć strategię przemierzania opartą na rozmiarze i układzie danych w repozytorium. Możesz opracować własną strategię lub wybrać jedną z tych strategii wdrożonych w pakiecie SDK:

Strategia pełnego przemierzania

Strategia pełnego przemierzania skanuje całe repozytorium i indeksuje na ślepo każdy element. Ta strategia jest często stosowana, gdy masz małe repozytorium i możesz pozwolić sobie na wysiłek związany z pełnym przemierzaniem przy każdym indeksowaniu.

Ta strategia przemierzania jest odpowiednia w przypadku małych repozytoriów zawierających głównie dane statyczne, niehierarchiczne. Możesz też używać tej strategii przemierzania, jeśli 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, aby określić stan każdego elementu. Następnie oprogramowanie sprzęgające wykonuje drugie przejście i indeksuje tylko te elementy, które są nowe lub zostały zaktualizowane od ostatniego indeksowania. Ta strategia jest zwykle wykorzystywana do wykonywania przyrostowych aktualizacji istniejącego indeksu (zamiast konieczności wykonywania pełnego przemierzania za każdym razem, gdy aktualizujesz indeks).

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

Omijanie wykresu

Strategia przemierzania wykresu skanuje cały węzeł nadrzędny, określając stan każdego elementu. Następnie oprogramowanie sprzęgające wykonuje drugą procedurę 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 przechodzi do kolejnych węzłów podrzędnych w sposób rekurencyjny, dopóki nie naprawi się wszystkich elementów. Takie przemierzanie jest zwykle używane w przypadku repozytoriów hierarchicznych, w których nie można wyliczać 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 implementowana przez klasę oprogramowania sprzęgającego szablonu w pakiecie SDK. Możesz wdrożyć własną strategię przemierzania, jednak te szablony 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 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 przemierzania pełnego za pomocą klasy szablonu

Ta sekcja dokumentacji dotyczy fragmentów kodu z przykładu FullTraversalSample.

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

Punktem wejścia do oprogramowania sprzęgającego jest metoda main(). Podstawowym 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 FullTraversalConnector. FullTraversalConnector akceptuje obiekt Repository, którego metody implementujesz. Ten fragment kodu pokazuje, jak wdrożyć metodę main():

/**
 * 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 upewnić się, że metoda Configuration nie została zainicjowana.
2. Inicjuje obiekt Configuration z parami klucz-wartość dostarczonymi przez Google. Każda para klucz-wartość jest przechowywana w obiekcie ConfigValue w obiekcie Configuration.

Wdrażanie interfejsu Repository

Jedynym celem obiektu Repository jest przemierzanie i indeksowanie elementów repozytorium. Aby utworzyć łącznik treści, jeśli używasz szablonu, musisz zastąpić tylko niektóre metody w interfejsie Repository. Metody zastępowania zależą od używanego szablonu i strategii przemierzania. W przypadku metody FullTraversalConnector zastąp te metody:

• Metoda init(). Aby przeprowadzić konfigurację i inicjalizację 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 przemierzania przyrostowego (zgodnie z definicją w konfiguracji) w celu pobrania zmodyfikowanych elementów i ich zindeksowania.

• (opcjonalnie) Metoda close(). Jeśli chcesz 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 określony typ obiektu ApiOperation. Obiekt ApiOperation wykonuje działanie w formie pojedynczego wywołania IndexingService.indexItem() lub wielu wywołań, aby wykonać faktyczne indeksowanie repozytorium.

Pobierz niestandardowe parametry konfiguracji

W ramach konfiguracji oprogramowania sprzęgającego musisz pobrać wszelkie parametry niestandardowe z obiektu Configuration. 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 ze źródła FullTraversalSample pokazuje, jak pobrać z obiektu Configuration jedną niestandardową wartość całkowitą:

@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 typów klasy Configuration do przeanalizowania danych na dyskretne fragmenty. Ten fragment kodu z oprogramowania sprzęgającego samouczka używa metody getMultiValue do pobrania listy nazw repozytoriów GitHub:

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

Wykonaj pełne przemierzenie

Zastąp getAllDocs(), aby wykonać pełne przemierzenie i zindeksować repozytorium. Metoda getAllDocs() akceptuje punkt kontrolny. Służy on do wznowienia indeksowania określonego elementu, jeśli ten proces zostanie przerwany. W przypadku każdego elementu w repozytorium wykonaj te czynności w metodzie getAllDocs():

1. Ustaw uprawnienia.
2. Ustaw metadane zindeksowanego elementu.
3. Połącz metadane i element w jeden możliwy do indeksowania element RepositoryDoc.
4. Umieść każdy element możliwy do indeksowania w iterator zwrócony przez metodę getAllDocs(). Zwróć uwagę, że getAllDocs() zwraca obiekt CheckpointCloseableIterable, który jest iteracją obiektów ApiOperation, z których każdy reprezentuje żądanie do interfejsu API wykonane w obiekcie RepositoryDoc, np. jego zindeksowanie.

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

Ustawianie uprawnień elementu

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

Musisz zduplikować listę kontroli dostępu używaną w repozytorium, aby mieć pewność, że tylko użytkownicy z dostępem do elementu zobaczą ten element w wynikach wyszukiwania. Podczas indeksowania elementu musi być uwzględniana lista kontroli dostępu (ACL), aby usługa Google Cloud Search miała informacje potrzebne do zapewnienia odpowiedniego poziomu dostępu do tego elementu.

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

Uwaga: interfejs Cloud Search Indexing API obsługuje listy kontroli dostępu (ACL) w jednej domenie. Nie obsługuje międzydomenowych list kontroli dostępu. Aby ustawić dostęp do poszczególnych elementów za pomocą listy kontroli dostępu, użyj klasy Acl.Builder. Poniższy fragment kodu, pobrany z pełnego przykładowego fragmentu kodu, umożliwia wszystkim użytkownikom lub podmiotom zabezpieczeń (getCustomerPrincipal()) „odczytującymi” wszystkie elementy (.setReaders()) podczas wyszukiwania.

// 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 w repozytorium, musisz znać listy kontroli dostępu. Możesz na przykład indeksować pliki w systemie plików, który korzysta z pewnego modelu dziedziczenia, w którym foldery podrzędne dziedziczą uprawnienia z folderów nadrzędnych. Dziedziczenie ACL w modelowaniu wymaga dodatkowych informacji zawartych na 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.

// 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 indeksowania

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

// 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 obiektu ApiOperation, który wykonuje faktyczne żądanie IndexingService.indexItem().

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

ASYNCHRONOUS

Tryb asynchroniczny wydłuża czas oczekiwania na indeksowanie i uwzględnia duży limit przepustowości żądań indeksowania. Tryb asynchroniczny jest zalecany w przypadku początkowego indeksowania (zapasowego) całego repozytorium.

SYNCHRONOUS

Tryb synchroniczny skraca czas oczekiwania od indeksowania do czasu wyświetlania i uwzględnia ograniczony limit przepustowości. Tryb synchroniczny jest zalecany do indeksowania aktualizacji i zmian w repozytorium. Jeśli tryb żądania nie zostanie określony, domyślnie ustawiony jest tryb SYNCHRONOUS.

Spakuj każdy element możliwy do zindeksowania w iteratorze

Metoda getAllDocs() zwraca Iterator, a w szczególności CheckpointCloseableIterable obiektów RepositoryDoc. Za pomocą klasy CheckpointClosableIterableImpl.Builder możesz utworzyć i zwrócić iterator. Fragment kodu poniżej pokazuje, jak utworzyć i zwrócić iterator.

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

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

Dalsze kroki

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

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

Utwórz oprogramowanie sprzęgające 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 przemierzania list przekazuje identyfikatory elementów do kolejki indeksowania Google Cloud Search i pobiera je pojedynczo do indeksowania. Google Cloud Search utrzymuje kolejki i porównuje ich zawartość, aby określić stan elementu, na przykład to, czy został on usunięty z repozytorium. Więcej informacji o kolejce indeksowania w Cloud Search znajdziesz w artykule Kolejka indeksowania w Cloud Search.

Ta sekcja dokumentacji dotyczy fragmentów kodu z przykładu ListTraversalSample.

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

Punktem wejścia do oprogramowania sprzęgającego jest metoda main(). Podstawowym 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órego metody stosujesz. Ten fragment kodu pokazuje, jak instalować obiekt ListingConnector i powiązany z nim element Repository:

/**
 * 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 upewnić się, że metoda Configuration nie została zainicjowana.
2. Inicjuje obiekt Configuration z parami klucz-wartość dostarczonymi przez Google. Każda para klucz-wartość jest przechowywana w obiekcie ConfigValue w obiekcie Configuration.

Wdrażanie interfejsu Repository

Jedynym celem obiektu Repository jest przemierzanie i indeksowanie elementów repozytorium. Jeśli używasz szablonu, musisz zastąpić tylko niektóre metody w interfejsie Repository, aby utworzyć łącznik treści. Metody zastępowania zależą od używanego szablonu i strategii przemierzania. W przypadku metody ListingConnector zastąp te metody:

• Metoda init(). Aby przeprowadzić konfigurację i inicjalizację 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 dodać nowe, 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 przemierzania przyrostowego (zgodnie z definicją w konfiguracji) w celu pobrania zmodyfikowanych elementów i ich zindeksowania.

• (opcjonalnie) Metoda close(). Jeśli chcesz 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 określony typ obiektu ApiOperation. Obiekt ApiOperation wykonuje działanie w formie pojedynczego wywołania IndexingService.indexItem() lub wielu wywołań, aby wykonać faktyczne indeksowanie repozytorium.

Pobierz niestandardowe parametry konfiguracji

W ramach konfiguracji oprogramowania sprzęgającego musisz pobrać wszelkie parametry niestandardowe z obiektu Configuration. 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 ze źródła FullTraversalSample pokazuje, jak pobrać z obiektu Configuration jedną niestandardową wartość całkowitą:

@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 typów klasy Configuration do przeanalizowania danych na dyskretne fragmenty. Ten fragment kodu z oprogramowania sprzęgającego samouczka używa metody getMultiValue do pobrania listy nazw repozytoriów GitHub:

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

Przeprowadź przemierzanie listy

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

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

Przekazuj identyfikatory elementów i wartości skrótu

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

Metoda getIds() akceptuje punkt kontrolny reprezentujący ostatni element do zindeksowania. Za jego pomocą możesz wznowić indeksowanie określonego elementu, jeśli ten proces zostanie przerwany. W przypadku 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.
• Umieść każdą parę identyfikatora i wartości skrótu w PushItems.
• Połącz poszczególne parametry PushItems w iterator zwrócony przez metodę getIds(). Zwróć uwagę, że getIds() zwraca obiekt CheckpointCloseableIterable będący iteracją obiektów ApiOperation, czyli każdy obiekt reprezentujący żądanie do interfejsu API wykonane w obiekcie RepositoryDoc, na przykład przez przekazanie elementów do kolejki.

Ten fragment kodu pokazuje, jak uzyskać identyfikator i wartość skrótu każdego produktu oraz wstawić je w PushItems. PushItems to żądanie ApiOperation umożliwiające przekazanie elementu do kolejki indeksowania w Cloud Search.

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

Ten fragment kodu pokazuje, jak za pomocą klasy PushItems.Builder spakować identyfikatory i wartości skrótu do pojedynczego komunikatu pushApiOperation.

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 przetwarzania.

Pobieranie i obsługa każdego elementu

Zastąp getDoc(), aby obsługiwać każdy element w kolejce indeksowania w Cloud Search. Element może być nowy, zmodyfikowany lub niezmieniony albo nie może już istnieć w repozytorium źródłowym. Pobierz i zindeksuj każdy nowy lub zmodyfikowany element. Usunąć 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 za pomocą metody getDoc():

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

2. Przeprowadź ankietę w indeksie pod kątem stanu elementu i jeśli element się nie zmieni (ACCEPTED), nie rób nic.

3. Zmieniony indeks lub nowe elementy:

   1. Ustaw uprawnienia.
   2. Ustaw metadane zindeksowanego elementu.
   3. Połącz metadane i element w jeden możliwy do indeksowania element RepositoryDoc.
   4. Zwrot RepositoryDoc.

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

Obsługa usuniętych elementów

Ten fragment kodu pokazuje, jak sprawdzić, czy element istnieje w repozytorium, a jeśli nie, go usunąć.

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 documents nie znaleziono elementu documentID, zwróć APIOperations.deleteItem(resourceName), aby usunąć element z indeksu.

Obsługa niezmienionych elementów

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

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 oraz inne metadane, które mogą wskazywać na zmianę. W tym przykładzie do określenia, czy element uległ zmianie, używany jest hasz metadanych.

/**
 * 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

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

Musisz zduplikować listę kontroli dostępu używaną w repozytorium, aby mieć pewność, że tylko użytkownicy z dostępem do elementu zobaczą ten element w wynikach wyszukiwania. Podczas indeksowania elementu musi być uwzględniana lista kontroli dostępu (ACL), aby usługa Google Cloud Search miała informacje potrzebne do zapewnienia odpowiedniego poziomu dostępu do tego elementu.

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

Uwaga: interfejs Cloud Search Indexing API obsługuje listy kontroli dostępu (ACL) w jednej domenie. Nie obsługuje międzydomenowych list kontroli dostępu. Aby ustawić dostęp do poszczególnych elementów za pomocą listy kontroli dostępu, użyj klasy Acl.Builder. Poniższy fragment kodu, pobrany z pełnego przykładowego fragmentu kodu, umożliwia wszystkim użytkownikom lub podmiotom zabezpieczeń (getCustomerPrincipal()) „odczytującymi” wszystkie elementy (.setReaders()) podczas wyszukiwania.

// 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 w repozytorium, musisz znać listy kontroli dostępu. Możesz na przykład indeksować pliki w systemie plików, który korzysta z pewnego modelu dziedziczenia, w którym foldery podrzędne dziedziczą uprawnienia z folderów nadrzędnych. Dziedziczenie ACL w modelowaniu wymaga dodatkowych informacji zawartych na 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.

// 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 indeksowania

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

// 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 obiektu ApiOperation, który wykonuje rzeczywiste żądanie IndexingService.indexItem().

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

ASYNCHRONOUS

Tryb asynchroniczny wydłuża czas oczekiwania na indeksowanie i uwzględnia duży limit przepustowości żądań indeksowania. Tryb asynchroniczny jest zalecany w przypadku początkowego indeksowania (zapasowego) całego repozytorium.

SYNCHRONOUS

Tryb synchroniczny skraca czas oczekiwania od indeksowania do czasu wyświetlania i uwzględnia ograniczony limit przepustowości. Tryb synchroniczny jest zalecany do indeksowania aktualizacji i zmian w repozytorium. Jeśli tryb żądania nie zostanie określony, domyślnie ustawiony jest tryb SYNCHRONOUS.

Dalsze kroki

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

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

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 przemierzania wykresów przekazuje identyfikatory elementów do kolejki indeksowania w Google Cloud Search i pobiera je pojedynczo w celu zindeksowania. Google Cloud Search utrzymuje kolejki i porównuje ich zawartość, aby określić stan elementu, na przykład czy został on 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 rekurencyjnie przetwarza identyfikatory elementów nadrzędnych i podrzędnych, aż obejmą wszystkie elementy.

Ta sekcja dokumentacji dotyczy fragmentów kodu z przykładu GraphTraversalSample.

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

Punktem wejścia do oprogramowania sprzęgającego jest metoda main(). Podstawowym 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, aby utworzyć instancję szablonu ListingConnector. ListingConnector akceptuje obiekt Repository, którego metody implementujesz.

Ten fragment kodu pokazuje, jak instalować obiekt ListingConnector i powiązany z nim element Repository:

/**
 * 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 upewnić się, że metoda Configuration nie została zainicjowana.
2. Inicjuje obiekt Configuration z parami klucz-wartość dostarczonymi przez Google. Każda para klucz-wartość jest przechowywana w obiekcie ConfigValue w obiekcie Configuration.

Wdrażanie interfejsu Repository

Jedynym celem obiektu Repository jest przemierzanie i indeksowanie elementów repozytorium. Jeśli używasz szablonu, musisz zastąpić tylko niektóre metody w interfejsie Repository, aby utworzyć łącznik treści. Metody zastępowania zależą od używanego szablonu i strategii przemierzania. W przypadku metody ListingConnector zastępujesz te metody:

• Metoda init(). Aby przeprowadzić konfigurację i inicjalizację 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 dodać nowe, 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 przemierzania przyrostowego (zgodnie z definicją w konfiguracji) w celu pobrania zmodyfikowanych elementów i ich zindeksowania.

• (opcjonalnie) Metoda close(). Jeśli chcesz 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 określony typ obiektu ApiOperation. Obiekt ApiOperation wykonuje działanie w formie pojedynczego wywołania IndexingService.indexItem() lub wielu wywołań, aby wykonać faktyczne indeksowanie repozytorium.

Pobierz niestandardowe parametry konfiguracji

W ramach konfiguracji oprogramowania sprzęgającego musisz pobrać wszelkie parametry niestandardowe z obiektu Configuration. 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 ze źródła FullTraversalSample pokazuje, jak pobrać z obiektu Configuration jedną niestandardową wartość całkowitą:

@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 typów klasy Configuration do przeanalizowania danych na dyskretne fragmenty. Ten fragment kodu z oprogramowania sprzęgającego samouczka używa metody getMultiValue do pobrania listy nazw repozytoriów GitHub:

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

Wykonaj przemierzanie wykresu

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

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

Przekazuj identyfikatory elementów i wartości skrótu

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

Metoda getIds() akceptuje punkt kontrolny reprezentujący ostatni element do zindeksowania. Za jego pomocą możesz wznowić indeksowanie określonego elementu, jeśli ten proces zostanie przerwany. W przypadku 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.
• Umieść każdą parę identyfikatora i wartości skrótu w PushItems.
• Połącz każde polecenie PushItems w iterator zwrócony przez metodę getIds(). Zwróć uwagę, że getIds() zwraca obiekt CheckpointCloseableIterable będący iteracją obiektów ApiOperation, czyli każdy obiekt reprezentujący żądanie do interfejsu API wykonane w obiekcie RepositoryDoc, na przykład przez przekazanie elementów do kolejki.

Ten fragment kodu pokazuje, jak uzyskać identyfikator produktu i wartość skrótu oraz wstawić je w PushItems. Żądanie PushItems to żądanie ApiOperation umożliwiające przekazanie elementu do kolejki indeksowania w Cloud Search.

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

Ten fragment kodu pokazuje, jak za pomocą klasy PushItems.Builder spakować identyfikatory i wartości skrótu do pojedynczego komunikatu push ApiOperation.

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 przetwarzania.

Pobieranie i obsługa każdego elementu

Zastąp getDoc(), aby obsługiwać każdy element w kolejce indeksowania w Cloud Search. Element może być nowy, zmodyfikowany lub niezmieniony albo nie może już istnieć w repozytorium źródłowym. Pobierz i zindeksuj każdy nowy lub zmodyfikowany element. Usunąć 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 za pomocą metody getDoc():

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

2. Zmieniony indeks lub nowe elementy:

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

Obsługa usuniętych elementów

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

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

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

Musisz zduplikować listę kontroli dostępu używaną w repozytorium, aby mieć pewność, że tylko użytkownicy z dostępem do elementu zobaczą ten element w wynikach wyszukiwania. Podczas indeksowania elementu musi być uwzględniana lista kontroli dostępu (ACL), aby usługa Google Cloud Search miała informacje potrzebne do zapewnienia odpowiedniego poziomu dostępu do tego elementu.

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

Uwaga: interfejs Cloud Search Indexing API obsługuje listy kontroli dostępu (ACL) w jednej domenie. Nie obsługuje międzydomenowych list kontroli dostępu. Aby ustawić dostęp do poszczególnych elementów za pomocą listy kontroli dostępu, użyj klasy Acl.Builder. Poniższy fragment kodu, pobrany z pełnego przykładowego fragmentu kodu, umożliwia wszystkim użytkownikom lub podmiotom zabezpieczeń (getCustomerPrincipal()) „odczytującymi” wszystkie elementy (.setReaders()) podczas wyszukiwania.

// 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 w repozytorium, musisz znać listy kontroli dostępu. Możesz na przykład indeksować pliki w systemie plików, który korzysta z pewnego modelu dziedziczenia, w którym foldery podrzędne dziedziczą uprawnienia z folderów nadrzędnych. Dziedziczenie ACL w modelowaniu wymaga dodatkowych informacji zawartych na 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.

// 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 indeksowania

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

// 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 obiektu ApiOperation, który wykonuje faktyczne żądanie IndexingService.indexItem().

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

ASYNCHRONOUS

Tryb asynchroniczny wydłuża czas oczekiwania na indeksowanie i uwzględnia duży limit przepustowości żądań indeksowania. Tryb asynchroniczny jest zalecany w przypadku początkowego indeksowania (zapasowego) całego repozytorium.

SYNCHRONOUS

Tryb synchroniczny skraca czas oczekiwania od indeksowania do czasu wyświetlania i uwzględnia ograniczony limit przepustowości. Tryb synchroniczny jest zalecany do indeksowania aktualizacji i zmian w repozytorium. Jeśli tryb żądania nie zostanie określony, domyślnie ustawiony jest tryb SYNCHRONOUS.

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

Fragment kodu poniżej pokazuje, jak dołączyć identyfikatory podrzędne aktualnie przetwarzanego elementu nadrzędnego do kolejki przetwarzania. Identyfikatory te są przetwarzane po zindeksowaniu elementu nadrzędnego.

// 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 kilka kolejnych kroków, które możesz podjąć:

• (Opcjonalnie) Zaimplementuj metodę close(), aby zwolnić 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

W poniższych sekcjach dowiesz się, jak utworzyć łącznik treści za pomocą interfejsu API REST.

Określ strategię przemierzania

Główną funkcją łącznika treści jest przemierzanie repozytorium i indeksowanie jego danych. Musisz wdrożyć strategię przemierzania opartą na rozmiarze i układzie danych w repozytorium. Oto 3 typowe strategie przemierzania:

Strategia pełnego przemierzania

Strategia pełnego przemierzania skanuje całe repozytorium i indeksuje na ślepo każdy element. Ta strategia jest często stosowana, gdy masz małe repozytorium i możesz pozwolić sobie na wysiłek związany z pełnym przemierzaniem przy każdym indeksowaniu.

Ta strategia przemierzania jest odpowiednia w przypadku małych repozytoriów zawierających głównie dane statyczne, niehierarchiczne. Możesz też używać tej strategii przemierzania, jeśli 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, aby określić stan każdego elementu. Następnie oprogramowanie sprzęgające wykonuje drugie przejście i indeksuje tylko te elementy, które są nowe lub zostały zaktualizowane od ostatniego indeksowania. Ta strategia jest zwykle wykorzystywana do wykonywania przyrostowych aktualizacji istniejącego indeksu (zamiast konieczności wykonywania pełnego przemierzania za każdym razem, gdy aktualizujesz indeks).

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

Omijanie wykresu

Strategia przemierzania wykresu skanuje cały węzeł nadrzędny, określając stan każdego elementu. Następnie oprogramowanie sprzęgające wykonuje drugą procedurę 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 przechodzi do kolejnych węzłów podrzędnych w sposób rekurencyjny, dopóki nie naprawi się wszystkich elementów. Takie przemierzanie jest zwykle używane w przypadku repozytoriów hierarchicznych, w których nie można wyliczać wszystkich identyfikatorów.

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

Wdróż strategię przemierzania i indeksuj elementy

W Cloud Search API każdy możliwy do indeksowania element jest nazywany elementem. Elementem może być plik, folder, wiersz w pliku CSV lub rekord bazy danych.

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

1. (Opcjonalnie) Użycie 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) Użycie właściwości media.upload do przesyłania plików multimedialnych do indeksowania.

3. Użycie tagu items.index do zindeksowania elementu. Jeśli na przykład schemat korzysta z definicji obiektu w schemacie filmu, żądanie indeksowania pojedynczego elementu 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) Użycie wywołań items.get do sprawdzenia, czy produkt został zindeksowany.

Aby wykonać pełne przemierzanie, konieczne było okresowe ponowne indeksowanie całego repozytorium. Aby wykonać przemierzanie list lub wykresów, musisz zaimplementować kod do obsługi zmian w repozytorium.

Obsługa zmian w repozytorium

Możesz okresowo gromadzić i indeksować poszczególne elementy z repozytorium, aby wykonać pełne indeksowanie. Pełne indeksowanie może być kosztowne w przypadku obsługi większych lub hierarchicznych repozytoriów, choć skutecznie zapewnia aktualność indeksu.

Zamiast co jakiś czas korzystać z wywołań indeksu do indeksowania całego repozytorium, możesz też użyć kolejki indeksowania w Google Cloud jako mechanizmu do śledzenia zmian i indeksowania tylko tych elementów, które uległy zmianie. Za pomocą żądań items.push możesz przekazywać elementy do kolejki na potrzeby późniejszego odpytywania i aktualizowania. Więcej informacji o kolejce indeksowania w Google Cloud znajdziesz na stronie Kolejka indeksowania w Google Cloud.

Więcej informacji o interfejsie Google Cloud Search API znajdziesz na stronie Cloud Search API.