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

İçerik bağlayıcısı, bir kuruluşun deposundaki verileri çekip 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'sı, REST API'yi çevreleyen bir sarmalayıcıdır ve hızlıca bağlayıcı oluşturmanıza olanak tanır. SDK'yı kullanarak bir içerik bağlayıcı oluşturmak için Content Connector SDK'sını kullanarak içerik bağlayıcı oluşturma konusuna bakın.

  • Alt düzey bir REST API veya API kitaplıkları. Java'da programlama yapmıyorsanız veya kod tabanınız bir REST API'yi veya bir kitaplığı daha uygunsa bu seçenekleri kullanın. REST API kullanarak içerik bağlayıcısı 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 yerine getirir:

  1. Yapılandırma parametrelerini okur ve işler.
  2. Üçüncü taraf içerik deposundan, "items" adı verilen ve dizine eklenebilir verilerin ayrı parçalarını toplar.
  3. ACL'leri, meta verileri ve içerik verilerini dizine eklenebilir öğelerde birleştirir.
  4. Öğeleri Cloud Search veri kaynağına dizine ekler.
  5. (isteğe bağlı) Üçüncü taraf içerik deposundan gelen bildirimleri değiştirmeyi dinler. Değişiklik bildirimleri, Cloud Search veri kaynağının üçüncü taraf veri havuzuyla senkronize olmasını sağlamak için 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ısı oluşturma

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

Bağımlılıkları belirleme

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şturma

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

  • İçerik bağlayıcıları için deponuzun konumunu ve depoya erişmek için gereken özel anahtarı tanımlayan api.sourceId ve api.serviceAccountPrivateKeyFile parametrelerini bildirmeniz gerekir.
  • Bu parametre harici kimlik kaynağınızın konumunu tanımladığından, kimlik bağlayıcısı için api.identitySourceId değerini bildirmeniz gerekir. Kullanıcıları senkronize ediyorsanız kuruluşunuzun Google Workspace hesabının benzersiz kimliği olarak api.customerId öğesini de beyan etmeniz gerekir.

Google tarafından sağlanan diğer parametrelerin varsayılan değerlerini geçersiz kılmak istemediğiniz sürece bunları yapılandırma dosyanızda belirtmeniz gerekmez. Google'ın sağladığı yapılandırma parametreleri hakkında, belirli kimliklerin ve anahtarların nasıl oluşturulacağı gibi ek bilgiler için Google'ın sağladığı yapılandırma parametreleri bölümüne bakın.

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

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

Yapılandırma dosyasını bağlayıcınıza aktarmak 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 bir yapılandırma dosyasına erişmeye çalışır.

Geçiş stratejinizi belirleyin

İçerik bağlayıcısının birincil işlevi, bir depoyu ç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 stratejiler arasından seçim yapabilirsiniz:

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 işleminizde tam bir geçiş yapmanın ek yükünü karşılayabilir.

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

Liste geçiş stratejisi

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

Bu geçiş stratejisi, değişiklik algılamanın zor olduğu veya depo tarafından desteklenmediği durumlarda, hiyerarşik olmayan verileriniz olduğunda ve çok büyük veri kümeleriyle çalışıyorsanız 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 yeni veya son dizine ekleme işleminden bu yana güncellenmiş öğeleri dizine ekler. Son olarak, bağlayıcı tüm alt kimlikleri iletir ve 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 tür geçiş, genellikle tüm kimliklerin listelenmesinin pratik olmadığı hiyerarşik depolar için kullanılır.

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

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 ö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 geçin:

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

Belgelerin bu bölümü, FullTraversalSample örneğindeki kod snippet'lerini ifade eder.

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 bu yöntemin start() yöntemini çağırmaktır.

application.start() çağrısından ö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
/**
 * 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 initConfig() yöntemini Application.build çağırır. initConfig() yöntemi aşağıdaki görevleri gerçekleştirir:

  1. Configuration'in 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 anahtar/değer çifti, Configuration nesnesi içindeki bir ConfigValue nesnesinde depolanır.

Repository arayüzünü uygulama

Repository nesnesinin tek amacı, depo öğelerinin geçişini ve dizine eklenmesini gerçekleştirmektir. Şablon kullanırken içerik bağlayıcısı oluşturmak için yalnızca Repository arayüzünde 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 deposu 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 çekip dizine eklemek için getAllDocs() yöntemini geçersiz kılın. Bu yöntem, her bir planlanmış geçiş için bir kez (yapılandırmanız tarafından tanımlandığı şekilde) çağrılır.

  • (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 planlanmış her artımlı geçiş (yapılandırmanız tarafından tanımlandığı gibi) 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. 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 nesne türü döndürür. ApiOperation nesnesi, deponuzu gerçek dizine eklemeyi gerçekleştirmek için tek bir veya belki de birden fazla IndexingService.indexItem() çağrısı şeklinde bir işlem gerçekleştirir.

Özel yapılandırma parametrelerini alma

Bağlayıcı yapılandırmanızı işlemenin bir parçası olarak Configuration nesnesinden tüm özel parametreleri almanız gerekir. Bu görev genellikle Repository sınıfının init() yönteminde 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 öğesinden aşağıdaki snippet, bir Configuration nesnesinden tek bir özel tam sayı değerinin nasıl alınacağını gösterir:

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

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

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

Tam geçiş gerçekleştir

Tam geçiş yapmak ve deponuzu dizine eklemek için getAllDocs() değerini geçersiz kılın. getAllDocs() yöntemi bir kontrol noktası kabul eder. Kontrol noktası, işlemin kesintiye uğraması durumunda belirli bir öğede dizine eklemeyi devam ettirmek için 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 RepositoryDoc klasöründe birleştirin.
  4. Dizine eklenebilir her öğeyi, getAllDocs() yöntemi tarafından döndürülen bir iteratöre paketleyin. getAllDocs() işlevinin aslında ApiOperation nesnelerinin iterasyonunu içeren bir CheckpointCloseableIterable döndürdüğünü unutmayın. Her nesne,RepositoryDoc üzerinde gerçekleştirilen bir API isteğini (ör. dizine ekleme) temsil eder.

Öğe grubu tek bir çağrıda işlenemeyecek kadar büyükse bir kontrol noktası ekleyin ve dizine eklenmeye daha fazla öğenin olduğunu belirtmek 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 (EKL) kullanır. EKL, öğeye erişebilen grup veya kullanıcıların kimlik listesidir.

Bir arama sonucundaki öğeyi yalnızca öğeye erişimi olan kullanıcıların görebileceğinden emin olmak için deponuz tarafından kullanılan EKL'yi kopyalamanız gerekir. Google Cloud Search'ün öğeye doğru erişim düzeyini sağlamak için ihtiyaç duyduğu bilgilere sahip olması amacıyla, bir öğe dizine eklenirken öğenin EKL'si eklenmelidir.

Content Connector SDK'sı, çoğu deponun EKL'lerini modellemek için zengin bir EKL sınıfı ve yöntemleri kümesi sağlar. Deponuzdaki her öğe için EKL'yi analiz etmeniz ve bir öğeyi dizine eklediğinizde 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 modelleme yöntemi zor 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()) "okuyucuları" olmasına olanak tanır.

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

Depoda EKL'leri doğru şekilde modellemek için ACL'leri anlamanız gerekir. Örneğin, alt klasörlerin izinleri üst klasörlerden devraldığı bir tür devralma modeli kullanan bir dosya sistemindeki dosyaları dizine ekliyor olabilirsiniz. EKL devralmayı 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 bir dize kimliği, öğe türü, EKL, URL ve sürümü olması gerekir. Aşağıdaki kod snippet'inde, IndexingItemBuilder yardımcı sınıfını kullanarak Item özelliğinin nasıl oluşturulacağı gösterilmektedir.

FullTraversalSample.java
// Url is required. Use google.com as a placeholder for this sample.
String viewUrl = "https://www.google.com";

// Version is required, set to current timestamp.
byte[] version = Longs.toByteArray(System.currentTimeMillis());

// Using the SDK item builder class to create the document with appropriate attributes
// (this can be expanded to include metadata fields etc.)
Item item = IndexingItemBuilder.fromConfiguration(Integer.toString(id))
    .setItemType(IndexingItemBuilder.ItemType.CONTENT_ITEM)
    .setAcl(acl)
    .setSourceRepositoryUrl(IndexingItemBuilder.FieldOrValue.withValue(viewUrl))
    .setVersion(version)
    .build();

Dizine eklenebilir öğeyi oluşturma

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

FullTraversalSample.java
// For this sample, content is just plain text
String content = String.format("Hello world from sample doc %d", id);
ByteArrayContent byteContent = ByteArrayContent.fromString("text/plain", content);

// Create the fully formed document
RepositoryDoc doc = new RepositoryDoc.Builder()
    .setItem(item)
    .setContent(byteContent, IndexingService.ContentFormat.TEXT)
    .build();

RepositoryDoc, 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 eklemeden sunma gecikmesine neden olur ve dizine ekleme istekleri için yüksek işleme hızı kotasını kapsar. Tüm deponun ilk dizine ekleme (dolgu) işlemi için eşzamansız mod önerilir.
SYNCHRONOUS
Eşzamanlı mod, dizine ekleme ve sunma arasındaki gecikme süresini kısaltır ve sınırlı işleme hızı kotasını kapsar. Güncellemelerin ve depodaki değişikliklerin dizine eklenmesi için eşzamanlı mod önerilir. Belirtilmemişse varsayılan istek modu SYNCHRONOUS olur.

Dizine eklenebilir her öğeyi bir iteratörde paketleyin

getAllDocs() yöntemi, Iterator (özellikle de bir CheckpointCloseableIterable) RepositoryDoc nesnesi döndürür. Bir iteratör 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östermektedir.

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

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

Sonraki adımlar

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

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

Cloud Search Dizine Ekleme Sırası, depodaki her bir öğe için kimlikleri ve isteğe bağlı karma değerlerini tutmak amacıyla 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 ekleme için bunları birer birer alır. Google Cloud Search, sıraları tutar ve öğelerin depodan silinip silinmediği gibi öğe durumunu belirlemek için 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ı bölümüne bakın.

Belgelerin bu bölümü, ListTraversalSample örneğindeki kod snippet'lerini ifade eder.

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 bu yöntemin start() yöntemini çağırmaktır.

application.start() çağrısından ö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'te, ListingConnector ve ilişkili Repository işleminin nasıl başlatılacağı gösterilmektedir:

ListTraversalSample.java
/**
 * This sample connector uses the Cloud Search SDK template class for a
 * list traversal connector.
 *
 * @param args program command line arguments
 * @throws InterruptedException thrown if an abort is issued during initialization
 */
public static void main(String[] args) throws InterruptedException {
  Repository repository = new SampleRepository();
  IndexingConnector connector = new ListingConnector(repository);
  IndexingApplication application = new IndexingApplication.Builder(connector, args).build();
  application.start();
}

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

  1. Configuration'in 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 anahtar/değer çifti, Configuration nesnesi içindeki bir ConfigValue nesnesinde depolanır.

Repository arayüzünü uygulama

Repository nesnesinin tek amacı, depo öğelerinin geçişini ve dizine eklenmesini 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ı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 deposu 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 öğe 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 planlanmış her artımlı geçiş (yapılandırmanız tarafından tanımlandığı gibi) 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. 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 nesne döndürür. ApiOperation nesnesi, deponuzu gerçek dizine eklemeyi gerçekleştirmek için tek bir veya belki de birden fazla IndexingService.indexItem() çağrısı şeklinde bir işlem gerçekleştirir.

Özel yapılandırma parametrelerini alma

Bağlayıcı yapılandırmanızı işlemenin bir parçası olarak Configuration nesnesinden tüm özel parametreleri almanız gerekir. Bu görev genellikle Repository sınıfının init() yönteminde 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 öğesinden aşağıdaki snippet, bir Configuration nesnesinden tek bir özel tam sayı değerinin nasıl alınacağını gösterir:

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

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

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

Liste 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. Kontrol noktası, işlemin kesintiye uğraması durumunda belirli bir öğede dizine eklemeye devam etmek 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.

Öğe kimliklerini ve karma değerlerini aktarın

Depodan öğe kimliklerini ve ilişkili içerik karması değerlerini 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. Kök veya üst kimlikler genellikle tüm öğe hiyerarşisi işleninceye kadar önce ardından alt kimlikler aktarılır.

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

  • Depodan her öğe kimliğini ve ilişkili karma değerini alın.
  • Her kimlik ve karma değeri çiftini bir PushItems olarak paketleyin.
  • Her PushItems işlemini, getIds() yöntemi tarafından döndürülen bir iteratörde birleştirin. getIds() işlevinin ApiOperation nesnelerinin yinelemesi olan bir CheckpointCloseableIterable döndürdüğünü unutmayın. Her nesne, öğeleri sıraya aktarma gibi RepositoryDoc aşamasında gerçekleştirilen bir API isteğini temsil eder.

Aşağıdaki kod snippet'inde her bir öğe kimliğinin ve karma değerinin nasıl alınacağı ve PushItems içine nasıl ekleneceği gösterilmektedir. PushItems, bir öğeyi Cloud Search Dizine Ekleme Sırasına aktarmak için gönderilen bir ApiOperation isteğidir.

ListTraversalSample.java
PushItems.Builder allIds = new PushItems.Builder();
for (Map.Entry<Integer, Long> entry : this.documents.entrySet()) {
  String documentId = Integer.toString(entry.getKey());
  String hash = this.calculateMetadataHash(entry.getKey());
  PushItem item = new PushItem().setMetadataHash(hash);
  log.info("Pushing " + documentId);
  allIds.addPushItem(documentId, item);
}

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ı ApiOperationgöstermektedir.

ListTraversalSample.java
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 gönderilir.

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ş, değiştirilmemiş veya artık kaynak depoda yer almayabilir. 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önteminde şu adımları uygulayın:

  1. Cloud Search Dizine Ekleme Sırasındaki öğe kimliğinin depoda olup olmadığını kontrol edin. Değilse öğeyi dizinden silin.

  2. Dizinde öğe durumu için anket yapın ve bir öğe değişmemişse (ACCEPTED) hiçbir şey yapmayın.

  3. Dizin değişti 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 RepositoryDoc klasöründe birleştirin.
    4. RepositoryDoc öğesini iade edin.

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

Silinen öğeleri işleme

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

ListTraversalSample.java
String resourceName = item.getName();
int documentId = Integer.parseInt(resourceName);

if (!documents.containsKey(documentId)) {
  // Document no longer exists -- delete it
  log.info(() -> String.format("Deleting document %s", item.getName()));
  return ApiOperations.deleteItem(resourceName);
}

documents öğesinin, depoyu temsil eden bir veri yapısı olduğunu unutmayın. documents içinde documentID bulunamazsa öğeyi dizinden silmek için APIOperations.deleteItem(resourceName) değerini 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
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 değişikliğe işaret edebilecek diğer meta verilerin yanı sıra öğenin durumunu kontrol edin. Bu örnekte, öğenin değiştirilip değiştirilmediğini belirlemek için meta veri karması kullanılmıştır.

ListTraversalSample.java
/**
 * Checks to see if an item is already up to date
 *
 * @param previousItem Polled item
 * @param currentHash  Metadata hash of the current github object
 * @return PushItem operation
 */
private boolean canSkipIndexing(Item previousItem, String currentHash) {
  if (previousItem.getStatus() == null || previousItem.getMetadata() == null) {
    return false;
  }
  String status = previousItem.getStatus().getCode();
  String previousHash = previousItem.getMetadata().getHash();
  return "ACCEPTED".equals(status)
      && previousHash != null
      && previousHash.equals(currentHash);
}

Bir öğenin izinlerini ayarlama

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

Bir arama sonucundaki öğeyi yalnızca öğeye erişimi olan kullanıcıların görebileceğinden emin olmak için deponuz tarafından kullanılan EKL'yi kopyalamanız gerekir. Google Cloud Search'ün öğeye doğru erişim düzeyini sağlamak için ihtiyaç duyduğu bilgilere sahip olması amacıyla, bir öğe dizine eklenirken öğenin EKL'si eklenmelidir.

Content Connector SDK'sı, çoğu deponun EKL'lerini modellemek için zengin bir EKL sınıfı ve yöntemleri kümesi sağlar. Deponuzdaki her öğe için EKL'yi analiz etmeniz ve bir öğeyi dizine eklediğinizde 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 modelleme yöntemi zor 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()) "okuyucuları" olmasına olanak tanır.

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

Depoda EKL'leri doğru şekilde modellemek için ACL'leri anlamanız gerekir. Örneğin, alt klasörlerin izinleri üst klasörlerden devraldığı bir tür devralma modeli kullanan bir dosya sistemindeki dosyaları dizine ekliyor olabilirsiniz. EKL devralmayı 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 bir dize kimliği, öğe türü, EKL, URL ve sürümü olması gerekir. Aşağıdaki kod snippet'inde, IndexingItemBuilder yardımcı sınıfını kullanarak Item özelliğinin nasıl oluşturulacağı gösterilmektedir.

ListTraversalSample.java
// Url is required. Use google.com as a placeholder for this sample.
String viewUrl = "https://www.google.com";

// Version is required, set to current timestamp.
byte[] version = Longs.toByteArray(System.currentTimeMillis());

// Set metadata hash so queue can detect changes
String metadataHash = this.calculateMetadataHash(documentId);

// Using the SDK item builder class to create the document with
// appropriate attributes. This can be expanded to include metadata
// fields etc.
Item item = IndexingItemBuilder.fromConfiguration(Integer.toString(documentId))
    .setItemType(IndexingItemBuilder.ItemType.CONTENT_ITEM)
    .setAcl(acl)
    .setSourceRepositoryUrl(IndexingItemBuilder.FieldOrValue.withValue(viewUrl))
    .setVersion(version)
    .setHash(metadataHash)
    .build();

Dizine eklenebilir öğe oluşturma

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

ListTraversalSample.java
// For this sample, content is just plain text
String content = String.format("Hello world from sample doc %d", documentId);
ByteArrayContent byteContent = ByteArrayContent.fromString("text/plain", content);

// Create the fully formed document
RepositoryDoc doc = new RepositoryDoc.Builder()
    .setItem(item)
    .setContent(byteContent, IndexingService.ContentFormat.TEXT)
    .build();

RepositoryDoc, 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 eklemeden sunma gecikmesine neden olur ve dizine ekleme istekleri için yüksek işleme hızı kotasını kapsar. Tüm deponun ilk dizine ekleme (dolgu) işlemi için eşzamansız mod önerilir.
SYNCHRONOUS
Eşzamanlı mod, dizine ekleme ve sunma arasındaki gecikme süresini kısaltır ve sınırlı işleme hızı kotasını kapsar. Güncellemelerin ve depodaki değişikliklerin dizine eklenmesi için eşzamanlı mod önerilir. Belirtilmemişse varsayılan istek modu SYNCHRONOUS olur.

Sonraki adımlar

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

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

Cloud Search Dizine Ekleme Sırası, depodaki her bir öğe için kimlikleri ve isteğe bağlı karma değerlerini tutmak amacıyla kullanılır. Bir grafik geçiş bağlayıcısı, öğe kimliklerini Google Cloud Search Dizine Ekleme Sırasına aktarır ve dizine eklemek için bunları birer birer alır. Google Cloud Search, sıraları tutar ve sıra içeriklerini karşılaştırarak öğe durumunu (örneğin, bir öğenin depodan silinip silinmediğini) belirler. 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.

Dizine ekleme sırasında, öğe içeriği veri deposundan alınır 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 olarak işlemeye devam eder.

Belgelerin bu bölümü, GraphTraversalSample örneğindeki kod snippet'lerini ifade eder.

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 bu yöntemin start() yöntemini çağırmaktır.

application.start() çağrısından ö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'te, ListingConnector ve ilişkili Repository işleminin nasıl başlatılacağı gösterilmektedir:

GraphTraversalSample.java
/**
 * This sample connector uses the Cloud Search SDK template class for a graph
 * traversal connector.
 *
 * @param args program command line arguments
 * @throws InterruptedException thrown if an abort is issued during initialization
 */
public static void main(String[] args) throws InterruptedException {
  Repository repository = new SampleRepository();
  IndexingConnector connector = new ListingConnector(repository);
  IndexingApplication application = new IndexingApplication.Builder(connector, args).build();
  application.start();
}

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

  1. Configuration'in 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 anahtar/değer çifti, Configuration nesnesi içindeki bir ConfigValue nesnesinde depolanır.

Repository arayüzünü uygulama

Repository nesnesinin tek amacı, depo öğelerinin geçişini ve dizine eklenmesini 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ı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ılarsınız:

  • init() yöntemi. Veri deposu 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 öğe 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 planlanmış her artımlı geçiş (yapılandırmanız tarafından tanımlandığı gibi) 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. 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, deponuzu gerçek dizine ekleme işlemini gerçekleştirmek için tek bir veya belki birden fazla IndexingService.indexItem() çağrısı şeklinde bir işlem gerçekleştirir.

Özel yapılandırma parametrelerini alma

Bağlayıcı yapılandırmanızı işlemenin bir parçası olarak Configuration nesnesinden tüm özel parametreleri almanız gerekir. Bu görev genellikle Repository sınıfının init() yönteminde 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 öğesinden aşağıdaki snippet, bir Configuration nesnesinden tek bir özel tam sayı değerinin nasıl alınacağını gösterir:

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

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

GithubRepository.java
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ı kabul eder. Kontrol noktası, işlemin kesintiye uğraması durumunda belirli bir öğede dizine eklemeye devam etmek 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.

Öğe kimliklerini ve karma değerlerini aktarın

Depodan öğe kimliklerini ve ilişkili içerik karması değerlerini 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. Kök veya üst kimlikler genellikle tüm öğe hiyerarşisi işleninceye kadar önce ardından alt kimlikler aktarılır.

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

  • Depodan her öğe kimliğini ve ilişkili karma değerini alın.
  • Her kimlik ve karma değeri çiftini bir PushItems olarak paketleyin.
  • Her PushItems öğesini, getIds() yöntemi tarafından döndürülen bir iteratörde birleştirin. getIds() işlevinin ApiOperation nesnelerinin yinelemesi olan bir CheckpointCloseableIterable döndürdüğünü unutmayın. Her nesne, öğeleri sıraya aktarma gibi RepositoryDoc aşamasında gerçekleştirilen bir API isteğini temsil eder.

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österir. PushItems, bir öğeyi Cloud Search Dizine Ekleme Sırasına aktarmak için ApiOperation isteğidir.

GraphTraversalSample.java
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 aktarımda (ApiOperation) paketlemek için PushItems.Builder sınıfının nasıl kullanılacağını göstermektedir.

GraphTraversalSample.java
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 gönderilir.

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ş, değiştirilmemiş veya artık kaynak depoda yer almayabilir. 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ındaki bir öğeyi kabul eder. Sıradaki her öğe için getDoc() yönteminde şu adımları uygulayın:

  1. Cloud Search Dizine Ekleme Sırasındaki öğe kimliğinin depoda olup olmadığını kontrol edin. Değilse öğeyi dizinden silin. Öğe mevcutsa sonraki adıma geçin.

  2. Dizin değişti 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 RepositoryDoc klasöründe birleştirin.
    4. Alt kimlikleri daha fazla işlenmek üzere Cloud Search Dizine Ekleme Sırasına yerleştirin.
    5. RepositoryDoc öğesini iade edin.

Silinen öğeleri işleme

Aşağıdaki kod snippet'i, bir öğenin dizinde var olup olmadığının nasıl silinip silinmeyeceğini nasıl belirleyeceğinizi göstermektedir.

GraphTraversalSample.java
String resourceName = item.getName();
if (documentExists(resourceName)) {
  return buildDocumentAndChildren(resourceName);
}
// Document doesn't exist, delete it
log.info(() -> String.format("Deleting document %s", resourceName));
return ApiOperations.deleteItem(resourceName);

Bir öğenin izinlerini ayarlama

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

Bir arama sonucundaki öğeyi yalnızca öğeye erişimi olan kullanıcıların görebileceğinden emin olmak için deponuz tarafından kullanılan EKL'yi kopyalamanız gerekir. Google Cloud Search'ün öğeye doğru erişim düzeyini sağlamak için ihtiyaç duyduğu bilgilere sahip olması amacıyla, bir öğe dizine eklenirken öğenin EKL'si eklenmelidir.

Content Connector SDK'sı, çoğu deponun EKL'lerini modellemek için zengin bir EKL sınıfı ve yöntemleri kümesi sağlar. Deponuzdaki her öğe için EKL'yi analiz etmeniz ve bir öğeyi dizine eklediğinizde 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 modelleme yöntemi zor 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()) "okuyucuları" olmasına olanak tanır.

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

Depoda EKL'leri doğru şekilde modellemek için ACL'leri anlamanız gerekir. Örneğin, alt klasörlerin izinleri üst klasörlerden devraldığı bir tür devralma modeli kullanan bir dosya sistemindeki dosyaları dizine ekliyor olabilirsiniz. EKL devralmayı 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 bir dize kimliği, öğe türü, EKL, URL ve sürümü olması gerekir. Aşağıdaki kod snippet'inde, IndexingItemBuilder yardımcı sınıfını kullanarak Item özelliğinin nasıl oluşturulacağı gösterilmektedir.

GraphTraversalSample.java
// Url is required. Use google.com as a placeholder for this sample.
String viewUrl = "https://www.google.com";

// Version is required, set to current timestamp.
byte[] version = Longs.toByteArray(System.currentTimeMillis());

// Using the SDK item builder class to create the document with
// appropriate attributes. This can be expanded to include metadata
// fields etc.
Item item = IndexingItemBuilder.fromConfiguration(documentId)
    .setItemType(IndexingItemBuilder.ItemType.CONTENT_ITEM)
    .setAcl(acl)
    .setSourceRepositoryUrl(IndexingItemBuilder.FieldOrValue.withValue(viewUrl))
    .setVersion(version)
    .build();

Dizine eklenebilir öğeyi oluşturma

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

GraphTraversalSample.java
// For this sample, content is just plain text
String content = String.format("Hello world from sample doc %s", documentId);
ByteArrayContent byteContent = ByteArrayContent.fromString("text/plain", content);

RepositoryDoc.Builder docBuilder = new RepositoryDoc.Builder()
    .setItem(item)
    .setContent(byteContent, IndexingService.ContentFormat.TEXT);

RepositoryDoc, 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 eklemeden sunma gecikmesine neden olur ve dizine ekleme istekleri için yüksek işleme hızı kotasını kapsar. Tüm deponun ilk dizine ekleme (dolgu) işlemi için eşzamansız mod önerilir.
SYNCHRONOUS
Eşzamanlı mod, dizine ekleme ve sunma arasındaki gecikme süresini kısaltır ve sınırlı işleme hızı kotasını kapsar. Güncellemelerin ve depodaki değişikliklerin dizine eklenmesi için eşzamanlı mod önerilir. Belirtilmemişse varsayılan istek modu SYNCHRONOUS olur.

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

Sonraki adımlar

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

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

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

Geçiş stratejinizi belirleyin

İçerik bağlayıcısının birincil işlevi, bir depoyu ç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 işleminizde tam bir geçiş yapmanın ek yükünü karşılayabilir.

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

Liste geçiş stratejisi

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

Bu geçiş stratejisi, değişiklik algılamanın zor olduğu veya depo tarafından desteklenmediği durumlarda, hiyerarşik olmayan verileriniz olduğunda ve çok büyük veri kümeleriyle çalışıyorsanız 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 yeni veya son dizine ekleme işleminden bu yana güncellenmiş öğeleri dizine ekler. Son olarak, bağlayıcı tüm alt kimlikleri iletir ve 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 tür geçiş, genellikle tüm kimliklerin listelenmesinin pratik olmadığı hiyerarşik depolar için kullanılır.

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

Geçiş stratejinizi uygulayın ve öğeleri dizine ekleyin

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 veritabanı kaydı olabilir.

Şemanız kaydedildikten sonra dizini şu şekilde doldurabilirsiniz:

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

  2. (İsteğe bağlı) Dizine eklenecek medya dosyalarını yüklemek için media.upload kullanılması.

  3. Öğeyi dizine eklemek için items.index kullanılıyor. Örneğin, şemanız film şemasındaki nesne tanımını kullanıyorsa tek bir öğe için dizine ekleme isteği şöyle 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ın kullanılması.

Tam geçiş yapmak için deponun tamamını düzenli aralıklarla yeniden dizine eklersiniz. Liste veya grafik geçişi gerçekleştirmek için depo değişikliklerini işlemek için kod uygulamanız gerekir.

Depo değişikliklerini işleme

Tam dizine ekleme yapmak için depodaki her öğeyi düzenli aralıklarla toplayıp dizine ekleyebilirsiniz. Dizininizin güncel olmasını sağlama konusunda etkili olsa da, daha büyük veya hiyerarşik depolarla çalışırken tam dizin oluşturma maliyetli olabilir.

Kod deposunun tamamını dizine eklemek için sık sık dizin çağrılarını kullanmak yerine, değişiklikleri izlemek ve yalnızca değişen öğeleri dizine eklemek için bir mekanizma olarak Google Cloud Dizine Ekleme Sırası'nı da kullanabilirsiniz. Öğeleri daha sonra yoklamak ve güncellemek üzere 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ı bölümüne bakın.

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