CSV Bağlayıcısı dağıtma

Bu kılavuz, Google Cloud Search CSV (virgülle ayrılmış değerler) bağlayıcısı yöneticileri, yani bağlayıcıyı indirmek, yapılandırmak, çalıştırmak ve izlemekten sorumlu olan herkes için hazırlanmıştır.

Bu kılavuzda, CSV bağlayıcısının dağıtımıyla ilgili temel görevleri gerçekleştirme talimatları yer alır:

• Google Cloud Search CSV bağlayıcı yazılımını indirin
• Bağlayıcıyı belirli bir CSV veri kaynağıyla kullanılacak şekilde yapılandırma
• Bağlayıcıyı dağıtma ve çalıştırma

Bu belgedeki kavramları anlamak için Google Workspace, CSV dosyaları ve erişim kontrol listeleri (ACL'ler) ile ilgili temel bilgileri edinmeniz gerekir.

Google Cloud Search CSV bağlayıcısına genel bakış

Cloud Search CSV bağlayıcısı, virgülle ayrılmış değerler (CSV) metin dosyalarıyla çalışır. CSV dosyası, tablo biçimindeki verileri depolar ve dosyanın her satırı bir veri kaydıdır.

Google Cloud Search'ün CSV bağlayıcısı, bir CSV dosyasından tek tek satırları ayıklar ve Cloud Search'ün Indexing API'si aracılığıyla Cloud Search'te dizine ekler. Başarıyla dizine eklendikten sonra, CSV dosyalarındaki tek tek satırlar Cloud Search'ün istemcileri veya Cloud Search'ün Query API'si aracılığıyla aranabilir. CSV bağlayıcı, ACL'leri kullanarak kullanıcıların arama sonuçlarındaki içeriğe erişimini kontrol etmeyi de destekler.

Google Cloud Search CSV bağlayıcısı Linux veya Windows'a yüklenebilir. Google Cloud Search CSV bağlayıcısını dağıtmadan önce aşağıdaki gerekli bileşenlere sahip olduğunuzdan emin olun:

• Google Cloud Search CSV bağlayıcısının çalıştığı bilgisayarda Java JRE 1.8 yüklü olmalıdır.

• Google Cloud Search ile veri kaynağı arasında ilişki kurmak için gereken Google Workspace bilgileri:

  • Google Workspace özel anahtarı (hizmet hesabı kimliğini içerir)
  • Google Workspace veri kaynağı kimliği

  Genellikle, alanın Google Workspace yöneticisi bu kimlik bilgilerini sizin için sağlayabilir.

Dağıtım adımları

Google Cloud Search CSV bağlayıcısını dağıtmak için aşağıdaki adımları uygulayın:

1. Google Cloud Search CSV bağlayıcı yazılımını yükleme
2. CSV bağlayıcı yapılandırmasını belirtme
3. Google Cloud Search veri kaynağına erişimi yapılandırma
4. CSV dosyası erişimini yapılandırma
5. Dizin oluşturulacak sütun adlarını, benzersiz anahtar sütunlarını ve tarih/saat sütunlarını belirtin
6. Tıklanabilir arama sonucu URL'lerinde kullanılacak sütunları belirtme
7. Meta veri bilgilerini ve sütun biçimlerini belirtme
8. Veri geçişini planlama
9. Erişim kontrol listesi (EKL) seçeneklerini belirtme

1. SDK'yı yükleme

SDK'yı yerel Maven deponuza yükleyin.

1. SDK deposunu GitHub'dan klonlayın.

   $ git clone https://github.com/google-cloudsearch/connector-sdk.git
   $ cd connector-sdk/csv

2. SDK'nın istediğiniz sürümüne göz atın:

   $ git checkout tags/v1-0.0.3

3. Bağlayıcıyı oluşturun:

   $ mvn package

4. Bağlayıcı ZIP dosyasını yerel yükleme dizininize kopyalayın:

   $ cp target/google-cloudsearch-csv-connector-v1-0.0.3.zip installation-dir
   $ cd installation-dir
   $ unzip google-cloudsearch-csv-connector-v1-0.0.3.zip
   $ cd google-cloudsearch-csv-connector-v1-0.0.3

2. CSV bağlayıcı yapılandırmasını belirtin

Bağlayıcı yöneticisi olarak, CSV bağlayıcının davranışını ve bağlayıcının yapılandırma dosyasındaki parametreleri tanımlayan özellikleri kontrol edersiniz. Yapılandırılabilir parametreler şunlardır:

• Veri kaynağına erişim
• CSV dosyasının konumu
• CSV sütun tanımları
• Benzersiz bir kimliği tanımlayan sütunlar
• Geçiş seçenekleri
• Veri erişimini kısıtlamak için ACL seçenekleri

Bağlayıcının bir CSV dosyasına düzgün şekilde erişip ilgili içeriği dizine eklemesi için önce yapılandırma dosyasını oluşturmanız gerekir.

Yapılandırma dosyası oluşturmak için:

1. Seçtiğiniz bir metin düzenleyiciyi açın ve yapılandırma dosyasını adlandırın.
   Dosya içeriğine, aşağıdaki bölümlerde açıklandığı şekilde anahtar=değer çiftleri ekleyin.
2. Yapılandırma dosyasını kaydedin ve adlandırın.
   Google, bağlayıcıyı çalıştırmak için ek komut satırı parametreleri gerekmemesi amacıyla yapılandırma dosyasını connector-config.properties adlandırmanızı önerir.

Yapılandırma dosyası yolunu komut satırında belirtebileceğiniz için standart bir dosya konumu gerekli değildir. Ancak, izlemeyi ve bağlayıcıyı çalıştırmayı kolaylaştırmak için yapılandırma dosyasını bağlayıcıyla aynı dizinde tutun.

Bağlayıcının yapılandırma dosyanızı tanıdığından emin olmak için komut satırında dosyanın yolunu belirtin. Aksi takdirde, bağlayıcı varsayılan dosya adı olarak yerel dizininizdeki connector-config.properties öğesini kullanır. Komut satırında yapılandırma yolunu belirtme hakkında bilgi için Cloud Search CSV bağlayıcısını çalıştırma başlıklı makaleyi inceleyin.

3. Google Cloud Search veri kaynağına erişimi yapılandırma

Her yapılandırma dosyasının belirtmesi gereken ilk parametreler, aşağıdaki tabloda gösterildiği gibi Cloud Search veri kaynağına erişmek için gerekli olanlardır. Genellikle, bağlayıcının Cloud Search'e erişimini yapılandırmak için veri kaynağı kimliği, hizmet hesabı kimliği ve hizmet hesabının özel anahtar dosyasının yolu gerekir. Veri kaynağı oluşturmak için gereken adımlar Üçüncü taraf veri kaynaklarını yönetme başlıklı makalede açıklanmaktadır.

4. CSV dosyası parametrelerini yapılandırma

Bağlayıcı, bir CSV dosyasında gezinip dizine ekleme için dosyadan veri ayıklamadan önce dosyanın yolunu belirlemeniz gerekir. Ayrıca dosya biçimini ve dosya kodlama türünü de belirtebilirsiniz. Yapılandırma dosyasında CSV dosyası özelliklerini belirtmek için aşağıdaki parametreleri ekleyin.

5. Dizin oluşturulacak sütun adlarını ve benzersiz anahtar sütunlarını belirtin

Bağlayıcının CSV dosyalarına erişip bunları dizine eklemesi için yapılandırma dosyasında sütun tanımları hakkında bilgi sağlamanız gerekir. Yapılandırma dosyasında, dizine eklenecek sütun adlarını ve benzersiz anahtar sütunlarını belirten parametreler yoksa varsayılan değerler kullanılır.

6. Tıklanabilir arama sonucu URL'lerinde kullanılacak sütunları belirtme

Bir kullanıcı Google Cloud Search'ü kullanarak arama yaptığında, her sonuç için tıklanabilir URL'ler içeren bir sonuç sayfası göstererek yanıt verir. Bu özelliği etkinleştirmek için aşağıdaki tabloda gösterilen parametreyi yapılandırma dosyasına eklemeniz gerekir.

7. Meta veri bilgilerini, sütun biçimlerini ve arama kalitesini belirtin.

Yapılandırma dosyasına aşağıdaki bilgileri belirten parametreler ekleyebilirsiniz:

• Meta Veri Yapılandırma Parametreleri
• Sütun biçimleri
• Arama kalitesi

Meta Veri Yapılandırma Parametreleri

Meta veri yapılandırma parametreleri, öğe meta verilerini doldurmak için kullanılan CSV sütunlarını açıklar. Yapılandırma dosyası bu parametreleri içermiyorsa varsayılan değerler kullanılır. Bu parametreler aşağıdaki tabloda gösterilmektedir.

Tarih ve saat biçimleri

Tarih/saat biçimleri, meta veri özelliklerinde beklenen biçimleri belirtir. Yapılandırma dosyası bu parametreyi içermiyorsa varsayılan değerler kullanılır. Bu parametre aşağıdaki tabloda gösterilmektedir.

Sütun biçimleri

Sütun biçimleri, aranabilir içeriğin bir parçası olması gereken sütunlarla ilgili bilgileri belirtir. Yapılandırma dosyası bu parametreleri içermiyorsa varsayılan değerler kullanılır. Bu parametreler aşağıdaki tabloda gösterilmektedir.

Arama kalitesi

Cloud Search CSV bağlayıcısı, veri alanları için otomatik HTML biçimlendirmesine olanak tanır. Bağlayıcınız, bağlayıcı yürütülmesinin başında veri alanlarını tanımlar ve ardından her veri kaydını Cloud Search'e yüklemeden önce biçimlendirmek için bir içerik şablonu kullanır.

İçerik şablonu, arama için her alan değerinin önemini tanımlar. Başlık alanı zorunludur ve en yüksek öncelikli olarak tanımlanır. Diğer tüm içerik alanları için arama kalitesi önem düzeylerini (yüksek, orta veya düşük) belirleyebilirsiniz. Belirli bir kategoride tanımlanmayan tüm içerik alanları varsayılan olarak düşük öncelikli olur. Bu parametreler aşağıdaki tabloda gösterilmektedir.

8. Veri geçişini planlama

Geçiş, bağlayıcının veri kaynağındaki (bu örnekte bir CSV dosyası) içeriği keşfetme işlemidir. CSV bağlayıcısı çalışırken CSV dosyasının satırlarını geçer ve her satırı Indexing API aracılığıyla Cloud Search'te indeksler.

Tam geçiş, dosyadaki tüm sütunları indeksler. Artımlı geçiş yalnızca önceki geçişten bu yana eklenen veya değiştirilen sütunları indeksler. CSV bağlayıcısı yalnızca tam geçişler gerçekleştirir. Artımlı geçişler gerçekleştirmez.

Planlama parametreleri, bağlayıcının geçişler arasında ne sıklıkta bekleyeceğini belirler. Yapılandırma dosyası planlama parametreleri içermiyorsa varsayılan değerler kullanılır. Bu parametreler aşağıdaki tabloda gösterilmektedir.

9. Erişim kontrol listesi (EKL) seçeneklerini belirtme

Google Cloud Search CSV bağlayıcısı, arama sonuçlarındaki CSV dosyasının içeriğine erişimi kontrol etmek için ACL'ler aracılığıyla izinleri destekler. Dizinlenmiş kayıtlara kullanıcı erişimini korumanıza olanak tanıyan birden fazla ACL seçeneği vardır.

Deponuzda her dokümanla ilişkili ayrı EKL bilgileri varsa Cloud Search'te doküman erişimini kontrol etmek için tüm EKL bilgilerini yükleyin. Deponuzda kısmi veya hiç ACL bilgisi yoksa SDK'nın bağlayıcıya sağladığı aşağıdaki parametrelerde varsayılan ACL bilgilerini sağlayabilirsiniz.

Bağlayıcı, yapılandırma dosyasında varsayılan ACL'lerin etkinleştirilmesine bağlıdır. Varsayılan EKL'leri etkinleştirmek için defaultAcl.mode değerini none dışındaki bir moda ayarlayın ve defaultAcl.* ile yapılandırın.

Şema Tanımı

Cloud Search, yapılandırılmış ve yapılandırılmamış içeriklerin dizine eklenmesine ve sunulmasına olanak tanır. Verilerinizde yapılandırılmış veri sorgularını desteklemek için veri kaynağınızın şemasını ayarlamanız gerekir.

Tanımlandıktan sonra CSV bağlayıcı, dizine ekleme istekleri oluşturmak için tanımlanan şemaya başvurabilir. Açıklayıcı bir örnek vermek için filmlerle ilgili bilgileri içeren bir CSV dosyasını ele alalım.

Giriş CSV dosyasının aşağıdaki içeriğe sahip olduğunu varsayalım.

1. movieId
2. movieTitle
3. açıklama
4. yıl
5. releaseDate
6. actors (virgülle (,) ayrılmış birden fazla değer)
7. tür (birden çok değer)
8. değerlendirmeler

Yukarıdaki veri yapısına göre, CSV dosyasındaki verileri dizine eklemek istediğiniz bir veri kaynağının şemasını tanımlayabilirsiniz.

{
  "objectDefinitions": [
    {
      "name": "movie",
      "propertyDefinitions": [
        {
          "name": "actors",
          "isReturnable": true,
          "isRepeatable": true,
          "isFacetable": true,
          "textPropertyOptions": {
            "operatorOptions": {
              "operatorName": "actor"
            }
          }
        },
        {
          "name": "releaseDate",
          "isReturnable": true,
          "isRepeatable": false,
          "isFacetable": false,
          "datePropertyOptions": {
            "operatorOptions": {
              "operatorName": "released",
              "lessThanOperatorName": "releasedbefore",
              "greaterThanOperatorName": "releasedafter"
            }
          }
        },
        {
          "name": "movieTitle",
          "isReturnable": true,
          "isRepeatable": false,
          "isFacetable": false,
          "textPropertyOptions": {
            "retrievalImportance": {
              "importance": "HIGHEST"
            },
            "operatorOptions": {
              "operatorName": "title"
            }
          }
        },
        {
          "name": "genre",
          "isReturnable": true,
          "isRepeatable": true,
          "isFacetable": true,
          "enumPropertyOptions": {
            "operatorOptions": {
              "operatorName": "genre"
            },
            "possibleValues": [
              {
                "stringValue": "Action"
              },
              {
                "stringValue": "Documentary"
              },
              {
                "stringValue": "Drama"
              },
              {
                "stringValue": "Crime"
              },
              {
                "stringValue": "Sci-fi"
              }
            ]
          }
        },
        {
          "name": "userRating",
          "isReturnable": true,
          "isRepeatable": false,
          "isFacetable": true,
          "integerPropertyOptions": {
            "orderedRanking": "ASCENDING",
            "maximumValue": "10",
            "operatorOptions": {
              "operatorName": "score",
              "lessThanOperatorName": "scorebelow",
              "greaterThanOperatorName": "scoreabove"
            }
          }
        }
      ]
    }
  ]
}

Örnek yapılandırma dosyası

Aşağıdaki örnek yapılandırma dosyasında, örnek bir bağlayıcının davranışını tanımlayan key=value parametre çiftleri gösterilmektedir.

# data source access
api.sourceId=1234567890abcd
api.serviceAccountPrivateKeyFile=./PrivateKey.json

# CSV data structure
csv.filePath=./movie_content.csv
csv.csvColumns=movieId,movieTitle,description,releaseYear,genre,actors,ratings,releaseDate
csv.skipHeaderRecord=true
url.format=https://mymoviesite.com/movies/{0}
url.columns=movieId
csv.datetimeFormat.releaseDate=yyyy-mm-dd
csv.multiValueColumns=genre,actors
csv.multiValue.genre=;
contentTemplate.csv.title=movieTitle

# metadata structured data and content
itemMetadata.title.field=movieTitle
itemMetadata.createTime.field=releaseDate
itemMetadata.contentLanguage.defaultValue=en-US
itemMetadata.objectType.defaultValue=movie
contentTemplate.csv.quality.medium=description
contentTemplate.csv.unmappedColumnsMode=IGNORE

#ACLs
defaultAcl.mode=fallback
defaultAcl.public=true

Her parametrenin ayrıntılı açıklaması için Yapılandırma parametreleri referansı başlıklı makaleyi inceleyin.

Cloud Search CSV bağlayıcısını çalıştırma

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

$ java -jar google-cloudsearch-csv-connector-v1-0.0.3.jar -Dconfig=my.config

Bağlayıcı günlükleri varsayılan olarak standart çıkışta kullanılabilir. logging.properties değerini belirterek dosyalara günlük kaydı oluşturabilirsiniz.