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

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

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

• Google Cloud Search CSV bağlayıcı yazılımını indirme
• Bağlayıcıyı belirli bir CSV veri kaynağıyla kullanmak için 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 denetimi listeleri (ACL'ler) ile ilgili temel bilgilere sahip olmanız 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) içeren tüm metin dosyalarıyla çalışır. CSV dosyası tablo biçimindeki verileri depolar ve dosyanın her satırı bir veri kaydı olur.

Google Cloud Search'in CSV Bağlayıcısı, bir CSV dosyasından tek tek satırları ayıklayıp Cloud Search'in dizine ekleme API'si aracılığıyla Cloud Search'te dizine ekler. Başarıyla dizine eklendikten sonra CSV dosyalarındaki satırları Cloud Search istemcileri veya Cloud Search Query API üzerinden arayabilirsiniz. CSV bağlayıcısı, 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ı çalıştıran bir bilgisayarda Java JRE 1.8 yüklü olmalıdır.

• Google Cloud Search ile veri kaynağı arasında ilişki oluşturmak 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. Dizine eklenecek 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 taramasını 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 kopyalayı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ı belirtme

Bağlayıcı yöneticisi olarak, CSV bağlayıcısının davranışını ve bağlayıcının yapılandırma dosyasında parametreleri tanımlayan özelliklerini siz 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 kimliği tanımlayan sütunlar
• Geçiş seçenekleri
• Veri erişimini kısıtlamak için ACL seçenekleri

Bağlantıcının bir CSV dosyasına düzgün şekilde erişmesi ve 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. İstediğiniz bir metin düzenleyiciyi açıp yapılandırma dosyasını adlandırın.
   Aşağıdaki bölümlerde açıklandığı şekilde dosya içeriğine anahtar=değer çiftleri ekleyin.
2. Yapılandırma dosyasını kaydedip adlandırın.
   Bağlayıcıyı çalıştırmak için ek komut satırı parametresi gerekmemesi amacıyla Google, yapılandırma dosyasını connector-config.properties olarak adlandırmanızı önerir.

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

Bağlantıyı sağlayan aracının yapılandırma dosyanızı tanıması için komut satırında dosya yolunu belirtin. Aksi takdirde, bağlayıcı varsayılan dosya adı olarak yerel dizininizdeki connector-config.properties dosyasını kullanır. Komut satırında yapılandırma yolunu belirtme hakkında bilgi edinmek 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 gerekenlerdir. Bağlantıcının Cloud Search'a erişimini yapılandırmak için genellikle veri kaynağı kimliği, hizmet hesabı kimliği ve hizmet hesabının özel anahtar dosyasının yoluna ihtiyacınız vardır. Veri kaynağı oluşturmak için gereken adımlar Üçüncü taraf veri kaynaklarını yönetme başlıklı makalede açıklanmıştır.

4. CSV dosyası parametrelerini yapılandırma

Bağlayıcının bir CSV dosyasını tarayabilmesi ve dizine ekleme için dosyasındaki verileri ayıklayabilmesi için dosyanın yolunu tanımlamanız gerekir. Dosya biçimini ve dosya kodlamasının türünü de belirtebilirsiniz. Yapılandırma dosyasında CSV dosyası özelliklerini belirtmek için aşağıdaki parametreleri ekleyin.

5. Dizine eklenecek sütun adlarını ve benzersiz anahtar sütunlarını belirtin

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

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

Kullanıcı Google Cloud Search'ı kullanarak arama yaptığında, her bir sonucun tıklanabilir URL'lerini içeren bir sonuç sayfası gösterilir. 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, arama kalitesini belirtin

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

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

Meta Veri Yapılandırma Parametreleri

Meta Veri Yapılandırması 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ının yürütülmesinin başında veri alanlarını tanımlar ve ardından her veri kaydını Cloud Search'a yüklemeden önce biçimlendirmek için bir içerik şablonu kullanır.

İçerik şablonu, arama için her bir 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 olarak 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. Verileri incelemeyi planlama

Gezinme, bağlayıcının veri kaynağından (bu durumda bir CSV dosyası) içerik keşfetme işlemidir. CSV bağlayıcısı çalışırken CSV dosyasının satırlarını tarar ve her bir satırı dizine ekleme API'si aracılığıyla Cloud Search'e dizine ekler.

Tam tarama, dosyadaki tüm sütunları dizine ekler. Artımlı tarama yalnızca önceki taramadan bu yana eklenen veya değiştirilen sütunları dizine ekler. 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 beklediğ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. Kullanıcıların dizine eklenen kayıtlara 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'ta doküman erişimini kontrol etmek için tüm EKL bilgilerini yükleyin. Deponuzdan kısmi ACL bilgileri sağlanıyorsa veya hiç ACL bilgisi sağlanmıyorsa 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ştirilmesini kullanır. Varsayılan EKL'leri etkinleştirmek için defaultAcl.mode'ü none dışında 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çeriğin dizine eklenmesine ve yayınlanmasına olanak tanır. Verilerinizde yapılandırılmış veri sorgularını desteklemek için veri kaynağınız için şemayı ayarlamanız gerekir.

CSV Bağlayıcı, tanımlandıktan sonra dizine ekleme istekleri oluşturmak için tanımlanmış şemaya başvurabilir. Açıklayıcı bir örnek vermek için filmlerle ilgili bilgiler 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. oyuncular (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ından verileri dizine eklemek istediğiniz veri kaynağı için şemayı 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 ç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çıklamaları için Yapılandırma parametreleri referansına bakın.

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

Bağlantı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ı ekleyebilirsiniz.