İçerik bağlayıcı oluşturma

İçerik bağlayıcısı, bir kurumun deposundaki verileri aktarmak ve bir veri kaynağını doldurmak için kullanılan bir yazılım programıdır. Google, içerik bağlayıcıları geliştirmek için aşağıdaki seçenekleri sunar:

• Content Connector SDK'sı. Java'da programlama yapıyorsanız bu iyi bir seçenektir. Content Connector SDK, REST API'yi çevreleyen bir sarmalayıcıdır. Bu şekilde bağlayıcıları hızlıca oluşturabilirsiniz. SDK'yı kullanarak içerik bağlayıcı oluşturmak için Content Connector SDK'sını kullanarak içerik bağlayıcı oluşturma bölümüne bakın.

• Alt düzey REST API veya API kitaplıkları. Java'da programlama kullanmıyorsanız veya kod tabanınız REST API'yi ya da kitaplığı daha iyi destekliyorsa bu seçenekleri kullanın. REST API'yi kullanarak içerik bağlayıcı oluşturmak için REST API kullanarak içerik bağlayıcısı oluşturma bölümüne bakın.

Tipik bir içerik bağlayıcısı aşağıdaki görevleri gerçekleştirir:

1. Yapılandırma parametrelerini okur ve işler.
2. Üçüncü taraf içerik deposundan, "öğeler" olarak adlandırılan farklı dizine eklenebilir veri parçalarını çeker.
3. EKL'leri, meta verileri ve içerik verilerini dizine eklenebilir öğeler halinde birleştirir.
4. Öğeleri Cloud Search veri kaynağına dizine ekler.
5. (isteğe bağlı) Üçüncü taraf içerik deposundan gelen değişiklikleri dinler. Cloud Search veri kaynağının üçüncü taraf deposuyla senkronize olmasını sağlamak için değişiklik bildirimleri, dizine ekleme isteklerine dönüştürülür. Bağlayıcı bu görevi yalnızca depo, değişiklik algılamayı destekliyorsa gerçekleştirir.

Content Connector SDK'sını kullanarak içerik bağlayıcı oluşturma

Aşağıdaki bölümlerde, Content Connector SDK'yı kullanarak nasıl içerik bağlayıcısı oluşturulacağı açıklanmaktadır.

Bağımlılıkları ayarlama

SDK'yı kullanmak için derleme dosyanıza belirli bağımlılıkları eklemeniz gerekir. Derleme ortamınızın bağımlılıklarını görüntülemek için aşağıdaki sekmelerden birini tıklayın:

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'

Bağlayıcı yapılandırmanızı oluşturun

Her bağlayıcının, bağlayıcı tarafından kullanılan parametreleri (ör. deponuzun kimliği) içeren bir yapılandırma dosyası vardır. Parametreler, api.sourceId=1234567890abcdef gibi anahtar/değer çiftleri olarak tanımlanır.

Google Cloud Search SDK'da, tüm bağlayıcılar tarafından kullanılan, Google'ın sağladığı çeşitli yapılandırma parametreleri bulunur. Yapılandırma dosyanızda Google tarafından sağlanan aşağıdaki parametreleri beyan etmeniz gerekir:

• İçerik bağlayıcısı için api.sourceId ve api.serviceAccountPrivateKeyFile değerlerini bildirmeniz gerekir. Bu parametreler deponuzun konumunu ve depoya erişmek için gereken özel anahtarı tanımlar.

Not: Özel anahtar dosyanız bir JSON anahtarı değilse api.serviceAccountId politikasını da geçersiz kılmanız gerekir.

• Bu parametre harici kimlik kaynağınızın konumunu tanımladığından, kimlik bağlayıcısı için api.identitySourceId bildirmeniz gerekir. Kullanıcıları senkronize ediyorsanız kuruluşunuzun Google Workspace hesabı için api.customerId benzersiz kimlik olarak da beyan etmeniz gerekir.

Google tarafından sağlanan diğer parametrelerin varsayılan değerlerini geçersiz kılmak istemiyorsanız bunları yapılandırma dosyanızda bildirmeniz gerekmez. Google'ın sağladığı yapılandırma parametreleri hakkında, belirli kimlikleri ve anahtarların nasıl oluşturulacağı gibi ek bilgiler için Google'ın sağladığı yapılandırma parametrelerine bakın.

Yapılandırma dosyanızda kullanmak üzere depoya özel parametrelerinizi de tanımlayabilirsiniz.

Not: Bağlayıcı özellikleri dosyası için katı bir adlandırma gereksinimi yoktur ancak dosyayı .properties veya .config uzantısı kullanarak kaydetmenizi öneririz.

Yapılandırma dosyasını bağlayıcıya

Yapılandırma dosyasını bağlayıcınıza iletecek şekilde config sistem özelliğini ayarlayın. Bağlayıcıyı başlatırken -D bağımsız değişkenini kullanarak özelliği ayarlayabilirsiniz. Örneğin, aşağıdaki komut bağlayıcıyı MyConfig.properties yapılandırma dosyasıyla başlatır:

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

Bu bağımsız değişken eksikse SDK, connector-config.properties adlı varsayılan yapılandırma dosyasına erişmeye çalışır.

Geçiş stratejinizi belirleme

İçerik bağlayıcısının ana işlevi, depoda bilgi çekip verilerini dizine eklemektir. Deponuzdaki verilerin boyutuna ve düzenine bağlı olarak bir geçiş stratejisi uygulamanız gerekir. Kendi stratejinizi tasarlayabilir veya SDK'da uygulanan aşağıdaki stratejilerden birini seçebilirsiniz:

Tam geçiş stratejisi

Tam geçiş stratejisi, tüm depoyu tarar ve her öğeyi gizlice dizine ekler. Bu strateji genellikle küçük bir deponuz olduğunda kullanılır ve her dizine ekleme yaptığınızda tam geçiş yapma ek yükünü karşılayabilir.

Bu geçiş stratejisi, çoğunlukla statik ve hiyerarşik olmayan verilerin bulunduğu küçük depolar için uygundur. Bu geçiş stratejisini, değişiklik algılamanın zor olduğu veya depo tarafından desteklenmediğinde de kullanabilirsiniz.

Liste geçiş stratejisi

Liste geçiş stratejisi, tüm alt düğümler de dahil olmak üzere deponun tamamını tarayarak her öğenin durumunu belirler. Daha sonra, bağlayıcı ikinci bir geçiş yapar ve yalnızca son dizine ekleme işleminden sonra güncellenmiş veya yeni olan öğeleri dizine ekler. Bu strateji genellikle mevcut bir dizine artımlı güncellemeler yapmak için kullanılır (dizini her güncellediğinizde tam geçiş yapmak yerine).

Bu geçiş stratejisi, değişiklik algılamanın zor olduğu veya depo tarafından desteklenmediği, hiyerarşik olmayan verilerinizin olduğu ve çok büyük veri kümeleriyle çalıştığınız durumlarda uygundur.

Grafik geçişi

Grafik geçiş stratejisi, her öğenin durumunu belirlemek için üst düğümün tamamını tarar. Ardından, bağlayıcı ikinci bir geçiş yapar ve yalnızca kök düğümdeki dizin oluşturma işlemi yenidir veya son dizine ekleme işleminden sonra güncellenmiştir. Son olarak, bağlayıcı tüm alt kimlikleri geçirir ve ardından alt düğümlerdeki yeni veya güncellenmiş öğeleri dizine ekler. Bağlayıcı, tüm öğeler ele alınana kadar tüm alt düğümlerde yinelemeli bir şekilde devam eder. Bu tür geçişler, genellikle tüm kimliklerin listelenmesinin pratik olmadığı hiyerarşik depolar için kullanılır.

Bu strateji, dizin veya web sayfası dizisi gibi taranması gereken hiyerarşik verileriniz varsa uygundur.

Not: Bu belgede ve örnek kodda "öğe" ve "doküman" terimleri eş anlamlıdır.

Bu geçiş stratejilerinin her biri, SDK'da bir şablon bağlayıcı sınıfı tarafından uygulanır. Kendi geçiş stratejinizi uygulayabilirsiniz, ancak bu şablonlar bağlayıcınızın geliştirilmesini önemli ölçüde hızlandırır. Şablon kullanarak bağlayıcı oluşturmak için geçiş stratejinize karşılık gelen bölüme ilerleyin:

• Şablon sınıfı kullanarak tam geçiş bağlayıcısı oluşturma
• Bir şablon sınıfı kullanarak liste geçiş bağlayıcısı oluşturma
• Şablon sınıfı kullanarak grafik geçiş bağlayıcısı oluşturma

Şablon sınıfı kullanarak tam geçiş bağlayıcısı oluşturma

Belgelerin bu bölümünde FullTraversalSample örneğindeki kod snippet'leri ele alınmaktadır.

Bağlayıcının giriş noktasını uygulayın

Bağlayıcıya giriş noktası main() yöntemidir. Bu yöntemin birincil görevi, Application sınıfının bir örneğini oluşturmak ve bağlayıcıyı çalıştırmak için ilgili start() yöntemini çağırmaktır.

application.start() yöntemini çağırmadan önce FullTraversalConnector şablonunu örneklendirmek için IndexingApplication.Builder sınıfını kullanın. FullTraversalConnector, yöntemlerini uyguladığınız bir Repository nesnesini kabul eder. Aşağıdaki kod snippet'i, main() yönteminin nasıl uygulanacağını gösterir:

FullTraversalSample.java

GitHub'da göster

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

Arka planda SDK, bağlayıcınızın main() yöntemi çağrısından sonra Application.build initConfig() yöntemini çağırır. initConfig() yöntemi aşağıdaki görevleri gerçekleştirir:

1. Configuration özelliğinin başlatılmadığından emin olmak için Configuation.isInitialized() yöntemini çağırır.
2. Google'ın sağladığı anahtar/değer çiftleriyle bir Configuration nesnesini başlatır. Her bir anahtar/değer çifti, Configuration nesnesinin içindeki bir ConfigValue nesnesinde depolanır.

Repository arayüzünü uygulama

Repository nesnesinin tek amacı, depo öğeleri arasında geçiş ve dizin oluşturma işlemi gerçekleştirmektir. Bir şablon kullanırken içerik bağlayıcısı oluşturmak için yalnızca Repository arayüzü içindeki belirli yöntemleri geçersiz kılmanız gerekir. Geçersiz kılacağınız yöntemler, kullandığınız şablona ve geçiş stratejisine bağlıdır. FullTraversalConnector için aşağıdaki yöntemleri geçersiz kılın:

• init() yöntemi. Veri deposu kurulumunu ve başlatmasını gerçekleştirmek için init() yöntemini geçersiz kılın.

• getAllDocs() yöntemi. Veri deposundaki tüm öğeleri incelemek ve dizine eklemek için getAllDocs() yöntemini geçersiz kılın. Bu yöntem, planlanan her geçiş için bir kez çağrılır (yapılandırmanızda tanımlandığı şekilde).

• (isteğe bağlı) getChanges() yöntemi. Deponuz değişiklik algılamayı destekliyorsa getChanges() yöntemini geçersiz kılın. Bu yöntem, değiştirilen öğeleri almak ve dizine eklemek üzere planlanan her bir artımlı geçiş için (yapılandırmanızda tanımlandığı şekilde) bir kez çağrılır.

• (isteğe bağlı) close() yöntemi. Depo temizliği gerçekleştirmeniz gerekirse close() yöntemini geçersiz kılın. Bu yöntem, bağlayıcının kapatılması sırasında bir kez çağrılır.

Repository nesnesinin yöntemlerinin her biri, bir tür ApiOperation nesnesi döndürür. ApiOperation nesnesi, deponuzda asıl dizine ekleme işlemini gerçekleştirmek için bir veya daha fazla IndexingService.indexItem() çağrısı şeklinde işlem gerçekleştirir.

Özel yapılandırma parametrelerini alma

Bağlayıcınızın yapılandırmasını işlemenin bir parçası olarak, Configuration nesnesinden tüm özel parametreleri almanız gerekir. Bu görev genellikle bir Repository sınıfının init() yöntemiyle gerçekleştirilir.

Configuration sınıfı, bir yapılandırmadan farklı veri türlerini almak için çeşitli yöntemler sunar. Her yöntem bir ConfigValue nesnesi döndürür. Daha sonra, gerçek değeri almak için ConfigValue nesnesinin get() yöntemini kullanırsınız. FullTraversalSample alanında bulunan aşağıdaki snippet, Configuration nesnesinden tek bir özel tam sayı değerinin nasıl alınacağını gösterir:

FullTraversalSample.java

GitHub'da göster

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

Birden fazla değer içeren bir parametreyi almak ve ayrıştırmak için Configuration sınıfı tür ayrıştırıcılardan birini kullanarak verileri ayrı parçalara ayırın. Eğitim bağlayıcısındaki aşağıdaki snippet, GitHub deposu adlarının listesini almak için getMultiValue yöntemini kullanır:

GithubRepository.java

GitHub'da göster

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

Tam geçiş yapma

Tam geçiş gerçekleştirmek ve deponuzu dizine eklemek için bu ayarı geçersiz kılın: getAllDocs(). getAllDocs() yöntemi kontrol noktası kabul eder. Sürecin kesintiye uğraması durumunda, belirli bir öğede dizine ekleme işlemini devam ettirmek için kontrol noktası kullanılır. Deponuzdaki her öğe için getAllDocs() yönteminde şu adımları uygulayın:

1. İzinleri ayarlayın.
2. Dizine eklediğiniz öğenin meta verilerini ayarlayın.
3. Meta veriyi ve öğeyi dizine eklenebilir tek bir RepositoryDocda birleştirin.
4. Her dizine eklenebilir öğeyi getAllDocs() yöntemi tarafından döndürülen bir yinelemede paketleyin. getAllDocs() işlevinin aslında ApiOperation nesnelerinin yinelemesi olan bir CheckpointCloseableIterable döndürdüğünü unutmayın. Her nesne, dizine ekleme gibi bir RepositoryDoc üzerinde gerçekleştirilen API isteğini temsil eder.

Öğe grubu tek bir çağrıda işlenemeyecek kadar büyükse bir kontrol noktası ekleyin ve dizine eklemeye uygun daha fazla öğenin olduğunu göstermek için hasMore(true) değerini ayarlayın.

Bir öğenin izinlerini ayarlama

Deponuz, bir öğeye erişimi olan kullanıcıları veya grupları tanımlamak için Erişim Kontrol Listesi (ACL) kullanır. EKL, öğeye erişebilen grupların veya kullanıcıların kimliklerini içeren bir listedir.

Yalnızca bir öğeye erişimi olan kullanıcıların arama sonucunda öğeyi görebildiğinden emin olmak için deponuz tarafından kullanılan EKL'yi kopyalamanız gerekir. Bir öğenin EKL'sinin eklenmesi gerekir. Böylece Google Cloud Search, öğeye doğru erişim düzeyini sağlamak için gereken bilgilere sahip olur.

Content Connector SDK, çoğu deponun EKL'lerini modellemek için zengin bir EKL sınıfları ve yöntemleri sunar. Deponuzdaki her öğenin EKL'sini analiz etmeniz ve bir öğeyi dizine eklerken Google Cloud Search için buna karşılık gelen bir EKL oluşturmanız gerekir. Deponuzun EKL'si, EKL devralma gibi kavramlar kullanıyorsa bu EKL'yi modellemek yanıltıcı olabilir. Google Cloud Search EKL'leri hakkında daha fazla bilgi için Google Cloud Search EKL'leri bölümüne bakın.

Not: Cloud Search Indexing API, tek alanlı EKL'leri destekler. Alanlar arası EKL'leri desteklemez. EKL kullanarak her öğeye erişimi ayarlamak için Acl.Builder sınıfını kullanın. Tam geçiş örneğinden alınan aşağıdaki kod snippet'i, arama yaparken tüm kullanıcıların veya "ana hesapların" (getCustomerPrincipal()) tüm öğelerin ".setReaders()) "okuyucusu" olmasına izin verir.

FullTraversalSample.java

GitHub'da göster

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

Kod deposu için EKL'leri doğru şekilde modellemek için EKL'leri anlamanız gerekir. Örneğin, bir dosya sistemindeki dosyaları dizine ekliyor ve alt klasörlerin izinleri üst klasörlerden devraldığı bir tür devralma modeli kullanıyor olabilirsiniz. EKL devrisini modellemek için Google Cloud Search EKL'lerinde ele alınan ek bilgiler gerekir.

Bir öğenin meta verilerini ayarlama

Meta veriler bir Item nesnesinde depolanır. Item oluşturmak için öğenin en az benzersiz dize kimliği, öğe türü, EKL, URL ve sürümü gerekir. Aşağıdaki kod snippet'i, IndexingItemBuilder yardımcı sınıfını kullanarak nasıl Item oluşturacağınızı göstermektedir.

FullTraversalSample.java

GitHub'da göster

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

Dizine eklenebilir öğeyi oluşturma

Öğe için meta verileri ayarladıktan sonra, RepositoryDoc.Builder sınıfını kullanarak gerçek dizine eklenebilir öğeyi oluşturabilirsiniz. Aşağıdaki örnekte tek bir dizine eklenebilir öğenin nasıl oluşturulacağı gösterilmektedir.

FullTraversalSample.java

GitHub'da göster

// 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, gerçek IndexingService.indexItem() isteğini gerçekleştiren bir ApiOperation türüdür.

Dizine ekleme isteğini ASYNCHRONOUS veya SYNCHRONOUS olarak tanımlamak için RepositoryDoc.Builder sınıfının setRequestMode() yöntemini de kullanabilirsiniz:

ASYNCHRONOUS

Eş zamansız mod, dizine eklemede sunuma kadar gecikme süresinin uzamasına neden olur ve dizine ekleme istekleri için yüksek işleme hızı kotasına uyum sağlar. Eşzamansız mod, tüm deponun ilk dizine ekleme (dolgu) işlemi için önerilir.

SYNCHRONOUS

Eşzamanlı mod, dizine ekleme-sunum gecikmesinin daha kısa olmasını sağlar ve sınırlı işleme hızı kotasına uyum sağlar. Eşzamanlı mod, güncellemelerin ve depo değişikliklerinin dizine eklenmesi için önerilir. Bir değer belirtilmezse istek modu varsayılan olarak SYNCHRONOUS değerine ayarlanır.

Dizine eklenebilir her öğeyi bir yinelemede paketle

getAllDocs() yöntemi, RepositoryDoc nesneden bir Iterator, özellikle de CheckpointCloseableIterable döndürür. Bir yineleyici oluşturmak ve döndürmek için CheckpointClosableIterableImpl.Builder sınıfını kullanabilirsiniz. Aşağıdaki kod snippet'i, bir yinelemenin nasıl oluşturulacağını ve döndürüleceğini göstermektedir.

FullTraversalSample.java

GitHub'da göster

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

SDK, yineleyicinin içinde yer alan her dizine ekleme çağrısını yürütür.

Not: Cloud Search tüm dosyaların meta verilerini dizine ekler. Cloud Search, bir öğenin dosya türüne bağlı olarak metin içeriğini de dizine ekler. Buna, resim ve diğer dosyalarda Optik Karakter Tanıma (OCR) kullanımı da dahildir. Metin çıkarmayı destekleyen dosya türlerinin listesi için Metin çıkarma için desteklenen dosya türleri bölümüne bakın.

Sonraki adımlar

Atabileceğiniz sonraki adımlardan bazıları şunlardır:

• (İsteğe bağlı) Dizine ekleme işleme hızınız yavaşsa FullTraversalConnector için dizine ekleme oranını artırma başlıklı makaleyi inceleyin.
• (İsteğe bağlı) Kapanıştan önce kaynakları serbest bırakmak için close() yöntemini uygulayın.
• (isteğe bağlı) Content Connector SDK'sını kullanarak bir kimlik bağlayıcısı oluşturun.

Bir şablon sınıfı kullanarak liste geçiş bağlayıcısı oluşturma

Cloud Search Dizine Ekleme Sırası, kod deposundaki her bir öğenin kimliklerini ve isteğe bağlı karma değerlerini tutmak için kullanılır. Liste geçiş bağlayıcısı, öğe kimliklerini Google Cloud Search Dizine Ekleme Sırası'na aktarır ve bunları dizine ekleme için teker teker alır. Google Cloud Search, öğe durumunu (örneğin bir öğenin depodan silinip silinmediğini) belirlemek için sıraları tutar ve sıra içeriklerini karşılaştırır. Cloud Search Dizine Ekleme Sırası hakkında daha fazla bilgi için Cloud Search Dizine Ekleme Sırası'na bakın.

Belgelerin bu bölümünde ListTraversalSample örneğindeki kod snippet'leri açıklanmaktadır.

Bağlayıcının giriş noktasını uygulayın

Bağlayıcıya giriş noktası main() yöntemidir. Bu yöntemin birincil görevi, Application sınıfının bir örneğini oluşturmak ve bağlayıcıyı çalıştırmak için ilgili start() yöntemini çağırmaktır.

application.start() yöntemini çağırmadan önce ListingConnector şablonunu örneklendirmek için IndexingApplication.Builder sınıfını kullanın. ListingConnector, yöntemlerini uyguladığınız bir Repository nesnesini kabul eder. Aşağıdaki snippet, ListingConnector ve ilişkili Repository öğesinin nasıl başlatılacağını gösterir:

ListTraversalSample.java

GitHub'da göster

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

Arka planda SDK, bağlayıcınızın main() yöntemi çağrısından sonra Application.build initConfig() yöntemini çağırır. initConfig() yöntemi:

1. Configuration özelliğinin başlatılmadığından emin olmak için Configuation.isInitialized() yöntemini çağırır.
2. Google'ın sağladığı anahtar/değer çiftleriyle bir Configuration nesnesini başlatır. Her bir anahtar/değer çifti, Configuration nesnesinin içindeki bir ConfigValue nesnesinde depolanır.

Repository arayüzünü uygulama

Repository nesnesinin tek amacı, depo öğeleri arasında geçiş ve dizin oluşturma işlemi gerçekleştirmektir. Şablon kullanırken içerik bağlayıcısı oluşturmak için yalnızca Repository arayüzündeki belirli yöntemleri geçersiz kılmanız gerekir. Geçersiz kılacağınız yöntemler, kullandığınız şablona ve geçiş stratejisine bağlıdır. ListingConnector için aşağıdaki yöntemleri geçersiz kılın:

• init() yöntemi. Veri deposu kurulumunu ve başlatmasını gerçekleştirmek için init() yöntemini geçersiz kılın.

• getIds() yöntemi. Depodaki tüm kayıtların kimliklerini ve karma değerlerini almak için getIds() yöntemini geçersiz kılın.

• getDoc() yöntemi. Dizine yeni öğeler eklemek, mevcut öğeleri güncellemek, değiştirmek veya silmek için getDoc() yöntemini geçersiz kılın.

• (isteğe bağlı) getChanges() yöntemi. Deponuz değişiklik algılamayı destekliyorsa getChanges() yöntemini geçersiz kılın. Bu yöntem, değiştirilen öğeleri almak ve dizine eklemek üzere planlanan her bir artımlı geçiş için (yapılandırmanızda tanımlandığı şekilde) bir kez çağrılır.

• (isteğe bağlı) close() yöntemi. Depo temizliği gerçekleştirmeniz gerekirse close() yöntemini geçersiz kılın. Bu yöntem, bağlayıcının kapatılması sırasında bir kez çağrılır.

Repository nesnesinin yöntemlerinin her biri, bir tür ApiOperation nesnesi döndürür. ApiOperation nesnesi, deponuzda asıl dizine ekleme işlemini gerçekleştirmek için bir veya daha fazla IndexingService.indexItem() çağrısı şeklinde işlem gerçekleştirir.

Özel yapılandırma parametrelerini alma

Bağlayıcınızın yapılandırmasını işlemenin bir parçası olarak, Configuration nesnesinden tüm özel parametreleri almanız gerekir. Bu görev genellikle bir Repository sınıfının init() yöntemiyle gerçekleştirilir.

Configuration sınıfı, bir yapılandırmadan farklı veri türlerini almak için çeşitli yöntemler sunar. Her yöntem bir ConfigValue nesnesi döndürür. Daha sonra, gerçek değeri almak için ConfigValue nesnesinin get() yöntemini kullanırsınız. FullTraversalSample alanında bulunan aşağıdaki snippet, Configuration nesnesinden tek bir özel tam sayı değerinin nasıl alınacağını gösterir:

FullTraversalSample.java

GitHub'da göster

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

Birden fazla değer içeren bir parametreyi almak ve ayrıştırmak için Configuration sınıfı tür ayrıştırıcılardan birini kullanarak verileri ayrı parçalara ayırın. Eğitim bağlayıcısındaki aşağıdaki snippet, GitHub deposu adlarının listesini almak için getMultiValue yöntemini kullanır:

GithubRepository.java

GitHub'da göster

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

Liste geçişini gerçekleştir

Depodaki tüm kayıtların kimliklerini ve karma değerlerini almak için getIds() yöntemini geçersiz kılın. getIds() yöntemi bir kontrol noktası kabul eder. Sürecin kesintiye uğraması durumunda kontrol noktası, belirli bir öğede dizine eklemeyi devam ettirmek için kullanılır.

Ardından, Cloud Search Dizine Ekleme Sırası'ndaki her bir öğeyi işlemek için getDoc() yöntemini geçersiz kılın.

Push öğesi kimlikleri ve karma değerleri

Öğe kimliklerini ve bunlarla ilişkili içerik karma değerlerini depodan getirmek için getIds() değerini geçersiz kılın. Daha sonra kimlik ve karma değer çiftleri, Cloud Search Dizine Ekleme Sırası'na aktarma işlemi isteği olarak paketlenir. Genellikle önce kök veya üst kimlikler, ardından öğeler hiyerarşisinin tamamı işlenene kadar alt kimlikler aktarılır.

getIds() yöntemi, dizine eklenecek son öğeyi temsil eden bir kontrol noktasını kabul eder. Sürecin kesintiye uğraması durumunda, belirli bir öğede dizine eklemeyi devam ettirmek için kontrol noktası kullanılabilir. Deponuzdaki her öğe için getIds() yönteminde şu adımları uygulayın:

• Kod deposundaki her öğe kimliğini ve ilgili karma değerini alın.
• Her bir kimlik ve karma değer çiftini bir PushItems içinde paketleyin.
• Her PushItems öğesini, getIds() yöntemi tarafından döndürülen bir yinelemede birleştirin. getIds() öğesinin aslında ApiOperation nesnelerinin yinelemesi olan bir CheckpointCloseableIterable döndürdüğünü unutmayın. Her nesne, bir RepositoryDoc üzerinde gerçekleştirilen API isteğini temsil eder (ör. öğeleri sıraya aktarma).

Aşağıdaki kod snippet'i, her bir öğe kimliği ve karma değerinin nasıl alınacağını ve bir PushItems içine nasıl ekleneceğini göstermektedir. PushItems, bir öğeyi Cloud Search Dizine Ekleme Sırası'na aktarmaya yönelik ApiOperation isteğidir.

ListTraversalSample.java

GitHub'da göster

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

Aşağıdaki kod snippet'i, kimlikleri ve karma değerlerini tek bir aktarma işleminde paketlemek için PushItems.Builder sınıfının nasıl kullanılacağınıApiOperation göstermektedir.

ListTraversalSample.java

GitHub'da göster

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

Öğeler, daha fazla işlenmek üzere Cloud Search Dizine Ekleme Sırası'na aktarılır.

Her bir öğeyi alma ve işleme

Cloud Search Dizine Ekleme Sırası'ndaki her bir öğeyi işlemek için getDoc() değerini geçersiz kılın. Bir öğe yeni, değiştirilmiş veya değiştirilmemiş olabilir ya da artık kaynak depoda mevcut olmayabilir. Yeni veya değiştirilen her öğeyi alın ve dizine ekleyin. Artık kaynak kod deposunda bulunmayan öğeleri dizinden kaldırın.

getDoc() yöntemi, Google Cloud Search Dizine Ekleme Sırası'ndaki bir öğeyi kabul eder. Sıradaki her bir öğe için getDoc() yönteminde şu adımları uygulayın:

1. Cloud Search Dizine Ekleme Sırası içindeki öğenin kimliğinin depoda olup olmadığını kontrol edin. Değilse, öğeyi dizinden silin.

2. Öğe durumu için dizini anket yapın ve bir öğe değişmediyse (ACCEPTED) hiçbir şey yapmayın.

3. Dizin değiştirildi veya yeni öğeler:

   1. İzinleri ayarlayın.
   2. Dizine eklediğiniz öğenin meta verilerini ayarlayın.
   3. Meta veriyi ve öğeyi dizine eklenebilir tek bir RepositoryDocda birleştirin.
   4. RepositoryDoc kartını iade edin.

Not: ListingConnector şablonu, getDoc() yönteminde null döndürülmesini desteklemez. null döndürülmesi NullPointerException. ile sonuçlanır

Silinen öğeleri işleme

Aşağıdaki kod snippet'i, bir öğenin depoda mevcut olup olmadığının nasıl belirleneceğini ve yoksa nasıl silineceğini gösterir.

ListTraversalSample.java

GitHub'da göster

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

documents bilgisinin, depoyu temsil eden bir veri yapısı olduğunu unutmayın. documents içinde documentID bulunamazsa öğeyi dizinden silmek için APIOperations.deleteItem(resourceName) döndürün.

Değiştirilmeyen öğeleri işleyin

Aşağıdaki kod snippet'i, Cloud Search Dizine Ekleme Sırası'nda öğe durumunun nasıl sorgulanacağını ve değiştirilmemiş bir öğenin nasıl işleneceğini gösterir.

ListTraversalSample.java

GitHub'da göster

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

Öğenin değiştirilip değiştirilmediğini belirlemek için öğenin durumunu ve bir değişikliği belirtebilecek diğer meta verileri kontrol edin. Bu örnekte, öğenin değiştirilip değiştirilmediğini belirlemek için meta veri karması kullanılır.

ListTraversalSample.java

GitHub'da göster

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

Bir öğenin izinlerini ayarlama

Deponuz, bir öğeye erişimi olan kullanıcıları veya grupları tanımlamak için Erişim Kontrol Listesi (ACL) kullanır. EKL, öğeye erişebilen grupların veya kullanıcıların kimliklerini içeren bir listedir.

Yalnızca bir öğeye erişimi olan kullanıcıların arama sonucunda öğeyi görebildiğinden emin olmak için deponuz tarafından kullanılan EKL'yi kopyalamanız gerekir. Bir öğenin EKL'sinin eklenmesi gerekir. Böylece Google Cloud Search, öğeye doğru erişim düzeyini sağlamak için gereken bilgilere sahip olur.

Content Connector SDK, çoğu deponun EKL'lerini modellemek için zengin bir EKL sınıfları ve yöntemleri sunar. Deponuzdaki her öğenin EKL'sini analiz etmeniz ve bir öğeyi dizine eklerken Google Cloud Search için buna karşılık gelen bir EKL oluşturmanız gerekir. Deponuzun EKL'si, EKL devralma gibi kavramlar kullanıyorsa bu EKL'yi modellemek yanıltıcı olabilir. Google Cloud Search EKL'leri hakkında daha fazla bilgi için Google Cloud Search EKL'leri bölümüne bakın.

Not: Cloud Search Indexing API, tek alanlı EKL'leri destekler. Alanlar arası EKL'leri desteklemez. EKL kullanarak her öğeye erişimi ayarlamak için Acl.Builder sınıfını kullanın. Tam geçiş örneğinden alınan aşağıdaki kod snippet'i, arama yaparken tüm kullanıcıların veya "ana hesapların" (getCustomerPrincipal()) tüm öğelerin ".setReaders()) "okuyucusu" olmasına izin verir.

FullTraversalSample.java

GitHub'da göster

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

Kod deposu için EKL'leri doğru şekilde modellemek için EKL'leri anlamanız gerekir. Örneğin, bir dosya sistemindeki dosyaları dizine ekliyor ve alt klasörlerin izinleri üst klasörlerden devraldığı bir tür devralma modeli kullanıyor olabilirsiniz. EKL devrisini modellemek için Google Cloud Search EKL'lerinde ele alınan ek bilgiler gerekir.

Bir öğenin meta verilerini ayarlama

Meta veriler bir Item nesnesinde depolanır. Item oluşturmak için öğenin en az benzersiz dize kimliği, öğe türü, EKL, URL ve sürümü gerekir. Aşağıdaki kod snippet'i, IndexingItemBuilder yardımcı sınıfını kullanarak nasıl Item oluşturacağınızı göstermektedir.

ListTraversalSample.java

GitHub'da göster

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

Dizine eklenebilir öğe oluşturma

Öğe için meta verileri ayarladıktan sonra, RepositoryDoc.Builder aracılığıyla gerçek dizine eklenebilir öğeyi oluşturabilirsiniz. Aşağıdaki örnekte tek bir dizine eklenebilir öğenin nasıl oluşturulacağı gösterilmektedir.

ListTraversalSample.java

GitHub'da göster

// 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, gerçek IndexingService.indexItem() isteğini gerçekleştiren bir ApiOperation türüdür.

Dizine ekleme isteğini ASYNCHRONOUS veya SYNCHRONOUS olarak tanımlamak için RepositoryDoc.Builder sınıfının setRequestMode() yöntemini de kullanabilirsiniz:

ASYNCHRONOUS

Eş zamansız mod, dizine eklemede sunuma kadar gecikme süresinin uzamasına neden olur ve dizine ekleme istekleri için yüksek işleme hızı kotasına uyum sağlar. Eşzamansız mod, tüm deponun ilk dizine ekleme (dolgu) işlemi için önerilir.

SYNCHRONOUS

Eşzamanlı mod, dizine ekleme-sunum gecikmesinin daha kısa olmasını sağlar ve sınırlı işleme hızı kotasına uyum sağlar. Eşzamanlı mod, güncellemelerin ve depo değişikliklerinin dizine eklenmesi için önerilir. Bir değer belirtilmezse istek modu varsayılan olarak SYNCHRONOUS değerine ayarlanır.

Not: Cloud Search tüm dosyaların meta verilerini dizine ekler. Cloud Search, bir öğenin dosya türüne bağlı olarak elle yazılmış içerikte Optik Karakter Tanıma (OCR) kullanımı dahil olmak üzere metin içeriğini de dizine ekler. Metin çıkarmayı destekleyen dosya türlerinin listesi için Metin çıkarma için desteklenen dosya türleri bölümüne bakın.

Sonraki adımlar

Atabileceğiniz sonraki adımlardan bazıları şunlardır:

• (İsteğe bağlı) Kapanıştan önce kaynakları serbest bırakmak için close() yöntemini uygulayın.
• (isteğe bağlı) Content Connector SDK'sını kullanarak bir kimlik bağlayıcısı oluşturun.

Şablon sınıfı kullanarak grafik geçiş bağlayıcısı oluşturma

Cloud Search Dizine Ekleme Sırası, kod deposundaki her bir öğenin kimliklerini ve isteğe bağlı karma değerlerini tutmak için kullanılır. Grafik geçiş bağlayıcısı, öğe kimliklerini Google Cloud Search Dizine Ekleme Sırası'na aktarır ve bunları dizine eklemek için teker teker alır. Google Cloud Search, öğe durumunu (ör. bir öğenin depodan silinip silinmediğini) belirlemek için sıraları tutar ve sıra içeriklerini karşılaştırır. Cloud Search Dizine Ekleme Sırası hakkında daha fazla bilgi için Google Cloud Search Dizine Ekleme Sırası'na bakın.

Dizin sırasında, öğe içeriği veri deposundan getirilir ve tüm alt öğe kimlikleri sıraya aktarılır. Bağlayıcı, tüm öğeler işlenene kadar üst ve alt kimlikleri yinelemeli şekilde işlemeye devam eder.

Belgelerin bu bölümünde GraphTraversalSample örneğindeki kod snippet'leri ele alınmaktadır.

Bağlayıcının giriş noktasını uygulayın

Bağlayıcıya giriş noktası main() yöntemidir. Bu yöntemin birincil görevi, Application sınıfının bir örneğini oluşturmak ve bağlayıcıyı çalıştırmak için ilgili start() yöntemini çağırmaktır.

application.start() yöntemini çağırmadan önce ListingConnector şablonunu örneklendirmek için IndexingApplication.Builder sınıfını kullanın. ListingConnector, yöntemlerini uyguladığınız bir Repository nesnesini kabul eder.

Not: Grafik geçiş stratejisinde, liste geçiş stratejisi ile aynı şablon sınıfı (ListingConnector) kullanılır.

Aşağıdaki snippet, ListingConnector ve ilişkili Repository öğesinin nasıl başlatılacağını gösterir:

GraphTraversalSample.java

GitHub'da göster

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

Arka planda SDK, bağlayıcınızın main() yöntemi çağrısından sonra Application.build initConfig() yöntemini çağırır. initConfig() yöntemi:

1. Configuration özelliğinin başlatılmadığından emin olmak için Configuation.isInitialized() yöntemini çağırır.
2. Google'ın sağladığı anahtar/değer çiftleriyle bir Configuration nesnesini başlatır. Her bir anahtar/değer çifti, Configuration nesnesinin içindeki bir ConfigValue nesnesinde depolanır.

Repository arayüzünü uygulama

Repository nesnesinin tek amacı, depo öğelerine geçiş ve dizin oluşturma işlemleri gerçekleştirmektir. Şablon kullanırken içerik bağlayıcısı oluşturmak için Repository arayüzünde yalnızca belirli yöntemleri geçersiz kılmanız gerekir. Geçersiz kılacağınız yöntemler, kullandığınız şablona ve geçiş stratejisine bağlıdır. ListingConnector için aşağıdaki yöntemleri geçersiz kılarsınız:

• init() yöntemi. Veri deposu kurulumunu ve başlatmasını gerçekleştirmek için init() yöntemini geçersiz kılın.

• getIds() yöntemi. Depodaki tüm kayıtların kimliklerini ve karma değerlerini almak için getIds() yöntemini geçersiz kılın.

• getDoc() yöntemi. Dizine yeni öğeler eklemek, mevcut öğeleri güncellemek, değiştirmek veya silmek için getDoc() yöntemini geçersiz kılın.

• (isteğe bağlı) getChanges() yöntemi. Deponuz değişiklik algılamayı destekliyorsa getChanges() yöntemini geçersiz kılın. Bu yöntem, değiştirilen öğeleri almak ve dizine eklemek üzere planlanan her bir artımlı geçiş için (yapılandırmanızda tanımlandığı şekilde) bir kez çağrılır.

• (isteğe bağlı) close() yöntemi. Depo temizliği gerçekleştirmeniz gerekirse close() yöntemini geçersiz kılın. Bu yöntem, bağlayıcının kapatılması sırasında bir kez çağrılır.

Repository nesnesinin yöntemlerinin her biri, bir tür ApiOperation nesnesi döndürür. ApiOperation nesnesi, deponuzda asıl dizine ekleme işlemini gerçekleştirmek için bir veya daha fazla IndexingService.indexItem() çağrısı şeklinde işlem gerçekleştirir.

Özel yapılandırma parametrelerini alma

Bağlayıcınızın yapılandırmasını işlemenin bir parçası olarak, Configuration nesnesinden tüm özel parametreleri almanız gerekir. Bu görev genellikle bir Repository sınıfının init() yöntemiyle gerçekleştirilir.

Configuration sınıfı, bir yapılandırmadan farklı veri türlerini almak için çeşitli yöntemler sunar. Her yöntem bir ConfigValue nesnesi döndürür. Daha sonra, gerçek değeri almak için ConfigValue nesnesinin get() yöntemini kullanırsınız. FullTraversalSample alanında bulunan aşağıdaki snippet, Configuration nesnesinden tek bir özel tam sayı değerinin nasıl alınacağını gösterir:

FullTraversalSample.java

GitHub'da göster

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

Birden fazla değer içeren bir parametreyi almak ve ayrıştırmak için Configuration sınıfı tür ayrıştırıcılardan birini kullanarak verileri ayrı parçalara ayırın. Eğitim bağlayıcısındaki aşağıdaki snippet, GitHub deposu adlarının listesini almak için getMultiValue yöntemini kullanır:

GithubRepository.java

GitHub'da göster

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

Grafik geçişini gerçekleştirme

Depodaki tüm kayıtların kimliklerini ve karma değerlerini almak için getIds() yöntemini geçersiz kılın. getIds() yöntemi bir kontrol noktası kabul eder. Sürecin kesintiye uğraması durumunda kontrol noktası, belirli bir öğede dizine eklemeyi devam ettirmek için kullanılır.

Ardından, Cloud Search Dizine Ekleme Sırası'ndaki her bir öğeyi işlemek için getDoc() yöntemini geçersiz kılın.

Push öğesi kimlikleri ve karma değerleri

Öğe kimliklerini ve bunlarla ilişkili içerik karma değerlerini depodan getirmek için getIds() değerini geçersiz kılın. Daha sonra kimlik ve karma değer çiftleri, Cloud Search Dizine Ekleme Sırası'na aktarma işlemi isteği olarak paketlenir. Genellikle önce kök veya üst kimlikler, ardından öğeler hiyerarşisinin tamamı işlenene kadar alt kimlikler aktarılır.

getIds() yöntemi, dizine eklenecek son öğeyi temsil eden bir kontrol noktasını kabul eder. Sürecin kesintiye uğraması durumunda, belirli bir öğede dizine eklemeyi devam ettirmek için kontrol noktası kullanılabilir. Deponuzdaki her öğe için getIds() yönteminde şu adımları uygulayın:

• Kod deposundaki her öğe kimliğini ve ilgili karma değerini alın.
• Her bir kimlik ve karma değer çiftini bir PushItems içinde paketleyin.
• Her PushItems öğesini, getIds() yöntemi tarafından döndürülen bir yinelemede birleştirin. getIds() öğesinin aslında ApiOperation nesnelerinin yinelemesi olan bir CheckpointCloseableIterable döndürdüğünü unutmayın. Her nesne, bir RepositoryDoc üzerinde gerçekleştirilen API isteğini temsil eder (ör. öğeleri sıraya aktarma).

Aşağıdaki kod snippet'i, her bir öğe kimliğinin ve karma değerinin nasıl alınacağını ve bir PushItems içine nasıl ekleneceğini göstermektedir. PushItems, bir öğeyi Cloud Search Dizine Ekleme Sırası'na aktarmaya yönelik ApiOperation isteğidir.

GraphTraversalSample.java

GitHub'da göster

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

Aşağıdaki kod snippet'i, kimlikleri ve karma değerlerini tek bir aktarma ApiOperation işleminde paketlemek için PushItems.Builder sınıfının nasıl kullanılacağını göstermektedir.

GraphTraversalSample.java

GitHub'da göster

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

Öğeler, daha fazla işlenmek üzere Cloud Search Dizine Ekleme Sırası'na aktarılır.

Her bir öğeyi alma ve işleme

Cloud Search Dizine Ekleme Sırası'ndaki her bir öğeyi işlemek için getDoc() değerini geçersiz kılın. Bir öğe yeni, değiştirilmiş veya değiştirilmemiş olabilir ya da artık kaynak depoda mevcut olmayabilir. Yeni veya değiştirilen her öğeyi alın ve dizine ekleyin. Artık kaynak kod deposunda bulunmayan öğeleri dizinden kaldırın.

getDoc() yöntemi, Cloud Search Dizine Ekleme Sırasındaki bir Öğeyi kabul eder. Sıradaki her bir öğe için getDoc() yönteminde şu adımları uygulayın:

1. Cloud Search Dizine Ekleme Sırası içindeki öğenin kimliğinin depoda mevcut olup olmadığını kontrol edin. Değilse, öğeyi dizinden silin. Öğe varsa sonraki adımla devam edin.

2. Dizin değiştirildi veya yeni öğeler:

   1. İzinleri ayarlayın.
   2. Dizine eklediğiniz öğenin meta verilerini ayarlayın.
   3. Meta veriyi ve öğeyi dizine eklenebilir tek bir RepositoryDocda birleştirin.
   4. Daha fazla işlenmek üzere alt kimlikleri Cloud Search Dizine Ekleme Sırası'na yerleştirin.
   5. RepositoryDoc kartını iade edin.

Silinen öğeleri işleme

Aşağıdaki kod snippet'i, bir öğenin dizinde mevcut olup olmadığının nasıl belirleneceğini ve nasıl silineceğini gösterir.

GraphTraversalSample.java

GitHub'da göster

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

Bir öğenin izinlerini ayarlama

Deponuz, bir öğeye erişimi olan kullanıcıları veya grupları tanımlamak için Erişim Kontrol Listesi (ACL) kullanır. EKL, öğeye erişebilen grupların veya kullanıcıların kimliklerini içeren bir listedir.

Yalnızca bir öğeye erişimi olan kullanıcıların arama sonucunda öğeyi görebildiğinden emin olmak için deponuz tarafından kullanılan EKL'yi kopyalamanız gerekir. Bir öğenin EKL'sinin eklenmesi gerekir. Böylece Google Cloud Search, öğeye doğru erişim düzeyini sağlamak için gereken bilgilere sahip olur.

Content Connector SDK, çoğu deponun EKL'lerini modellemek için zengin bir EKL sınıfları ve yöntemleri sunar. Deponuzdaki her öğenin EKL'sini analiz etmeniz ve bir öğeyi dizine eklerken Google Cloud Search için buna karşılık gelen bir EKL oluşturmanız gerekir. Deponuzun EKL'si, EKL devralma gibi kavramlar kullanıyorsa bu EKL'yi modellemek yanıltıcı olabilir. Google Cloud Search EKL'leri hakkında daha fazla bilgi için Google Cloud Search EKL'leri bölümüne bakın.

Not: Cloud Search Indexing API, tek alanlı EKL'leri destekler. Alanlar arası EKL'leri desteklemez. EKL kullanarak her öğeye erişimi ayarlamak için Acl.Builder sınıfını kullanın. Tam geçiş örneğinden alınan aşağıdaki kod snippet'i, arama yaparken tüm kullanıcıların veya "ana hesapların" (getCustomerPrincipal()) tüm öğelerin ".setReaders()) "okuyucusu" olmasına izin verir.

FullTraversalSample.java

GitHub'da göster

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

Kod deposu için EKL'leri doğru şekilde modellemek için EKL'leri anlamanız gerekir. Örneğin, bir dosya sistemindeki dosyaları dizine ekliyor ve alt klasörlerin izinleri üst klasörlerden devraldığı bir tür devralma modeli kullanıyor olabilirsiniz. EKL devrisini modellemek için Google Cloud Search EKL'lerinde ele alınan ek bilgiler gerekir.

Bir öğenin meta verilerini ayarlama

Meta veriler bir Item nesnesinde depolanır. Item oluşturmak için öğenin en az benzersiz dize kimliği, öğe türü, EKL, URL ve sürümü gerekir. Aşağıdaki kod snippet'i, IndexingItemBuilder yardımcı sınıfını kullanarak nasıl Item oluşturacağınızı göstermektedir.

GraphTraversalSample.java

GitHub'da göster

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

Dizine eklenebilir öğeyi oluşturma

Öğe için meta verileri ayarladıktan sonra, RepositoryDoc.Builder aracılığıyla gerçek dizine eklenebilir öğeyi oluşturabilirsiniz. Aşağıdaki örnekte tek bir dizine eklenebilir öğenin nasıl oluşturulacağı gösterilmektedir.

GraphTraversalSample.java

GitHub'da göster

// 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, gerçek IndexingService.indexItem() isteğini gerçekleştiren bir ApiOperation türüdür.

Dizine ekleme isteğini ASYNCHRONOUS veya SYNCHRONOUS olarak tanımlamak için RepositoryDoc.Builder sınıfının setRequestMode() yöntemini de kullanabilirsiniz:

ASYNCHRONOUS

Eş zamansız mod, dizine eklemede sunuma kadar gecikme süresinin uzamasına neden olur ve dizine ekleme istekleri için yüksek işleme hızı kotasına uyum sağlar. Eşzamansız mod, tüm deponun ilk dizine ekleme (dolgu) işlemi için önerilir.

SYNCHRONOUS

Eşzamanlı mod, dizine ekleme-sunum gecikmesinin daha kısa olmasını sağlar ve sınırlı işleme hızı kotasına uyum sağlar. Eşzamanlı mod, güncellemelerin ve depo değişikliklerinin dizine eklenmesi için önerilir. Bir değer belirtilmezse istek modu varsayılan olarak SYNCHRONOUS değerine ayarlanır.

Alt kimlikleri Cloud Search Dizine Ekleme Sırasına yerleştirme

Aşağıdaki kod snippet'i, şu anda işlenen üst öğe için alt kimliklerin işlenmek üzere sıraya nasıl ekleneceğini göstermektedir. Bu kimlikler, üst öğe dizine eklendikten sonra işlenir.

GraphTraversalSample.java

GitHub'da göster

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

Not: Cloud Search tüm dosyaların meta verilerini dizine ekler. Cloud Search, bir öğenin dosya türüne bağlı olarak elle yazılmış içerikte Optik Karakter Tanıma (OCR) kullanımı dahil olmak üzere metin içeriğini de dizine ekler. Metin çıkarmayı destekleyen dosya türlerinin listesi için Metin çıkarma için desteklenen dosya türleri bölümüne bakın.

Sonraki adımlar

Atabileceğiniz sonraki adımlardan bazıları şunlardır:

• (İsteğe bağlı) Kapanıştan önce kaynakları serbest bırakmak için close() yöntemini uygulayın.
• (isteğe bağlı) Identity Connector SDK'sını kullanarak bir kimlik bağlayıcısı oluşturun.

REST API kullanarak içerik bağlayıcı oluşturma

Aşağıdaki bölümlerde, REST API kullanarak nasıl içerik bağlayıcısı oluşturulacağı açıklanmaktadır.

Geçiş stratejinizi belirleme

İçerik bağlayıcısının ana işlevi, depoda bilgi çekip verilerini dizine eklemektir. Deponuzdaki verilerin boyutuna ve düzenine bağlı olarak bir geçiş stratejisi uygulamanız gerekir. Aşağıda, yaygın olarak kullanılan üç geçiş stratejisi verilmiştir:

Tam geçiş stratejisi

Tam geçiş stratejisi, tüm depoyu tarar ve her öğeyi gizlice dizine ekler. Bu strateji genellikle küçük bir deponuz olduğunda kullanılır ve her dizine ekleme yaptığınızda tam geçiş yapma ek yükünü karşılayabilir.

Bu geçiş stratejisi, çoğunlukla statik ve hiyerarşik olmayan verilerin bulunduğu küçük depolar için uygundur. Bu geçiş stratejisini, değişiklik algılamanın zor olduğu veya depo tarafından desteklenmediğinde de kullanabilirsiniz.

Liste geçiş stratejisi

Liste geçiş stratejisi, tüm alt düğümler de dahil olmak üzere deponun tamamını tarayarak her öğenin durumunu belirler. Daha sonra, bağlayıcı ikinci bir geçiş yapar ve yalnızca son dizine ekleme işleminden sonra güncellenmiş veya yeni olan öğeleri dizine ekler. Bu strateji genellikle mevcut bir dizine artımlı güncellemeler yapmak için kullanılır (dizini her güncellediğinizde tam geçiş yapmak yerine).

Bu geçiş stratejisi, değişiklik algılamanın zor olduğu veya depo tarafından desteklenmediği, hiyerarşik olmayan verilerinizin olduğu ve çok büyük veri kümeleriyle çalıştığınız durumlarda uygundur.

Grafik geçişi

Grafik geçiş stratejisi, her öğenin durumunu belirlemek için üst düğümün tamamını tarar. Ardından, bağlayıcı ikinci bir geçiş yapar ve yalnızca kök düğümdeki dizin oluşturma işlemi yenidir veya son dizine ekleme işleminden sonra güncellenmiştir. Son olarak, bağlayıcı tüm alt kimlikleri geçirir ve ardından alt düğümlerdeki yeni veya güncellenmiş öğeleri dizine ekler. Bağlayıcı, tüm öğeler ele alınana kadar tüm alt düğümlerde yinelemeli bir şekilde devam eder. Bu tür geçişler, genellikle tüm kimliklerin listelenmesinin pratik olmadığı hiyerarşik depolar için kullanılır.

Bu strateji, dizi dizinleri veya web sayfaları gibi taranması gereken hiyerarşik verileriniz varsa uygundur.

Not: Bu belgede ve örnek kodda "öğe" ve "doküman" terimleri eş anlamlıdır.

Geçiş stratejinizi uygulama ve öğelerinizi dizine ekleme

Cloud Search için dizine eklenebilir her öğe, Cloud Search API'de bir öğe olarak adlandırılır. Öğe bir dosya, klasör, CSV dosyasındaki bir satır veya bir veritabanı kaydı olabilir.

Şemanız kaydedildikten sonra dizini aşağıdaki şekilde doldurabilirsiniz:

1. (isteğe bağlı) Dizine eklemek üzere 100 KiB'tan büyük dosyaları yüklemek için items.upload kullanma. Daha küçük dosyalar için içeriği items.index kullanarak inlineContent olarak yerleştirin.

2. (İsteğe bağlı) Dizine eklemek üzere medya dosyalarını yüklemek için media.upload kullanma.

3. Öğeyi dizine eklemek için items.index kullanılıyor. Örneğin, şemanız film şemasında nesne tanımını kullanıyorsa tek bir öğe için dizine ekleme isteği şu şekilde görünür:

   {
     "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. (İsteğe bağlı) Bir öğenin dizine eklendiğini doğrulamak için items.get çağrılarını kullanma.

Tam bir geçiş gerçekleştirmek için deponun tamamını düzenli aralıklarla yeniden dizine eklemeniz gerekir. Liste veya grafik geçişi gerçekleştirmek için depo değişikliklerini işleme kodu uygulamanız gerekir.

Not: ItemMetadata öğesindeki objectType alanı, şemadaki nesne tanımı adıyla eşleşmelidir. Bu şekilde, Cloud Search dizin isteğinde nesnenin beklenen yapısını tanımlar. Bir dizine ekleme isteğinde, geçerli şemayla kaydedilmemiş özellikler içeren yapılandırılmış veriler gönderirseniz veya şemadaki nesne tanımlarından birinin adına karşılık gelmeyen bir nesne türü belirtirseniz nesne veya özellik yoksayılır. Ayrıca, şemada kayıtlı olan türden farklı bir türe sahip özellikler gönderirseniz Cloud Search, dizine ekleme zamanında bir hata yanıtı döndürür.

Not: İstemcinizin yaptığı her HTTP bağlantısı ek yük oluşturur. Genel gideri azaltmak için birden fazla API çağrısını tek bir HTTP isteğinde birlikte toplayabilirsiniz. HTTP bağlantılarınızın ek yükünü nasıl azaltacağınızı öğrenmek için Toplu işlem isteğinde bulunma bölümüne bakın. Büyük medya yüklemelerinin nasıl ele alınacağını öğrenmek için Doğrudan ve Devam Ettirilebilir Medya Yüklemeleri bölümüne bakın.

Depo değişikliklerini işleme

Tam dizine ekleme için her öğeyi bir depodaki belirli aralıklarla toplayabilir ve dizine ekleyebilirsiniz. Dizininizin güncel olmasını sağlamada etkili olsa da, daha büyük veya hiyerarşik depolarla çalışırken tam dizine ekleme işlemi maliyetli olabilir.

Bir deponun tamamını dizine eklemek için sık sık dizin çağrıları kullanmak yerine, değişiklikleri izleyip yalnızca değişen öğeleri dizine eklemek için kullanılan bir mekanizma olarak Google Cloud Dizine Ekleme Sırası'nı da kullanabilirsiniz. Öğeleri daha sonra yoklama ve güncelleme amacıyla sıraya aktarmak için items.push isteklerini kullanabilirsiniz. Google Cloud Dizine Ekleme Sırası hakkında daha fazla bilgi için Google Cloud Dizine Ekleme Sırası'na bakın.

Google Cloud Search API hakkında daha fazla bilgi için Cloud Search API sayfasına bakın.