Feishu 다차원 테이블 데이터 소스 구성
AE 데이터 개발 플랫폼은 Feishu 다차원 테이블을 데이터 소스로 사용하여 테이블의 데이터를 사전 설정 스토리지에 쓰는 방식으로 데이터를 동기화할 수 있습니다.
이 문서에서는 Feishu 다차원 테이블 LarkSheet 데이터 소스의 구성 기능을 소개합니다.
지원 버전
- 모든 SaaS 버전 또는 프라이빗 배포 버전의 Feishu 다차원 테이블.
사용 제한
- Feishu 다차원 테이블 데이터 소스는 오프라인 읽기(데이터 출처로 사용)만 지원하며, 데이터 목적지로 쓰기는 지원하지 않습니다.
- 다차원 테이블 데이터를 읽을 때는 String/ Datetime/ Date 타입의 필드만 읽을 수 있으며, 다른 데이터 타입으로 읽는 것은 아직 지원하지 않습니다.
- Feishu 스프레드시트에는 헤더 개념이 없지만, Feishu 스프레드시트 가져오기 작업을 더 규범적으로 운영하기 위해 다음과 같이 약속합니다.
테이블의 첫 번째 행을 헤더로 사용합니다. 헤더는 A1 셀에서 시작하고, 연속되며, 비어 있지 않고, 이름이 중복될 수 없는 일련의 셀이어야 합니다. 헤더는 필드 매핑에만 사용되며 데이터 전송에는 포함되지 않습니다.
예를 들어 헤더 행 데이터가 다음과 같다면:- 잘못된 헤더(D열이 비어 있음)
| A | B | C | D | E |
|---|---|---|---|---|
| 이름 | 나이 | 취미 | 학교 |
사전 조건
1. Feishu 자체 구축 앱 준비 및 권한 설정
Refer: https://open.feishu.cn/document/best-practices/intro-to-custom-app-review
Feishu API를 호출하려면 테이블 owner가 Feishu 클라우드 문서 앱(Feishu 기업 자체 구축 앱이라고도 함)에 권한을 부여해야 데이터를 가져올 수 있습니다.
기업 내부 애플리케이션이므로 먼저 권한이 충분히 설정된 앱을 준비해야 합니다.
Feishu 오픈 플랫폼에서 미리 Custom App을 생성하고, Custom App에 스프레드시트 읽기 및 편집 권한을 부여합니다.
부여할 구체적인 권한은 다음과 같습니다.
-
지식 베이스 조회, 편집 및 관리: wiki:wiki
-
문서 조회, 댓글, 편집 및 관리: docs:doc
-
다차원 테이블 조회, 댓글, 편집 및 관리: bitable:app
-
스프레드시트 조회, 댓글, 편집 및 관리: sheets:spreadsheet
-
클라우드 스페이스의 모든 파일 조회, 댓글, 편집 및 관리: drive:drive
-
현재 사용자의 클라우드 문서 권한 보유 여부 확인: docs:permission.member:auth
자세한 내용은 기업 자체 구축 앱 개발 프로세스를 참고하십시오.
2. App ID 및 App Secret 가져오기
Feishu 개발자 콘솔에서 앱 자격 증명을 가져와 AE 데이터 개발 플랫폼의 커넥터에 입력하고 연결 테스트를 통과해야 합니다.
가져온 App id와 Secret을 통합 계획의 데이터 소스 설정에 입력합니다.
3. 연동할 다차원 테이블 찾기
연동할 다차원 테이블에 권한을 할당합니다. 최소한 조직 내 링크를 받은 사람 읽기 가능 권한을 할당해야 합니다.
- 조직 내 링크를 받은 사람 읽기 가능/편집 가능을 선택한 경우, 데이터 개발 플랫폼에서 링크로 Feishu 테이블 데이터를 가져올 때 조직 권한 검증을 수행합니다.
- 인터넷에서 링크를 받은 사람 읽기 가능/편집 가능을 선택한 경우, 해당 링크의 Feishu 테이블 데이터를 바로 가져올 수 있습니다.
기업 데이터 보안에 유의하여 적절한 권한을 할당하고 링크 정보를 안전하게 관리하십시오.
Feishu 다차원 테이블에서 문서 앱을 추가하고, 생성한 Custom App을 추가한 후 해당 읽기 또는 편집 권한을 부여합니다.
4. 다차원 테이블 링크 가져오기
연동할 다차원 테이블 링크를 가져옵니다.
5. 지원하는 다차원 테이블 가져오기 방식
| 다차원 테이블 저장 위치 | 설명 | 지원 여부 |
|---|---|---|
| Wiki 지식 베이스의 다차원 테이블 | 지식 베이스의 리소스는 지식 베이스(wiki)에 연결된 리소스를 말합니다.
| 지원 |
| 개인 Base의 다차원 테이블 | 개인 Feishu 클라우드 드라이브의 다차원 테이블 리소스입니다.
| 지원 |
| Feishu 클라우드 문서(Doc)의 다차원 테이블 | Feishu 클라우드 문서에 삽입된 다차원 테이블 | 아직 지원하지 않음 |
Feishu 다차원 테이블 데이터 소스 생성
데이터 개발 플랫폼 - 통합 모듈에서 Feishu 다차원 테이블 데이터 소스 추가를 선택할 수 있습니다.
데이터 소스 설정 파라미터 정보
데이터 소스에 필요한 설정 정보를 입력하고 연결 테스트를 완료하면 Feishu 다차원 테이블 데이터 소스가 생성됩니다.
| 필드 이름 | 설명 |
|---|---|
| 기본 정보 | |
| *데이터 소스 이름 | 데이터 개발 플랫폼 공간 내에서 고유해야 하며, 영문자, 숫자, 밑줄로 구성하고 숫자나 밑줄로 시작할 수 없습니다 |
| 비고 | 선택 사항 |
| 데이터 소스 설정 | |
| APP ID | 앱 증명서 계정 |
| APP Secret | 앱 증명서 비밀번호 |
| Base URL | 도메인. 기본값은 https://open.feishu.cn입니다. 프라이빗 배포된 Feishu를 사용하는 경우 프라이빗 도메인을 입력하십시오. |
파라미터 이름 앞에 *가 있는 항목은 필수 파라미터이고, *가 없는 항목은 선택 파라미터입니다.
오프라인 동기화 작업 생성
위 단계에 따라 Feishu 다차원 테이블 데이터 소스 생성을 완료하고 연결 테스트에 성공했다면, 실제 시나리오에 맞게 Feishu 다차원 테이블 오프라인 읽기 작업을 구성할 수 있습니다.
Feishu 다차원 테이블을 데이터 소스로 사용
데이터 소스에서 Feishu 다차원 테이블을 선택하고 다음 관련 파라미터를 설정합니다.
| 필드 이름 | 설명 |
|---|---|
| *소스 타입 | 데이터 소스의 대상 타입으로 Feishu 다차원 테이블 선택 |
| *데이터 소스 이름 | 데이터 소스 관리 화면에 등록된 Feishu 데이터 소스이며, 드롭다운에서 선택할 수 있습니다. 해당 데이터 소스를 아직 만들지 않았다면 데이터 소스 관리 버튼을 클릭하여 Feishu 다차원 테이블 데이터 소스를 생성할 수 있습니다. |
| *다차원 테이블 URL | 동기화할 Feishu 다차원 테이블 url을 복사하여 텍스트 상자에 붙여넣고 URL 검증을 클릭합니다 |
| *소스 데이터 테이블 | 읽을 Feishu 다차원 테이블의 데이터 테이블 이름으로, 드롭다운에서 선택할 수 있습니다
|
| *소스 뷰 | 읽을 데이터 테이블의 뷰 이름으로, 드롭다운에서 선택할 수 있습니다
|
데이터를 가져오지 못한 경우 표시될 수 있는 오류 메시지와 처리 방법:
- Feishu 연동 연결 상태를 확인하십시오: 연동이 활성화되지 않았거나 설정 정보가 불완전하거나 token이 만료되었습니다.
- 테이블 정보를 가져올 권한이 없습니다. 해당 API의 인터페이스 권한을 활성화하십시오: Feishu 앱의 API 권한이 활성화되지 않았습니다.
- 유효한 Feishu 다차원 테이블 링크를 입력하십시오: 제공한 링크가 올바른지 확인합니다.
- Feishu 인터페이스 요청 실패: 데이터가 너무 커서 서버 계산 시간이 초과되었거나 이전에 제출한 변경 사항이 아직 처리되지 않았습니다. 적절히 재시도할 수 있습니다.
- 테이블 링크의 권한 설정을 확인하십시오: 스프레드시트와 다차원 테이블의 링크 공유 범위를 조정해야 합니다.
- Feishu API 요청 실패: Feishu 공식 오류 문서에서 해당 오류 원인을 확인할 수 있습니다.
지원 필드 타입
Feishu 스프레드시트에는 강제 Schema 제약이 없으므로, Date, Datetime 필드 타입을 인식하여 특별히 처리하는 경우를 제외하고 데이터 개발 플랫폼은 테이블의 모든 셀을 string으로 처리합니다. 대상 Writer 데이터 소스의 해당 필드도 string 타입으로 하는 것이 좋으며, 그렇지 않으면 데이터 형식 변환 오류로 작업이 실패할 수 있습니다.
- 기본적으로 데이터가 있는 테이블의 마지막 열까지 읽거나 사용자 지정 열 수만큼 읽으며, 중간의 빈 열은 null로 채워집니다
- 빈 행은 Feishu 스프레드시트에서 sheet의 행 수에 포함되므로 빈 데이터가 발생할 수 있습니다.
- 열 이름은 중복될 수 없습니다
- 수식 처리는 지원하지 않습니다
필드 매핑 설명
데이터 소스와 타겟 설정을 완료한 후에는 필드 매핑 관계를 설정해야 합니다. 시스템은 매핑 관계에 따라 소스 필드의 데이터를 타겟 필드로 자동 동기화합니다. 필드 매핑 관계는 다음 세 가지 방식으로 설정할 수 있습니다.
- 방법 1: 직접 선택. 소스 테이블 필드를 선택한 후 타겟 테이블의 타겟 필드를 선택합니다
- 방법 2: 동일 이름으로 매핑. 시스템이 소스 테이블과 타겟 테이블에서 이름이 같은 필드 사이에 매핑 관계를 자동으로 설정합니다
- 방법 3: 동일 행으로 매핑. 시스템이 같은 행에 있는 필드 사이에 매핑 관계를 자동으로 설정합니다
하나의 타겟 필드는 하나의 소스 필드에만 대응할 수 있다는 점에 유의하십시오.
기본 정보 설정
마지막으로 통합 계획의 기본 정보를 설정해야 합니다. 계획 이름, 담당자, 통합 동기화 속도, 비고 등이 포함됩니다.
설정을 완료한 후 저장 버튼을 클릭하면 통합 계획 생성이 완료됩니다.
참고: 계획 이름은 저장 후 수정할 수 없습니다
상세 페이지:
오프라인 동기화 계획을 작업 플로우에 연결
작업 플로우에 연결
1. 연결 시작
- 통합 계획 상세 페이지에서 오른쪽 상단의 작업 플로우에 연결 버튼을 클릭합니다
2. 작업 플로우 선택
-
드롭다운 메뉴에서 대상 작업 플로우를 선택합니다
-
새 작업 플로우를 만들려면:
- 드롭다운 메뉴 아래의 새 작업 플로우 바로가기 버튼을 클릭합니다
- 또는 개발 모듈로 이동하여 생성합니다
-
팁: 대상 작업 플로우가 표시되지 않으면 오른쪽의 ↻ 새로고침 버튼을 클릭합니다
3. 동기화 노드 생성
- 작업 플로우에서 오프라인 동기화 계획 타입의 노드를 새로 만듭니다
- 이 노드는 현재 통합 계획과 연관되며, 노드가 실행되면 해당 통합 계획의 실행이 트리거됩니다
4. 연결 완료
- 노드 생성 및 연결을 클릭하여 설정을 완료합니다
- 연결에 성공하면 작업 플로우로 이동을 클릭하여 연결 결과를 바로 확인할 수 있습니다
참고: 작업 플로우에 연결하여 생성된 작업 노드는 아직 배포되지 않은 상태입니다. 작업 플로우로 이동하여 확인한 후 해당 노드를 배포하여 라이브 상태로 전환하는 것을 권장합니다.
작업 플로우 연결 해제
오프라인 동기화 계획의 작업 플로우 연결을 해제하려면 다음과 같이 진행합니다.
- 작업 플로우가 아직 배포되지 않았다면, 해당 계획이 연결된 작업 플로우로 이동하여 개발 모드에서 해당 오프라인 동기화 계획 작업 노드를 삭제하면 됩니다.
- 작업 플로우가 이미 배포되어 라이브 상태라면, 개발 모드에서 해당 오프라인 동기화 계획 작업 노드를 삭제한 후 작업 플로우를 다시 배포해야 합니다. 이렇게 하면 운영 환경에서도 해당 노드의 연결이 함께 해제됩니다.