Singer 소스

설명

Singer 소스를 사용하면 Singer tap을 통해 Stripe, GitHub, Slack, BigQuery 같은 다양한 SaaS 앱, API, 데이터베이스에서 PlaidCloud로 데이터를 가져올 수 있습니다. 각 tap은 하나의 소스를 위한 커넥터이며, 연결을 만들 때 tap을 선택하면 PlaidCloud가 해당 tap에 필요한 구성 필드를 표시합니다.

Singer 소스를 사용하는 과정은 두 부분으로 구성됩니다.

1. Singer 소스 연결에는 tap 선택 및 해당 설정(API 토큰, 계정 ID, 시작 날짜 등)이 저장됩니다.
2. Import Singer Source 워크플로 단계는 tap에서 사용할 수 있는 스트림을 검색하고, 가져올 스트림과 각 스트림이 저장될 위치를 선택하게 한 다음, 추출을 실행합니다.

참고

PlaidCloud는 허용적 라이선스가 적용된 tap을 엄선한 카탈로그로 제공합니다. 구성 필드는 tap마다 다르며, 연결 폼은 선택한 tap에 따라 생성됩니다.

Singer 소스 연결에는 tap과 해당 설정이 저장되며, Import Singer Source 단계는 tap의 스트림을 검색하여 선택한 스트림을 프로젝트 테이블에 저장합니다.

시작하기 전에

소스 시스템의 자격 증명(예: GitHub 개인용 액세스 토큰 또는 Stripe API 키)과 데이터를 저장할 프로젝트 및 워크플로가 필요합니다.

Singer 소스 연결 만들기

1. Tools > Connections를 엽니다.
2. New Connection을 클릭하고 Singer 소스를 선택합니다.
3. 연결에 이름을 지정합니다(예: GitHub (prod)).
4. 드롭다운에서 Tap을 선택합니다. 아래 폼이 다시 구성되어 해당 tap의 필드가 표시됩니다. 전체 카탈로그와 각 소스의 구성 문서 링크는 Singer 소스를 참조하십시오.
5. tap의 구성 필드를 입력한 다음 만들기를 클릭합니다.

구성 필드 유형

필드는 tap에 따라 다르며, 각 필드는 tap이 요구하는 값에 맞게 표시됩니다.

• 텍스트 - 한 줄 값(예: 계정 ID 또는 시작 날짜).

• 암호 - API 토큰이나 키 같은 비밀 정보. 비밀 정보는 쓰기 전용입니다. 연결을 편집할 때 표시되지 않으며, 저장할 때 비워 두면 저장된 값이 유지됩니다.

• 번호 - 정수 또는 소수(예: 포트 또는 페이지 크기).

• 목록 - 한 줄에 하나씩 입력하는 항목(예: 리포지토리 또는 프로젝트 ID 목록).

• JSON - JSON으로 입력하는 구조화된 값으로, tap이 개체 또는 개체 배열을 요구할 때 사용합니다. 예를 들어 CSV tap의 파일 정의는 다음과 같습니다.

  [
    { "entity": "orders", "path": "/data/orders.csv", "keys": ["id"] }
  ]

• 확인란 - 켜기/끄기 옵션.

필수 필드에는 표시가 있으며, 폼은 저장하기 전에 이를 검증합니다(JSON 및 숫자 필드의 형식이 올바른지 포함).

스트림을 워크플로로 가져오기

1. 워크플로를 열고 Analyze Steps 탭으로 이동합니다.
2. 단계를 추가하고 유형으로 가져오기: Singer 소스를 선택합니다. 편집기가 소스 탭과 스트림 탭과 함께 열립니다.
3. 소스 탭에서 다음을 수행합니다.
   • 연결(Singer 소스 연결)을 선택합니다.
   • 동기화 모드를 선택합니다. 전체 테이블(실행마다 바꿈), 증분(새 데이터 추가) 또는 업서트(키 기준 병합) 중에서 선택합니다.
   • 스트림 검색을 클릭합니다. 검색은 러너에서 실행되며 처음에는 최대 3분 정도 걸릴 수 있습니다. 상태에 검색된 스트림 수가 표시됩니다.
4. 스트림 탭에는 검색된 스트림마다 한 행씩 표시됩니다. 가져오려는 각 스트림에 대해 다음을 수행합니다.
   • 스트림 패널을 열고 이 스트림 가져오기를 선택합니다.
   • 스트림 데이터가 저장될 대상 테이블을 선택합니다.
   • 동기화 모드가 업서트이면 스트림의 키 열을 한 줄에 열 이름 하나씩 설정합니다. 이 필드의 기본값은 tap에 선언된 기본 키이며, 다른 열을 기준으로 병합하려면 이를 재정의하십시오. 모드가 업서트일 때는 가져오는 모든 스트림에 키 열이 하나 이상 필요합니다.
5. 단계를 저장하고 워크플로의 일부로 실행합니다(또는 단독으로 실행).

주의

선택한 스트림이 곧 저장되는 집합입니다. 가져올 스트림을 변경하려면 스트림 검색을 다시 클릭하십시오. 다시 나타나는 스트림은 이미 설정한 대상 테이블과 선택 상태를 유지합니다.

동기화 모드

• 전체 테이블(실행마다 바꿈) 은 실행할 때마다 스트림 전체를 다시 추출하여 대상 테이블을 바꿉니다. 작거나 전체를 새로 고치는 소스에 사용하십시오.
• 증분(새 데이터 추가) 은 마지막 실행 이후 새로 추가된 행만 추출하여 추가하며, 이전 실행이 중단된 지점부터 이어서 진행합니다. tap이 증분 동기화할 수 있는 스트림, 즉 복제 키(업데이트 타임스탬프나 증가하는 ID 같은)를 제공하는 스트림에서만 작동합니다. 증분을 선택했는데 선택한 스트림에 복제 키가 없으면 단계는 해당 스트림을 전체 테이블로 전환하거나 선택을 해제하라고 안내합니다.
• 업서트(키 기준 병합) 는 실행할 때마다 스트림 전체를 다시 추출한 다음 스트림의 키 열을 기준으로 대상에 병합합니다. 키가 기존 행과 일치하는 행은 그 자리에서 업데이트되고, 새 키를 가진 행은 삽입됩니다. 이번 실행에 없는 기존 행은 유지됩니다. 시간이 지나며 레코드가 변경되는 소스와 테이블을 동기화된 상태로 유지할 때 사용하십시오. 추가 방식에서 생기는 중복이나 바꾸기 방식의 전체 재구성이 없습니다. 대상 테이블은 첫 번째 실행에서 만들어지므로 첫 번째 업서트에서는 모든 행이 삽입됩니다.

참고

증분 진행 상황은 단계별로 추적됩니다. 첫 번째 증분 실행은 모든 항목을 추출하고, 이후 실행은 새 행만 가져옵니다.

참고

업서트는 실행할 때마다 스트림 전체를 다시 추출하므로(복제 키를 사용하지 않음), 기존 행이 업데이트되고 키당 하나의 행을 유지하려는 소스에 적합합니다. 스트림 탭에서 각 스트림의 키 열을 설정하십시오. 기본값은 tap에 선언된 기본 키입니다.

주의

항상 존재하는 키 열을 선택하십시오. 업서트는 정확한 키 값으로 행을 일치시키며, 빈 값(null) 키는 다른 키와 절대 일치하지 않습니다. 따라서 null 키가 있는 행은 병합되지 않고 항상 삽입되어 실행을 거듭하면서 누적될 수 있습니다.

자격 증명 처리 방식

단계에는 연결의 자격 증명 사본이 아니라 연결에 대한 참조가 저장됩니다. 실행할 때마다 연결의 현재 자격 증명을 읽습니다. 따라서 토큰이나 키를 교체할 때 연결에서 한 번만 업데이트하면 이를 사용하는 모든 단계가 다음 실행에서 새 값을 사용하며, 개별 단계에서 업데이트할 것은 없습니다.

추출은 tap 자체의 구성만 받는 격리된 작업에서 실행되며, 다른 연결이나 PlaidCloud의 내부 서비스에는 액세스할 수 없습니다.

관련 문서

• Singer 소스 카탈로그 - 사용 가능한 모든 소스와 해당 구성 문서
• Import Singer Source 단계 참조
• 연결