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

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

Bu kılavuzda aşağıdaki temel görevlerle ilgili talimatlar yer almaktadır:

  • Cloud Search CSV bağlayıcı yazılımını indirin.
  • Bağlayıcıyı belirli bir CSV veri kaynağı için yapılandırın.
  • Bağlayıcıyı dağıtın ve çalıştırın.

Bu belgedeki kavramları anlamak için Google Workspace, CSV dosyaları ve Erişim Kontrol Listeleri (EKL'ler) hakkında bilgi sahibi olmanız gerekir.

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ı, her satırın bir veri kaydı olduğu tablo verilerini depolar.

Bağlayıcı, bir CSV dosyasından satırları ayıklar ve dizine ekleme API'sini kullanarak bunları Cloud Search'te dizine ekler. Dizine eklendikten sonra satırlar, Cloud Search istemcileri veya Query API aracılığıyla aranabilir. Bağlayıcı, kullanıcının içeriğe erişimini kontrol etmek için ACL'leri de destekler.

Bağlayıcıyı Linux veya Windows'a yükleyebilirsiniz. Dağıtımdan önce aşağıdaki bileşenlere sahip olduğunuzdan emin olun:

Genellikle, alanın Google Workspace yöneticisi bu kimlik bilgilerini sağlar.

Dağıtım adımları

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

  1. Bağlayıcı yazılımını yükleme
  2. Bağlayıcı yapılandırmasını belirtme
  3. Cloud Search veri kaynağına erişimi yapılandırma
  4. CSV dosyası erişimini yapılandırma
  5. Sütun adlarını, benzersiz anahtarları ve tarih/saat sütunlarını belirtin
  6. Tıklanabilir arama sonucu URL'leri için sütun belirtme
  7. Meta verileri ve sütun biçimlerini belirtme
  8. Veri geçişini planlama
  9. 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. Seçtiğiniz sürümü inceleyin: 

    $ git checkout tags/v1-0.0.3

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

    $ mvn package

  4. Bağlayıcıyı çıkarıp yükleyin: 

    $ 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ının davranışını, yapılandırma dosyasındaki parametreler aracılığıyla kontrol edersiniz. Yapılandırılabilir parametreler şunlardır:

  • Veri kaynağı erişimi.
  • CSV dosyasının konumu ve tanımları.
  • Benzersiz kimlik sütunları.
  • Geçiş ve EKL seçenekleri.

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

  1. Bir metin düzenleyici açın ve dosyayı connector-config.properties olarak adlandırın.
  2. Yapılandırma parametrelerini key=value çiftleri olarak ekleyin. Her çift yeni bir satırda olmalıdır. Yapılandırma dosyası örneği için Örnek yapılandırma dosyası başlıklı makaleye bakın.

İzlemeyi basitleştirmek için yapılandırma dosyasını bağlayıcıyla aynı dizinde tutun. Bağlayıcının dosyanızı tanıdığından emin olmak için komut satırında dosyanızın yolunu belirtin. Aksi takdirde, bağlayıcı yerel dizininizde varsayılan olarak connector-config.properties olur. Bağlayıcıyı çalıştırma başlıklı makaleyi inceleyin.

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

Yapılandırma dosyasında, Cloud Search veri kaynağına erişmek için parametreler belirtilmelidir. Veri kaynağı kimliği, hizmet hesabı kimliği ve hizmet hesabının özel anahtar dosyasının yolu gerekir.

Ayar Parametre
Veri kaynağı kimliği api.sourceId=1234567890abcdef

Zorunlu. Google Workspace yöneticisi tarafından ayarlanan Cloud Search kaynak kimliği.
Hizmet hesabı özel anahtarının yolu api.serviceAccountPrivateKeyFile=./PrivateKey.json

Zorunlu. Bağlayıcı erişimi için hizmet hesabı anahtar dosyası.
Kimlik kaynağı kimliği api.identitySourceId=x0987654321

Harici kullanıcılar ve gruplar kullanılıyorsa gereklidir. Google Workspace yöneticisi tarafından ayarlanan kimlik kaynağı kimliği.

4. CSV dosyası parametrelerini yapılandırma

Dosyanın yolunu, biçimini ve kodlamasını belirleyin.

Ayar Parametre
CSV dosyasının yolu csv.filePath=./movie_content.csv

Zorunlu. Dizin oluşturma için dosyanın yolu.
Dosya biçimi csv.format=DEFAULT

Dosyanın biçimi. Olası değerler, Apache Commons CSV CSVFormat sınıfından alınmıştır.

Biçim değerleri şunlardır: DEFAULT, EXCEL, INFORMIX_UNLOAD, INFORMIX_UNLOAD_CSV, MYSQL, RFC4180, ORACLE, POSTGRESQL_CSV, POSTGRESQL_TEXT ve TDF. Belirtilmezse Cloud Search, DEFAULT kullanır.
Dosya biçimi değiştiricisi csv.format.withMethod=value

Cloud Search'ün dosyayı işleme şekliyle ilgili bir değişiklik yapılması. Olası yöntemler, Apache Commons CSV CSVFormat sınıfından alınır ve tek karakter, dize veya boole değeri alan yöntemleri içerir.

Örneğin, sınırlayıcı olarak noktalı virgül belirtmek için csv.format.withDelimiter=; kullanın. Boş satırları yoksaymak için csv.format.withIgnoreEmptyLines=true kullanın.
Dosya kodlama türü csv.fileEncoding=UTF-8

Kullanılacak Java karakter kümesi. Varsayılan olarak platform karakter kümesi kullanılır.

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

Yapılandırma dosyasında sütun bilgilerini sağlayın.

Ayar Parametre
Dizine eklenecek sütunlar csv.csvColumns=movieId,movieTitle,description,actors,releaseDate,year,userratings...

CSV dosyasından dizine eklenecek sütun adları. Varsayılan olarak, CSV'nin ilk satırı başlık olarak kullanılır. csv.csvColumns belirtilirse öncelikli olur. csv.csvColumns ayarlandığında ve ilk satırda başlıklar bulunduğunda ilk satırın veri olarak dizine eklenmesini önlemek için csv.skipHeaderRecord=true ayarını da yapın.
Benzersiz anahtar sütunları csv.uniqueKeyColumns=movieId

Benzersiz bir kimlik oluşturmak için kullanılan sütunlar. Varsayılan olarak kaydın karma kodu kullanılır.

6. Tıklanabilir arama sonucu URL'leri için sütunları belirtme

Arama sonuçları için tıklanabilir URL'leri etkinleştirin.

Ayar Parametre
Arama sonucu URL biçimi url.format=https://mymoviesite.com/movies/{0}

Zorunlu. Görünüm URL'sini oluşturmak için kullanılan biçim.
URL parametreleri url.columns=movieId

Zorunlu. Değerleri, kaydın görüntüleme URL'sini oluşturmak için kullanılacak CSV sütun adları.
Arama sonuçları URL'sinde çıkış karakteri uygulanacak parametreler url.columnsToEscape=movieId

İsteğe bağlı. Geçerli görünüm URL'si oluşturmak için değerleri URL'den kaçırılacak CSV sütun adları.

7. Meta verileri, sütun biçimlerini ve arama kalitesini belirtme

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

Meta veri yapılandırma parametreleri

Bu parametreler, öğe meta verilerini doldurmak için kullanılan sütunları açıklar.

Ayar Parametre
Başlık itemMetadata.title.field=movieTitle
itemMetadata.title.defaultValue=Gone with the Wind

Doküman başlığı için meta veri özelliği. Varsayılan değer boş bir dizedir.
URL itemMetadata.sourceRepositoryUrl.field=url
itemMetadata.sourceRepositoryUrl.defaultValue=https://www.imdb.com/title/tt0031381/
Arama sonuçlarındaki doküman URL'si için meta veri özelliği.
Oluşturma zaman damgası itemMetadata.createTime.field=releaseDate
itemMetadata.createTime.defaultValue=1940-01-17

Doküman oluşturma zaman damgası için meta veri özelliği.
Son değiştirilme zamanı itemMetadata.updateTime.field=releaseDate
itemMetadata.updateTime.defaultValue=1940-01-17

Dokümanın son değiştirme zaman damgası için meta veri özelliği.
Belge dili itemMetadata.contentLanguage.field=languageCode
itemMetadata.contentLanguage.defaultValue=en-US

Dizin oluşturulan dokümanların içerik dili.
Şema nesne türü itemMetadata.objectType.field=type
itemMetadata.objectType.defaultValue=movie

Şemada tanımlandığı şekilde, bağlayıcı tarafından kullanılan nesne türü. Bu mülk belirtilmezse bağlayıcı, yapılandırılmış verileri dizine eklemez.
Tarih ve saat biçimleri

Bu parametre, dize değerlerinin tarih veya tarih-saat alanlarına ayrıştırılması için ek tarih ve saat biçimleri belirtir.

Ayar Parametre
Ek tarih/saat biçimleri structuredData.dateTimePatterns=MM/dd/uuuu HH:mm:ssXXX
Ek noktalı virgülle ayrılmış java.time.format.DateTimeFormatter kalıpların listesi. Bu kalıplar, meta verilerdeki veya şemadaki tarih ya da tarih-saat alanları için dize değerleri ayrıştırılırken kullanılır. Varsayılan değer boş bir listedir ancak RFC 3339 ve RFC 1123 biçimleri her zaman desteklenir.

Sütun biçimleri

Bu parametreler, CSV dosyasındaki sütunların nasıl ayrıştırılacağını belirtir.

Ayar Parametre
Üstbilgiyi atla csv.skipHeaderRecord=true

İlk satırı yoksayın. Varsayılan değer false'tur.
Çok değerli sütunlar csv.multiValueColumns=genre,actors

Birden fazla değer içeren sütun adları.
Çok değerli sütunlar için sınırlayıcı csv.multiValue.genre=;

Çok değerli sütunlar için sınırlayıcı. Varsayılan sınırlayıcı virgüldür.

Arama kalitesi

Bağlayıcı, kayıtları biçimlendirmek için bir içerik şablonu kullanır. Başlık alanı en yüksek önceliğe sahiptir. Diğer alanlara öncelik düzeyleri (yüksek, orta, düşük) atayabilirsiniz.

Ayar Parametre
İçerik başlığı contentTemplate.csv.title=movieTitle

İçerik başlığı, en yüksek arama kalitesine sahip alandır.
İçerik alanları için yüksek arama kalitesi contentTemplate.csv.quality.high=actors

Yüksek arama kalitesi değeri verilen içerik alanları. Varsayılan değer boş bir dizedir.
İçerik alanları için düşük arama kalitesi contentTemplate.csv.quality.low=genre

İçerik alanlarına düşük arama kalitesi değeri verilmesi. Varsayılan değer boş bir dizedir.
İçerik alanları için orta düzeyde arama kalitesi contentTemplate.csv.quality.medium=description

İçerik alanlarına orta düzeyde arama kalitesi değeri verilmiş. Varsayılan değer boş bir dizedir.
Belirtilmemiş içerik alanları contentTemplate.csv.unmappedColumnsMode=IGNORE

Bağlayıcının, belirtilmemiş içerik alanlarını nasıl işlediği. Geçerli değerler şunlardır:

  • APPEND: Belirtilmemiş içerik alanlarını şablona ekler.
  • IGNORE: Belirtilmemiş içerik alanlarını yoksay.

Varsayılan değer APPEND'dir.

8. Veri geçişini planlama

Geçiş, içeriği keşfetme sürecidir. Bağlayıcı, CSV satırlarını tarar ve Dizine Ekleme API'sini kullanarak bunları dizine ekler. CSV bağlayıcısı yalnızca tam geçişler gerçekleştirir.

Ayar Parametre
Geçiş aralığı schedule.traversalIntervalSecs=7200

Tam geçişler arasındaki aralık (saniye). Varsayılan değer 86400'dür (bir gün).
Başlangıçta geçiş schedule.performTraversalOnStart=false

Bağlayıcı, ilk aralığın süresinin dolmasını beklemek yerine bağlayıcı başlatıldığında geçiş gerçekleştirir. Varsayılan değer: true.

9. EKL seçeneklerini belirtme

Bağlayıcı, erişimi kontrol etmek için EKL'leri kullanır. Deponuzda ACL'ler varsa bunları yükleyin. Aksi takdirde, varsayılan ACL'leri yapılandırın. defaultAcl.mode öğesini none dışında bir değere ayarlayın.

Ayar Parametre
EKL modu defaultAcl.mode=fallback

Zorunlu. Bağlayıcı yalnızca yedek modu destekler.
Varsayılan EKL adı defaultAcl.name=VIRTUAL_CONTAINER_FOR_CONNECTOR_1

İsteğe bağlı. Bağlayıcı tarafından varsayılan ACL'ler için kullanılan sanal kapsayıcı adını geçersiz kılar. Varsayılan değer: DEFAULT_ACL_VIRTUAL_CONTAINER. Aynı veri kaynağındaki içerikleri birden fazla bağlayıcı dizine ekliyorsa bu ayarı geçersiz kılmayı düşünebilirsiniz.
Varsayılan genel EKL defaultAcl.public=true

Deponun tamamını kamuya açık erişime ayarlar. Varsayılan değer false'tur.
Ortak EKL grubu okuyucuları defaultAcl.readers.groups=google:group1, group2
Yaygın EKL okuyucuları defaultAcl.readers.users=user1, user2, google:user3
Ortak EKL, grup okuyucularını reddetti defaultAcl.denied.groups=group3
Yaygın olarak ACL'nin okuyuculara erişimi reddetmesinin nedenleri defaultAcl.denied.users=user4, user5
Alanın tamamına erişim Dizine eklenen her kaydın alandaki her kullanıcı tarafından herkese açık olarak erişilebileceğini belirtmek için aşağıdaki seçeneklerin her ikisini de değerlerle ayarlayın:
  • defaultAcl.mode=fallback
  • defaultAcl.public=true
Ortak tanımlanmış EKL Her kayıt için ortak bir ACL tanımlamak üzere aşağıdaki parametreleri ayarlayın:
  • defaultAcl.mode=fallback
  • defaultAcl.public=false
  • defaultAcl.readers.groups=google:group1, group2
  • defaultAcl.readers.users=user1, user2, google:user3
  • defaultAcl.denied.groups=group3
  • defaultAcl.denied.users=user4, user5

Kullanıcılar ve grupların önüne "google:" eklenmediği sürece yerel alan tanımlı olduğu varsayılır.

Varsayılan kullanıcı veya grup boş bir dizedir. Yalnızca defaultAcl.public değeri false ise kullanıcı ve grup seçeneklerini sağlayın. Birden fazla grup ve kullanıcı için virgülle ayrılmış liste kullanın.

defaultAcl.mode none ise kayıtlar ayrı erişim kontrol listeleri olmadan aranamaz.

Şema tanımı

Yapılandırılmış veri sorgularını desteklemek için veri kaynağınızda şema oluşturun.

Örneğin, filmlerle ilgili aşağıdaki bilgileri içeren bir CSV dosyasını ele alalı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

Bu yapıya göre, veri kaynağınız için aşağıdaki ş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 parametre 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

Bağlayıcıyı çalıştırma

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

$ 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 kaydedebilirsiniz.