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

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

  • İçerik Bağlayıcı SDK'sı. Java ile programlama yapıyorsanız bu iyi bir seçenektir. İçerik Bağlayıcı SDK, REST API'nin sarmalayıcısıdır ve bağlayıcıları hızlı bir şekilde oluşturmanıza olanak tanır. SDK'yı kullanarak içerik bağlayıcı oluşturmak için İçerik Bağlayıcı SDK'sını kullanarak içerik bağlayıcı oluşturma başlıklı makaleyi inceleyin.

  • Düşük düzeyli bir REST API veya API kitaplıkları. Java ile programlama yapmıyorsanız veya kod tabanınız bir REST API'yi ya da kitaplığı daha iyi destekliyorsa bu seçenekleri kullanın. REST API'yi kullanarak içerik bağlayıcı oluşturmak için REST API'yi kullanarak içerik bağlayıcı oluşturma başlıklı makaleyi inceleyin.

Tipik bir içerik bağlayıcı aşağıdaki görevleri yerine getirir:

  1. Yapılandırma parametrelerini okur ve işler.
  2. Üçüncü taraf içerik deposundan "öğe" adı verilen, dizine eklenebilir verilerin ayrı parçalarını çeker.
  3. Erişim kontrol listelerini, meta verileri ve içerik verilerini dizine eklenebilir öğeler halinde birleştirir.
  4. Öğeleri Cloud Search veri kaynağında dizine ekler.
  5. (isteğe bağlı) Üçüncü taraf içerik deposundan gelen değişiklik bildirimlerini dinler. Değişiklik bildirimleri, Cloud Search veri kaynağının üçüncü taraf veri havuzuyla senkronize kalması 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.

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

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

Bağımlılıkları ayarlama

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

Maven

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

Gradle

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

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

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

Google Cloud Search SDK, tüm bağlayıcılar tarafından kullanılan, Google tarafından sağlanan çeşitli yapılandırma parametreleri içerir. Yapılandırma dosyanızda Google tarafından sağlanan aşağıdaki parametreleri bildirmeniz gerekir:

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

Google tarafından sağlanan diğer parametrelerin varsayılan değerlerini geçersiz kılmak istemiyorsanız bunları yapılandırma dosyanızda belirtmeniz gerekmez. Google tarafından sağlanan yapılandırma parametreleri (ör. belirli kimliklerin ve anahtarların nasıl oluşturulacağı) hakkında daha fazla bilgi için Google tarafından sağlanan yapılandırma parametreleri başlıklı makaleyi inceleyin.

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

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

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 mülkü 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 belirleme

İçerik bağlayıcının temel işlevi, bir depoyu geçerek verilerini dizine eklemektir. Veri havuzunuzdaki verilerin boyutuna ve düzenine göre bir geçiş stratejisi uygulamanız gerekir. Kendi stratejinizi tasarlayabilir veya SDK'da uygulanan aşağıdaki stratejilerden birini seçebilirsiniz:

Tam geçiş stratejisi

Tam geçiş stratejisi, tüm depoyu tarar ve her öğeyi körü körüne indeksler. Bu strateji, küçük bir deponuz olduğunda ve her indeksleme işleminde tam geçiş yapmanın ek yükünü karşılayabildiğinizde yaygın olarak kullanılır.

Bu geçiş stratejisi, çoğunlukla statik ve hiyerarşik olmayan verilerin bulunduğu küçük depolar için uygundur. Bu geçiş stratejisini, değişiklik algılama işleminin zor olduğu veya depoda desteklenmediği durumlarda da kullanabilirsiniz.

Liste geçiş stratejisi

Liste geçişi stratejisi, tüm alt düğümler de dahil olmak üzere tüm depoyu tarayarak her öğenin durumunu belirler. Ardından bağlayıcı ikinci bir geçiş yapar ve yalnızca son indekslemeden bu yana yeni olan veya güncellenen öğeleri indeksler. Bu strateji, mevcut bir dizinde artımlı güncellemeler yapmak için yaygın olarak kullanılır (dizini her güncellediğinizde tam geçiş yapmak zorunda kalmak yerine).

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

Grafik geçişi (Graph traversal)

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

Bu strateji, taranması gereken hiyerarşik verileriniz (ör. bir dizi dizin veya web sayfası) 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ştirilmesini büyük ö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 gidin:

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

Dokümanların bu bölümünde, FullTraversalSample örneğindeki kod snippet'lerine atıfta bulunulmaktadır.

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

Bir bağlayıcının giriş noktası, main() yöntemidir. Bu yöntemin temel 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.

Aramadan önce application.start(), IndexingApplication.Builder sınıfını kullanarak FullTraversalConnector şablonunu oluşturun. FullTraversalConnector, yöntemlerini uyguladığınız bir Repository nesnesini kabul eder. Aşağıdaki kod snippet'inde main() yönteminin nasıl uygulanacağı gösterilmektedir:

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

  1. Configuation.isInitialized() yöntemini çağırarak Configuration öğesinin başlatılmadığından emin olur.
  2. Google tarafından sağlanan 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 sağlamaktır. Şablon kullanırken içerik bağlayıcı oluşturmak için Repository arayüzündeki belirli yöntemleri geçersiz kılmanız yeterlidir. Geçersiz kılacağınız yöntemler, kullandığınız şablona ve geçiş stratejisine bağlıdır. FullTraversalConnector için aşağıdaki yöntemleri geçersiz kılın:

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

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

  • (İsteğ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 yapılandırmanızda tanımlandığı şekilde planlanan her artımlı geçiş için bir kez çağrılır.

  • (İsteğe bağlı) close() yöntemi. Depo temizliği yapmanız gerekiyorsa close() yöntemini geçersiz kılın. Bu yöntem, bağlayıcı kapatılırken bir kez çağrılır.

Repository nesnesinin her yöntemi bir tür ApiOperation nesnesi döndürür. Bir ApiOperation nesnesi, deponuzun gerçek indekslemesini gerçekleştirmek için tek 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ınızın yapılandırmasını işleme sürecinde, Configuration nesnesinden tüm özel parametreleri 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ürlerini almak için çeşitli yöntemlere sahiptir. 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, FullTraversalSample kaynağından alınmıştır ve Configuration nesnesinden tek bir özel tamsayı 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();
}

Birden fazla değer içeren bir parametreyi almak ve ayrıştırmak için verileri ayrı parçalar halinde ayrıştırmak üzere Configuration sınıfının tür ayrıştırıcılarından birini kullanın. Eğitim bağlayıcısından alınan aşağıdaki snippet, GitHub depo 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ştirme

Tam geçiş yapmak ve deponuzu dizine eklemek için getAllDocs() geçersiz kılın. getAllDocs() yöntemi, kontrol noktası kabul eder. Kontrol noktası, işlem kesintiye uğrarsa dizine eklemeyi belirli bir öğeden devam ettirmek için kullanılır. Deponuzdaki her öğe için getAllDocs()method bölümünde şu adımları uygulayın:

  1. İzinleri ayarlayın.
  2. Dizin oluşturduğunuz öğenin meta verilerini ayarlayın.
  3. Meta verileri ve öğeyi tek bir dizine eklenebilir RepositoryDoc içinde birleştirin.
  4. Dizinlenebilir her öğeyi getAllDocs() yöntemi tarafından döndürülen bir yineleyiciye paketleyin. getAllDocs()'nın aslında ApiOperation nesnelerinin bir yinelemesi olan 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 daha fazla öğenin dizine eklenmeye hazır 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ı belirlemek için Erişim Kontrol Listesi (EKL) kullanıyor. EKL, öğeye erişebilen grupların veya kullanıcıların kimliklerinin listesidir.

Yalnızca bir öğeye erişimi olan kullanıcıların arama sonucunda bu öğeyi görebilmesi için, deponuz tarafından kullanılan EKL'yi kopyalamanız gerekir. Google Cloud Search'ün öğeye doğru düzeyde erişim sağlamak için ihtiyaç duyduğu bilgilere sahip olması amacıyla, bir öğe dizine eklenirken öğenin erişim kontrol listesi de eklenmelidir.

İçerik Bağlayıcı SDK, çoğu depodaki EKL'leri modellemek için zengin bir EKL sınıfları ve yöntemleri grubu sağlar. Deponuzdaki her öğenin erişim kontrol listesini analiz etmeniz ve bir öğeyi dizine eklediğinizde Google Cloud Search için karşılık gelen bir erişim kontrol listesi oluşturmanız gerekir. Deponuzun erişim kontrol listesi, erişim kontrol listesi devralma gibi kavramlar kullanıyorsa bu erişim kontrol listesini modellemek zor olabilir. Google Cloud Search erişim kontrol listeleri hakkında daha fazla bilgi için Google Cloud Search erişim kontrol listeleri başlıklı makaleyi inceleyin.

Not: Cloud Search Dizine Ekleme API'si, tek alanlı ACL'leri destekler. Alanlar arası ACL'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 "asıl kullanıcıların" (getCustomerPrincipal()) tüm öğelerin (.setReaders()) "okuyucusu" 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();

Depo için EKL'leri doğru şekilde modellemek istiyorsanız EKL'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 devralma özelliğinin modellenmesi için Google Cloud Search EKL'leri başlıklı makalede ele alınan ek bilgiler gerekir.

Öğe için meta verileri ayarlama

Meta veriler Item nesnesinde depolanır. Item oluşturmak için öğenin benzersiz bir dize kimliği, öğe türü, ACL, URL ve sürümüne ihtiyacınız vardır. Aşağıdaki kod snippet'inde, IndexingItemBuilder yardımcı sınıfı kullanılarak nasıl Item 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();

Dizinlenebilir öğeyi oluşturma

Öğenin meta verilerini ayarladıktan sonra, RepositoryDoc.Builder sınıfını kullanarak gerçek indekslenebilir öğeyi oluşturabilirsiniz. Aşağıdaki örnekte, tek bir dizine eklenebilir öğ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 ekleme ile yayınlama arasındaki gecikmenin daha uzun olmasına neden olur ve dizine ekleme istekleri için büyük bir işleme hızı kotası sağlar. Asenkron mod, tüm depoyu ilk kez dizine eklemek (dolgu) için önerilir.
SYNCHRONOUS
Eşzamanlı mod, dizine ekleme ile reklam sunma arasındaki gecikmeyi kısaltır ve sınırlı işleme hızı kotasını karşılar. Senkron mod, güncellemelerin ve depodaki değişikliklerin dizine eklenmesi için önerilir. Belirtilmezse istek modu varsayılan olarak SYNCHRONOUS olur.

Dizinlenebilir her öğeyi bir yineleyicide paketleyin.

getAllDocs() yöntemi, Iterator döndürür. Bu, RepositoryDoc nesnelerinin CheckpointCloseableIterable'idir. Yineleyici oluşturmak ve döndürmek için CheckpointClosableIterableImpl.Builder sınıfını kullanabilirsiniz. Aşağıdaki kod snippet'inde, yineleyicinin nasıl oluşturulacağı ve döndürüleceği gösterilmektedir.

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

SDK, yineleyicinin içine alınmış her indeksleme çağrısını yürütür.

Sonraki Adımlar

İzleyebileceğiniz bazı adımlar:

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

Cloud Search dizine ekleme sırası, depodaki her öğenin kimliklerini ve isteğe bağlı karma değerlerini tutmak için kullanılır. Liste geçişi bağlayıcısı, öğe kimliklerini Google Cloud Search dizine ekleme sırasına gönderir ve dizine ekleme için bunları tek tek alır. Google Cloud Search, kuyrukları korur ve öğe durumunu belirlemek için kuyruk içeriklerini karşılaştırır. Örneğin, bir öğenin depodan silinip silinmediğini belirler. Cloud Search dizine ekleme sırası hakkında daha fazla bilgi için Cloud Search dizine ekleme sırası başlıklı makaleyi inceleyin.

Dokümanların bu bölümünde, ListTraversalSample örneğindeki kod snippet'lerine atıfta bulunulmaktadır.

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

Bir bağlayıcının giriş noktası, main() yöntemidir. Bu yöntemin temel 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.

Aramadan önce application.start(), IndexingApplication.Builder sınıfını kullanarak ListingConnector şablonunu oluşturun. ListingConnector, yöntemlerini uyguladığınız bir Repository nesnesini kabul eder. Aşağıdaki snippet'te ListingConnector ve ilişkili Repository öğesinin nasıl oluşturulacağı 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, bağlayıcınızın main() yöntemi Application.build yöntemini çağırdıktan sonra SDK, initConfig() yöntemini çağırır. initConfig() yöntemi:

  1. Configuation.isInitialized() yöntemini çağırarak Configuration öğesinin başlatılmadığından emin olur.
  2. Google tarafından sağlanan 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 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ılacağınız yöntemler, kullandığınız şablona ve geçiş stratejisine bağlıdır. ListingConnector için aşağıdaki yöntemleri geçersiz kılın:

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

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

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

  • (İsteğ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 yapılandırmanızda tanımlandığı şekilde planlanan her artımlı geçiş için bir kez çağrılır.

  • (İsteğe bağlı) close() yöntemi. Depo temizliği yapmanız gerekiyorsa close() yöntemini geçersiz kılın. Bu yöntem, bağlayıcı kapatılırken bir kez çağrılır.

Repository nesnesinin her yöntemi bir tür ApiOperation nesnesi döndürür. Bir ApiOperation nesnesi, deponuzun gerçek indekslemesini gerçekleştirmek için tek 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ınızın yapılandırmasını işleme sürecinde, Configuration nesnesinden tüm özel parametreleri 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ürlerini almak için çeşitli yöntemlere sahiptir. 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, FullTraversalSample kaynağından alınmıştır ve Configuration nesnesinden tek bir özel tamsayı 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();
}

Birden fazla değer içeren bir parametreyi almak ve ayrıştırmak için verileri ayrı parçalar halinde ayrıştırmak üzere Configuration sınıfının tür ayrıştırıcılarından birini kullanın. Eğitim bağlayıcısından alınan aşağıdaki snippet, GitHub depo 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 geçersiz kılma getIds() yöntemi. getIds() yöntemi, kontrol noktası kabul eder. İşlem kesintiye uğrarsa belirli bir öğede dizine ekleme işlemine devam etmek için kontrol noktası 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.

Öğe kimliklerini ve karma değerlerini gönderme

Öğe kimliklerini ve bunlarla ilişkili içerik karması değerlerini depodan getirmek için geçersiz kılın. getIds() Kimlik ve karma değeri çiftleri daha sonra Cloud Search dizine ekleme sırasına gönderilecek push işlemi isteği olarak paketlenir. Öğelerin tüm hiyerarşisi işlenene kadar genellikle önce kök veya üst kimlikler, ardından alt kimlikler gönderilir.

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

  • Her öğe kimliğini ve ilişkili karma değerini depodan alın.
  • Her kimlik ve karma değeri çiftini bir PushItems içine paketleyin.
  • Her PushItems öğesini, getIds() yöntemi tarafından döndürülen bir yineleyiciye birleştirin. getIds()'nın aslında ApiOperation nesnelerinin bir yinelemesi olan CheckpointCloseableIterable döndürdüğünü unutmayın. Her nesne, öğeleri sıraya gönderme gibi RepositoryDoc üzerinde gerçekleştirilen bir API isteğini temsil eder.

Aşağıdaki kod snippet'inde, her öğe kimliğinin ve karma değerinin nasıl alınacağı ve bunların nasıl PushItems içine ekleneceği gösterilmektedir. PushItems, bir öğeyi Cloud Search dizine ekleme sırasına gönderme 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'inde, kimlikleri ve karma değerlerini tek bir push işleminde paketlemek için PushItems.Builder sınıfının nasıl kullanılacağı gösterilmektedir ApiOperation.

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 öğeyi alma ve işleme

Cloud Search Indexing Kuyruğu'ndaki her öğeyi işlemek için getDoc() geçersiz kılın. Bir öğe yeni, değiştirilmiş, değişmemiş olabilir veya kaynak deposunda artık mevcut olmayabilir. Yeni veya değiştirilmiş her öğeyi alıp dizine ekleyin. Kaynak depoda artık bulunmayan öğeleri dizinden kaldırın.

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

  1. Öğenin Cloud Search dizine ekleme sırasındaki kimliğinin depoda olup olmadığını kontrol edin. Aksi takdirde öğeyi dizinden silin.

  2. Öğe durumu için dizini yoklayın ve bir öğe değişmemişse (ACCEPTED) herhangi bir işlem yapmayın.

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

    1. İzinleri ayarlayın.
    2. Dizin oluşturduğunuz öğenin meta verilerini ayarlayın.
    3. Meta verileri ve öğeyi tek bir dizine eklenebilir RepositoryDoc içinde birleştirin.
    4. RepositoryDoc ürününü iade edin.

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

Silinen öğeleri işleme

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

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, depoyu temsil eden bir veri yapısıdır. documentID, documents içinde bulunmuyorsa öğeyi dizinden silmek için APIOperations.deleteItem(resourceName) değerini döndürün.

Değiştirilmeyen öğeleri işleme

Aşağıdaki kod snippet'inde, Cloud Search dizine ekleme kuyruğundaki öğe durumunun nasıl sorgulanacağı ve değişmeyen bir öğenin nasıl işleneceği gösterilmektedir.

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 öğenin durumunu ve değişikliği 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
/**
 * 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ı belirlemek için Erişim Kontrol Listesi (EKL) kullanıyor. EKL, öğeye erişebilen grupların veya kullanıcıların kimliklerinin listesidir.

Yalnızca bir öğeye erişimi olan kullanıcıların arama sonucunda bu öğeyi görebilmesi için, deponuz tarafından kullanılan EKL'yi kopyalamanız gerekir. Google Cloud Search'ün öğeye doğru düzeyde erişim sağlamak için ihtiyaç duyduğu bilgilere sahip olması amacıyla, bir öğe dizine eklenirken öğenin erişim kontrol listesi de eklenmelidir.

İçerik Bağlayıcı SDK, çoğu depodaki EKL'leri modellemek için zengin bir EKL sınıfları ve yöntemleri grubu sağlar. Deponuzdaki her öğenin erişim kontrol listesini analiz etmeniz ve bir öğeyi dizine eklediğinizde Google Cloud Search için karşılık gelen bir erişim kontrol listesi oluşturmanız gerekir. Deponuzun erişim kontrol listesi, erişim kontrol listesi devralma gibi kavramlar kullanıyorsa bu erişim kontrol listesini modellemek zor olabilir. Google Cloud Search erişim kontrol listeleri hakkında daha fazla bilgi için Google Cloud Search erişim kontrol listeleri başlıklı makaleyi inceleyin.

Not: Cloud Search Dizine Ekleme API'si, tek alanlı ACL'leri destekler. Alanlar arası ACL'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 "asıl kullanıcıların" (getCustomerPrincipal()) tüm öğelerin (.setReaders()) "okuyucusu" 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();

Depo için EKL'leri doğru şekilde modellemek istiyorsanız EKL'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 devralma özelliğinin modellenmesi için Google Cloud Search EKL'leri başlıklı makalede ele alınan ek bilgiler gerekir.

Öğe için meta verileri ayarlama

Meta veriler Item nesnesinde depolanır. Item oluşturmak için öğenin benzersiz bir dize kimliği, öğe türü, ACL, URL ve sürümüne ihtiyacınız vardır. Aşağıdaki kod snippet'inde, IndexingItemBuilder yardımcı sınıfı kullanılarak nasıl Item 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();

Dizinlenebilir öğe oluşturma

Öğenin meta verilerini ayarladıktan sonra RepositoryDoc.Builder kullanarak gerçek dizine eklenebilir öğeyi oluşturabilirsiniz. Aşağıdaki örnekte, tek bir dizine eklenebilir öğ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 ekleme ile yayınlama arasındaki gecikmenin daha uzun olmasına neden olur ve dizine ekleme istekleri için büyük bir işleme hızı kotası sağlar. Asenkron mod, tüm depoyu ilk kez dizine eklemek (dolgu) için önerilir.
SYNCHRONOUS
Eşzamanlı mod, dizine ekleme ile reklam sunma arasındaki gecikmeyi kısaltır ve sınırlı işleme hızı kotasını karşılar. Senkron mod, güncellemelerin ve depodaki değişikliklerin dizine eklenmesi için önerilir. Belirtilmezse istek modu varsayılan olarak SYNCHRONOUS olur.

Sonraki Adımlar

İzleyebileceğiniz bazı adımlar:

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

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

Cloud Search dizine ekleme sırası, veri deposundaki her öğe için kimlikleri ve isteğe bağlı karma değerlerini tutmak için kullanılır. Grafik geçişi bağlayıcısı, öğe kimliklerini Google Cloud Search dizine ekleme sırasına gönderir ve dizine ekleme için bunları tek tek alır. Google Cloud Search, kuyrukları korur ve öğe durumunu belirlemek için kuyruk içeriklerini karşılaştırır. Örneğin, bir öğenin depodan silinip silinmediğini belirlemek için bu karşılaştırmayı yapar. Cloud Search dizine ekleme sırası hakkında daha fazla bilgi için Google Cloud Search dizine ekleme sırası başlıklı makaleyi inceleyin.

Dizin oluşturma sırasında, öğe içeriği veri deposundan alınır ve tüm alt öğe kimlikleri sıraya gönderilir. Bağlayıcı, tüm öğeler işlenene kadar üst ve alt öğe kimliklerini yinelemeli olarak işler.

Dokümanların bu bölümünde, GraphTraversalSample örneğindeki kod snippet'lerine atıfta bulunulmaktadır.

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

Bir bağlayıcının giriş noktası, main() yöntemidir. Bu yöntemin temel 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.

Aramadan önce application.start(), ListingConnector şablonunu oluşturmak 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 öğesinin nasıl oluşturulacağı 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, bağlayıcınızın main() yöntemi Application.build yöntemini çağırdıktan sonra SDK, initConfig() yöntemini çağırır. initConfig() yöntemi:

  1. Configuation.isInitialized() yöntemini çağırarak Configuration öğesinin başlatılmadığından emin olur.
  2. Google tarafından sağlanan 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ı oluşturmak için yalnızca Repository arayüzündeki belirli yöntemleri geçersiz kılmanız gerekir. Geçersiz kılacağınız yöntemler, kullandığınız şablona ve geçiş stratejisine bağlıdır. ListingConnector için aşağıdaki yöntemleri geçersiz kılarsınız:

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

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

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

  • (İsteğ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 yapılandırmanızda tanımlandığı şekilde planlanan her artımlı geçiş için bir kez çağrılır.

  • (İsteğe bağlı) close() yöntemi. Depo temizliği yapmanız gerekiyorsa close() yöntemini geçersiz kılın. Bu yöntem, bağlayıcı kapatılırken bir kez çağrılır.

Repository nesnesinin her yöntemi bir tür ApiOperation nesnesi döndürür. Bir ApiOperation nesne, deponuzun gerçek indekslemesini gerçekleştirmek için tek veya birden fazla IndexingService.indexItem() çağrısı şeklinde bir işlem gerçekleştirir.

Özel yapılandırma parametrelerini alma

Bağlayıcınızın yapılandırmasını işleme sürecinde, Configuration nesnesinden tüm özel parametreleri 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ürlerini almak için çeşitli yöntemlere sahiptir. 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, FullTraversalSample kaynağından alınmıştır ve Configuration nesnesinden tek bir özel tamsayı 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();
}

Birden fazla değer içeren bir parametreyi almak ve ayrıştırmak için verileri ayrı parçalar halinde ayrıştırmak üzere Configuration sınıfının tür ayrıştırıcılarından birini kullanın. Eğitim bağlayıcısından alınan aşağıdaki snippet, GitHub depo 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ştirme

Depodaki tüm kayıtların kimliklerini ve karma değerlerini almak için geçersiz kılma getIds() yöntemi. getIds() yöntemi, kontrol noktası kabul eder. İşlem kesintiye uğrarsa belirli bir öğede dizine ekleme işlemine devam etmek için kontrol noktası 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.

Öğe kimliklerini ve karma değerlerini gönderme

Öğe kimliklerini ve bunlarla ilişkili içerik karması değerlerini depodan getirmek için geçersiz kılın. getIds() Kimlik ve karma değeri çiftleri daha sonra Cloud Search dizine ekleme sırasına gönderilecek push işlemi isteği olarak paketlenir. Öğelerin tüm hiyerarşisi işlenene kadar genellikle önce kök veya üst kimlikler, ardından alt kimlikler gönderilir.

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

  • Her öğe kimliğini ve ilişkili karma değerini depodan alın.
  • Her kimlik ve karma değeri çiftini bir PushItems içine paketleyin.
  • Her bir PushItems öğesini getIds() yöntemi tarafından döndürülen bir yineleyiciye birleştirin. getIds()'nın aslında ApiOperation nesnelerinin bir yinelemesi olan CheckpointCloseableIterable döndürdüğünü unutmayın. Her nesne, öğeleri sıraya gönderme gibi RepositoryDoc üzerinde gerçekleştirilen bir API isteğini temsil eder.

Aşağıdaki kod snippet'inde, her öğe kimliğinin ve karma değerinin nasıl alınacağı ve bunların nasıl PushItems içine ekleneceği gösterilmektedir. PushItems, bir öğeyi Cloud Search dizine ekleme sırasına gönderme ApiOperation isteğidir.

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

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

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 öğeyi alma ve işleme

Cloud Search Indexing Kuyruğu'ndaki her öğeyi işlemek için getDoc() geçersiz kılın. Bir öğe yeni, değiştirilmiş, değişmemiş olabilir veya kaynak deposunda artık mevcut olmayabilir. Yeni veya değiştirilmiş her öğeyi alıp dizine ekleyin. Kaynak depoda artık bulunmayan öğeleri dizinden kaldırın.

getDoc() yöntemi, Cloud Search dizine ekleme kuyruğundan bir öğe kabul eder. Kuyruktaki her öğe için getDoc() yönteminde şu adımları uygulayın:

  1. Öğenin kimliğinin, Cloud Search dizine ekleme kuyruğunda, depoda olup olmadığını kontrol edin. Aksi takdirde öğeyi dizinden silin. Öğe varsa sonraki adıma geçin.

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

    1. İzinleri ayarlayın.
    2. Dizin oluşturduğunuz öğenin meta verilerini ayarlayın.
    3. Meta verileri ve öğeyi tek bir dizine eklenebilir RepositoryDoc içinde birleştirin.
    4. Daha fazla işlem için alt kimlikleri Cloud Search dizine ekleme sırasına yerleştirin.
    5. RepositoryDoc ürününü iade edin.

Silinen öğeleri işleme

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

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ı belirlemek için Erişim Kontrol Listesi (EKL) kullanıyor. EKL, öğeye erişebilen grupların veya kullanıcıların kimliklerinin listesidir.

Yalnızca bir öğeye erişimi olan kullanıcıların arama sonucunda bu öğeyi görebilmesi için, deponuz tarafından kullanılan EKL'yi kopyalamanız gerekir. Google Cloud Search'ün öğeye doğru düzeyde erişim sağlamak için ihtiyaç duyduğu bilgilere sahip olması amacıyla, bir öğe dizine eklenirken öğenin erişim kontrol listesi de eklenmelidir.

İçerik Bağlayıcı SDK, çoğu depodaki EKL'leri modellemek için zengin bir EKL sınıfları ve yöntemleri grubu sağlar. Deponuzdaki her öğenin erişim kontrol listesini analiz etmeniz ve bir öğeyi dizine eklediğinizde Google Cloud Search için karşılık gelen bir erişim kontrol listesi oluşturmanız gerekir. Deponuzun erişim kontrol listesi, erişim kontrol listesi devralma gibi kavramlar kullanıyorsa bu erişim kontrol listesini modellemek zor olabilir. Google Cloud Search erişim kontrol listeleri hakkında daha fazla bilgi için Google Cloud Search erişim kontrol listeleri başlıklı makaleyi inceleyin.

Not: Cloud Search Dizine Ekleme API'si, tek alanlı ACL'leri destekler. Alanlar arası ACL'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 "asıl kullanıcıların" (getCustomerPrincipal()) tüm öğelerin (.setReaders()) "okuyucusu" 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();

Depo için EKL'leri doğru şekilde modellemek istiyorsanız EKL'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 devralma özelliğinin modellenmesi için Google Cloud Search EKL'leri başlıklı makalede ele alınan ek bilgiler gerekir.

Öğe için meta verileri ayarlama

Meta veriler Item nesnesinde depolanır. Item oluşturmak için öğenin benzersiz bir dize kimliği, öğe türü, ACL, URL ve sürümüne ihtiyacınız vardır. Aşağıdaki kod snippet'inde, IndexingItemBuilder yardımcı sınıfı kullanılarak nasıl Item 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();

Dizinlenebilir öğeyi oluşturma

Öğenin meta verilerini ayarladıktan sonra RepositoryDoc.Builder kullanarak gerçek dizine eklenebilir öğeyi oluşturabilirsiniz. Aşağıdaki örnekte, tek bir dizine eklenebilir öğ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 ekleme ile yayınlama arasındaki gecikmenin daha uzun olmasına neden olur ve dizine ekleme istekleri için büyük bir işleme hızı kotası sağlar. Asenkron mod, tüm depoyu ilk kez dizine eklemek (dolgu) için önerilir.
SYNCHRONOUS
Eşzamanlı mod, dizine ekleme ile reklam sunma arasındaki gecikmeyi kısaltır ve sınırlı işleme hızı kotasını karşılar. Senkron mod, güncellemelerin ve depodaki değişikliklerin dizine eklenmesi için önerilir. Belirtilmezse istek modu varsayılan olarak SYNCHRONOUS olur.

Alt öğe kimliklerini Cloud Search dizine ekleme sırasına yerleştirme

Aşağıdaki kod snippet'inde, şu anda işlenmekte olan üst öğe için alt öğe kimliklerinin işleme sırasına nasıl ekleneceği gösterilmektedir. 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

İzleyebileceğiniz bazı adımlar:

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

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

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

Geçiş stratejinizi belirleme

İçerik bağlayıcının temel işlevi, bir depoyu geçerek verilerini dizine eklemektir. Veri havuzunuzdaki verilerin boyutuna ve düzenine göre bir geçiş stratejisi uygulamanız gerekir. Aşağıda üç yaygın geçiş stratejisi verilmiştir:

Tam geçiş stratejisi

Tam geçiş stratejisi, tüm depoyu tarar ve her öğeyi körü körüne indeksler. Bu strateji, küçük bir deponuz olduğunda ve her indeksleme işleminde tam geçiş yapmanın ek yükünü karşılayabildiğinizde yaygın olarak kullanılır.

Bu geçiş stratejisi, çoğunlukla statik ve hiyerarşik olmayan verilerin bulunduğu küçük depolar için uygundur. Bu geçiş stratejisini, değişiklik algılama işleminin zor olduğu veya depoda desteklenmediği durumlarda da kullanabilirsiniz.

Liste geçiş stratejisi

Liste geçişi stratejisi, tüm alt düğümler de dahil olmak üzere tüm depoyu tarayarak her öğenin durumunu belirler. Ardından bağlayıcı ikinci bir geçiş yapar ve yalnızca son indekslemeden bu yana yeni olan veya güncellenen öğeleri indeksler. Bu strateji, mevcut bir dizinde artımlı güncellemeler yapmak için yaygın olarak kullanılır (dizini her güncellediğinizde tam geçiş yapmak zorunda kalmak yerine).

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

Grafik geçişi (Graph traversal)

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

Bu strateji, taranması gereken hiyerarşik verileriniz (ör. bir dizi dizin veya web sayfası) varsa uygundur.

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

Cloud Search'te 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 şu şekilde doldurabilirsiniz:

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

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

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

    {
  "name": "datasource/<data_source_id>/items/titanic",
  "acl": {
    "readers": [
      {
        "gsuitePrincipal": {
          "gsuiteDomain": true
        }
      }
    ]
  },
  "metadata": {
    "title": "Titanic",
    "viewUrl": "http://www.imdb.com/title/tt2234155/?ref_=nv_sr_1",
    "objectType": "movie"
  },
  "structuredData": {
    "object": {
      "properties": [
        {
          "name": "movieTitle",
          "textValues": {
            "values": [
              "Titanic"
            ]
          }
        },
        {
          "name": "releaseDate",
          "dateValues": {
            "values": [
              {
                "year": 1997,
                "month": 12,
                "day": 19
              }
            ]
          }
        },
        {
          "name": "actorName",
          "textValues": {
            "values": [
              "Leonardo DiCaprio",
              "Kate Winslet",
              "Billy Zane"
            ]
          }
        },
        {
          "name": "genre",
          "enumValues": {
            "values": [
              "Drama",
              "Action"
            ]
          }
        },
        {
          "name": "userRating",
          "integerValues": {
            "values": [
              8
            ]
          }
        },
        {
          "name": "mpaaRating",
          "textValues": {
            "values": [
              "PG-13"
            ]
          }
        },
        {
          "name": "duration",
          "textValues": {
            "values": [
              "3 h 14 min"
            ]
          }
        }
      ]
    }
  },
  "content": {
    "inlineContent": "A seventeen-year-old aristocrat falls in love with a kind but poor artist aboard the luxurious, ill-fated R.M.S. Titanic.",
    "contentFormat": "TEXT"
  },
  "version": "01",
  "itemType": "CONTENT_ITEM"
}

  4. (İsteğe bağlı) items.get çağrılarını kullanarak bir öğenin dizine eklendiğini doğrulayın.

Tam geçiş gerçekleştirmek için tüm depoyu düzenli olarak yeniden dizine eklersiniz. Liste veya grafik geçişi gerçekleştirmek için depo değişikliklerini işleyecek kodu uygulamanız gerekir.

Depo değişikliklerini işleme

Tam dizine ekleme işlemi gerçekleştirmek için bir depodaki her öğeyi düzenli olarak toplayıp dizine ekleyebilirsiniz. Tam indeksleme, indeksinizin güncel olmasını sağlamada etkili olsa da daha büyük veya hiyerarşik depolarda maliyetli olabilir.

Belirli aralıklarla tüm depoyu dizine eklemek için dizin oluşturma çağrılarını kullanmak yerine, değişiklikleri izleme ve yalnızca değişen öğeleri dizine ekleme mekanizması olarak Google Cloud Indexing Queue'yu da kullanabilirsiniz. Öğeleri daha sonra yoklama ve güncelleme için sıraya göndermek üzere items.push isteklerini kullanabilirsiniz. Google Cloud dizine ekleme sırası hakkında daha fazla bilgi için Google Cloud dizine ekleme sırası başlıklı makaleyi inceleyin.

Google Cloud Search API hakkında daha fazla bilgi için Cloud Search API başlıklı makaleyi inceleyin.