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

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

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

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

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

  1. Yapılandırma parametrelerini okur ve işler.
  2. Üçüncü taraf içerik deposundan "öğeler" olarak adlandırılan ayrı dizine eklenebilir veri parçalarını alır.
  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 değişiklik bildirimlerini dinler. Cloud Search veri kaynağının üçüncü taraf veri havuzuyla senkronize kalması için değişiklik bildirimleri dizine ekleme isteklerine dönüştürülür. Bağlantı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ının nasıl oluşturulacağı açıklanmaktadır.

Bağımlılıkları ayarlama

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

Maven

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

Gradle

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

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

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

Google Cloud Search SDK'sı, tüm bağlayıcılar tarafından kullanılan ve 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 belirtmeniz gerekir:

  • İçerik bağlayıcı için api.sourceId ve api.serviceAccountPrivateKeyFile parametrelerini belirtmeniz gerekir. Bu parametreler, deponuzun konumunu ve depoya erişmek için gereken özel anahtarı tanımlar.
  • Kimlik bağlayıcısı için api.identitySourceId parametresini belirtmeniz gerekir. Bu parametre, harici kimlik kaynağınızın konumunu tanımlar. Kullanıcıları senkronize ediyorsanız kuruluşunuzun Google Workspace hesabı için benzersiz kimlik olarak api.customerId değerini de belirtmeniz 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 hakkında ek bilgi (ör. belirli kimliklerin ve anahtarların nasıl oluşturulacağı) için Google tarafından sağlanan yapılandırma parametreleri başlıklı makaleyi inceleyin.

Ayrıca, yapılandırma dosyanızda kullanmak üzere kendi depoya özgü parametrelerinizi de tanımlayabilirsiniz.

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

Yapılandırma dosyasını bağlayıcınıza iletmek için config sistem özelliğini ayarlayın. Bağlantı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 belirleyin

İçerik bağlayıcının birincil işlevi, bir depoda gezinmek ve verilerini dizine eklemektir. Deponuzdan veri boyutuna ve düzenine göre bir tarama stratejisi uygulamanız gerekir. Kendi stratejinizi tasarlayabilir veya SDK'da uygulanan aşağıdaki stratejilerden birini seçebilirsiniz:

Tam tarama stratejisi

Tam tarama stratejisi, deponun tamamını tarar ve her öğeyi kör bir şekilde dizine ekler. Bu strateji, küçük bir deponuz olduğunda ve dizine her eklediğinizde tam bir tarama yapmanın masrafını karşılayabildiğinizde genellikle kullanılır.

Bu tarama stratejisi, çoğunlukla statik, hiyerarşik olmayan veriler içeren küçük depolar için uygundur. Değişiklik algılama zor olduğunda veya depo tarafından desteklenmediğinde de bu tarama stratejisini kullanabilirsiniz.

Liste tarama stratejisi

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

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

Grafiğin taranması

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

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

Bu tarama 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 tarama konnektörü oluşturma

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

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

Bir 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 sınıfın start() yöntemini çağırmaktır.

application.start() işlevini çağırmadan önce, FullTraversalConnector şablonunu örneklemek 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'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();
}

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

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

Repository arayüzünü uygulama

Repository nesnesinin tek amacı, kod deposu öğelerinin taranmasını ve dizine eklenmesini gerçekleştirmektir. Şablon kullanırken içerik bağlayıcı oluşturmak için Repositoryarabiriminde yalnızca belirli yöntemleri geçersiz kılmanız gerekir. Geçersiz kıldığınız yöntemler, kullandığınız şablona ve geçiş stratejisine bağlıdır. FullTraversalConnector için aşağıdaki yöntemleri geçersiz kılın:

  • init() yöntemi. Veri deposu kurulumu ve ilklendirmesi yapmak için init() yöntemini geçersiz kılın.

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

  • (isteğe bağlı) getChanges() yöntemi. Deponuzdan değişiklik algılama özelliğini destekliyorsa getChanges() yöntemini geçersiz kılın. Bu yöntem, değiştirilen öğeleri almak ve dizine eklemek için her planlanmış artımlı tarama (yapılandırmanız tarafından tanımlandığı şekilde) için bir kez çağrılır.

  • (isteğe bağlı) close() yöntemi. Depoyu temizlemeniz 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. ApiOperation nesnesi, deponuzun gerçek dizine ekleme işlemini 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ğlantıcınızın yapılandırmasını işleme kapsamında, tüm özel parametreleri Configuration nesnesinden almanız gerekir. Bu görev genellikle bir Repository sınıfının init() yönteminde gerçekleştirilir.

Configuration sınıfında, bir yapılandırmadan farklı veri türleri elde etmek için çeşitli yöntemler bulunur. 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. FullTraversalSample kaynağından alınan aşağıdaki snippet'te, Configuration nesnesinden tek bir özel tamsayı değerinin nasıl alınacağı gösterilmektedir:

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çalara ayırmak üzere Configuration sınıfının tür ayrıştırıcılarından birini kullanın. Eğitim amaçlı bağlayıcıdan alınan aşağıdaki snippet'te, GitHub depo adlarının listesini almak için getMultiValue yöntemi kullanılır:

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

Tam bir geçiş gerçekleştirme

Tam bir tarama gerçekleştirmek ve deponuzu dizine eklemek için getAllDocs() değerini geçersiz kılın. getAllDocs() yöntemi bir kontrol noktasını kabul eder. Kontrol noktası, süreç kesintiye uğradığında dizine ekleme işlemini belirli bir öğede devam ettirmek için kullanılır. Deponuzdan her bir öğe için getAllDocs() yönteminde aşağıdaki adımları uygulayın:

  1. İzinleri ayarlayın.
  2. Dizine eklediğiniz öğenin meta verilerini ayarlayın.
  3. Meta verileri ve öğeyi dizine eklenebilir tek bir RepositoryDoc öğesinde birleştirin.
  4. Dizine eklenebilir her öğeyi getAllDocs()yöntemi tarafından döndürülen bir iteratöre paketleyin. getAllDocs()'ün aslında ApiOperation nesnelerinin iterasyonu olan bir CheckpointCloseableIterable döndürdüğünü unutmayın. Her nesne, bir RepositoryDoc üzerinde yapılan 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 eklenebilecek daha fazla öğe 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. ACL, öğeye erişebilen grupların veya kullanıcıların kimliklerinin listesidir.

Yalnızca bir öğeye erişimi olan kullanıcıların, söz konusu öğeyi arama sonucunda görebilmesi için deponuzun kullandığı ACL'yi kopyalamanız gerekir. Bir öğe dizine eklenirken öğenin ACL'si eklenmelidir. Böylece Google Cloud Search, öğeye doğru erişim düzeyini sağlamak için ihtiyaç duyduğu bilgilere sahip olur.

Content Connector SDK'sı, çoğu deponun ACL'lerini modellemek için zengin bir ACL sınıfı ve yöntem grubu sağlar. Bir öğeyi dizine eklediğinizde, veri havuzunuzdaki her öğenin ACL'sini analiz etmeniz ve Google Cloud Search için ilgili bir ACL oluşturmanız gerekir. Deponuzun ACL'sinde ACL devralma gibi kavramlar kullanılıyorsa bu ACL'yi modellemek zor olabilir. Google Cloud Search ACL'leri hakkında daha fazla bilgi için Google Cloud Search ACL'leri başlıklı makaleyi inceleyin.

Not: Cloud Search Dizine Ekleme API'si tek alan adında ACL'leri destekler. Alanlar arası ACL'leri desteklemez. Her bir öğeye erişimi EKL kullanarak ayarlamak için Acl.Builder sınıfını kullanın. Tam tarama örneğinden alınan aşağıdaki kod snippet'i, tüm kullanıcıların veya "yöneticilerin" (getCustomerPrincipal()), arama yaparken 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 ACL'leri doğru şekilde modellemek üzere ACL'leri anlamanız gerekir. Örneğin, alt klasörlerin üst klasörlerden izinleri devraldığı bir tür devralma modeli kullanan bir dosya sistemindeki dosyaları dizine ekleyebilirsiniz. EKL devralımının modellenmesi için Google Cloud Search EKL'leri bölümünde açıklanan ek bilgiler gerekir.

Bir öğenin meta verilerini ayarlama

Meta veriler Item nesnesinde depolanır. Item oluşturmak için en azından benzersiz bir dize kimliği, öğe türü, ACL, URL ve öğe sürümü gerekir. Aşağıdaki kod snippet'inde, IndexingItemBuilder yardımcı sınıfı kullanılarak Item oluşturma işlemi 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şturun

Öğenin meta verilerini ayarladıktan sonra RepositoryDoc.Builder sınıfını kullanarak gerçek dizine eklenebilir öğ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 ekleme ile yayınlama arasında daha uzun gecikme süresine neden olur ve dizine ekleme istekleri için büyük bir işleme hızı kotasına sahiptir. Deponun tamamının ilk dizine eklenmesi (dolgu) için ayarsız mod önerilir.
SYNCHRONOUS
Senkron mod, dizine ekleme ile yayınlama arasında daha kısa gecikme süresine neden olur ve sınırlı işleme hızı kotasını karşılar. Depodaki güncellemelerin ve değişikliklerin dizine eklenmesi için senkron modu önerilir. Belirtilmemişse istek modu varsayılan olarak SYNCHRONOUS olur.

Dizine eklenebilir her öğeyi bir iteratörde paketleyin

getAllDocs() yöntemi, RepositoryDoc nesnelerinden oluşan bir Iterator (özellikle CheckpointCloseableIterable) 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'inde, bir iteratör oluşturma ve döndürme işlemi gösterilmektedir.

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

SDK, her dizine ekleme çağrısını iteratör içine yerleştirilmiş şekilde yürütür.

Sonraki Adımlar

Aşağıda, uygulayabileceğiniz birkaç adım verilmiştir:

Şablon sınıfı kullanarak liste tarama konnektörü oluşturma

Cloud Search dizine ekleme sırası, depodaki her öğenin kimliklerini ve isteğe bağlı karma oluşturma değerlerini tutmak için kullanılır. Liste tarama 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, bir öğenin veri havuzundan silinip silinmediğini belirlemek gibi öğe durumlarını belirlemek için sıraları korur ve sıra içeriklerini karşılaştırır. Cloud Search dizine ekleme sırası hakkında daha fazla bilgi 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'leri ele alınmaktadır.

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

Bir 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 sınıfın start() yöntemini çağırmaktır.

application.start() işlevini çağırmadan önce, ListingConnector şablonunu örneklemek için IndexingApplication.Builder sınıfını kullanın. ListingConnector, yöntemlerini uyguladığınız bir Repository nesnesi 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();
}

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

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

Repository arayüzünü uygulama

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

  • init() yöntemi. Veri deposu kurulumu ve ilklendirmesi 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. Deponuzdan değişiklik algılama özelliğini destekliyorsa getChanges() yöntemini geçersiz kılın. Bu yöntem, değiştirilen öğeleri almak ve dizine eklemek için her planlanmış artımlı tarama (yapılandırmanız tarafından tanımlandığı şekilde) için bir kez çağrılır.

  • (isteğe bağlı) close() yöntemi. Depoyu temizlemeniz 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. ApiOperation nesnesi, deponuzun gerçek dizine ekleme işlemini 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ğlantıcınızın yapılandırmasını işleme kapsamında, tüm özel parametreleri Configuration nesnesinden almanız gerekir. Bu görev genellikle bir Repository sınıfının init() yönteminde gerçekleştirilir.

Configuration sınıfında, bir yapılandırmadan farklı veri türleri elde etmek için çeşitli yöntemler bulunur. 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. FullTraversalSample kaynağından alınan aşağıdaki snippet'te, Configuration nesnesinden tek bir özel tamsayı değerinin nasıl alınacağı gösterilmektedir:

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çalara ayırmak üzere Configuration sınıfının tür ayrıştırıcılarından birini kullanın. Eğitim amaçlı bağlayıcıdan alınan aşağıdaki snippet'te, GitHub depo adlarının listesini almak için getMultiValue yöntemi kullanılır:

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

Listeyi inceleme işlemini gerçekleştirin

Depodaki tüm kayıtların kimliklerini ve karma değerlerini almak için getIds() yöntemini geçersiz kılın. getIds() yöntemi bir kontrol noktasını kabul eder. Kontrol noktası, işlem kesintiye uğradığında dizine ekleme işlemini belirli bir öğede devam ettirmek için kullanılır.

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

Öğe kimliklerini ve karma oluşturma değerlerini gönderme

Öğe kimliklerini ve ilişkili içerik karma değerlerini depodan almak için getIds() parametresini geçersiz kılın. Kimlik ve karma değer çiftleri daha sonra Cloud Search dizine ekleme sırasına gönderme işlemi isteği olarak paketlenir. Kök veya üst kimlikler genellikle önce itilir, ardından öğe hiyerarşisinin tamamı işlenene kadar alt kimlikler itilir.

getIds() yöntemi, dizine eklenecek son öğeyi temsil eden bir kontrol noktasını kabul eder. Kontrol noktası, süreç kesintiye uğrarsa dizine ekleme işlemini belirli bir öğede devam ettirmek için kullanılabilir. Deponuzdan her öğe için getIds() yönteminde aşağıdaki adımları uygulayın:

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

Aşağıdaki kod snippet'inde, her öğe kimliğinin ve karma oluşturma değerinin nasıl alınacağı ve bir PushItems içine nasıl 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 oluşturma değerlerini tek bir pushApiOperation içine paketlemek için PushItems.Builder sınıfının nasıl kullanılacağı gösterilmektedir.

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

Öğeler, daha fazla işleme alınmak üzere Cloud Search dizine ekleme sırasına gönderilir.

Her öğeyi alma ve işleme

Cloud Search dizine ekleme kuyruğundaki her öğeyi işlemek için getDoc() değerini geçersiz kılın. Bir öğe yeni, değiştirilmiş, değiştirilmemiş veya kaynak depoda artık mevcut olmayabilir. Yeni veya değiştirilmiş her öğeyi alıp dizine ekleyin. Artık kaynak depoda bulunmayan öğeleri dizinden kaldırın.

getDoc() yöntemi, Google Cloud Search dizine ekleme kuyruğundan bir öğe kabul eder. Sırada bulunan her öğe için getDoc() yönteminde aşağıdaki adımları uygulayın:

  1. Cloud Search dizine ekleme kuyruğundaki öğenin kimliğinin depoda bulunup bulunmadığını kontrol edin. Aksi takdirde öğeyi dizinden silin.

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

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

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

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

Silinen öğeleri işleme

Aşağıdaki kod snippet'inde, bir öğenin depoda bulunup bulunmadığının nasıl belirleneceği ve bulunmadığı takdirde 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 değerinin, deposu temsil eden bir veri yapısı olduğunu unutmayın. documentID, documents içinde bulunamazsa öğeyi dizinden silmek için APIOperations.deleteItem(resourceName) döndürün.

Değişmeyen öğeleri işleme

Aşağıdaki kod snippet'inde, Cloud Search dizine ekleme kuyruğunda öğe durumunun nasıl sorgulandığı ve değişmeyen bir öğenin nasıl işlendiğ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şiklik gösterebileceği 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ı tanımlamak için erişim kontrol listesi (EKL) kullanır. ACL, öğeye erişebilen grupların veya kullanıcıların kimliklerinin listesidir.

Yalnızca bir öğeye erişimi olan kullanıcıların, söz konusu öğeyi arama sonucunda görebilmesi için deponuzun kullandığı ACL'yi kopyalamanız gerekir. Bir öğe dizine eklenirken öğenin ACL'si eklenmelidir. Böylece Google Cloud Search, öğeye doğru erişim düzeyini sağlamak için ihtiyaç duyduğu bilgilere sahip olur.

Content Connector SDK'sı, çoğu deponun ACL'lerini modellemek için zengin bir ACL sınıfı ve yöntem grubu sağlar. Bir öğeyi dizine eklediğinizde, veri havuzunuzdaki her öğenin ACL'sini analiz etmeniz ve Google Cloud Search için ilgili bir ACL oluşturmanız gerekir. Deponuzun ACL'sinde ACL devralma gibi kavramlar kullanılıyorsa bu ACL'yi modellemek zor olabilir. Google Cloud Search ACL'leri hakkında daha fazla bilgi için Google Cloud Search ACL'leri başlıklı makaleyi inceleyin.

Not: Cloud Search Dizine Ekleme API'si tek alan adında ACL'leri destekler. Alanlar arası ACL'leri desteklemez. Her bir öğeye erişimi EKL kullanarak ayarlamak için Acl.Builder sınıfını kullanın. Tam tarama örneğinden alınan aşağıdaki kod snippet'i, tüm kullanıcıların veya "yöneticilerin" (getCustomerPrincipal()), arama yaparken 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 ACL'leri doğru şekilde modellemek üzere ACL'leri anlamanız gerekir. Örneğin, alt klasörlerin üst klasörlerden izinleri devraldığı bir tür devralma modeli kullanan bir dosya sistemindeki dosyaları dizine ekleyebilirsiniz. EKL devralımının modellenmesi için Google Cloud Search EKL'leri bölümünde açıklanan ek bilgiler gerekir.

Bir öğenin meta verilerini ayarlama

Meta veriler Item nesnesinde depolanır. Item oluşturmak için en azından benzersiz bir dize kimliği, öğe türü, ACL, URL ve öğe sürümü gerekir. Aşağıdaki kod snippet'inde, IndexingItemBuilder yardımcı sınıfı kullanılarak Item oluşturma işlemi 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 öğesini kullanarak gerçek dizine eklenebilir öğ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()ApiOperation isteklerini yürüten bir türdü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ında daha uzun gecikme süresine neden olur ve dizine ekleme istekleri için büyük bir işleme hızı kotasına sahiptir. Deponun tamamının ilk dizine eklenmesi (dolgu) için ayarsız mod önerilir.
SYNCHRONOUS
Senkron mod, dizine ekleme ile yayınlama arasında daha kısa gecikme süresine neden olur ve sınırlı işleme hızı kotasını karşılar. Depodaki güncellemelerin ve değişikliklerin dizine eklenmesi için senkron modu önerilir. Belirtilmemişse istek modu varsayılan olarak SYNCHRONOUS olur.

Sonraki Adımlar

Aşağıda, uygulayabileceğiniz birkaç adım verilmiştir:

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

Şablon sınıfı kullanarak grafik tarama konnektörü oluşturma

Cloud Search dizine ekleme sırası, depodaki her öğe için kimlikleri ve isteğe bağlı karma oluşturma değerlerini tutmak için kullanılır. Grafik tarama 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, öğe durumunu (ör. bir öğenin depoda silinip silinmediğini) belirlemek için sıraları korur ve sıra içeriklerini karşılaştırır. Cloud Search dizine ekleme sırası hakkında daha fazla bilgi için Google Cloud Search dizine ekleme sırası başlıklı makaleyi inceleyin.

Dizine ekleme sırasında öğe içeriği veri deposundan alınır ve tüm alt öğe kimlikleri sıraya eklenir. Bağlantılayıcı, tüm öğeler işlenene kadar üst ve alt öğe kimliklerini yinelemeli olarak işlemeye devam eder.

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

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

Bir 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 sınıfın start() yöntemini çağırmaktır.

application.start() işlevini çağırmadan önce ListingConnector şablonunu örneklemek 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();
}

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

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

Repository arayüzünü uygulama

Repository nesnesinin tek amacı, depo öğelerinin taranmasını 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ı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 ilklendirmesi 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. Deponuzdan değişiklik algılama özelliğini destekliyorsa getChanges() yöntemini geçersiz kılın. Bu yöntem, değiştirilen öğeleri almak ve dizine eklemek için her planlanmış artımlı tarama (yapılandırmanız tarafından tanımlandığı şekilde) için bir kez çağrılır.

  • (isteğe bağlı) close() yöntemi. Depoyu temizlemeniz 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. ApiOperation nesnesi, deponuzun gerçek dizine ekleme işlemini 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ğlantıcınızın yapılandırmasını işleme kapsamında, tüm özel parametreleri Configuration nesnesinden almanız gerekir. Bu görev genellikle bir Repository sınıfının init() yönteminde gerçekleştirilir.

Configuration sınıfında, bir yapılandırmadan farklı veri türleri elde etmek için çeşitli yöntemler bulunur. 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. FullTraversalSample kaynağından alınan aşağıdaki snippet'te, Configuration nesnesinden tek bir özel tamsayı değerinin nasıl alınacağı gösterilmektedir:

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çalara ayırmak üzere Configuration sınıfının tür ayrıştırıcılarından birini kullanın. Eğitim amaçlı bağlayıcıdan alınan aşağıdaki snippet'te, GitHub depo adlarının listesini almak için getMultiValue yöntemi kullanılır:

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

Grafiği inceleme

Depodaki tüm kayıtların kimliklerini ve karma değerlerini almak için getIds() yöntemini geçersiz kılın. getIds() yöntemi bir kontrol noktasını kabul eder. Kontrol noktası, işlem kesintiye uğradığında dizine ekleme işlemini belirli bir öğede devam ettirmek için kullanılır.

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

Öğe kimliklerini ve karma oluşturma değerlerini gönderme

Öğe kimliklerini ve ilişkili içerik karma değerlerini depodan almak için getIds() parametresini geçersiz kılın. Kimlik ve karma değer çiftleri daha sonra Cloud Search dizine ekleme sırasına gönderme işlemi isteği olarak paketlenir. Kök veya üst kimlikler genellikle önce itilir, ardından öğe hiyerarşisinin tamamı işlenene kadar alt kimlikler itilir.

getIds() yöntemi, dizine eklenecek son öğeyi temsil eden bir kontrol noktasını kabul eder. Kontrol noktası, süreç kesintiye uğrarsa dizine ekleme işlemini belirli bir öğede devam ettirmek için kullanılabilir. Deponuzdan her öğe için getIds() yönteminde aşağıdaki adımları uygulayın:

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

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

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

Öğeler, daha fazla işleme alınmak üzere Cloud Search dizine ekleme sırasına gönderilir.

Her öğeyi alma ve işleme

Cloud Search dizine ekleme kuyruğundaki her öğeyi işlemek için getDoc() değerini geçersiz kılın. Bir öğe yeni, değiştirilmiş, değiştirilmemiş veya kaynak depoda artık mevcut olmayabilir. Yeni veya değiştirilmiş her öğeyi alıp dizine ekleyin. Artık kaynak depoda bulunmayan öğeleri dizinden kaldırın.

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

  1. Cloud Search dizine ekleme kuyruğundaki öğenin kimliğinin depolama alanında bulunup bulunmadığını kontrol edin. Aksi takdirde öğeyi dizinden silin. Öğe mevcutsa sonraki adıma geçin.

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

    1. İzinleri ayarlayın.
    2. Dizine eklediğiniz öğenin meta verilerini ayarlayın.
    3. Meta verileri ve öğeyi dizine eklenebilir tek bir RepositoryDoc öğesinde birleştirin.
    4. Daha fazla işlem için alt kimlikleri Cloud Search dizine ekleme sırasına ekleyin.
    5. RepositoryDoc cihazını iade edin.

Silinen öğeleri işleme

Aşağıdaki kod snippet'inde, bir öğenin dizinde bulunup bulunmadığının nasıl belirleneceği ve bulunmaması durumunda öğenin 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ı tanımlamak için erişim kontrol listesi (EKL) kullanır. ACL, öğeye erişebilen grupların veya kullanıcıların kimliklerinin listesidir.

Yalnızca bir öğeye erişimi olan kullanıcıların, söz konusu öğeyi arama sonucunda görebilmesi için deponuzun kullandığı ACL'yi kopyalamanız gerekir. Bir öğe dizine eklenirken öğenin ACL'si eklenmelidir. Böylece Google Cloud Search, öğeye doğru erişim düzeyini sağlamak için ihtiyaç duyduğu bilgilere sahip olur.

Content Connector SDK'sı, çoğu deponun ACL'lerini modellemek için zengin bir ACL sınıfı ve yöntem grubu sağlar. Bir öğeyi dizine eklediğinizde, veri havuzunuzdaki her öğenin ACL'sini analiz etmeniz ve Google Cloud Search için ilgili bir ACL oluşturmanız gerekir. Deponuzun ACL'sinde ACL devralma gibi kavramlar kullanılıyorsa bu ACL'yi modellemek zor olabilir. Google Cloud Search ACL'leri hakkında daha fazla bilgi için Google Cloud Search ACL'leri başlıklı makaleyi inceleyin.

Not: Cloud Search Dizine Ekleme API'si tek alan adında ACL'leri destekler. Alanlar arası ACL'leri desteklemez. Her bir öğeye erişimi EKL kullanarak ayarlamak için Acl.Builder sınıfını kullanın. Tam tarama örneğinden alınan aşağıdaki kod snippet'i, tüm kullanıcıların veya "yöneticilerin" (getCustomerPrincipal()), arama yaparken 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 ACL'leri doğru şekilde modellemek üzere ACL'leri anlamanız gerekir. Örneğin, alt klasörlerin üst klasörlerden izinleri devraldığı bir tür devralma modeli kullanan bir dosya sistemindeki dosyaları dizine ekleyebilirsiniz. EKL devralımının modellenmesi için Google Cloud Search EKL'leri bölümünde açıklanan ek bilgiler gerekir.

Bir öğenin meta verilerini ayarlama

Meta veriler Item nesnesinde depolanır. Item oluşturmak için en azından benzersiz bir dize kimliği, öğe türü, ACL, URL ve öğe sürümü gerekir. Aşağıdaki kod snippet'inde, IndexingItemBuilder yardımcı sınıfı kullanılarak Item oluşturma işlemi 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şturun

Öğenin meta verilerini ayarladıktan sonra RepositoryDoc.Builder öğesini kullanarak gerçek dizine eklenebilir öğ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 ekleme ile yayınlama arasında daha uzun gecikme süresine neden olur ve dizine ekleme istekleri için büyük bir işleme hızı kotasına sahiptir. Deponun tamamının ilk dizine eklenmesi (dolgu) için ayarsız mod önerilir.
SYNCHRONOUS
Senkron mod, dizine ekleme ile yayınlama arasında daha kısa gecikme süresine neden olur ve sınırlı işleme hızı kotasını karşılar. Depodaki güncellemelerin ve değişikliklerin dizine eklenmesi için senkron modu önerilir. Belirtilmemişse istek modu varsayılan olarak SYNCHRONOUS olur.

Alt kimlikleri Cloud Search dizine ekleme sırasına ekleme

Aşağıdaki kod snippet'inde, şu anda işlenmekte olan ebeveyn öğenin 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

Aşağıda, uygulayabileceğiniz birkaç adım verilmiştir:

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

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

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

Geçiş stratejinizi belirleyin

İçerik bağlayıcının birincil işlevi, bir depoda gezinmek ve verilerini dizine eklemektir. Deponuzdan veri boyutuna ve düzenine göre bir tarama stratejisi uygulamanız gerekir. Aşağıda, yaygın olarak kullanılan üç tarama stratejisi verilmiştir:

Tam tarama stratejisi

Tam tarama stratejisi, deponun tamamını tarar ve her öğeyi kör bir şekilde dizine ekler. Bu strateji, küçük bir deponuz olduğunda ve dizine her eklediğinizde tam bir tarama yapmanın masrafını karşılayabildiğinizde genellikle kullanılır.

Bu tarama stratejisi, çoğunlukla statik, hiyerarşik olmayan veriler içeren küçük depolar için uygundur. Değişiklik algılama zor olduğunda veya depo tarafından desteklenmediğinde de bu tarama stratejisini kullanabilirsiniz.

Liste tarama stratejisi

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

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

Grafiğin taranması

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

Bu strateji, dizine eklenmiş seri 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 öğ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. (isteğe bağlı) Dizine ekleme için 100 KB'tan büyük dosyaları yüklemek üzere items.upload kullanma Küçük dosyalar için items.index kullanarak içeriği inlineContent olarak yerleştirin.

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

  3. Öğeyi dizine eklemek için items.index kullanma Örneğin, şemanız film şemasında bulunan 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ı kullanma.

Tam bir tarama yapmak için deponun tamamını düzenli olarak yeniden dizine eklemeniz gerekir. Liste veya grafik geçişi yapmak için depo değişikliklerini işlemek üzere kod uygulamanız gerekir.

Depo değişikliklerini işleme

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

Deponun tamamını belirli aralıklarla dizine eklemek için dizin çağrıları kullanmak yerine, değişiklikleri izlemek ve yalnızca değişen öğeleri dizine eklemek için Google Cloud dizine ekleme sırasını da kullanabilirsiniz. Daha sonra sorgulamak ve güncellemek üzere öğeleri sıraya eklemek 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ı başlıklı makaleyi inceleyin.

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