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

İçerik bağlayıcı, bir işletmenin deposundaki verileri aktarmak ve bir veri kaynağını doldurmak için kullanılan 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'nin çevresinde yer alan ve bağlayıcıları hızlıca oluşturmanıza olanak tanıyan bir sarmalayıcıdır. 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 yapmıyorsanız veya kod tabanınız bir REST API'yi veya kitaplığı daha iyi barındırıyorsa bu seçenekleri kullanın. REST API'yi kullanarak içerik bağlayıcı oluşturmak için REST API'yi kullanarak içerik bağlayıcı oluşturma bölümüne bakın.

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

1. Yapılandırma parametrelerini okur ve işler.
2. Üçüncü taraf içerik veri havuzundan, "items" adlı ayrı 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 bildirimleri değiştirmeyi dinler. Cloud Search veri kaynağını üçüncü taraf deposuyla senkronize tutmak 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 uygular.

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

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

Bağımlılık oluşturma

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 bir sekmeyi 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, depo tarafından kullanılan kimlik gibi, bağlayıcı tarafından kullanılan parametreleri 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'sı, tüm bağlayıcılar tarafından kullanılan, Google tarafından sağlanan çeşitli yapılandırma parametrelerini içerir. Google tarafından sağlanan aşağıdaki parametreleri yapılandırma dosyanızda bildirmeniz gerekir:

• İçerik bağlayıcı söz konusu olduğunda, bu parametreler depoya erişmek için gereken deponuzun ve özel anahtarınızın konumunu tanımladığından api.sourceId ve api.serviceAccountPrivateKeyFile beyan etmeniz gerekir.

Not: Özel anahtar dosyanız bir JSON anahtarı değilse bunu da geçersiz kılmanız gerekirapi.serviceAccountId.

• Bir kimlik bağlayıcısı için api.identitySourceId parametresi, harici kimlik kaynağınızın konumunu tanımladığından bunu bildirmeniz gerekir. Kullanıcıları senkronize ediyorsanız api.customerId hizmetinin, kuruluşunuzun Google Workspace hesabı için benzersiz kimlik olarak da beyan edilmesi 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 tarafından sağlanan yapılandırma parametreleri hakkında, belirli kimliklerin ve anahtarların nasıl oluşturulacağı gibi ek bilgiler için Google tarafından sağlanan yapılandırma parametrelerine bakın.

Yapılandırma dosyanızda kullanılacak, depoya özel parametreleri de tanımlayabilirsiniz.

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

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

Yapılandırma dosyasını bağlayıcınıza iletmek için 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ının birincil işlevi, bir depodan veri aktarmak ve 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, deponun tamamını tarar ve her öğeyi kör olarak dizine ekler. Bu strateji genellikle küçük bir deponuz olduğunda kullanılır ve her dizine ekleme işleminizde tam geçiş yapmanın ek yüküne neden olabilir.

Bu geçiş stratejisi, çoğunlukla hiyerarşik olmayan, statik verileri olan küçük depolar için uygundur. Bu geçiş stratejisini, değişiklik algılaması zor olduğunda veya depo tarafından desteklenmediğinde de kullanabilirsiniz.

Geçiş stratejisi listeleme

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

Bu geçiş stratejisi, değişiklik algılaması zor olduğunda veya veri havuzu tarafından desteklenmediğinde, hiyerarşik olmayan verileriniz olduğunda ve çok büyük veri kümeleriyle çalıştığınızda uygundur.

Grafik geçişi

Grafik geçiş stratejisi, her bir öğ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 öğeler yenidir veya son dizine ekleme işleminden sonra güncellenir. Son olarak bağlayıcı, tüm alt kimlikleri iletir. Ardından yeni veya güncellenmiş alt düğümlerdeki öğeleri dizine ekler. Bağlayıcı, tüm öğeler ele alınana kadar tüm alt düğümlerde yinelemeli olarak devam eder. Bu geçiş, genellikle tüm kimliklerin listelenmesinin pratik olmadığı hiyerarşik depolar için kullanılır.

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

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

Bu geçiş stratejilerinin her biri, SDK'daki 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şimini büyük ölçüde hızlandırır. Bir ş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
• Ş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

Dokümanların bu bölümünde, FullTraversalSample örneğinden alınan kod snippet'leri açıklanmaktadır.

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

Bağlayıcının 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 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ıldıktan sonra initConfig() yöntemini Application.build çağırır. initConfig() yöntemi aşağıdaki görevleri gerçekleştirir:

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

Repository arayüzünü uygulama

Repository nesnesinin tek amacı, depo öğelerinin geçişini ve dizine eklenmesini sağlamaktır. Şablon kullanırken içerik bağlayıcı oluşturmak için Repository arayüzünde yalnızca belirli yöntemleri geçersiz kılmanız gerekir. Geçersiz kıldığı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 havuzu kurulumu ve başlatma işlemleri yapmak için init() yöntemini geçersiz kılın.

• getAllDocs() yöntemi. Veri deposundaki tüm öğeleri yönlendirmek 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 için planlanan her bir artımlı geçiş (yapılandırmanız tarafından tanımlandığı şekilde) için bir kez çağrılır.

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

Repository nesnesinin yöntemlerinden her biri, bir tür ApiOperation nesnesi döndürür. Bir ApiOperation nesnesi, deponuzun gerçek dizine eklenmesini sağlamak için tek veya birkaç IndexingService.indexItem() çağrısı şeklinde bir işlem gerçekleştirir.

Özel yapılandırma parametreleri alma

Bağlayıcınızın yapılandırmasını yönetirken, özel parametreleri Configuration nesnesinden almanız gerekir. Bu görev genellikle bir Repository sınıfının init() yönteminde gerçekleştirilir.

Configuration sınıfı, bir yapılandırmadan farklı veri türleri almaya yönelik birkaç yöntem sunar. Her yöntem bir ConfigValue nesnesi döndürür. Ardından, gerçek değeri almak için ConfigValue nesnesinin get() yöntemini kullanırsınız. Aşağıdaki snippet'te (FullTraversalSample) Configuration nesnesinden tek bir özel tam sayı değerinin nasıl alınacağını görebilirsiniz:

FullTraversalSample.java

GitHub'da göster

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

Birkaç değer içeren bir parametre almak ve ayrıştırmak için Configuration sınıfı türündeki 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'te, bir GitHub deposu adı listesi almak için getMultiValue yöntemi kullanılır:

GitHubRepository.java

GitHub'da göster

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

Tam geçiş yapma

Geçişi tam olarak gerçekleştirmek ve deponuzu dizine eklemek için getAllDocs() parametresini geçersiz kılın. getAllDocs() yöntemi, bir kontrol noktasını kabul eder. İşlem kesintiye uğrarsa 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 verileri ve öğeyi dizine eklenebilir tek bir RepositoryDoc altında birleştirin.
4. Dizine eklenebilir her öğeyi getAllDocs() yöntemi tarafından döndürülen bir iterasyon öğesi halinde paketleyin. getAllDocs(), aslında ApiOperation nesnelerinden oluşan bir iterasyon olan bir CheckpointCloseableIterable döndürür. Her nesne, birRepositoryDoc cihazda gerçekleştirilen API isteğini temsil eder (dizine ekleme gibi).

Bir grup öğe, tek bir çağrıda işlenemeyecek kadar büyükse bir kontrol noktası ekleyin ve hasMore(true) öğesini, dizine eklenebilecek daha fazla öğe olduğunu gösterecek şekilde ayarlayın.

Bir öğenin izinlerini ayarlama

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

Yalnızca bir öğeye erişimi olan kullanıcıların arama sonuçlarında bu öğeyi görebilmesi için deponuz tarafından kullanılan EKL'yi kopyalamanız gerekir. Google Cloud Search'ün bir öğeye doğru erişim düzeyini sağlamak için gerekli bilgilere sahip olması amacıyla, öğeyi dizine eklerken bir öğenin EKL'si eklenmelidir.

Content Connector SDK'sı, çoğu deponun EKL'lerini modellemek için zengin bir EKL sınıf seti ve yöntemi sağlar. Deponuzdaki her öğe için EKL'yi analiz etmeniz ve bir öğeyi dizine eklediğinizde Google Cloud Search için karşılık gelen bir EKL oluşturmanız gerekir. Deponuzun EKL'sinde EKL devralma gibi kavramlar kullanılıyorsa ilgili EKL'yi modellemek karmaşık olabilir. Google Cloud Search EKL'leri hakkında daha fazla bilgi için Google Cloud Search EKL'leri bölümünü inceleyin.

Not: Cloud Search dizine ekleme API'si, tek alanlı EKL'leri destekler. Alanlar arası EKL'leri desteklemez. EKL kullanarak her bir öğeye erişimi ayarlamak için Acl.Builder sınıfını kullanın. Tüm geçiş örneğinden alınan aşağıdaki kod snippet'i, arama yaparken tüm kullanıcıların veya "ana hesabın" (getCustomerPrincipal()) tüm öğelerin "okuyucuları" (.setReaders()) olmasına olanak tanır.

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

Deponun EKL'lerini doğru bir şekilde modellemek için EKL'leri anlamanız gerekir. Örneğin, alt klasörlerin izinleri üst klasörlerden devraldığı bir tür devralma modeli kullanan dosya sistemindeki dosyaları dizine ekliyor olabilirsiniz. EKL'yi devralma modelleme, Google Cloud Search EKL'lerinde açıklanan ek bilgileri gerektirir

Bir öğenin meta verilerini ayarlama

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

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 öğe oluşturma

Öğenin meta verilerini belirledikten sonra, RepositoryDoc.Builder sınıfını kullanarak gerçek dizine eklenebilir öğe oluşturabilirsiniz. Aşağıdaki örnekte dizine eklenebilir tek bir öğ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 ekleme-sunuma gecikmesinin artmasını ve dizine ekleme istekleri için büyük işleme hızı kotasını karşılar. Deponun tamamının ilk dizine eklenmesi (dolgu) işlemi için eşzamansız modun kullanılması önerilir.

SYNCHRONOUS

Eşzamanlı mod, dizine ekleme-sunum gecikme süresinin daha kısa olmasını sağlar ve sınırlı işleme hızı kotasına uyum sağlar. Depoda yapılan güncellemelerin ve değişikliklerin dizine eklenmesi için eşzamanlı mod önerilir. Belirtilmezse istek modu varsayılan olarak SYNCHRONOUS değerine ayarlanır.

Dizine eklenebilir her öğeyi bir iterasyon aracında paketleyin

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

FullTraversalSample.java

GitHub'da göster

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

SDK, yinelenen her bir dizine ekleme çağrısını yürütür.

Not: Cloud Search tüm dosyaların meta verilerini dizine ekler. Bir dosyanın dosya türüne bağlı olarak Cloud Search, resim ve diğer dosyalarda Optik Karakter Tanıma (OCR) kullanımı da dahil olmak üzere metin içeriğini dizine ekler. Metin çıkarmayı destekleyen dosya türlerinin listesi için Metin çıkarma için desteklenen dosya türleri başlıklı makaleyi inceleyin.

Sonraki Adımlar

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

• (isteğe bağlı) Dizine ekleme işleme hızınız yavaş görünüyorsa FullTraversalConnector için dizine ekleme oranını artırma başlıklı makaleyi inceleyin.
• (İsteğe bağlı) Kapatmadan önce tüm 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ı oluşturun.

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

Cloud Search Dizine Ekleme Sırası, depodaki her bir öğeye ait kimlikleri ve isteğe bağlı karma değerlerini bekletmek için kullanılır. Bir liste geçiş bağlayıcısı, öğe kimliklerini Google Cloud Search dizine ekleme sırasına aktarır ve dizine eklenmek için tek tek alır. Google Cloud Search, öğe durumunu (bir öğenin depodan silinip silinmediği gibi) belirlemek için sıraları korur ve sıra içeriklerini karşılaştırır. Cloud Search dizine ekleme sırası hakkında daha fazla bilgi edinmek için Cloud Search dizine ekleme sırası bölümüne bakın.

Dokümanların bu bölümünde, ListTraversalSample örneğinden alınan kod snippet'leri açıklanmaktadır.

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

Bağlayıcının 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 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 davet edileceğini 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ıldıktan sonra initConfig() yöntemini Application.build çağırır. initConfig() yöntemi:

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

Repository arayüzünü uygulama

Repository nesnesinin tek amacı, depo öğelerinin geçişini ve dizine eklenmesini sağlamaktır. Şablon kullanırken içerik bağlayıcı oluşturmak için yalnızca Repository arayüzündeki belirli yöntemleri geçersiz kılmanız gerekir. Geçersiz kıldığı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 havuzu kurulumu ve başlatma işlemleri yapmak 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 için planlanan her bir artımlı geçiş (yapılandırmanız tarafından tanımlandığı şekilde) için bir kez çağrılır.

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

Repository nesnesinin yöntemlerinden her biri, bir tür ApiOperation nesnesi döndürür. Bir ApiOperation nesnesi, deponuzun gerçek dizine eklenmesini sağlamak için tek veya birkaç IndexingService.indexItem() çağrısı şeklinde bir işlem gerçekleştirir.

Özel yapılandırma parametreleri alma

Bağlayıcınızın yapılandırmasını yönetirken, özel parametreleri Configuration nesnesinden almanız gerekir. Bu görev genellikle bir Repository sınıfının init() yönteminde gerçekleştirilir.

Configuration sınıfı, bir yapılandırmadan farklı veri türleri almaya yönelik birkaç yöntem sunar. Her yöntem bir ConfigValue nesnesi döndürür. Ardından, gerçek değeri almak için ConfigValue nesnesinin get() yöntemini kullanırsınız. Aşağıdaki snippet'te (FullTraversalSample) Configuration nesnesinden tek bir özel tam sayı değerinin nasıl alınacağını görebilirsiniz:

FullTraversalSample.java

GitHub'da göster

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

Birkaç değer içeren bir parametre almak ve ayrıştırmak için Configuration sınıfı türündeki 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'te, bir GitHub deposu adı listesi almak için getMultiValue yöntemi kullanılı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ını kabul eder. Kontrol noktası, süreç kesintiye uğrarsa belirli bir öğenin dizine eklenmesini devam ettirmek için kullanılır.

Ardından, Cloud Search dizine ekleme sırasındaki her öğeyi işlemek için getDoc() yöntemini geçersiz kılın.

Push öğesi kimlikleri ve karma değerleri

Depodan öğe kimliklerini ve ilişkili içerik karma değerlerini almak için getIds() etiketini geçersiz kılın. Ardından kimlik ve karma değeri çiftleri, Cloud Search dizine ekleme sırasına aktarma işlemi isteği olarak paketlenir. Kök veya üst kimlikler genellikle tüm öğe hiyerarşisi işlenene kadar ilk olarak alt kimlikler aktarılır.

getIds() yöntemi, dizine eklenecek son öğeyi temsil eden bir kontrol noktasını kabul eder. İşlem kesintiye uğrarsa belirli bir öğede dizine ekleme işlemine devam etmek için kontrol noktası kullanılabilir. Deponuzdaki her öğe için getIds() yöntemini kullanarak aşağıdaki adımları uygulayın:

• Depodan her öğe kimliğini ve ilişkili karma değerini alın.
• Her kimliği ve karma değeri çiftini bir PushItems olarak paketleyin.
• Her PushItems öğesini, getIds() yöntemi tarafından döndürülen bir iterasyonda birleştirin. getIds() işlevinin aslında ApiOperation nesnelerinden oluşan bir CheckpointCloseableIterable döndürmesi olduğunu unutmayın. Bu nesne, RepositoryDoc üzerinde gerçekleştirilen bir API isteğini temsil eden her nesne (ör. öğeleri sıraya aktarmak).

Aşağıdaki kod snippet'i, her bir öğe kimliğini ve karma değerini nasıl alacağınızı ve PushItems öğesine nasıl ekleneceğini gösterir. PushItems, bir öğeyi Cloud Search Dizine Ekleme sırasına aktarmaya yönelik bir 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'inde, kimlikleri ve karma değerlerini tek bir aktarma paketinde paketlemek için PushItems.Builder sınıfının nasıl kullanılacağı gösterilmektedirApiOperation.

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 alın ve işleyin

Cloud Search dizine ekleme sırasındaki her öğeyi işlemek için getDoc() değerini geçersiz kılın. Bir öğe yeni veya değiştirilmiş olabilir ya da artık kaynak veri havuzunda bulunamaz. Yeni veya değiştirilmiş her bir öğeyi alın ve dizine ekleyin. Artık kaynak depoda bulunmayan öğeleri dizinden kaldırın.

getDoc() yöntemi, Google Cloud Search dizine ekleme sırasındaki bir öğeyi kabul eder. Sıradaki her öğe için getDoc() yöntemini kullanarak şu adımları uygulayın:

1. Cloud Search Dizine Ekleme Sırası'nda öğe kimliğinin depoda olup olmadığını kontrol edin. Doğru değilse öğeyi dizinden silin.

2. Öğe durumunun dizinini sorgulayın. Bir öğede değişiklik olmazsa (ACCEPTED) hiçbir şey yapmayın.

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

   1. İzinleri ayarlayın.
   2. Dizine eklediğiniz öğenin meta verilerini ayarlayın.
   3. Meta verileri ve öğeyi dizine eklenebilir tek bir RepositoryDoc altında birleştirin.
   4. RepositoryDoc değerini döndürün.

Not: ListingConnector şablonu, getDoc() yönteminde null döndürülmesini desteklemez. null sonucunu NullPointerException. ile döndürür

Silinen öğeleri işleme

Aşağıdaki kod snippet'i, bir öğenin depoda olup olmadığını nasıl belirleyeceğinizi ve yoksa öğeyi nasıl sileceğinizi 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 veri havuzunu temsil eden bir veri yapısı olduğunu unutmayın. documentID documents öğesinde bulunamazsa öğeyi dizinden silmek için APIOperations.deleteItem(resourceName) döndürün.

Değişmeyen öğeleri işleme

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 herhangi bir değişiklik olduğunu gösterebilecek diğer meta verileri kontrol edin. Ö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 bir Erişim Kontrol Listesi (EKL) kullanır. EKL, öğeye erişebilen gruplar veya kullanıcılar için bir kimlik listesidir.

Yalnızca bir öğeye erişimi olan kullanıcıların arama sonuçlarında bu öğeyi görebilmesi için deponuz tarafından kullanılan EKL'yi kopyalamanız gerekir. Google Cloud Search'ün bir öğeye doğru erişim düzeyini sağlamak için gerekli bilgilere sahip olması amacıyla, öğeyi dizine eklerken bir öğenin EKL'si eklenmelidir.

Content Connector SDK'sı, çoğu deponun EKL'lerini modellemek için zengin bir EKL sınıf seti ve yöntemi sağlar. Deponuzdaki her öğe için EKL'yi analiz etmeniz ve bir öğeyi dizine eklediğinizde Google Cloud Search için karşılık gelen bir EKL oluşturmanız gerekir. Deponuzun EKL'sinde EKL devralma gibi kavramlar kullanılıyorsa ilgili EKL'yi modellemek karmaşık olabilir. Google Cloud Search EKL'leri hakkında daha fazla bilgi için Google Cloud Search EKL'leri bölümünü inceleyin.

Not: Cloud Search dizine ekleme API'si, tek alanlı EKL'leri destekler. Alanlar arası EKL'leri desteklemez. EKL kullanarak her bir öğeye erişimi ayarlamak için Acl.Builder sınıfını kullanın. Tüm geçiş örneğinden alınan aşağıdaki kod snippet'i, arama yaparken tüm kullanıcıların veya "ana hesabın" (getCustomerPrincipal()) tüm öğelerin "okuyucuları" (.setReaders()) olmasına olanak tanır.

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

Deponun EKL'lerini doğru bir şekilde modellemek için EKL'leri anlamanız gerekir. Örneğin, alt klasörlerin izinleri üst klasörlerden devraldığı bir tür devralma modeli kullanan dosya sistemindeki dosyaları dizine ekliyor olabilirsiniz. EKL'yi devralma modelleme, Google Cloud Search EKL'lerinde açıklanan ek bilgileri gerektirir

Bir öğenin meta verilerini ayarlama

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

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 bir öğe oluşturma

Öğenin meta verilerini belirledikten sonra RepositoryDoc.Builder öğesini kullanarak gerçek dizine eklenebilir öğe oluşturabilirsiniz. Aşağıdaki örnekte dizine eklenebilir tek bir öğ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 ekleme-sunuma gecikmesinin artmasını ve dizine ekleme istekleri için büyük işleme hızı kotasını karşılar. Deponun tamamının ilk dizine eklenmesi (dolgu) işlemi için eşzamansız modun kullanılması önerilir.

SYNCHRONOUS

Eşzamanlı mod, dizine ekleme-sunum gecikme süresinin daha kısa olmasını sağlar ve sınırlı işleme hızı kotasına uyum sağlar. Depoda yapılan güncellemelerin ve değişikliklerin dizine eklenmesi için eşzamanlı mod önerilir. Belirtilmezse istek modu varsayılan olarak SYNCHRONOUS değerine ayarlanır.

Not: Cloud Search tüm dosyalar için meta verileri dizine ekler. Bir öğenin dosya türüne bağlı olarak Cloud Search, elle yazılmış içeriklerde Optik Karakter Tanıma (OCR) kullanımı da dahil olmak üzere metin içeriğini dizine ekler. Metin çıkarmayı destekleyen dosya türlerinin listesi için Metin çıkarma için desteklenen dosya türleri başlıklı makaleyi inceleyin.

Sonraki Adımlar

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

• (İsteğe bağlı) Kapatmadan önce tüm 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ı oluşturun.

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

Cloud Search Dizine Ekleme Sırası, depodaki her bir öğeye ait kimlikleri ve isteğe bağlı karma değerlerini bekletmek 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 dizine eklenmek için tek tek alır. Google Cloud Search sıraları korur ve sıra içeriklerini, bir öğenin depodan silinip silinmediği gibi belirlemek için 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ı bölümüne 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 yinelenen bir şekilde işlemeye devam eder.

Dokümanların bu bölümünde, GraphTraversalSample örneğindeki kod snippet'leri ele alınmıştır.

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

Bağlayıcının 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 start() yöntemini çağırmaktır.

application.start() bölümünü çağırmadan önce IndexingApplication.Builder sınıfını kullanarak ListingConnector şablonunu oluşturun. ListingConnector, yöntemlerini uyguladığınız bir Repository nesnesini kabul eder.

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

Aşağıdaki snippet, ListingConnector ve ilişkili Repository öğesinin nasıl davet edileceğini 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ıldıktan sonra initConfig() yöntemini Application.build çağırır. initConfig() yöntemi:

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

Repository arayüzünü uygulama

Repository nesnesinin tek amacı, depo öğelerinin geçişini ve dizine eklenmesini sağlamaktır. Şablon kullanırken içerik bağlayıcı oluşturmak için yalnızca Repository arayüzündeki belirli yöntemleri geçersiz kılmanız gerekir. Geçersiz kıldığınız yöntemler, şablona ve kullandığınız geçiş stratejisine bağlıdır. ListingConnector için aşağıdaki yöntemleri geçersiz kılabilirsiniz:

• init() yöntemi. Veri havuzu kurulumu ve başlatma işlemleri yapmak 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 için planlanan her bir artımlı geçiş (yapılandırmanız tarafından tanımlandığı şekilde) için bir kez çağrılır.

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

Repository nesnesinin yöntemlerinden her biri, bir ApiOperation nesnesi türünü döndürür. Bir ApiOperation nesnesi, deponuzun gerçek dizine eklenmesini gerçekleştirmek için tek veya birkaç IndexingService.indexItem() çağrısı şeklinde bir işlem gerçekleştirir.

Özel yapılandırma parametreleri alma

Bağlayıcınızın yapılandırmasını yönetirken, özel parametreleri Configuration nesnesinden almanız gerekir. Bu görev genellikle bir Repository sınıfının init() yönteminde gerçekleştirilir.

Configuration sınıfı, bir yapılandırmadan farklı veri türleri almaya yönelik birkaç yöntem sunar. Her yöntem bir ConfigValue nesnesi döndürür. Ardından, gerçek değeri almak için ConfigValue nesnesinin get() yöntemini kullanırsınız. Aşağıdaki snippet'te (FullTraversalSample) Configuration nesnesinden tek bir özel tam sayı değerinin nasıl alınacağını görebilirsiniz:

FullTraversalSample.java

GitHub'da göster

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

Birkaç değer içeren bir parametre almak ve ayrıştırmak için Configuration sınıfı türündeki 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'te, bir GitHub deposu adı listesi almak için getMultiValue yöntemi kullanılı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ş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ını kabul eder. Kontrol noktası, süreç kesintiye uğrarsa belirli bir öğenin dizine eklenmesini devam ettirmek için kullanılır.

Ardından, Cloud Search dizine ekleme sırasındaki her öğeyi işlemek için getDoc() yöntemini geçersiz kılın.

Push öğesi kimlikleri ve karma değerleri

Depodan öğe kimliklerini ve ilişkili içerik karma değerlerini almak için getIds() etiketini geçersiz kılın. Ardından kimlik ve karma değeri çiftleri, Cloud Search dizine ekleme sırasına aktarma işlemi isteği olarak paketlenir. Kök veya üst kimlikler genellikle tüm öğe hiyerarşisi işlenene kadar ilk olarak alt kimlikler aktarılır.

getIds() yöntemi, dizine eklenecek son öğeyi temsil eden bir kontrol noktasını kabul eder. İşlem kesintiye uğrarsa belirli bir öğede dizine ekleme işlemine devam etmek için kontrol noktası kullanılabilir. Deponuzdaki her öğe için getIds() yöntemini kullanarak aşağıdaki adımları uygulayın:

• Depodan her öğe kimliğini ve ilişkili karma değerini alın.
• Her kimliği ve karma değeri çiftini bir PushItems olarak paketleyin.
• Her PushItems öğesini, getIds() yöntemi tarafından döndürülen bir iterasyonda birleştirin. getIds() işlevinin aslında ApiOperation nesnelerinden oluşan bir CheckpointCloseableIterable döndürmesi olduğunu unutmayın. Bu nesne, RepositoryDoc üzerinde gerçekleştirilen bir API isteğini temsil eden her nesne (ör. öğeleri sıraya aktarmak).

Aşağıdaki kod snippet'i, her bir öğe kimliğini ve karma değerini nasıl alacağınızı ve PushItems bölümüne nasıl ekleyeceğinizi gösterir. PushItems, bir öğeyi Cloud Search dizine ekleme sırasına aktarmaya yönelik bir 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'te paketlemek için PushItems.Builder sınıfının nasıl kullanılacağını gösterir.

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 alın ve işleyin

Cloud Search dizine ekleme sırasındaki her öğeyi işlemek için getDoc() değerini geçersiz kılın. Bir öğe yeni veya değiştirilmiş olabilir ya da artık kaynak veri havuzunda bulunamaz. Yeni veya değiştirilmiş her bir öğeyi alın ve dizine ekleyin. Artık kaynak depoda bulunmayan öğeleri dizinden kaldırın.

getDoc() yöntemi, Cloud Search dizine ekleme sırasından bir öğeyi kabul eder. Sıradaki her öğe için getDoc() yöntemini kullanarak şu adımları uygulayın:

1. Cloud Search Dizine Ekleme Sırası'ndaki öğe kimliğinin depoda olup olmadığını kontrol edin. Doğru değilse öğeyi dizinden silin. Öğe mevcutsa bir sonraki adımla devam edin.

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

   1. İzinleri ayarlayın.
   2. Dizine eklediğiniz öğenin meta verilerini ayarlayın.
   3. Meta verileri ve öğeyi dizine eklenebilir tek bir RepositoryDoc altında birleştirin.
   4. Daha fazla işlem görmesi için alt kimlikleri Cloud Search Dizine Ekleme Sırası'na yerleştirin.
   5. RepositoryDoc değerini döndürün.

Silinen öğeleri işleme

Aşağıdaki kod snippet'i, bir öğenin dizinde olup olmadığını nasıl belirleyeceğini ve yoksa silmemesini 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 bir Erişim Kontrol Listesi (EKL) kullanır. EKL, öğeye erişebilen gruplar veya kullanıcılar için bir kimlik listesidir.

Yalnızca bir öğeye erişimi olan kullanıcıların arama sonuçlarında bu öğeyi görebilmesi için deponuz tarafından kullanılan EKL'yi kopyalamanız gerekir. Google Cloud Search'ün bir öğeye doğru erişim düzeyini sağlamak için gerekli bilgilere sahip olması amacıyla, öğeyi dizine eklerken bir öğenin EKL'si eklenmelidir.

Content Connector SDK'sı, çoğu deponun EKL'lerini modellemek için zengin bir EKL sınıf seti ve yöntemi sağlar. Deponuzdaki her öğe için EKL'yi analiz etmeniz ve bir öğeyi dizine eklediğinizde Google Cloud Search için karşılık gelen bir EKL oluşturmanız gerekir. Deponuzun EKL'sinde EKL devralma gibi kavramlar kullanılıyorsa ilgili EKL'yi modellemek karmaşık olabilir. Google Cloud Search EKL'leri hakkında daha fazla bilgi için Google Cloud Search EKL'leri bölümünü inceleyin.

Not: Cloud Search dizine ekleme API'si, tek alanlı EKL'leri destekler. Alanlar arası EKL'leri desteklemez. EKL kullanarak her bir öğeye erişimi ayarlamak için Acl.Builder sınıfını kullanın. Tüm geçiş örneğinden alınan aşağıdaki kod snippet'i, arama yaparken tüm kullanıcıların veya "ana hesabın" (getCustomerPrincipal()) tüm öğelerin "okuyucuları" (.setReaders()) olmasına olanak tanır.

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

Deponun EKL'lerini doğru bir şekilde modellemek için EKL'leri anlamanız gerekir. Örneğin, alt klasörlerin izinleri üst klasörlerden devraldığı bir tür devralma modeli kullanan dosya sistemindeki dosyaları dizine ekliyor olabilirsiniz. EKL'yi devralma modelleme, Google Cloud Search EKL'lerinde açıklanan ek bilgileri gerektirir

Bir öğenin meta verilerini ayarlama

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

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 öğe oluşturma

Öğenin meta verilerini belirledikten sonra RepositoryDoc.Builder öğesini kullanarak gerçek dizine eklenebilir öğe oluşturabilirsiniz. Aşağıdaki örnekte dizine eklenebilir tek bir öğ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 ekleme-sunuma gecikmesinin artmasını ve dizine ekleme istekleri için büyük işleme hızı kotasını karşılar. Deponun tamamının ilk dizine eklenmesi (dolgu) işlemi için eşzamansız modun kullanılması önerilir.

SYNCHRONOUS

Eşzamanlı mod, dizine ekleme-sunum gecikme süresinin daha kısa olmasını sağlar ve sınırlı işleme hızı kotasına uyum sağlar. Depoda yapılan güncellemelerin ve değişikliklerin dizine eklenmesi için eşzamanlı mod önerilir. Belirtilmezse istek modu varsayılan olarak SYNCHRONOUS değerine ayarlanır.

Alt kimlikleri Cloud Search dizine ekleme sırasına yerleştirin

Aşağıdaki kod snippet'i, şu anda işlenmekte olan üst öğe için alt kimlikleri, işleme sırasına nasıl dahil edeceğinizi gösterir. 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. Bir öğenin dosya türüne bağlı olarak Cloud Search, elle yazılmış içeriklerde Optik Karakter Tanıma (OCR) kullanımı da dahil olmak üzere metin içeriğini dizine ekler. Metin çıkarmayı destekleyen dosya türlerinin listesi için Metin çıkarma için desteklenen dosya türleri başlıklı makaleyi inceleyin.

Sonraki Adımlar

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

• (İsteğe bağlı) Kapatmadan önce tüm 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ı oluşturun.

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

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

Geçiş stratejinizi belirleme

İçerik bağlayıcının birincil işlevi, bir depodan veri aktarmak ve verilerini dizine eklemektir. Deponuzdaki verilerin boyutuna ve düzenine bağlı olarak bir geçiş stratejisi uygulamanız gerekir. Yaygın olarak kullanılan üç geçiş stratejisi şunlardır:

Tam geçiş stratejisi

Tam geçiş stratejisi, deponun tamamını tarar ve her öğeyi kör olarak dizine ekler. Bu strateji genellikle küçük bir deponuz olduğunda kullanılır ve her dizine ekleme işleminizde tam geçiş yapmanın ek yüküne neden olabilir.

Bu geçiş stratejisi, çoğunlukla hiyerarşik olmayan, statik verileri olan küçük depolar için uygundur. Bu geçiş stratejisini, değişiklik algılaması zor olduğunda veya depo tarafından desteklenmediğinde de kullanabilirsiniz.

Geçiş stratejisi listeleme

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

Bu geçiş stratejisi, değişiklik algılaması zor olduğunda veya veri havuzu tarafından desteklenmediğinde, hiyerarşik olmayan verileriniz olduğunda ve çok büyük veri kümeleriyle çalıştığınızda uygundur.

Grafik geçişi

Grafik geçiş stratejisi, her bir öğ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 öğeler yenidir veya son dizine ekleme işleminden sonra güncellenir. Son olarak bağlayıcı, tüm alt kimlikleri iletir. Ardından yeni veya güncellenmiş alt düğümlerdeki öğeleri dizine ekler. Bağlayıcı, tüm öğeler ele alınana kadar tüm alt düğümlerde yinelemeli olarak devam eder. Bu geçiş, genellikle tüm kimliklerin listelenmesinin pratik olmadığı hiyerarşik depolar için kullanılır.

Seri dizinleri veya web sayfaları gibi taranması gereken hiyerarşik verileriniz varsa bu strateji uygundur.

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

Geçiş stratejinizi ve dizin öğelerinizi uygulama

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

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

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

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

3. Öğeyi dizine eklemek için items.index özelliğini kullanma. Örneğin, şemanız film şemasında nesne tanımını kullanıyorsa tek bir öğe için dizine ekleme isteği aşağıdaki gibi 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 öğeyi doğrulamak için items.get çağrıları dizine eklendi.

Geçişin tam olarak yapılması için deponun tamamını düzenli olarak yeniden dizine eklersiniz. Bir liste veya grafik geçişi gerçekleştirmek için depo deposu değişikliklerini işlemek üzere kodu uygulamanız gerekir.

Not: ItemMetadata içindeki objectType alanı, şemadaki nesne tanımlama adıyla eşleşmelidir. Bu şekilde Cloud Search, dizin isteğinde nesnenin beklenen yapısını tanımlar. Dizine ekleme isteğinde, mevcut şemaya 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ı türden farklı türde bir özellik gönderirseniz Cloud Search, dizine ekleme sırasında bir hata yanıtı döndürür.

Not: İstemcinizin yaptığı her HTTP bağlantısı genel sonuçlar oluşturur. Ek yükü azaltmak için birden fazla API çağrısını tek bir HTTP isteğinde gruplayabilirsiniz. HTTP bağlantılarınızın ek yükünü nasıl azaltacağınızı öğrenmek için Gruplandırma 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'ne bakın.

Depo değişikliklerini işleme

Tam dizine ekleme yapmak için bir depodan her öğeyi düzenli olarak toplayabilir ve dizine ekleyebilirsiniz. Dizininizin güncel olmasını sağlamada etkili olsa da daha büyük veya hiyerarşik veri havuzlarıyla çalışırken tam dizine ekleme maliyetli olabilir.

Bir deponun tamamını sık sık dizine eklemek için dizin çağrıları kullanmak yerine, değişiklikleri izleyen ve yalnızca değişen öğeleri dizine ekleyen bir mekanizma olarak Google Cloud Dizine Ekleme Sırası'nı da kullanabilirsiniz. Daha sonra yoklama ve güncelleme için öğeleri sıraya almak üzere items.push isteklerini kullanabilirsiniz. Google Cloud Dizine Ekleme Sırası hakkında daha fazla bilgi edinmek 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'ye bakın.