가져오기, 설정, 삭제
twenty-sdk/logic-function에서 kv를 임포트하세요. 값은 JSON으로 직렬화할 수 있는 모든 페이로드가 될 수 있습니다.
src/logic-functions/sync-linear-issues.ts
범위
각 항목에는 스코프가 있으며, 모든 호출에서 옵션으로 전달됩니다. 기본값은WORKSPACE입니다.
WORKSPACE(기본값) — 항목은 현재 워크스페이스에 설치된 앱 인스턴스에만 비공개입니다. 앱을 설치한 각 워크스페이스는 자체적인 독립 키 집합을 가집니다. 캐시, 커서, 워크스페이스별 상태에는 이 스코프를 사용하는 것이 적합합니다.SERVER— 항목은 서버에서 실행 중인 앱의 모든 설치 간에 공유됩니다. 서버 항목은 **클레임(claim)**처럼 동작합니다. 저장된 값은 항상 해당 키를 클레임한 workspaceId이며(set에서value를 생략하면 현재 워크스페이스에 대해 키를 클레임합니다), 그 워크스페이스만 해당 값을 덮어쓰거나 삭제할 수 있습니다. 어떤 설치에서든 해당 항목을 읽을 수 있습니다.
kv.set은 예외를 발생시킵니다.
사용 예: 비용이 큰 호출 캐시하기
일반적인 사용 예는 느리거나 rate limit이 걸린 서드파티 응답을 캐시해서, 반복 실행 시 매번 비용을 지불하지 않고 재사용하도록 하는 것입니다.src/logic-functions/getExchangeRate.logic-function.ts
패턴 및 팁
- 네임스페이스 구성. 서로 다른 관심사를 분리하기 위해 키에 접두사를 붙이세요 —
sync-cursor:linear,cache:exchange-rate:USD:EUR,lock:nightly-report. - 만료(TTL). 이 스토어에는 내장된 만료 기능이 없습니다. 값 안에 타임스탬프를 저장해(캐시 예제처럼) 읽을 때 확인하거나, cron-triggered function을 통해 오래된 키를 주기적으로 정리하세요.
- 무엇을 저장할지. 숫자, 문자열, 배열, 객체 등 JSON으로 직렬화 가능한 어떤 값이든 저장할 수 있습니다. 엔트리는 작게 유지하세요. 이 스토어는 대용량 blob이나 파일이 아니라, 조정 및 캐싱용입니다. 파일의 경우
FILES필드와uploadFile을 사용하세요. - 가시성. 항목은 워크스페이스 레코드가 아니라 인스턴스 데이터베이스에 저장됩니다. 따라서 워크스페이스 UI에 나타나지 않고, 앱의 데이터 모델의 일부도 아니며, 역할이나 객체 권한도 필요하지 않습니다.
대안: 조회 가능한 스토어 객체
기본 제공 스토어는 의도적으로 불투명합니다. 항목이 레코드가 아니기 때문에 UI에서 탐색하거나, 다른 객체와 관계를 맺거나, 레코드 쿼리로 필터링할 수 없습니다. 이러한 기능이 필요할 때(예: 눈에 보이는 동기화 로그나 레코드별 상태 등)에는 고유한key 필드와 RAW_JSON value 필드를 가진 작은 technical object를 정의하고, typed API client를 통해 이를 쿼리하세요. defineObject 레퍼런스는 Objects를, 키의 고유성을 강제하려면 Data → Unique indexes를 참고하세요.
- 레코드에 스코프 지정하기. ID를 키에 인코딩하지 말고, 스토어 객체에서 대상 객체로 relation을 추가하세요.
- 가시성 및 권한. 행은 다른 레코드와 마찬가지로 워크스페이스 데이터베이스에 저장되므로, API를 통해 조회할 수 있고 앱의 role을 그대로 따릅니다. 스토어를 기본 UI에서 숨기고 싶다면, navigation menu에 추가하지 마세요.
기본 제공 스토어와 달리 커스텀 객체는 항상 하나의 워크스페이스에만 스코프가 지정되며,
SERVER 키처럼 설치 간에 항목을 공유할 수 없습니다.