이 가이드는 커넥터를 다운로드, 구성, 실행, 모니터링할 책임이 있는 Google Cloud Search CSV (쉼표로 구분된 값) 커넥터 관리자를 대상으로 합니다.
이 가이드에는 다음 주요 작업에 대한 안내가 포함되어 있습니다.
- Cloud Search CSV 커넥터 소프트웨어를 다운로드합니다.
- 특정 CSV 데이터 소스에 맞게 커넥터를 구성합니다.
- 커넥터를 배포하고 실행합니다.
이 문서의 개념을 이해하려면 Google Workspace, CSV 파일, 액세스 제어 목록 (ACL)을 잘 알고 있어야 합니다.
Cloud Search CSV 커넥터 개요
Cloud Search CSV 커넥터는 모든 쉼표로 구분된 값 (CSV) 텍스트 파일과 연동합니다. CSV 파일은 표 형식 데이터를 저장하며, 각 줄은 하나의 데이터 레코드입니다.
커넥터는 CSV 파일에서 행을 추출하고 Indexing API를 사용하여 Cloud Search에 색인을 생성합니다. 색인이 생성되면 Cloud Search 클라이언트 또는 Query API를 통해 행을 검색할 수 있습니다. 커넥터는 콘텐츠에 대한 사용자 액세스를 제어하는 ACL도 지원합니다.
Linux 또는 Windows에 커넥터를 설치할 수 있습니다. 배포하기 전에 다음 구성요소가 있는지 확인하세요.
- 커넥터를 실행하는 컴퓨터에 Java JRE 1.8이 설치되어 있어야 합니다.
- 연결을 설정하기 위한 Google Workspace 정보:
- Google Workspace 비공개 키(서비스 계정 ID 포함)
- Google Workspace 데이터 소스 ID.
일반적으로 도메인의 Google Workspace 관리자가 이러한 사용자 인증 정보를 제공합니다.
배포 단계
Cloud Search CSV 커넥터를 배포하려면 다음 단계를 따르세요.
- 커넥터 소프트웨어 설치
- 커넥터 구성 지정
- 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
선택한 버전을 확인합니다.
$ git checkout tags/v1-0.0.3
커넥터를 빌드합니다.
$ mvn package
커넥터를 추출하고 설치합니다.
$ 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 파일 위치 및 정의입니다.
- 고유 ID 열입니다.
- 순회 및 ACL 옵션
구성 파일을 만들려면 다음 안내를 따르세요.
- 텍스트 편집기를 열고 파일 이름을
connector-config.properties로 지정합니다. - 구성 매개변수를
key=value쌍으로 추가합니다. 각 쌍은 새 줄에 있습니다. 구성 파일의 예시는 구성 파일 예시를 참고하세요.
추적을 간소화하기 위해 구성 파일을 커넥터와 같은 디렉터리에 보관합니다. 커넥터가 파일을 인식할 수 있도록 명령줄에서 경로를 지정합니다. 그렇지 않으면 커넥터는 로컬 디렉터리의 connector-config.properties를 기본값으로 사용합니다. 커넥터 실행을 참고하세요.
3. Cloud Search 데이터 소스에 대한 액세스 구성
구성 파일은 Cloud Search 데이터 소스에 액세스하는 매개변수를 지정해야 합니다. 데이터 소스 ID, 서비스 계정 ID, 서비스 계정의 비공개 키 파일 경로가 필요합니다.
| 설정 | 매개변수 |
| 데이터 소스 ID | api.sourceId=1234567890abcdef
필수 항목입니다. Google Workspace 관리자가 설정한 Cloud Search 소스 ID입니다. |
| 서비스 계정 비공개 키의 경로 | api.serviceAccountPrivateKeyFile=./PrivateKey.json
필수 항목입니다. 커넥터 액세스용 서비스 계정 키 파일입니다. |
| ID 소스 ID | api.identitySourceId=x0987654321
외부 사용자 및 그룹을 사용하는 경우 필수. Google Workspace 관리자가 설정한 ID 소스 ID입니다. |
4. CSV 파일 매개변수 구성
파일의 경로, 형식, 인코딩을 식별합니다.
| 설정 | 매개변수 |
| CSV 파일 경로 | csv.filePath=./movie_content.csv
필수 항목입니다. 색인 생성할 파일의 경로입니다. |
| 파일 형식 | csv.format=DEFAULT
파일의 형식입니다. 가능한 값은 Apache Commons CSV CSVFormat 클래스의 값입니다. 형식 값에는 |
| 파일 형식 한정자 | csv.format.withMethod=value
Cloud Search 파일 처리 방법의 수정입니다. 가능한 메서드는 Apache Commons CSV CSVFormat 클래스의 메서드이며 단일 문자, 문자열, 부울 값을 취하는 메서드가 포함됩니다. 예를 들어 세미콜론을 구분 기호로 지정하려면 |
| 파일 인코딩 유형 | csv.fileEncoding=UTF-8
사용할 Java 문자 집합입니다. 기본값은 플랫폼 문자 집합입니다. |
5. 색인을 생성할 열 이름과 고유 키 열 지정
구성 파일에 열 정보를 제공합니다.
| 설정 | 매개변수 |
| 색인을 생성할 열 | csv.csvColumns=movieId,movieTitle,description,actors,releaseDate,year,userratings...
CSV 파일에서 색인을 생성할 열 이름입니다. 기본적으로 CSV의 첫 번째 행이 헤더로 사용됩니다. |
| 고유 키 열 | csv.uniqueKeyColumns=movieId
고유 ID를 생성하는 데 사용되는 열입니다. 기본값은 레코드의 해시코드입니다. |
6. 클릭 가능한 검색 결과 URL의 열 지정
검색 결과에 클릭 가능한 URL을 사용 설정합니다.
| 설정 | 매개변수 |
| 검색결과 URL 형식 | url.format=https://mymoviesite.com/movies/{0}
필수 항목입니다. 보기 URL을 생성하는 데 사용되는 형식입니다. |
| URL 매개변수 | url.columns=movieId
필수 항목입니다. 레코드의 뷰 URL을 생성하는 데 사용할 값을 갖는 CSV 열 이름입니다. |
| 이스케이프할 검색결과 URL 매개변수 | url.columnsToEscape=movieId
선택사항입니다. URL로 이스케이프하여 유효한 뷰 URL을 생성할 값을 갖는 CSV 열 이름입니다. |
7. 메타데이터, 열 형식, 검색 품질 지정
구성 파일에 다음을 지정하는 매개변수를 추가할 수 있습니다.
메타데이터 구성 매개변수
이러한 매개변수는 항목 메타데이터를 채우는 열을 설명합니다.
| 설정 | 매개변수 |
| 제목 | 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 파일의 열을 파싱하는 방법을 지정합니다.
| 설정 | 매개변수 |
| 헤더 건너뛰기 | csv.skipHeaderRecord=true
첫 번째 줄은 무시합니다. 기본값은 false입니다. |
| 다중 값 열 | csv.multiValueColumns=genre,actors
다중 값을 갖는 열 이름입니다. |
| 다중 값 열 구분 기호 | csv.multiValue.genre=;
다중 값 열의 구분 기호입니다. 기본 구분자는 쉼표입니다. |
검색 품질
커넥터는 콘텐츠 템플릿을 사용하여 레코드의 형식을 지정합니다. 제목 필드의 우선순위가 가장 높습니다. 다른 필드에 우선순위 수준 (높음, 중간, 낮음)을 할당할 수 있습니다.
| 설정 | 매개변수 |
| 콘텐츠 제목 |
contentTemplate.csv.title=movieTitle
콘텐츠 제목은 최우선 검색 품질 필드입니다. |
| 콘텐츠 필드에 높은 검색 품질 사용 |
contentTemplate.csv.quality.high=actors
콘텐츠 필드에 높은 검색 품질 값을 부여합니다. 기본값은 빈 문자열입니다. |
| 콘텐츠 필드에 낮은 검색 품질 사용 |
contentTemplate.csv.quality.low=genre
콘텐츠 필드에 낮은 검색 품질 값을 부여합니다. 기본값은 빈 문자열입니다. |
| 콘텐츠 필드에 중간 검색 품질 사용 |
contentTemplate.csv.quality.medium=description
콘텐츠 필드에 중간 검색 품질 값을 부여합니다. 기본값은 빈 문자열입니다. |
| 지정되지 않은 콘텐츠 필드 |
contentTemplate.csv.unmappedColumnsMode=IGNORE
지정되지 않은 콘텐츠 필드를 커넥터가 처리하는 방법입니다. 유효한 값은 다음과 같습니다.
기본값은 APPEND입니다. |
8. 데이터 순회 예약
순회는 콘텐츠를 탐색하는 프로세스입니다. 커넥터는 CSV 행을 순회하고 Indexing API를 사용하여 색인을 생성합니다. CSV 커넥터는 전체 순회만 수행합니다.
| 설정 | 매개변수 |
| 순회 간격 | schedule.traversalIntervalSecs=7200
전체 순회 간격(초)입니다. 기본값은 86400 (1일)입니다. |
| 시작 시 순회 | schedule.performTraversalOnStart=false
커넥터가 첫 번째 간격이 만료되기를 기다리지 않고 커넥터 시작 시 순회를 수행합니다. 기본값은 |
9. ACL 옵션 지정
커넥터는 ACL을 사용하여 액세스를 제어합니다. 저장소에서 ACL을 제공하는 경우 이를 업로드합니다. 그렇지 않으면 기본 ACL을 구성합니다. defaultAcl.mode를 none 이외의 값으로 설정합니다.
| 설정 | 매개변수 |
| ACL 모드 | defaultAcl.mode=fallback
필수 항목입니다. 커넥터는 대체 모드만 지원합니다. |
| 기본 ACL 이름 | defaultAcl.name=VIRTUAL_CONTAINER_FOR_CONNECTOR_1
선택사항입니다. 커넥터가 기본 ACL에 사용하는 가상 컨테이너 이름을 재정의합니다. 기본값은 |
| 기본 공개 ACL | defaultAcl.public=true
전체 저장소를 공개 도메인 액세스로 설정합니다. 기본값은 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을 정의하려면 다음 매개변수를 설정합니다.
사용자와 그룹은 ' 기본 사용자 또는 그룹은 빈 문자열입니다.
|
스키마 정의
구조화된 데이터 쿼리를 지원하려면 데이터 소스의 스키마를 설정하세요.
예를 들어 영화에 관한 다음 정보가 포함된 CSV 파일을 살펴보겠습니다.
- movieId
- movieTitle
- description
- year
- releaseDate
- actors(쉼표(,)로 구분된 다중 값)
- genre(다중 값)
- 평가
이 구조를 기반으로 데이터 소스에 다음 스키마를 정의할 수 있습니다.
{
"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
커넥터 실행
명령줄에서 커넥터를 실행하려면 다음 단계를 따르세요.
$ java -jar google-cloudsearch-csv-connector-v1-0.0.3.jar -Dconfig=my.config
기본적으로 커넥터 로그가 표준 출력으로 제공됩니다. logging.properties를 지정하면 파일에 로깅할 수 있습니다.