Veritabanı bağlayıcısı dağıtma

Uyarı: Cloud Search referans bağlayıcıları, kendi çalışan bağlayıcılarınızı oluştururken kullanmanız için örnek kod olarak "olduğu gibi" sağlanır. Bu örnek kod, kavram kanıtlama veya üretim ortamlarında kullanılmadan önce önemli ölçüde özelleştirme ve test gerektirir. Üretim kullanımı için Cloud Search iş ortaklarımızın birinden yardım almanızı önemle tavsiye ederiz. Uygun bir Cloud Search iş ortağı bulma konusunda daha fazla yardım almak için Google hesap yöneticinizle iletişime geçin.

Google Cloud Search veritabanı bağlayıcısını kullanarak Google Cloud Search'ü, kuruluşunuzun veritabanlarındaki verileri keşfedip dizine ekleyecek şekilde ayarlayabilirsiniz.

Dikkat edilmesi gerekenler

Bağlayıcının hem internete hem de veritabanına erişimi olduğu sürece, Cloud Search veritabanı bağlayıcısını Java uygulamalarının çalışabildiği neredeyse tüm ortamlarda yükleyip çalıştırabilirsiniz.

Sistem gereksinimleri

Sistem gereksinimleri
İşletim sistemi Windows veya Linux
SQL veritabanı Aşağıdakiler dahil olmak üzere JDBC 4.0 veya sonraki sürümlerle uyumlu bir sürücüye sahip herhangi bir SQL veritabanı:
  • MS SQL Server (2008, 2012, 2014, 2016)
  • Oracle (11g, 12c)
  • Google Cloud SQL
  • MySQL
Yazılım Bağlayıcının veritabanına erişmek üzere kullanacağı JDBC sürücüsü (ayrı olarak indirilir ve yüklenir)

Bağlayıcıyı dağıtma

Aşağıdaki adımlarda bağlayıcının nasıl yükleneceği, ayrıca belirtilen veritabanlarını dizine eklemek ve sonuçları Cloud Search kullanıcılarına döndürecek şekilde nasıl yapılandırılacağı açıklanmaktadır.

Ön koşullar

Cloud Search veritabanı bağlayıcısını dağıtmadan önce aşağıdaki bilgileri toplayın:

1. Adım: Veritabanı bağlayıcı yazılımını indirin ve oluşturun

  1. GitHub'dan bağlayıcı deposunu klonlayın. 
    $ git clone https://github.com/google-cloudsearch/database-connector.git
$ cd database-connector
  2. Bağlayıcının istenen sürümünü kontrol edin:
    $ git checkout tags/v1-0.0.3
  3. Bağlayıcıyı oluşturun. 
    $ mvn package
    Bağlayıcıyı oluştururken testleri atlamak için mvn package -DskipTests politikasını kullanın.
  4. Bağlayıcı ZIP dosyasını yerel yükleme dizininize kopyalayın ve sıkıştırılmış dosyayı açın: 
    $ cp target/google-cloudsearch-database-connector-v1-0.0.3.zip installation-dir
$ cd installation-dir
$ unzip google-cloudsearch-database-connector-v1-0.0.3.zip
$ cd google-cloudsearch-database-connector-v1-0.0.3

2. adım: Veritabanı bağlayıcısını yapılandırma

  1. Bir metin dosyası oluşturun ve dosyayı connector-config.properties (varsayılan) veya benzer bir adla adlandırın. Google, yapılandırma dosyalarını .properties veya .config uzantısıyla adlandırmanızı ve dosyayı bağlayıcıyla aynı dizinde tutmanızı önerir. Farklı bir ad veya yol kullanıyorsanız bağlayıcıyı çalıştırdığınızda yolu belirtmeniz gerekir.
  2. Parametreleri dosya içeriğine anahtar/değer çiftleri olarak ekleyin. Yapılandırma dosyasında veri kaynağı erişimi, veritabanı erişimi, veritabanı tam geçiş SQL ifadesi, içerik alanı başlığı ve sütun tanımlarıyla ilgili parametreler belirtilmelidir. Ayrıca isteğe bağlı parametrelerle diğer bağlayıcı davranışlarını da yapılandırabilirsiniz. Örneğin: 
    # Required parameters for data source access
api.sourceId=1234567890abcdef
api.identitySourceId=0987654321lmnopq
api.serviceAccountPrivateKeyFile=./PrivateKey.json
#
# Required parameters for database access
db.url=jdbc:mysql://localhost:3306/mysql_test
db.user=root
db.password=passw0rd
#
# Required full traversal SQL statement parameter
db.allRecordsSql=select customer_id, first_name, last_name, phone, change_timestamp from address_book
#
# Required parameters for column definitions and URL format
db.allColumns=customer_id, first_name, last_name, phone, change_timestamp
db.uniqueKeyColumns=customer_id
url.columns=customer_id
#
# Required content field parameter
contentTemplate.db.title=customer_id
#
# Optional parameters to set ACLs to "entire domain" access
defaultAcl.mode=fallback
defaultAcl.public=true
#
# Optional parameters for schedule traversals
schedule.traversalIntervalSecs=36000
schedule.performTraversalOnStart=true
schedule.incrementalTraversalIntervalSecs=3600

    Veritabanına özel parametrelerin ayrıntılı açıklamaları için bu makalenin sonundaki Yapılandırma parametreleri referansı bölümüne gidin.

    Meta veri yapılandırması, tarih/saat biçimleri ve EKL seçenekleri gibi tüm Cloud Search bağlayıcılarında ortak olan parametreler hakkında bilgi edinmek için Google tarafından sağlanan bağlayıcı parametreleri bölümüne gidin.

    Varsa geçiş SQL sorgu parametrelerinde şema nesnesinin özelliklerini belirtin. SQL ifadesine genellikle takma ad ekleyebilirsiniz. Örneğin, bir film veritabanınız varsa ve veri kaynağı şeması "ActorName" adlı bir özellik tanımı içeriyorsa SQL ifadesi şu biçimde olabilir: SELECT …, last_name AS ActorName, … FROM … .

3. Adım: Veritabanı bağlayıcısını çalıştırın

Aşağıdaki örnekte, gerekli bileşenlerin bir Linux sistemindeki yerel dizinde bulunduğu varsayılmaktadır.

Bağlayıcıyı komut satırından çalıştırmak için aşağıdaki komutu girin: 

java \
   -cp "google-cloudsearch-database-connector-v1-0.0.3.jar:mysql-connector-java-5.1.41-bin.jar" \
   com.google.enterprise.cloudsearch.database.DatabaseFullTraversalConnector \
   [-Dconfig=mysql.config]

Burada:

  • google-cloud-search-database-connector-v1-0.0.3.jar, veritabanı bağlayıcısı .jar dosyasıdır
  • mysql-connector-java-5.1.41-bin.jar, veritabanına erişmek için kullanılan JDBC sürücüsüdür
  • mysql.config, özel adlandırılmış bir yapılandırma dosyasıdır. Bağlayıcının yapılandırma dosyanızı tanımasını sağlamak için komut satırında dosyanın yolunu belirtin. Aksi takdirde, bağlayıcı, yerel dizininizdeki varsayılan dosya adı olarak connector-config.properties'i kullanır.

Bağlayıcı, yapılandırma hatalarını algıladığında bunları bildirir. Bağlayıcının başlatılması sırasında bir veritabanı sütununun kayıt içeriğinin bir parçası olarak tanımlanması gibi bazı hatalar bildirilir (db.allColumns içinde), ancak sütun veritabanının geçiş SQL sorgusunda (db.allRecordsSql içinde) kullanılmaz. Diğer hatalar yalnızca bağlayıcı ilk geçiş için veritabanına erişmeye çalıştığında algılanır ve raporlanır (geçersiz SQL ifadesi söz dizimi gibi).

Yapılandırma parametreleri referansı

Veri kaynağı erişim parametreleri

Ayar Parametre
Veri kaynağı kimliği api.sourceId = source-ID

Zorunlu. Google Workspace yöneticisinin ayarladığı Cloud Search kaynak kimliği.
Kimlik kaynağı kimliği api.identitySourceId = identity-source-ID

EKL'ler için harici kullanıcıların ve grupların kullanılması gerekir. Google Workspace yöneticisinin ayarladığı Cloud Search kimlik kaynağı kimliği.
Hizmet hesabı api.serviceAccountPrivateKeyFile = path-to-private-key

Zorunlu. Google Workspace yöneticisinin oluşturduğu Cloud Search hizmet hesabı anahtar dosyasının yolu.

Veritabanı erişim parametreleri

Ayar Parametre
Veritabanı URL'si db.url = database-URL

Zorunlu. Erişilecek veritabanının tam yolu (ör. jdbc:mysql://127.0.0.1/dbname).
Veritabanı kullanıcı adı ve şifresi db.user = username
db.password = password

Zorunlu. Bağlayıcının veritabanına erişmek için kullandığı geçerli bir kullanıcı adı ve şifredir. Bu veritabanı kullanıcısının, okunmakta olan veritabanının ilgili kayıtlarına okuma erişimi olmalıdır.
JDBC sürücüsü db.driverClass = oracle.jdbc.OracleDriver

Yalnızca JDBC 4.0 sürücüsü sınıf yolunda önceden belirtilmediyse gereklidir.

Geçiş SQL sorgu parametreleri

Bağlayıcı, yapılandırma dosyasındaki SQL SELECT sorgularıyla veritabanı kayıtlarına bilgi katar. Tam geçiş sorgusu yapılandırmanız gerekir. Artımlı geçiş sorguları isteğe bağlıdır.

Tam geçiş, dizine ekleme için yapılandırılan her veritabanı kaydını okur. Cloud Search için yeni kayıtları dizine eklemek ve mevcut tüm kayıtları yeniden dizine eklemek için tam bir geçiş gereklidir.

Artımlı geçiş, yalnızca yeni değiştirilen veritabanı kayıtlarını ve veritabanındaki son girişleri okur ve yeniden dizine ekler. Artımlı geçişler, tam geçişlerden daha verimli olabilir. Artımlı geçişleri kullanmak için veritabanınızda değiştirilen kayıtları belirten zaman damgası alanları bulunmalıdır.

Bağlayıcı, bu geçişleri geçiş zaman planlaması parametrelerinde tanımladığınız planlara göre yürütür.

Ayar Parametre
Tam geçiş sorgusu db.allRecordsSql = SELECT column-1[, column-2,...] FROM database-name

Zorunlu. Sorgu, her tam geçiş için çalıştırılır.

Bağlayıcının herhangi bir kapasitede kullanacağı her sütun adı (içerik, benzersiz kimlik, EKL'ler) bu sorguda bulunmalıdır. Bağlayıcı, hataları ve eksiklikleri tespit etmek için başlangıçta bazı ön doğrulamalar gerçekleştirir. Bu nedenle, genel bir "SELECT * FROM ..." sorgusu kullanmayın.
Tam geçiş sayfalandırması db.allRecordsSql.pagination = {none | offset}

Değer şunlardan biri olabilir:

  • none: sayfalara ayırma kullanma
  • offset: satır ofsetine göre sayfalara ayırma kullanır

    Ofsetle sayfalandırmayı kullanmak için SQL sorgusunun, sıfırdan başlayan bir satır ofseti için yer tutucu soru işareti (?) içermesi gerekir. Her tam geçişte sorgu, hiçbir sonuç döndürülene kadar tekrar tekrar yürütülür.
Artımlı geçiş sorgusu db.incrementalUpdateSql = SELECT column-1[, column-2,...] FROM database-name WHERE last_update_time > ?

Artımlı geçişler planlarsanız gereklidir.

Sorgudaki "?", zaman damgası değeri için zorunlu bir yer tutucudur. Bağlayıcı, artımlı geçiş SQL sorguları arasındaki değişiklikleri izlemek için zaman damgasını kullanır.

Veritabanı zaman damgası sütununu son güncelleme zamanına göre izlemek için SQL deyimine timestamp_column takma adını ekleyin. Aksi takdirde, bağlayıcı geçişinin geçerli zaman damgasını kullanın.

İlk artımlı geçiş için bağlayıcı, bağlayıcının başlangıç zamanını kullanır. İlk artımlı geçişten sonra Cloud Search, bağlayıcı yeniden başlatmalarının önceki artımlı geçiş zaman damgasına erişebilmesi için zaman damgasını saklar.
Veritabanı saat dilimi db.timestamp.timezone = America/Los_Angeles

Veritabanı zaman damgaları için kullanılacak saat dilimini belirtir. Yeni kayıt eklemelerini veya yeni değiştirilen veritabanı kayıtlarını tanımlamak için kullanılan veritabanı zaman damgası. Varsayılan değer, bağlayıcının çalıştığı yerel saat dilimidir.

Geçiş SQL sorgusu örnekleri

  • Dizine ekleme için bir çalışan veritabanındaki ilgi alanlarının her kaydını okuyan temel tam geçiş sorgusu: 
    db.allRecordsSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field \
    FROM employee
  • Ofsete göre sayfalandırmayı belirtin ve tam geçişi birden çok sorguya bölün.

    SQL Server 2012 veya Oracle 12c için (standart SQL 2008 söz dizimi):

    db.allRecordsSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field \
    FROM employee \
    ORDER BY customer_id OFFSET ? ROWS FETCH FIRST 1000 ROWS ONLY
db.allRecordsSql.pagination = offset

    veya MySQL veya Google Cloud SQL için:

    db.allRecordsSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field \
    FROM employee \
    ORDER BY customer_id LIMIT 1000 OFFSET ?
db.allRecordsSql.pagination = offset
  • Takma adlarla tek tek EKL'leri uygulayan tam geçiş sorgusu: 
    db.allRecordsSql = SELECT customer_id, first_name, last_name,  employee_id, interesting_field, last_update_time, \
     permitted_readers AS readers_users, \
     denied_readers AS denied_users, \
     permitted_groups AS readers_groups, \
     denied_groups AS denied_groups \
     FROM employee
  • Temel artımlı geçiş sorgusu: 
    db.incrementalUpdateSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field, last_update_time \
     FROM employee \
     WHERE last_update_time > ?
  • Takma adlarla tek tek EKL'ler uygulayan artımlı geçiş sorgusu: 
    db.incrementalUpdateSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field, last_update_time, \
     permitted_readers AS readers_users, \
     denied_readers AS denied_users, \
     permitted_groups AS readers_groups, \
     denied_groups AS denied_groups \
     FROM employee \
     WHERE last_update_time > ?
  • Geçerli zaman yerine veritabanı zaman damgasını kullanan artımlı geçiş sorgusu: 
    db.incrementalUpdateSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field, \
     last_update_time AS timestamp_column \
     FROM employee \
     WHERE last_update_time > ?

Sütun tanımlama parametreleri

Aşağıdaki parametreler, geçiş ifadelerinde kullandığınız sütunları ve her bir kaydı benzersiz şekilde tanımlamak için kullanılır.

Ayar Parametre
Tüm sütunlar db.allColumns = column-1, column-2, ...column-N

Zorunlu. Veritabanına erişirken SQL sorgusunda gereken tüm sütunları tanımlar. Bu parametreyle tanımlanan sütunlara, sorgularda açıkça referans verilmelidir. Diğer tüm sütun tanımı parametreleri bu sütun grubuyla karşılaştırılır.

Örnek:

db.allColumns = customer_id, first_name, last_name, phone, change_timestamp
Benzersiz anahtar sütunları db.uniqueKeyColumns = column-1[, column-2]

Zorunlu. Benzersiz değerler içeren tek bir veritabanı sütununu veya değerleri birlikte benzersiz bir kimlik tanımlayan sütunların bir kombinasyonunu listeler.

Cloud Search, veri kaynağında aranabilir her dokümanın benzersiz bir tanımlayıcısının olmasını gerektirir. Sütun değerlerinden her veritabanı kaydı için benzersiz bir kimlik tanımlayabilmeniz gerekir. Ayrı veritabanlarında birden fazla bağlayıcı çalıştırır ancak bunları ortak bir veri kümesinde dizine eklerseniz tüm belgelerde benzersiz bir kimlik belirttiğinizden emin olun.

Örnekler:

db.uniqueKeyColumns = customer_id
# or
db.uniqueKeyColumns = last_name, first_name
URL bağlantısı sütunu url.columns = column-1[, column-2]

Zorunlu. Tıklanabilir arama sonucu için kullanılan URL için kullanılan sütunların bir veya daha fazla geçerli, tanımlanmış adını belirtir. Her veritabanı kaydıyla ilişkili alakalı bir URL'si olmayan veritabanlarındaki her kayıt için statik bir bağlantı kullanılabilir.

Bununla birlikte, sütun değerleri her kayıt için geçerli bir bağlantı tanımlıyorsa görüntüleme URL'si sütunları ve biçim yapılandırma değerleri belirtilmelidir.
URL biçimi url.format = https://www.example.com/{0}

Görüntüleme URL'sinin biçimini tanımlar. Numaralı parametreler, db.columns bölümünde belirtilen, sıfırdan başlayarak sıralı sütunlara referansta bulunur.

Bir ayar belirtilmezse varsayılan olarak "{0}." değeri kullanılır.

Örnekler aşağıdaki tabloda verilmiştir.
URL için yüzde olarak kodlanmış sütunlar url.columnsToEscape = column-1[, column-2]

Biçimlendirilmiş URL dizesine dahil edilmeden önce değerleri yüzdeyle kodlanmış olacak db.columns sütunlarını belirtir.

URL sütunu örnekleri

Geçiş sorgularında kullanılan sütunları ve görünüm URL'sinin biçimini belirtmek için:

  • Veritabanı kaydı değeri kullanmayan statik URL kullanmak için: 
    url.format = https://www.example.com
  • Görüntüleme URL'si olan tek bir sütun değeri kullanmak için: 
    url.format = {0}
url.columns = customer_id
  • {0} konumundaki görüntüleme URL'siyle değiştirilecek tek bir sütun değeri kullanmak için: 
    url.format = https://www.example.com/customer/id={0}
url.columns = customer_id
url.columnsToEscape = customer_id
  • Görüntüleme URL'sini oluşturmak üzere birden fazla sütun değeri kullanmak için (sütunlar sıraya bağlıdır): 
    url.format = {1}/customer={0}
url.columns = customer_id, linked_url
url.columnsToEscape = customer_id

İçerik alanları

Aranabilir içeriğin bir parçası olması gereken kayıt değerlerini belirlemek için içerik seçeneklerini kullanın.

Ayar Parametre
En yüksek kaliteli arama sütunu contentTemplate.db.title = column-name

Zorunlu. Arama dizine ekleme ve sonuç önceliklendirme için en yüksek kaliteli sütun.
Arama için sütun önceliği contentTemplate.db.quality.high = column-1[, column-2...]
contentTemplate.db.quality.medium = column-1[, column-2...]
contentTemplate.db.quality.low = column-1[, column-2...]

İçerik sütunlarını (contentTemplate.db.title için ayarlanan sütun hariç) yüksek, orta veya düşük arama kalitesi alanları olarak atayın. Belirtilmemiş sütunlar varsayılan olarak düşük olur.
İçerik verisi sütunları db.contentColumns = column-1[, column-2...]

Veritabanındaki içerik sütunlarını belirtin. Bunlar biçimlendirilir ve Cloud Search'e aranabilir doküman içeriği olarak yüklenir.

Bir değer belirtmezseniz varsayılan değer, içerik için tüm sütunların kullanılması gerektiğini belirten "*" olur.
Blob sütunu db.blobColumn = column-name

İçerik sütunlarının bir kombinasyonu yerine belge içeriği için kullanılacak tek bir blob sütununun adını belirtin.

Bir blob sütunu belirtilirse içerik sütunlarının da tanımlanmış olması hata olarak kabul edilir. Bununla birlikte, blob sütunlarıyla birlikte meta veri ve yapılandırılmış veri sütunu tanımlarına da izin verilir.