Cloud Storage Text to Firestore 템플릿은 Cloud Storage에 저장된 JSON 문서에서 Firestore로 가져오는 일괄 파이프라인입니다.
파이프라인 요구사항
대상 프로젝트에서 Firestore를 사용 설정해야 합니다.
입력 형식
각 입력 파일은 줄바꿈으로 구분된 JSON을 포함해야 하며, 여기서 각 줄에는 Datastore Entity
데이터 유형의 JSON 표현이 포함됩니다.
예를 들어 다음 JSON은 Users
라는 컬렉션의 문서를 나타냅니다. 이 예시는 가독성을 위해 형식이 지정되었지만 각 문서는 단일 입력 줄로 표시되어야 합니다.
{ "key": { "partitionId": { "projectId": "my-project" }, "path": [ { "kind": "users", "name": "alovelace" } ] }, "properties": { "first": { "stringValue": "Ada" }, "last": { "stringValue": "Lovelace" }, "born": { "integerValue": "1815", "excludeFromIndexes": true } } }
문서 모델에 관한 자세한 내용은 항목, 속성, 키를 참고하세요.
템플릿 매개변수
필수 매개변수
- textReadPattern: 텍스트 데이터 파일의 위치를 지정하는 Cloud Storage 경로 패턴입니다. 예를 들면
gs://mybucket/somepath/*.json
입니다. - firestoreWriteProjectId: Firestore 항목을 쓸 Google Cloud 프로젝트의 ID입니다.
- errorWritePath: 처리 중에 발생하는 쓰기 오류에 사용할 오류 로그 출력 파일입니다. 예를 들면
gs://your-bucket/errors/
입니다.
선택적 매개변수
- javascriptTextTransformGcsPath: 사용할 JavaScript 사용자 정의 함수 (UDF)를 정의하는 .js 파일의 Cloud Storage URI입니다. 예를 들면
gs://my-bucket/my-udfs/my_file.js
입니다. - javascriptTextTransformFunctionName: 사용할 JavaScript 사용자 정의 함수 (UDF)의 이름입니다. 예를 들어 JavaScript 함수가
myTransform(inJson) { /*...do stuff...*/ }
이면 함수 이름은myTransform
입니다. 샘플 JavaScript UDF는 UDF 예시(https://github.com/GoogleCloudPlatform/DataflowTemplates#udf-examples)를 참조하세요. - firestoreHintNumWorkers: Firestore 증가 제한 단계의 예상 작업자 수에 대한 힌트입니다. 기본값은
500
입니다.
사용자 정의 함수
선택적으로 사용자 정의 함수(UDF)를 작성하여 이 템플릿을 확장할 수 있습니다. 템플릿이 각 입력 요소에 대해 UDF를 호출합니다. 요소 페이로드는 JSON 문자열로 직렬화됩니다. 자세한 내용은 Dataflow 템플릿에 대한 사용자 정의 함수 만들기를 참조하세요.
함수 사양
UDF의 사양은 다음과 같습니다.
- 입력: Cloud Storage 입력 파일의 텍스트 줄입니다.
- 출력: JSON 문자열로 직렬화된
Entity
입니다.
템플릿 실행
콘솔
- Dataflow 템플릿에서 작업 만들기 페이지로 이동합니다. 템플릿에서 작업 만들기로 이동
- 작업 이름 필드에 고유한 작업 이름을 입력합니다.
- (선택사항): 리전 엔드포인트의 드롭다운 메뉴에서 값을 선택합니다. 기본 리전은
us-central1
입니다.Dataflow 작업을 실행할 수 있는 리전 목록은 Dataflow 위치를 참조하세요.
- Dataflow 템플릿 드롭다운 메뉴에서 the Text Files on Cloud Storage to Firestore template을 선택합니다.
- 제공된 매개변수 필드에 매개변수 값을 입력합니다.
- 작업 실행을 클릭합니다.
gcloud
셸 또는 터미널에서 템플릿을 실행합니다.
gcloud dataflow jobs run JOB_NAME \ --gcs-location gs://dataflow-templates-REGION_NAME/VERSION/GCS_Text_to_Firestore \ --region REGION_NAME \ --parameters \ textReadPattern=PATH_TO_INPUT_TEXT_FILES,\ javascriptTextTransformGcsPath=PATH_TO_JAVASCRIPT_UDF_FILE,\ javascriptTextTransformFunctionName=JAVASCRIPT_FUNCTION,\ firestoreWriteProjectId=PROJECT_ID,\ errorWritePath=ERROR_FILE_WRITE_PATH
다음을 바꿉니다.
JOB_NAME
: 선택한 고유한 작업 이름VERSION
: 사용할 템플릿 버전다음 값을 사용할 수 있습니다.
latest
: 버킷의 날짜가 지정되지 않은 상위 폴더(gs://dataflow-templates-REGION_NAME/latest/)에서 사용할 수 있는 최신 버전의 템플릿을 사용합니다.- 버전 이름(예:
2023-09-12-00_RC00
): 버킷의 날짜가 지정된 해당 상위 폴더(gs://dataflow-templates-REGION_NAME/)에 중첩되어 있는 특정 버전의 템플릿을 사용합니다.
REGION_NAME
: Dataflow 작업을 배포할 리전(예:us-central1
)PATH_TO_INPUT_TEXT_FILES
: Cloud Storage의 입력 파일 패턴JAVASCRIPT_FUNCTION
: 사용할 자바스크립트 사용자 정의 함수(UDF)의 이름입니다.예를 들어 자바스크립트 함수가
myTransform(inJson) { /*...do stuff...*/ }
이면 함수 이름은myTransform
입니다. 샘플 JavaScript UDF는 UDF 예시를 참조하세요.PATH_TO_JAVASCRIPT_UDF_FILE
: 사용할 JavaScript 사용자 정의 함수(UDF)를 정의하는.js
파일의 Cloud Storage URI입니다. 예를 들면gs://my-bucket/my-udfs/my_file.js
입니다.ERROR_FILE_WRITE_PATH
: Cloud Storage에서 오류 파일에 사용할 경로
API
REST API를 사용하여 템플릿을 실행하려면 HTTP POST 요청을 전송합니다. API 및 승인 범위에 대한 자세한 내용은 projects.templates.launch
를 참조하세요.
POST https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/LOCATION/templates:launch?gcsPath=gs://dataflow-templates-LOCATION/VERSION/GCS_Text_to_Firestore { "jobName": "JOB_NAME", "parameters": { "textReadPattern": "PATH_TO_INPUT_TEXT_FILES", "javascriptTextTransformGcsPath": "PATH_TO_JAVASCRIPT_UDF_FILE", "javascriptTextTransformFunctionName": "JAVASCRIPT_FUNCTION", "firestoreWriteProjectId": "PROJECT_ID", "errorWritePath": "ERROR_FILE_WRITE_PATH" }, "environment": { "zone": "us-central1-f" } }
다음을 바꿉니다.
PROJECT_ID
: Dataflow 작업을 실행하려는 Google Cloud 프로젝트 IDJOB_NAME
: 선택한 고유한 작업 이름VERSION
: 사용할 템플릿 버전다음 값을 사용할 수 있습니다.
latest
: 버킷의 날짜가 지정되지 않은 상위 폴더(gs://dataflow-templates-REGION_NAME/latest/)에서 사용할 수 있는 최신 버전의 템플릿을 사용합니다.- 버전 이름(예:
2023-09-12-00_RC00
): 버킷의 날짜가 지정된 해당 상위 폴더(gs://dataflow-templates-REGION_NAME/)에 중첩되어 있는 특정 버전의 템플릿을 사용합니다.
LOCATION
: Dataflow 작업을 배포할 리전(예:us-central1
)PATH_TO_INPUT_TEXT_FILES
: Cloud Storage의 입력 파일 패턴JAVASCRIPT_FUNCTION
: 사용할 자바스크립트 사용자 정의 함수(UDF)의 이름입니다.예를 들어 자바스크립트 함수가
myTransform(inJson) { /*...do stuff...*/ }
이면 함수 이름은myTransform
입니다. 샘플 JavaScript UDF는 UDF 예시를 참조하세요.PATH_TO_JAVASCRIPT_UDF_FILE
: 사용할 JavaScript 사용자 정의 함수(UDF)를 정의하는.js
파일의 Cloud Storage URI입니다. 예를 들면gs://my-bucket/my-udfs/my_file.js
입니다.ERROR_FILE_WRITE_PATH
: Cloud Storage에서 오류 파일에 사용할 경로
다음 단계
- Dataflow 템플릿 알아보기
- Google 제공 템플릿 목록 참조