이 가이드는 Google Cloud Search CSV(쉼표로 구분된 값) 커넥터 관리자(커넥터를 다운로드, 구성, 실행, 모니터링할 책임이 있는 모든 사용자)를 대상으로 합니다.
이 가이드에서는 CSV 커넥터 배포와 관련된 주요 태스크를 수행하는 방법을 설명합니다.
- Google Cloud Search CSV 커넥터 소프트웨어 다운로드
- 특정 CSV 데이터 소스를 사용하도록 커넥터 구성
- 커넥터 배포 및 실행
이 문서의 개념을 이해하려면 Google Workspace, CSV 파일, 액세스 제어 목록 (ACL)의 기본사항을 잘 알고 있어야 합니다.
Google Cloud Search CSV 커넥터 개요
Cloud Search CSV 커넥터는 모든 쉼표로 구분된 값 (CSV) 텍스트 파일과 연동합니다. CSV 파일은 표 형식 데이터를 저장하며, 파일의 각 줄은 하나의 데이터 레코드입니다.
Google Cloud Search의 CSV 커넥터는 CSV 파일에서 개별 행을 추출하고 Cloud Search의 Indexing API를 통해 Cloud Search에 행의 색인을 생성합니다. 색인 생성에 성공하면 Cloud Search의 클라이언트 또는 Cloud Search의 Query API를 통해 CSV 파일의 개별 행을 검색할 수 있습니다. 또한 CSV 커넥터는 ACL을 사용하여 검색결과의 내용에 대한 사용자 액세스를 제어하는 기능을 지원합니다.
Linux 또는 Windows에 Google Cloud Search CSV 커넥터를 설치할 수 있습니다. Google Cloud Search CSV 커넥터를 배포하기 전에 다음과 같은 필수 구성요소가 있는지 확인하세요.
- Google Cloud Search CSV 커넥터를 실행하는 컴퓨터에 자바 JRE 1.8 설치
Google Cloud Search와 데이터 소스 간의 관계를 설정하는 데 필요한 Google Workspace 정보:
- Google Workspace 비공개 키(서비스 계정 ID 포함)
- Google Workspace 데이터 소스 ID
일반적으로 도메인의 Google Workspace 관리자가 이러한 사용자 인증 정보를 제공할 수 있습니다.
배포 단계
Google Cloud Search CSV 커넥터를 배포하려면 다음 단계를 따르세요.
- Google Cloud Search CSV 커넥터 소프트웨어 설치
- CSV 커넥터 구성 지정
- Google Cloud Search 데이터 소스에 대한 액세스 구성
- CSV 파일 액세스 구성하기
- 색인을 생성할 열 이름, 고유 키 열, 날짜/시간 열 지정
- 클릭 가능한 검색 결과 URL에 사용할 열 지정
- 메타데이터 정보, 열 형식 지정
- 데이터 순회 예약
- 액세스 제어 목록 (ACL) 옵션 지정
1. SDK 설치
SDK를 로컬 Maven 저장소에 설치합니다.
GitHub의 SDK 저장소를 클론합니다.
$ git clone https://github.com/google-cloudsearch/connector-sdk.git $ cd connector-sdk/csv
원하는 버전의 SDK를 체크아웃합니다.
$ git checkout tags/v1-0.0.3
커넥터를 빌드합니다.
$ mvn package
커넥터 zip 파일을 로컬 설치 디렉터리에 복사합니다.
$ 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 커넥터 구성 지정
커넥터 관리자는 커넥터 구성 파일의 매개변수를 정의하여 CSV 커넥터의 동작과 속성을 제어합니다. 구성 가능한 매개변수의 예는 다음과 같습니다.
- 데이터 소스에 대한 액세스
- CSV 파일의 위치
- CSV 열 정의
- 고유 ID를 정의하는 열
- 순회 옵션
- 데이터 액세스를 제한하는 ACL 옵션
커넥터가 CSV 파일에 올바르게 액세스하고 관련 콘텐츠의 색인을 생성하려면 먼저 구성 파일을 만들어야 합니다.
구성 파일을 만드는 방법은 다음과 같습니다.
- 원하는 텍스트 편집기를 열고 구성 파일 이름을 지정합니다.
다음 섹션의 설명에 따라 파일 콘텐츠에 키=값 쌍을 추가합니다. - 구성 파일을 저장하고 이름을 지정합니다.
커넥터를 실행하는 데 명령줄 매개변수가 추가로 필요하지 않도록 구성 파일의 이름을connector-config.properties로 지정하는 것이 좋습니다.
구성 파일 경로를 명령줄에서 지정할 수 있으므로 표준 파일 위치는 필요하지 않습니다. 그러나 커넥터를 쉽게 추적하고 실행할 수 있도록 구성 파일을 커넥터와 같은 디렉토리에 두시기 바랍니다.
커넥터가 구성 파일을 인식할 수 있도록 명령줄에서 경로를 지정합니다. 그렇지 않으면 커넥터는 로컬 디렉터리의 connector-config.properties를 기본 파일 이름으로 사용합니다. 명령줄에서 구성 경로를 지정하는 방법은 Cloud Search CSV 커넥터 실행을 참고하세요.
3. Google Cloud Search 데이터 소스에 대한 액세스 구성
다음 표에서와 같이 모든 구성 파일은 Cloud Search 데이터 소스에 액세스하는 데 필요한 매개변수를 첫 번째로 지정해야 합니다. 일반적으로 커넥터의 Cloud Search 액세스를 구성하려면 데이터 소스 ID, 서비스 계정 ID, 서비스 계정의 비공개 키 파일 경로가 필요합니다. 데이터 소스를 설정하는 데 필요한 단계는 타사 데이터 소스 관리에서 설명합니다.
| 설정 | 매개변수 |
| 데이터 소스 ID | api.sourceId=1234567890abcdef
필수 항목입니다. 타사 데이터 소스 관리에 설명된 대로 Google Workspace 관리자가 설정한 Google Cloud Search 소스 ID입니다. |
| 서비스 계정 비공개 키 파일의 경로 | api.serviceAccountPrivateKeyFile=./PrivateKey.json
필수. Google Cloud Search 파일 시스템 커넥터 액세스용 Google Cloud Search 서비스 계정 키 파일입니다. |
| ID 소스 ID | api.identitySourceId=x0987654321
외부 사용자 및 그룹을 사용하는 경우 필수. Google Workspace 관리자가 설정한 Google Cloud Search ID 소스 ID입니다. |
4. CSV 파일 매개변수 구성
커넥터가 CSV 파일을 순회하면서 색인 생성을 위해 데이터를 추출하려면 먼저 파일의 경로를 식별해야 합니다. 파일 형식과 파일 인코딩 유형을 지정할 수도 있습니다. 구성 파일에 CSV 파일 속성을 지정하려면 다음 매개변수를 추가합니다.
| 설정 | 매개변수 |
| CSV 파일의 경로 | csv.filePath=./movie_content.csv
필수. 색인 생성을 위해 액세스하여 내용을 추출할 CSV 파일의 경로입니다. |
| 파일 형식 | csv.format=DEFAULT
파일의 형식입니다. 가능한 값은 Apache Commons CSV CSVFormat 클래스의 값입니다. 형식 값에는 |
| 파일 형식 한정자 | csv.format.withMethod=value
Cloud Search 파일 처리 방법의 수정입니다. 가능한 메서드는 Apache Commons CSV CSVFormat 클래스의 메서드이며 단일 문자, 문자열, 부울 값을 취하는 메서드가 포함됩니다. 예를 들어 세미콜론을 구분 기호로 지정하려면 |
| 파일 인코딩 유형 | csv.fileEncoding=UTF-8
Cloud Search에서 파일을 읽을 때 사용할 자바 문자 집합입니다. 지정하지 않으면 Cloud Search는 플랫폼 기본 문자 집합을 사용합니다. |
5. 색인을 생성할 열 이름과 고유 키 열 지정
커넥터가 CSV 파일에 액세스하고 색인을 생성할 수 있도록 하려면 구성 파일에 열 정의 정보를 제공해야 합니다. 구성 파일에 색인을 생성할 열 이름, 고유 키 열을 지정하는 매개변수가 없으면 기본값이 사용됩니다.
| 설정 | 매개변수 |
| 색인을 생성할 열 | csv.csvColumns=movieId,movieTitle,description,actors,releaseDate,year,userratings...
CSV 파일에서 색인을 생성할 열 이름입니다. |
| 고유 키 열 | csv.uniqueKeyColumns=movieId
각 레코드의 고유 ID를 생성하는 데 사용할 값을 갖는 CSV 열입니다. 지정하지 않으면 CSV 레코드의 해시가 고유 키로 사용됩니다. 기본값은 레코드의 해시코드입니다. |
6. 클릭 가능한 검색결과 URL에 사용할 열 지정
사용자가 Google Cloud Search로 검색하면 각 결과의 클릭 가능한 URL이 포함된 결과 페이지가 표시됩니다. 이 기능을 사용 설정하려면 다음 표의 매개변수를 구성 파일에 추가해야 합니다.
| 설정 | 매개변수 |
| 검색결과 URL 형식 | url.format=https://mymoviesite.com/movies/{0}
필수. CSV 콘텐츠의 뷰 URL을 생성할 형식입니다. |
| 검색결과 URL 매개변수 | url.columns=movieId
필수. 레코드의 뷰 URL을 생성하는 데 사용할 값을 갖는 CSV 열 이름입니다. |
| 이스케이프할 검색결과 URL 매개변수 | url.columnsToEscape=movieId
선택사항. URL로 이스케이프하여 유효한 뷰 URL을 생성할 값을 갖는 CSV 열 이름입니다. |
7. 메타데이터 정보, 열 형식, 검색 품질 지정
구성 파일에 다음을 지정하는 매개변수를 추가할 수 있습니다.
메타데이터 구성 매개변수
메타데이터 구성 매개변수는 항목 메타데이터를 채우는 데 사용되는 CSV 열을 설명합니다. 구성 파일에 이 매개변수가 없으면 기본값이 사용됩니다. 다음 표에서는 이러한 매개변수를 보여줍니다.
| 설정 | 매개변수 |
| 제목 | itemMetadata.title.field=movieTitle
itemMetadata.title.defaultValue=Gone with the Wind
문서 제목에 해당하는 값이 포함된 메타데이터 속성입니다. 기본값은 빈 문자열입니다. |
| URL | itemMetadata.sourceRepositoryUrl.field=url
itemMetadata.sourceRepositoryUrl.defaultValue=https://www.imdb.com/title/tt0031381/
검색 결과의 문서 URL 값이 포함된 메타데이터 속성입니다. |
| 생성된 타임스탬프 | itemMetadata.createTime.field=releaseDate
itemMetadata.createTime.defaultValue=1940-01-17
문서 생성 타임스탬프 값이 포함된 메타데이터 속성입니다. |
| 최종 수정 시간 | itemMetadata.updateTime.field=releaseDate
itemMetadata.updateTime.defaultValue=1940-01-17
문서의 마지막 수정 타임스탬프 값이 포함된 메타데이터 속성입니다. |
| 문서 언어 | itemMetadata.contentLanguage.field=languageCode
itemMetadata.contentLanguage.defaultValue=en-US
색인이 생성되는 문서의 콘텐츠 언어입니다. |
| 스키마 객체 유형 | itemMetadata.objectType.field=typeitemMetadata.objectType.defaultValue=movie
스키마에 정의된 대로 커넥터가 사용하는 객체 유형입니다. 이 속성을 지정하지 않으면 커넥터가 구조화된 데이터의 색인을 생성하지 않습니다. |
날짜/시간 형식
날짜/시간 형식은 메타데이터 속성에 필요한 형식을 지정합니다. 구성 파일에 이 매개변수가 없으면 기본값이 사용됩니다. 다음 표에서는 이 매개변수를 보여줍니다.
| 설정 | 매개변수 |
| 추가 날짜/시간 형식 | structuredData.dateTimePatterns=MM/dd/uuuu HH:mm:ssXXX
추가 java.time.format.DateTimeFormatter 패턴의 세미콜론으로 구분된 목록입니다. 이 패턴은 메타데이터 또는 스키마에서 날짜 또는 날짜-시간 필드의 문자열 값을 파싱할 때 사용됩니다. 기본값은 빈 목록이지만 RFC 3339 및 RFC 1123 형식은 항상 지원됩니다. |
열 형식
열 형식은 검색 가능한 콘텐츠에 포함되어야 하는 열에 대한 정보를 지정합니다. 구성 파일에 이 매개변수가 없으면 기본값이 사용됩니다. 다음 표에서는 이러한 매개변수를 보여줍니다.
| 설정 | 매개변수 |
| 헤더 건너뛰기 | csv.skipHeaderRecord=true
부울. CSV 파일의 헤더 레코드(첫 번째 줄)를 무시합니다. |
| 다중 값 열 | csv.multiValueColumns=genre,actors
CSV 파일에서 다중 값을 갖는 열 이름입니다. 기본값은 빈 문자열입니다. |
| 다중 값 열 구분 기호 | csv.multiValue.genre=;
다중 값 열의 구분 기호입니다. 기본 구분 기호는 쉼표입니다. |
검색 품질
Cloud Search CSV 커넥터는 데이터 필드를 자동으로 HTML 형식으로 만들 수 있습니다. 커넥터는 커넥터 실행이 시작될 때 데이터 필드를 정의하고, 콘텐츠 템플릿을 사용하여 각 데이터 레코드의 형식을 지정한 후에 Cloud Search에 업로드합니다.
콘텐츠 템플릿은 검색 시 각 필드 값의 중요도를 정의합니다. 제목 필드는 필수이며 가장 높은 우선순위로 정의됩니다. 다른 모든 콘텐츠 필드의 검색 품질 중요도 수준을 높음, 중간, 낮음으로 지정할 수 있습니다. 특정 카테고리로 정의되지 않은 콘텐츠 필드는 기본적으로 낮은 우선순위로 지정됩니다. 다음 표에서는 이러한 매개변수를 보여줍니다.
| 설정 | 매개변수 |
| 콘텐츠 제목 | contentTemplate.csv.title=movieTitle
콘텐츠 제목은 최우선 검색 품질 필드입니다. |
| 콘텐츠 필드에 높은 검색 품질 사용 | contentTemplate.csv.quality.high=actors
콘텐츠 필드에 높은 검색 품질 값을 부여합니다. 기본값은 빈 문자열입니다. |
| 콘텐츠 필드에 낮은 검색 품질 사용 | contentTemplate.csv.quality.low=genre
콘텐츠 필드에 낮은 검색 품질 값을 부여합니다. 기본값은 빈 문자열입니다. |
| 콘텐츠 필드에 중간 검색 품질 사용 | contentTemplate.csv.quality.medium=description
콘텐츠 필드에 중간 검색 품질 값을 부여합니다. 기본값은 빈 문자열입니다. |
| 지정되지 않은 콘텐츠 필드 | contentTemplate.csv.unmappedColumnsMode=IGNORE
지정되지 않은 콘텐츠 필드를 커넥터가 처리하는 방법입니다. 유효한 값은 다음과 같습니다.
|
8. 데이터 순회 예약
순회는 커넥터가 데이터 소스(이 경우 CSV 파일)에서 콘텐츠를 탐색하는 프로세스입니다. CSV 커넥터는 실행 중에 CSV 파일의 행을 순회하면서 Indexing API를 통해 각 행을 Cloud Search로 색인 생성합니다.
전체 순회에서는 파일의 모든 열을 색인 생성합니다. 증분 순회에서는 이전 순회 후에 추가 또는 수정된 열만 색인 생성합니다. CSV 커넥터는 전체 순회만 수행하며 증분 순회는 수행하지 않습니다.
예약 매개변수는 각 순회 사이에 커넥터가 대기하는 빈도를 지정합니다. 구성 파일에 예약 매개변수가 없으면 기본값이 사용됩니다. 다음 표에서는 이러한 매개변수를 보여줍니다.
| 설정 | 매개변수 |
| 간격 후 전체 순회 | schedule.traversalIntervalSecs=7200
지정된 간격이 지나면 커넥터가 전체 순회를 수행합니다. 순회 간격을 초 단위로 지정합니다. 기본값은 86,400 (하루 총 초 수)입니다. |
| 커넥터 시작 시 전체 순회 | schedule.performTraversalOnStart=false
커넥터가 첫 번째 간격이 만료되기를 기다리지 않고 커넥터 시작 시 전체 순회를 수행합니다. 기본값은 true입니다. |
9. 액세스제어 목록(ACL) 옵션 지정
Google Cloud Search CSV 커넥터는 ACL을 통한 권한으로 검색결과의 CSV 파일 내용에 대한 액세스를 제어하는 기능을 지원합니다. 색인 생성된 레코드에 대한 사용자 액세스를 보호하기 위해 여러 가지 ACL 옵션을 사용할 수 있습니다.
저장소의 각 문서에 개별 ACL 정보가 연결된 경우 모든 ACL 정보를 업로드하여 Cloud Search 내에서 문서 액세스를 제어합니다. 저장소가 ACL 정보를 부분적으로 제공하거나 전혀 제공하지 않는 경우에는 다음 매개변수를 통해 SDK가 커넥터에 제공하는 기본 ACL 정보를 입력할 수 있습니다.
커넥터는 구성 파일에서 기본 ACL이 사용 설정되었다고 가정합니다. 기본 ACL을 사용 설정하려면 defaultAcl.mode를 none 이외의 모드로 설정하고 defaultAcl.*로 구성합니다.
| 설정 | 매개변수 |
| ACL 모드 | defaultAcl.mode=fallback
필수. CSV 커넥터가 기본 ACL 기능을 사용합니다. 커넥터는 대체 모드만 지원합니다. |
| 기본 ACL 이름 | defaultAcl.name=VIRTUAL_CONTAINER_FOR_CONNECTOR_1
선택사항입니다. 커넥터가 기본 ACL을 설정하는 데 사용하는 가상 컨테이너 이름을 재정의하도록 허용합니다. 기본값은 'DEFAULT_ACL_VIRTUAL_CONTAINER'입니다. 여러 커넥터가 같은 데이터 소스의 콘텐츠를 색인 생성하는 경우 이 값을 재정의해야 할 수 있습니다. |
| 기본 공개 ACL | defaultAcl.public=true
전체 저장소에 사용되는 기본 ACL이 공개 도메인 액세스로 설정됩니다. 기본값은 false입니다. |
| 공통 ACL 그룹 리더 | defaultAcl.readers.groups=google:group1, group2 |
| 공통 ACL 리더 | defaultAcl.readers.users=user1, user2, google:user3 |
| 공통 ACL 거부된 그룹 리더 | defaultAcl.denied.groups=group3 |
| 공통 ACL 거부된 리더 | defaultAcl.denied.users=user4, user5 |
| 전체 도메인 액세스 | 색인 생성된 모든 레코드를 도메인의 모든 사용자가 공개적으로 액세스하도록 지정하려면 다음 옵션을 해당 값으로 설정합니다.
|
| 공통 정의 ACL | 데이터 저장소의 각 레코드에 단일 ACL을 지정하려면 다음 매개변수 값을 모두 설정합니다.
|
스키마 정의
Cloud Search는 구조화 여부에 관계없이 콘텐츠를 색인 생성하고 제공할 수 있습니다. 데이터에 대해 구조화된 데이터 쿼리를 지원하려면 데이터 소스의 스키마를 설정해야 합니다.
스키마를 정의하면 CSV 커넥터가 해당 스키마를 참조하여 색인 생성 요청을 작성할 수 있습니다. 예를 들어 영화 관련 정보를 포함하는 CSV 파일이 있다고 가정해 보겠습니다.
입력 CSV 파일의 콘텐츠는 다음과 같습니다.
- movieId
- movieTitle
- description
- year
- releaseDate
- actors(쉼표(,)로 구분된 다중 값)
- genre(다중 값)
- ratings
위와 같은 데이터 구조에 따라 CSV 파일의 데이터를 색인 생성하는 데 사용할 데이터 소스 스키마를 정의할 수 있습니다.
{
"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"
}
}
}
]
}
]
}
구성 파일 예시
다음 구성 파일 예에서는 예시 커넥터의 동작을 정의하는 매개변수 key=value 쌍을 보여줍니다.
# 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
각 매개변수에 대한 자세한 설명은 구성 매개변수 참조를 확인하세요.
Cloud Search CSV 커넥터 실행
명령줄에서 커넥터를 실행하려면 다음 명령어를 입력합니다.
$ java -jar google-cloudsearch-csv-connector-v1-0.0.3.jar -Dconfig=my.config
기본적으로 커넥터 로그가 표준 출력으로 제공됩니다. logging.properties를 지정하면 파일에 로깅할 수 있습니다.