데이터베이스 커넥터 배포

경고: Cloud Search 참조 커넥터는 '있는 그대로' 제공됩니다. 샘플 코드로 만드는 데 사용할 수 있습니다. 이 샘플 코드에는 상당한 맞춤설정과 테스트가 이루어져야 하며, 이는 개념 증명 또는 프로덕션 환경에는 적용되지 않습니다 프로덕션 용도로 사용하려면 지원을 받는 것이 좋습니다. Cloud Search 파트너가 제공합니다. 적합한 클라우드 솔루션을 찾는 데 검색 파트너인 경우 Google 계정 관리자에게 문의하세요.

Google Cloud Search를 설정하여 조직의 Google Cloud Search 데이터베이스 커넥터를 사용하여 데이터베이스를 검색할 수 있습니다.

중요 고려사항

커넥터가 두 가지 모두에 액세스할 수 있는 한, Java 앱을 실행할 수 있는 거의 모든 환경에 Cloud Search 데이터베이스 커넥터를 설치하고 실행할 수 있습니다. 데이터베이스입니다.

시스템 요구사항

시스템 요구사항
운영체제 Windows 또는 Linux
SQL Database 다음을 포함하여 JDBC 4.0 이상을 준수하는 드라이버가 있는 모든 SQL 데이터베이스
<ph type="x-smartling-placeholder">
    </ph>
  • MS SQL 서버(2008, 2012, 2014, 2016)
  • Oracle(11g, 12c)
  • Google Cloud SQL
  • MySQL
소프트웨어 커넥터가 데이터베이스에 액세스하는 데 사용할 JDBC 드라이버 (별도 다운로드 및 설치)

커넥터 배포

다음 단계에서는 커넥터를 설치하고 구성하는 방법을 설명합니다. 지정된 데이터베이스의 색인을 생성하고 Cloud Search 사용자에게 결과를 반환합니다.

기본 요건

Cloud Search 데이터베이스 커넥터를 배포하기 전에 다음 정보를 수집하세요.

1단계: 데이터베이스 커넥터 소프트웨어 다운로드 및 빌드

  1. GitHub의 커넥터 저장소를 클론합니다. 
    $ git clone https://github.com/google-cloudsearch/database-connector.git
$ cd database-connector
  2. 원하는 버전의 커넥터를 체크아웃합니다.
    $ git checkout tags/v1-0.0.3
  3. 커넥터를 빌드합니다. 
    $ mvn package
    커넥터를 빌드할 때 테스트를 건너뛰려면 mvn package -DskipTests를 사용합니다.
  4. 커넥터 ZIP 파일을 로컬 설치 디렉터리에 복사하고 압축을 풉니다. 
    $ 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단계: 데이터베이스 커넥터 구성

  1. 텍스트 파일을 만들고 이름을 connector-config.properties (기본값) 또는 유사한 이름으로 지정합니다. Google 추천 .properties 또는 .config 확장자로 파일을 만들고 파일을 커넥터와 동일한 디렉터리에 보관합니다. 다른 이름이나 경로를 사용하는 경우 커넥터를 실행할 때 경로를 지정해야 합니다.
  2. 매개변수를 키-값 쌍으로 파일 콘텐츠에 추가합니다. 구성 파일은 반드시 데이터 소스 액세스, 데이터베이스 액세스, 데이터베이스 전체 순회 SQL 문 콘텐츠 필드 제목, 열 정의가 포함됩니다. 다른 커넥터 동작을 구성할 수도 있습니다. 사용할 수 있습니다. 예를 들면 다음과 같습니다. 
    # 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
    를 통해 개인정보처리방침을 정의할 수 있습니다.

    데이터베이스별 매개변수에 대한 자세한 설명은 구성 매개변수 참조는 이 도움말의 끝부분에 있습니다.

    모든 Cloud Search에 공통된 매개변수에 대해 알아보기 위해 메타데이터 구성, 날짜/시간 형식, ACL 옵션과 같은 커넥터에 대한 자세한 내용은 <ph type="x-smartling-placeholder"></ph> Google 제공 커넥터 매개변수

    해당하는 경우 순회 SQL에서 스키마 객체의 속성을 지정합니다. 쿼리 매개변수를 추가할 수 있습니다. 일반적으로 SQL에 별칭을 추가할 수 있음 구문 예를 들어 '영화'라는 제목의 데이터 소스 스키마에 'ActorName'이 포함된 경우 SQL 문은 SELECT …, last_name AS ActorName, … FROM … 형식을 사용할 수 있습니다.

3단계: 데이터베이스 커넥터 실행

다음 예에서는 Linx 시스템의 로컬 디렉터리에 필수 구성요소가 있다고 가정합니다.

명령줄에서 커넥터를 실행하려면 다음 명령어를 입력하세요. 

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]

각 항목의 의미는 다음과 같습니다.

  • google-cloud-search-database-connector-v1-0.0.3.jar: 데이터베이스 커넥터 .jar 파일
  • mysql-connector-java-5.1.41-bin.jar는 사용 중인 JDBC 드라이버입니다. 데이터베이스 액세스
  • mysql.config는 이름이 지정된 커스텀 구성 파일입니다. 커넥터가 명령줄에서 해당 경로를 지정합니다. 그렇지 않으면 커넥터는 현지의 connector-config.properties 디렉터리를 기본 파일 이름으로 지정합니다.

커넥터는 구성 오류를 감지하면 보고합니다. 일부 오류는 데이터베이스 열이 레코드 콘텐츠의 일부로 정의된 경우 등 커넥터가 초기화됩니다. (db.allColumns에 있음), 그러나 이 열은 다음 열의 순회 SQL 쿼리에 사용되지 않습니다. 데이터베이스 (db.allRecordsSql에 있음) 다른 오류는 다음 경우에만 감지되고 보고됩니다. 커넥터가 잘못된 SQL 문 구문과 같은 첫 번째 순회를 위해 데이터베이스에 액세스하려고 시도합니다.

구성 매개변수 참조 정보

데이터 소스 액세스 매개변수

설정 매개변수
데이터 소스 ID api.sourceId = source-ID

필수 항목입니다. Cloud Search Google Workspace 관리자가 설정한 소스 ID입니다.
ID 소스 ID api.identitySourceId = identity-source-ID

ACL에 외부 사용자 및 그룹을 사용하는 데 필요합니다. Cloud Search Google Workspace 관리자가 설정한 ID 소스 ID입니다.
서비스 계정 api.serviceAccountPrivateKeyFile = path-to-private-key

필수 항목입니다. Cloud Search로 가는 경로 Google Workspace 관리자가 만든 서비스 계정 키 파일입니다.

데이터베이스 액세스 매개변수

설정 매개변수
데이터베이스 URL db.url = database-URL

필수 항목입니다. 이 액세스할 데이터베이스의 전체 경로입니다(예: jdbc:mysql://127.0.0.1/dbname).
데이터베이스 사용자 이름 및 비밀번호 db.user = username
db.password = password

필수항목. 커넥터가 데이터베이스 액세스에 사용하는 유효한 사용자 이름과 비밀번호입니다. 이 데이터베이스 사용자에게는 읽으려는 데이터베이스의 관련 레코드에 대한 읽기 권한이 있어야 합니다.
JDBC 드라이버 db.driverClass = oracle.jdbc.OracleDriver

JDBC 4.0 드라이버를 클래스 경로에 아직 지정하지 않은 경우에만 필수항목입니다.

SQL 쿼리 매개변수 순회

커넥터가 SQL SELECT를 사용하여 데이터베이스 레코드 순회 구성 파일에 있습니다. 전체 순회 쿼리를 구성해야 합니다. 검색어 증분 순회는 선택사항입니다.

전체 순회는 색인 생성을 위해 구성된 모든 데이터베이스 레코드를 읽습니다. Cloud Search에 사용할 새 레코드의 색인을 생성하고 기존 모든 레코드의 색인을 다시 생성하려면 전체 순회를 수행해야 합니다.

증분 순회는 새로 수정된 데이터베이스만 읽고 색인을 재생성함 최신 정보를 데이터베이스에 저장할 수 있습니다. 증분 순회는 전체 순회입니다. 증분 순회를 사용하려면 데이터베이스에 타임스탬프 필드가 있어야 합니다. 를 사용하여 수정된 레코드를 표시합니다.

커넥터는 에서 확인하세요. 순회 일정 매개변수를 사용합니다.

설정 매개변수
전체 순회 쿼리 db.allRecordsSql = SELECT column-1[, column-2,...] FROM database-name

필수 항목입니다. 전체 순회 시마다 쿼리가 실행됩니다.

커넥터가 사용할 모든 열 이름이 용량 (콘텐츠, 고유 ID, ACL)이 있어야 합니다. 커넥터는 오류 및 누락을 감지하기 위해 시작 시 몇 가지 사전 검증을 수행합니다. 이러한 이유로 일반적인 'SELECT * FROM…' 쿼리를 사용할 수 없습니다.
전체 순회 페이지로 나누기 db.allRecordsSql.pagination = {none | offset}

값은 다음과 같습니다.

  • none: 페이지로 나누기를 사용하지 않습니다.
  • offset: 행 오프셋 기준 페이지로 나누기를 사용합니다.

    오프셋별 페이지로 나누기를 사용하려면 SQL 쿼리에 자리표시자 물음표 (?)가 있어야 합니다. 0부터 시작하는 행 오프셋입니다. 각 전체 순회에서 쿼리는 반복적으로 실행됩니다. 결과를 반환할 수 없습니다.
증분 순회 쿼리 db.incrementalUpdateSql = SELECT column-1[, column-2,...] FROM database-name WHERE last_update_time > ?

증분 순회를 예약할 때 필요합니다.

'?' 문자는 타임스탬프 값의 필수 자리표시자입니다. 이 커넥터는 타임스탬프를 사용하여 증분 순회 SQL 쿼리 간의 수정사항을 추적합니다.

데이터베이스 타임스탬프 열에서 마지막 업데이트 시간을 추적하려면 SQL 문에 대한 timestamp_column 별칭 그렇지 않은 경우 있습니다.

첫 번째 증분 순회에서는 커넥터의 시작 시간이 사용됩니다. 그런 다음 첫 번째 증분 순회를 수행하면 Cloud Search는 타임스탬프를 저장하므로 커넥터가 다시 시작되면 이전 증분 순회에 액세스할 수 있음 타임스탬프
데이터베이스 시간대 db.timestamp.timezone = America/Los_Angeles

데이터베이스 타임스탬프에 사용할 시간대를 지정합니다. 새 레코드 추가 또는 새로 추가된 레코드를 식별하는 데 사용되는 데이터베이스 타임스탬프입니다. 데이터베이스 레코드를 수정합니다. 기본값은 커넥터가 실행 중인 현지 시간대입니다.

순회 SQL 쿼리 예

  • 색인 생성을 위해 직원 데이터베이스에서 관심 있는 모든 레코드를 읽는 기본 전체 순회 쿼리입니다. 
    db.allRecordsSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field \
    FROM employee
  • 오프셋별로 페이지로 나누기를 지정하고 전체 순회를 여러 쿼리로 나눕니다.

    SQL Server 2012 또는 Oracle 12c (표준 SQL 2008 구문):

    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

    또는 MySQL 또는 Google Cloud SQL의 경우:

    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
  • 별칭이 있는 개별 ACL을 적용하는 전체 순회 쿼리입니다. 
    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
  • 기본 증분 순회 쿼리: 
    db.incrementalUpdateSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field, last_update_time \
     FROM employee \
     WHERE last_update_time > ?
  • 별칭이 있는 개별 ACL을 적용하는 증분 순회 쿼리입니다. 
    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 > ?
  • 현재 시간이 아닌 데이터베이스 타임스탬프를 사용하는 증분 순회 쿼리입니다. 
    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 > ?

열 정의 매개변수

다음 매개변수는 순회 문에서 사용하는 열과 각 레코드를 고유하게 식별합니다.

설정 매개변수
모든 열 db.allColumns = column-1, column-2, ...column-N

필수항목. 데이터베이스에 액세스할 때 SQL 쿼리에 필요한 모든 열을 식별합니다. 이 매개변수에 정의된 열을 쿼리에서 명시적으로 참조해야 합니다. 매회 다른 열 정의 매개변수를 이 열 집합과 비교합니다.

예:

db.allColumns = customer_id, first_name, last_name, phone, change_timestamp
고유 키 열 db.uniqueKeyColumns = column-1[, column-2]

필수 항목입니다. 다음 중 하나를 나열 고유한 값을 포함하거나 값이 함께 고유 ID를 정의하는 열입니다.

Cloud Search를 사용하려면 데이터 소스에 있는 검색 가능한 모든 문서에 고유 식별자가 있어야 합니다. 각 데이터베이스 레코드에 고유 ID를 정의할 수 있어야 합니다. 추출해야 합니다. 별도의 데이터베이스에서 여러 커넥터를 실행하지만 색인 생성 시 고유한 ID를 지정해야 합니다. 모든 문서를 검토합니다.

예:

db.uniqueKeyColumns = customer_id
# or
db.uniqueKeyColumns = last_name, first_name
URL 링크 열 url.columns = column-1[, column-2]

필수 항목입니다. 하나 이상의 유효하고 정의됨 클릭 가능한 검색결과에 사용되는 URL에 사용되는 열의 이름입니다. 데이터베이스에 각 데이터베이스 레코드와 연결된 관련 URL이 없으면 정적 링크를 모든 레코드에 사용할 수 있습니다.

그러나 열 값이 각 레코드에 유효한 링크를 정의하는 경우, 뷰 URL 열과 형식 구성 값을 지정해야 합니다.
URL 형식 url.format = https://www.example.com/{0}

뷰 URL 형식을 정의합니다. 번호가 매겨진 매개변수는 db.columns에 지정된 열(0부터 시작)을 순서대로 참조합니다.

지정되지 않은 경우 기본값은 '{0}'입니다.

아래 표에 예시가 나와 있습니다.
URL의 퍼센트 인코딩 열 url.columnsToEscape = column-1[, column-2]

값을 형식이 지정된 URL 문자열에 포함하기 전에 백분율로 인코딩할 값이 있는 db.columns에서 열을 지정합니다.

URL 열 예시

순회 쿼리에 사용되는 열과 뷰 URL 형식을 지정하려면 다음 안내를 따르세요.

  • 데이터베이스 레코드 값을 사용하지 않는 정적 URL을 사용하려면 다음 안내를 따르세요. 
    url.format = https://www.example.com
  • 단일 열 값, 즉 보기 URL을 사용하는 방법은 다음과 같습니다. 
    url.format = {0}
url.columns = customer_id
  • 위치 {0}에서 보기 URL로 대체되는 단일 열 값을 사용하려면 다음을 실행합니다. 
    url.format = https://www.example.com/customer/id={0}
url.columns = customer_id
url.columnsToEscape = customer_id
  • 여러 열 값을 사용하여 보기 URL을 작성하는 방법은 다음과 같습니다 (열은 순서에 따라 다름). 
    url.format = {1}/customer={0}
url.columns = customer_id, linked_url
url.columnsToEscape = customer_id

콘텐츠 필드

다음 콘텐츠 옵션을 사용하면 검색 가능한 콘텐츠에 포함시킬 레코드 값을 정의할 수 있습니다.

설정 매개변수
최고 품질의 검색 열 contentTemplate.db.title = column-name

필수 항목입니다. 검색 색인 생성 및 결과 우선순위 지정을 위한 최고 품질의 열입니다.
검색을 위한 열 우선순위 지정 contentTemplate.db.quality.high = column-1[, column-2...]
contentTemplate.db.quality.medium = column-1[, column-2...]
contentTemplate.db.quality.low = column-1[, column-2...]

콘텐츠 열 지정 (contentTemplate.db.title 열 조합 제외) 높은 검색 품질, 중간 검색 품질, 낮은 검색 품질 필드로 구분됩니다. 지정되지 않은 열은 기본적으로 낮음으로 설정됩니다.
콘텐츠 데이터 열 db.contentColumns = column-1[, column-2...]

데이터베이스의 콘텐츠 열을 지정합니다. 이들은 포맷되고 검색 가능한 문서 콘텐츠로 업로드됩니다.

값을 지정하지 않으면 기본값 '*'가 사용됩니다. 이 기본값은 모든 열이 콘텐츠에 사용되어야 함을 나타냅니다.
Blob 열 db.blobColumn = column-name

단일 blob의 이름 지정 열 조합 대신 문서 콘텐츠에 사용할 열을 만듭니다.

Blob 열을 지정한 경우, 콘텐츠 열도 정의하면 Blob 열이 오류로 간주됩니다. 그러나 메타데이터 및 구조화된 데이터 열 정의는 여전히 Blob 열과 함께 허용됩니다.