Box용 Openflow 커넥터 설정

미리 보기 기능(Preview Feature)

Snowflake 커넥터는 Snowflake Openflow를 사용할 수 있는 모든 리전에서 지원돼요.

Openflow Snowflake 배포는 AWS, Azure, GCP 상용 리전의 모든 계정에서 사용할 수 있어요.

BYOC 배포의 Snowflake Openflow는 AWS 상용 리전(상용 리전)의 모든 계정에서만 사용할 수 있어요.

참고

이 커넥터는 Snowflake 커넥터 약관의 적용을 받아요.

이 항목에서는 Box용 Openflow 커넥터를 설정하는 단계를 설명해요.

사전 요구 사항

Box용 Openflow 커넥터 소개를 검토했는지 확인하세요.
Openflow - Snowflake 배포 설정 또는 Openflow - BYOC 설정을 완료했는지 확인하세요.
Openflow - Snowflake 배포를 사용하는 경우 필수 도메인 구성을 검토했고, Box 커넥터의 필수 도메인에 접근 권한을 부여했는지 확인하세요.

자격 증명 가져오기

Box 개발자 또는 Box 관리자로서 Box Platform 애플리케이션을 다음과 같이 만들어요.

Box 개발자 콘솔(Developer Console)로 이동해요.
Create Platform App을 선택해요.
애플리케이션 유형으로 Custom App을 선택해요.
앱의 이름과 설명을 제공하고 드롭다운 목록에서 용도를 선택해요.
인증 방법으로 Server Authentication (with JWT) 을 선택해요.
Create App을 선택해요.
앱을 구성하려면 Configuration 탭으로 이동해요.
App Access Level 섹션에서 App + Enterprise Access를 선택해요.
Application Scopes 섹션에서 다음 옵션을 선택해요.
- Read all files and folders stored in Box(Box에 저장된 모든 파일·폴더 읽기).
- Write all files and folders stored in Box(Box에 저장된 모든 파일·폴더 쓰기): 파일·폴더를 다운로드하기 위한 것입니다. 커넥터는 파일을 업로드할 수 없어요. Snowflake는 서비스 계정에 Viewer 역할만 부여하는 것을 권장해요. Box의 파일에 애플리케이션이 접근하도록 하려면 동기화하려는 폴더를 선택하고, General Settings 탭에서 저장한 서비스 계정의 이메일로 앱 서비스 계정과 공유하세요. Box용 Openflow 커넥터는 지정된 폴더와 모든 하위 폴더의 파일을 발견·다운로드할 수 있지만 파일을 수정할 수는 없어요.
- Manage users: 엔터프라이즈의 사용자를 읽기 위함.
- Manage groups: 엔터프라이즈의 그룹과 구성원을 읽기 위함.
- Manage enterprise properties: 엔터프라이즈 이벤트를 읽기 위함.
Add and Manage Public Keys 섹션에서 공개/비공개 키 페어를 생성해요. Box가 비공개 키가 포함된 JSON 구성 파일을 다운로드해요.
변경 사항을 저장해요.
Authorization 탭으로 이동해 엔터프라이즈 접근 권한 부여를 위해 앱을 제출해요.
엔터프라이즈 관리자에게 앱 승인을 요청해요.
승인이 나면 General Settings 탭으로 가서 앱 서비스 계정 이메일 주소를 저장해요.

자세한 내용은 JWT를 사용한 설정을 참조하세요.

Snowflake 계정 설정

Openflow 관리자로서 다음 작업을 수행해 Snowflake 계정을 설정하세요. 기본 SNOWFLAKE_MANAGED 인증 전략에서는 런타임의 execute-as 역할이 커넥터가 Snowflake에 접근할 때 사용하는 ID이므로 다음 권한을 부여하세요.

참고

Openflow - BYOC 배포에 커넥터를 배포하고, 권장되는 SNOWFLAKE_MANAGED 대신 KEY_PAIR 인증 전략을 사용한다면 런타임의 관리 토큰에 의존하는 대신 동일한 execute-as 역할을 서비스 사용자에게도 부여해야 해요. 서비스 사용자를 만들려면 Openflow - BYOC 배포의 키 페어 인증 설정을 참조하세요.

데이터베이스, 스키마, 웨어하우스 만들기

대상 데이터베이스를 만들어요.

USE ROLE OPENFLOW_ADMIN;
CREATE DATABASE IF NOT EXISTS <destination_database>;

대상 스키마를 만들어요.

CREATE SCHEMA IF NOT EXISTS <destination_database>.<destination_schema>;

런타임의 execute-as 역할에 필요한 권한을 부여해요.

GRANT USAGE ON DATABASE <destination_database> TO ROLE OPENFLOW_<RUNTIME_NAME>_EXECUTE_AS_RL;
GRANT USAGE ON SCHEMA <destination_database>.<destination_schema> TO ROLE OPENFLOW_<RUNTIME_NAME>_EXECUTE_AS_RL;
GRANT CREATE TABLE, CREATE DYNAMIC TABLE, CREATE STAGE, CREATE SEQUENCE ON SCHEMA <destination_database>.<destination_schema>
  TO ROLE OPENFLOW_<RUNTIME_NAME>_EXECUTE_AS_RL;

웨어하우스(또는 기존 웨어하우스)를 만들고 사용 권한을 부여해요.

CREATE WAREHOUSE IF NOT EXISTS <openflow_warehouse>
  WITH
  WAREHOUSE_SIZE = 'XSMALL'
  AUTO_SUSPEND = 300
  AUTO_RESUME = TRUE;

GRANT USAGE, OPERATE ON WAREHOUSE <openflow_warehouse> TO ROLE OPENFLOW_<RUNTIME_NAME>_EXECUTE_AS_RL;

커넥터가 수집한 원시 문서와 테이블에 다른 Snowflake 사용자가 접근해야 한다면(예: Snowflake에서 맞춤 처리용), 해당 사용자에게 execute-as 역할을 부여하세요.

Cortex Search 권한 부여

파일 수집 및 Cortex로 처리(Ingest files and perform processing with Cortex) 사용 사례에 커넥터를 사용한다면 다음 작업도 수행하세요.

이 커넥터가 만든 Cortex Search 서비스에 대한 읽기 접근 역할을 만들고, 서비스를 사용할 역할에 부여해요.

USE ROLE SECURITYADMIN;
CREATE ROLE IF NOT EXISTS <cortex_search_service_read_only_role>;
GRANT ROLE <cortex_search_service_read_only_role> TO ROLE <whatever_roles_will_access_search_service>;

Cortex Search 서비스를 만들 권한을 부여하고, 읽기 전용 역할에 데이터베이스·스키마 접근 권한을 부여해요.

GRANT CREATE CORTEX SEARCH SERVICE ON SCHEMA <destination_database>.<destination_schema> TO ROLE OPENFLOW_<RUNTIME_NAME>_EXECUTE_AS_RL;
GRANT USAGE ON DATABASE <destination_database> TO ROLE <cortex_search_service_read_only_role>;
GRANT USAGE ON SCHEMA <destination_database>.<destination_schema> TO ROLE <cortex_search_service_read_only_role>;

사용 사례

다음 사용 사례에 커넥터를 구성할 수 있어요.

파일만 수집(Ingest files only)
파일 수집 및 Cortex로 처리
Box AI로 Box 메타데이터를 추출해 Snowflake 테이블로 수집
Box 파일 메타데이터 인스턴스를 Snowflake 테이블과 동기화

파일만 수집

커넥터 정의를 사용해 수집된 파일에 맞춤 처리를 수행해요.

커넥터 설정

데이터 엔지니어로서 다음 작업을 수행해 커넥터를 설치·구성하세요.

커넥터 설치

데이터 엔지니어로서 커넥터를 설치하려면 다음을 수행하세요.

Openflow의 커넥터 라이브러리(Connector library) 탭으로 이동해요.
Openflow 커넥터 페이지에서 커넥터를 찾아 설치(Install) 를 선택해요.
런타임 선택(Select runtime) 대화상자에서 사용 가능한 런타임(Available runtimes) 드롭다운 목록에서 런타임을 선택하고 설치를 클릭해요.

참고

커넥터를 설치하기 전에 커넥터가 수집한 데이터를 저장할 데이터베이스와 스키마를 Snowflake에 만들어 두었는지 확인하세요.

Snowflake 계정 자격 증명으로 배포에 인증하고, 런타임 애플리케이션이 Snowflake 계정에 접근하도록 허용하라는 메시지가 표시되면 허용(Allow) 을 선택해요. 커넥터 설치 프로세스는 완료하는 데 몇 분 걸려요.
Snowflake 계정 자격 증명으로 런타임에 인증해요.

커넥터 프로세스 그룹이 추가된 Openflow 캔버스가 나타나요.

커넥터 구성

가져온 프로세스 그룹을 오른쪽 클릭하고 매개변수(Parameters) 를 선택해요.
Box 수집 매개변수, Box 대상 매개변수, Box 소스 매개변수에 설명된 대로 필수 매개변수 값을 입력해요.

Box 소스 매개변수

매개변수	설명
Box App Config JSON	앱 생성 중 다운로드한 애플리케이션 JSON 구성.
Box App Config File	앱 생성 중 다운로드한 애플리케이션 JSON 파일. "Box App Config File" 또는 "Box App Config JSON" 중 하나를 설정해야 해요. 구성 파일을 업로드하려면 Reference asset 확인란을 선택하세요.

Box 대상 매개변수

참고

execute-as 역할에 대한 자세한 내용은 관련 설정 문서를 참조하세요.

매개변수	설명	필수
Destination Database	데이터가 저장될 데이터베이스. Snowflake에 이미 존재해야 해요. 이름은 대소문자를 구분해요. 따옴표 없는 식별자는 대문자로 제공하세요.	예
Destination Schema	데이터가 저장될 스키마. Snowflake에 이미 존재해야 해요. 이름은 대소문자를 구분해요. 따옴표 없는 식별자는 대문자로 제공하세요. 예: CREATE SCHEMA SCHEMA_NAME 또는 CREATE SCHEMA schema_name → SCHEMA_NAME 사용. CREATE SCHEMA "schema_name" 또는 CREATE SCHEMA "SCHEMA_NAME" → 각각 schema_name 또는 SCHEMA_NAME 사용	예
Snowflake Authentication Strategy	사용 시: Snowflake Openflow 배포 또는 BYOC: SNOWFLAKE_MANAGED를 사용해요. 이 토큰은 Snowflake가 자동으로 관리해요. BYOC 배포는 SNOWFLAKE_MANAGED를 사용하기 위해 이전에 execute-as 역할을 구성해야 해요. BYOC: 대안으로 BYOC는 인증 전략 값으로 KEY_PAIR를 사용할 수 있어요.	예
Snowflake Account Identifier	사용 시: SNOWFLAKE_MANAGED 인증 전략: 비워 두어야 해요. KEY_PAIR: [조직 이름]-[계정 이름] 형식의 Snowflake 계정 이름.	예
Snowflake Private Key	사용 시: SNOWFLAKE_MANAGED 인증 전략: 비워 두어야 해요. KEY_PAIR: PKCS8 표준에 따라 형식화되고 표준 PEM 헤더·푸터를 포함하는 인증용 RSA 프라이빗 키. Snowflake Private Key File 또는 Snowflake Private Key 중 하나를 정의해야 해요.	아니요
Snowflake Private Key File	사용 시: SNOWFLAKE_MANAGED 인증 전략: 프라이빗 키 파일은 비워 두어야 해요. KEY_PAIR: PKCS8 표준에 따라 형식화되고 표준 PEM 헤더·푸터를 포함하는, Snowflake에 인증하는 데 사용되는 RSA 프라이빗 키가 들어 있는 파일을 업로드해요. 헤더 줄은 -----BEGIN PRIVATE로 시작해요. 프라이빗 키 파일을 업로드하려면 Reference asset 확인란을 선택하세요.	아니요
Snowflake Private Key Password	사용 시: SNOWFLAKE_MANAGED 인증 전략: 비워 두어야 해요. KEY_PAIR: Snowflake 프라이빗 키 파일과 연결된 비밀번호를 제공해요.	아니요
Snowflake Role	사용 시: SNOWFLAKE_MANAGED 인증 전략: 런타임의 execute-as 역할(또는 그에 부여된 하위 역할)을 사용해요. execute-as 역할은 Openflow UI의 런타임에 대한 View Details로 이동해 찾을 수 있어요. KEY_PAIR: 서비스 사용자에 대해 구성된 유효한 역할을 사용해요.	예
Snowflake Username	사용 시: SNOWFLAKE_MANAGED 인증 전략: 비워 두어야 해요. KEY_PAIR: Snowflake 인스턴스에 연결하는 데 사용되는 사용자 이름을 제공해요.	예
Snowflake Warehouse	쿼리를 실행하는 데 사용되는 Snowflake 웨어하우스.	예

Box 수집 매개변수

Box Folder ID는 파일을 읽어올 폴더의 ID예요. 0으로 설정하면 Box 앱이 접근할 수 있는 모든 폴더를 동기화해요. ID는 예를 들어 https://app.box.com/folder/FOLDER_ID URL에서 가져올 수 있어요.

매개변수	설명
Box Folder ID	파일을 읽어올 폴더의 ID. 0으로 설정하면 Box 앱이 접근할 수 있는 모든 폴더를 동기화. 예를 들어 https://app.box.com/folder/FOLDER_ID URL에서 가져올 수 있음.
File Extensions To Ingest	수집할 파일 확장자를 지정하는 쉼표로 구분된 목록. 커넥터는 가능하면 파일을 먼저 PDF 형식으로 변환하려고 해요. 그럼에도 확장자 검사는 원본 파일 확장자에 대해 수행돼요. 지정된 일부 파일 확장자가 Cortex Parse Document에서 지원되지 않으면, 커넥터는 해당 파일을 무시하고 이벤트 로그에 경고 메시지를 기록한 다음 다른 파일 처리를 계속해요.
Snowflake File Hash Table Name	내용이 변경되었는지 확인하기 위해 파일 해시를 저장하는 테이블 이름. 이 매개변수는 일반적으로 변경하면 안 돼요.

플로우 실행

캔버스를 오른쪽 클릭하고 모든 컨트롤러 서비스 활성화(Enable all Controller Services) 를 선택해요.
가져온 프로세스 그룹을 오른쪽 클릭하고 시작(Start) 을 선택해요. 커넥터가 데이터 수집을 시작해요.

커넥터를 시작하면 지정된 폴더의 모든 파일을 검색한 다음 지난 14일 이내의 admin_logs_streaming 이벤트를 소비해요. 이는 초기화 과정에서 놓칠 수 있었던 데이터를 캡처하기 위함이에요. 그 동안 이벤트에는 나타나지만 더 이상 존재하지 않는 파일로 인해 not found 오류가 발생할 수 있어요.

파일 수집 및 Cortex로 처리

커넥터 정의를 사용해 다음을 수행하세요.

조직의 Box 엔터프라이즈 내 공개 문서용 AI 어시스턴트 만들기
AI 어시스턴트가 조직의 Box 엔터프라이즈에 지정된 접근 제어를 준수하도록 지원

커넥터 설정

커넥터 설치

데이터 엔지니어로서 커넥터를 설치하려면 다음을 수행하세요.

Openflow의 커넥터 라이브러리 탭으로 이동해요.
Openflow 커넥터 페이지에서 커넥터를 찾아 설치를 선택해요.
런타임 선택 대화상자에서 사용 가능한 런타임 드롭다운 목록에서 런타임을 선택하고 설치를 클릭해요.

참고

커넥터를 설치하기 전에 커넥터가 수집한 데이터를 저장할 데이터베이스와 스키마를 Snowflake에 만들어 두었는지 확인하세요.

Snowflake 계정 자격 증명으로 배포에 인증하고, 런타임 애플리케이션이 Snowflake 계정에 접근하도록 허용하라는 메시지가 표시되면 허용을 선택해요. 커넥터 설치 프로세스는 완료하는 데 몇 분 걸려요.
Snowflake 계정 자격 증명으로 런타임에 인증해요.

커넥터 프로세스 그룹이 추가된 Openflow 캔버스가 나타나요.

커넥터 구성

가져온 프로세스 그룹을 오른쪽 클릭하고 매개변수를 선택해요.
Box Cortex Connect 수집 매개변수, Box Cortex Connect 대상 매개변수, Box Cortex Connect 소스 매개변수에 설명된 대로 필수 매개변수 값을 입력해요.

Box Cortex Connect 소스 매개변수

매개변수	설명
Box App Config JSON	앱 생성 중 다운로드한 애플리케이션 JSON 구성.
Box App Config File	앱 생성 중 다운로드한 애플리케이션 JSON 파일. "Box App Config File" 또는 "Box App Config JSON" 중 하나를 설정해야 해요. 구성 파일을 업로드하려면 Reference asset 확인란을 선택하세요.

Box Cortex Connect 대상 매개변수

매개변수	설명	필수
Destination Database	데이터가 저장될 데이터베이스. Snowflake에 이미 존재해야 해요. 이름은 대소문자를 구분해요. 따옴표 없는 식별자는 대문자로 제공하세요.	예
Destination Schema	데이터가 저장될 스키마. Snowflake에 이미 존재해야 해요. 이름은 대소문자를 구분해요. 따옴표 없는 식별자는 대문자로 제공하세요.	예
Snowflake Authentication Strategy	사용 시: Snowflake Openflow 배포 또는 BYOC: SNOWFLAKE_MANAGED를 사용해요. BYOC 배포는 SNOWFLAKE_MANAGED를 사용하기 위해 이전에 execute-as 역할을 구성해야 해요. BYOC: 대안으로 BYOC는 인증 전략 값으로 KEY_PAIR를 사용할 수 있어요.	예
Snowflake Account Identifier	사용 시: SNOWFLAKE_MANAGED 인증 전략: 비워 두어야 해요. KEY_PAIR: [조직 이름]-[계정 이름] 형식의 Snowflake 계정 이름.	예
Snowflake Private Key	사용 시: SNOWFLAKE_MANAGED 인증 전략: 비워 두어야 해요. KEY_PAIR: PKCS8 표준에 따라 형식화되고 표준 PEM 헤더·푸터를 포함하는 인증용 RSA 프라이빗 키.	아니요
Snowflake Private Key File	사용 시: SNOWFLAKE_MANAGED 인증 전략: 프라이빗 키 파일은 비워 두어야 해요. KEY_PAIR: 인증에 사용되는 RSA 프라이빗 키가 들어 있는 파일을 업로드해요. 헤더 줄은 -----BEGIN PRIVATE로 시작해요. Reference asset 확인란을 선택해 업로드하세요.	아니요
Snowflake Private Key Password	사용 시: SNOWFLAKE_MANAGED 인증 전략: 비워 두어야 해요. KEY_PAIR: Snowflake 프라이빗 키 파일과 연결된 비밀번호를 제공해요.	아니요
Snowflake Role	사용 시: SNOWFLAKE_MANAGED 인증 전략: 런타임의 execute-as 역할(또는 그에 부여된 하위 역할)을 사용해요. KEY_PAIR: 서비스 사용자에 대해 구성된 유효한 역할을 사용해요.	예
Snowflake Username	사용 시: SNOWFLAKE_MANAGED 인증 전략: 비워 두어야 해요. KEY_PAIR: Snowflake 인스턴스에 연결하는 데 사용되는 사용자 이름을 제공해요.	예
Snowflake Warehouse	쿼리를 실행하는 데 사용되는 Snowflake 웨어하우스.	예

Box Cortex Connect 수집 매개변수

Box Folder ID는 파일을 읽어올 폴더의 ID이며 URL에서 가져올 수 있어요. OCR 모드는 AI_PARSE_DOCUMENT로 문서 파싱 함수로 파일을 파싱할 때 사용하는 OCR 모드예요.

매개변수	설명
Box Folder ID	파일을 읽어올 폴더의 ID. 0으로 설정하면 Box 앱이 접근할 수 있는 모든 폴더를 동기화. 예를 들어 https://app.box.com/folder/FOLDER_ID URL에서 가져올 수 있음.
File Extensions To Ingest	수집할 파일 확장자를 지정하는 쉼표로 구분된 목록. 커넥터는 가능하면 파일을 먼저 PDF 형식으로 변환하려고 해요. 확장자 검사는 원본 파일 확장자에 대해 수행돼요. 지원되지 않는 확장자는 무시하고 경고를 기록한 뒤 계속 처리해요.
Snowflake File Hash Table Name	내용 변경 확인을 위해 파일 해시를 저장하는 테이블 이름. 일반적으로 변경하면 안 됨.
OCR Mode	AI_PARSE_DOCUMENT로 문서 파싱 함수로 파일을 파싱할 때 사용하는 OCR 모드. 값은 OCR 또는 LAYOUT일 수 있음.
Snowflake Cortex Search Service User Role	Cortex Search 서비스에 사용 권한이 부여된 역할의 식별자.

플로우 실행

캔버스를 오른쪽 클릭하고 모든 컨트롤러 서비스 활성화를 선택해요.
가져온 프로세스 그룹을 오른쪽 클릭하고 시작을 선택해요. 커넥터가 데이터 수집을 시작해요.

Cortex Search 서비스 쿼리

Cortex Search 서비스를 사용해 Box의 문서와 채팅하거나 검색하는 채팅·검색 애플리케이션을 구축할 수 있어요.

커넥터를 설치·구성하고 Box에서 콘텐츠 수집을 시작하면 Cortex Search 서비스를 쿼리할 수 있어요. Cortex Search 사용에 대한 자세한 내용은 Cortex Search 서비스 쿼리를 참조하세요.

응답 필터링

Cortex Search 서비스의 응답을 특정 사용자가 Box에서 접근 권한이 있는 문서로 제한하려면, Cortex Search를 쿼리할 때 사용자의 ID 또는 이메일 주소가 포함된 필터를 지정할 수 있어요. 예: [email protected]_ids 또는 [email protected]_emails. 커넥터가 만든 Cortex Search 서비스의 이름은 Cortex 스키마의 search_service예요.

SQL 워크시트에서 다음 SQL 코드를 실행해 Box에서 수집한 파일로 Cortex Search 서비스를 쿼리해요.

다음을 바꾸세요.

*application_instance_name*: 데이터베이스 및 커넥터 애플리케이션 인스턴스의 이름.
*user_emailID*: 응답을 필터링할 사용자의 이메일 ID.
*your_question*: 응답을 받을 질문.
*number_of_results*: 응답에서 반환할 최대 결과 수. 최대값은 1,000이고 기본값은 10.

SELECT PARSE_JSON(
  SNOWFLAKE.CORTEX.SEARCH_PREVIEW(
    '<application_instance_name>.cortex.search_service',
      '{
        "query": "<your_question>",
         "columns": ["chunk", "web_url"],
         "filter": {"@contains": {"user_emails": "<user_emailID>"} },
         "limit": <number_of_results>
       }'
   )
)['results'] AS results

columns에 입력할 수 있는 값의 전체 목록은 다음과 같아요.

열 이름	유형	설명
full_name	String	Box 폴더 루트부터의 파일 전체 경로. 예: folder_1/folder_2/file_name.pdf.
web_url	String	브라우저에서 원본 Box 파일을 표시하는 URL.
last_modified_date_time	String	항목이 가장 최근에 수정된 날짜와 시간.
chunk	String	Cortex Search 쿼리와 일치한 문서의 텍스트 조각.
user_ids	Array	문서에 접근 권한이 있는 사용자 ID 배열.
user_emails	Array	문서에 접근 권한이 있는 사용자 이메일 ID 배열.

예제: 인사(HR) 정보용 AI 어시스턴트 쿼리

Cortex Search를 사용해 직원용 AI 어시스턴트를 쿼리해 온보딩, 행동 강령, 팀 프로세스, 조직 정책 같은 최신 HR 정보와 채팅할 수 있어요. 응답 필터를 사용하면 Box에서 구성된 접근 제어를 준수하면서 HR 팀 구성원이 직원 계약서를 쿼리하도록 허용할 수도 있어요.

SQL 워크시트에서 다음을 실행해 Box에서 수집한 파일로 Cortex Search 서비스를 쿼리해요. 데이터베이스는 애플리케이션 인스턴스 이름으로, 스키마는 Cortex로 선택하세요.

다음을 바꾸세요.

*application_instance_name*: 데이터베이스 및 커넥터 애플리케이션 인스턴스의 이름.
*user_emailID*: 응답을 필터링할 사용자의 이메일 ID.

SELECT PARSE_JSON(
     SNOWFLAKE.CORTEX.SEARCH_PREVIEW(
          '<application_instance_name>.cortex.search_service',
          '{
             "query": "What is my vacation carryover policy?",
             "columns": ["chunk", "web_url"],
             "filter": {"@contains": {"user_emails": "<user_emailID>"} },
             "limit": 1
          }'
     )
 )['results'] AS results

Python 워크시트에서 다음 코드를 실행해 Box에서 수집한 파일로 Cortex Search 서비스를 쿼리해요. 데이터베이스에 snowflake.core 패키지를 추가했는지 확인하세요.

다음을 바꾸세요.

*application_instance_name*: 데이터베이스 및 커넥터 애플리케이션 인스턴스의 이름.
*user_emailID*: 응답을 필터링할 사용자의 이메일 ID.

import snowflake.snowpark as snowpark
from snowflake.snowpark import Session
from snowflake.core import Root

def main(session: snowpark.Session):

   root = Root(session)

   # fetch service
   my_service = (root
     .databases["<application_instance_name>"]
     .schemas["cortex"]
     .cortex_search_services["search_service"]
   )

   # query service
   resp = my_service.search(
     query="What is my vacation carryover policy?",
     columns = ["chunk", "web_url"],
     filter = {"@contains": {"user_emails": "<user_emailID>"} },
     limit=1
   )
   return (resp.to_json())

명령줄 인터페이스에서 다음 코드를 실행해 Box에서 수집한 파일로 Cortex Search 서비스를 쿼리해요. Snowflake REST API에 접근하려면 키 페어 인증과 OAuth를 모두 통한 인증이 필요해요. 자세한 내용은 REST API와 Snowflake로 Snowflake REST API 인증을 참조하세요.

다음을 바꾸세요.

*application_instance_name*: 데이터베이스 및 커넥터 애플리케이션 인스턴스의 이름.
*account_url*: Snowflake 계정 URL. 계정 URL 찾는 방법은 계정의 조직·계정 이름 찾기를 참조하세요.

curl --location "https://<account_url>/api/v2/databases/<application_instance_name>/schemas/cortex/cortex-search-services/search_service" \
     --header 'Content-Type: application/json' \
     --header 'Accept: application/json' \
     --header "Authorization: Bearer <CORTE...JWT>" \
     --data '{
         "query": "What is my vacation carryover policy?",
         "columns": ["chunk", "web_url"],
         "limit": 1
     }'

샘플 응답:

{
  "results" : [ {
  "web_url" : "https://<domain>.box.com/sites/<site_name>/<path_to_file>",
  "chunk" : "Answer to the question asked."
  } ]
}

Box AI로 Box 메타데이터를 추출해 Snowflake 테이블로 수집

커넥터 정의를 사용해 다음을 수행하세요.

Box 파일에 대한 메타데이터를 추출해 Snowflake 테이블로 수집
Box에 저장된 파일의 메타데이터에 대한 작업 수행

Box 메타데이터 저장용 Snowflake 테이블 만들기

메타데이터 추출이 발생하려면 Box AI가 활성화되어 있는지 확인하세요. 자세한 내용은 Box AI 구성을 참조하세요.
메타데이터가 전송될 Snowflake 테이블을 만들어요. 커넥터가 어떤 종류의 메타데이터를 추출할지 알 수 있도록, 추출하려는 필드의 열 이름으로 데이터베이스·스키마에 Snowflake 테이블을 만들어야 해요. 파일에서 메타데이터를 추출하는 데 사용되는 모델의 성능을 높이려면 각 열에 설명을 추가하세요.
이전 단계에서 만든 테이블에 Box 파일 ID를 저장할 열이 있고 그 유형이 VARCHAR인지 확인하세요. 이 열의 이름은 이후 단계에서 Box File Identifier Column 매개변수로 입력해야 해요. 메타데이터 테이블에 지원되는 열 유형 목록은 VARCHAR, STRING, TEXT, FLOAT, DOUBLE, DATE예요.

이 커넥터에 만들 수 있는 테이블의 예는 다음과 같아요.

CREATE OR REPLACE TABLE OPENFLOW.BOX_METADATA_SCHEMA.LOAN_AGREEMENT_METADATA (
  BOX_FILE_ID               VARCHAR    COMMENT 'Box file identifier column',
  LOAN_ID                   STRING     COMMENT 'Unique loan agreement identifier (e.g. L-2025-0001)',
  BORROWER_NAME             STRING     COMMENT 'Name of the borrower entity or individual',
  LENDER_NAME               STRING     COMMENT 'Name of the lending institution',
  LOAN_AMOUNT               DOUBLE     COMMENT 'Principal amount of the loan (in USD)',
  INTEREST_RATE             FLOAT      COMMENT 'Annual interest rate (%)',
  EFFECTIVE_DATE            DATE       COMMENT 'Date on which the loan becomes effective',
  MATURITY_DATE             DATE       COMMENT 'Scheduled loan maturity date',
  LOAN_TERM_MONTHS          FLOAT      COMMENT 'Original term length in months',
  COLLATERAL_DESCRIPTION    TEXT       COMMENT 'Description of collateral securing the loan',
  CREDIT_SCORE              FLOAT      COMMENT 'Borrower credit score',
  JURISDICTION              STRING     COMMENT 'Governing law jurisdiction (e.g. NY, CA)'
);

커넥터 설정

데이터 엔지니어로서 커넥터를 설치·구성하려면 다음 작업을 수행하세요.

커넥터 설치

Openflow의 커넥터 라이브러리 탭으로 이동해요.
Openflow 커넥터 페이지에서 커넥터를 찾아 설치를 선택해요.
런타임 선택 대화상자에서 사용 가능한 런타임 드롭다운 목록에서 런타임을 선택하고 설치를 클릭해요.

참고

커넥터를 설치하기 전에 커넥터가 수집한 데이터를 저장할 데이터베이스와 스키마를 Snowflake에 만들어 두었는지 확인하세요.

Snowflake 계정 자격 증명으로 배포에 인증하고, 런타임 애플리케이션이 Snowflake 계정에 접근하도록 허용하라는 메시지가 표시되면 허용을 선택해요. 커넥터 설치 프로세스는 완료하는 데 몇 분 걸려요.
Snowflake 계정 자격 증명으로 런타임에 인증해요. Openflow 캔버스가 커넥터 프로세스 그룹과 함께 나타나요.

커넥터 구성

가져온 프로세스 그룹을 오른쪽 클릭하고 매개변수를 선택해요.
Box Ingest Metadata 소스 매개변수, Box Ingest Metadata 대상 매개변수, Box Ingest Metadata 수집 매개변수에 설명된 대로 필수 매개변수 값을 입력해요.

Box Ingest Metadata 소스 매개변수

매개변수	설명
Box App Config JSON	앱 생성 중 다운로드한 애플리케이션 JSON 구성.
Box App Config File	앱 생성 중 다운로드한 애플리케이션 JSON 파일. "Box App Config File" 또는 "Box App Config JSON" 중 하나를 설정해야 해요. Reference asset 확인란을 선택해 업로드하세요.

Box Ingest Metadata 대상 매개변수

매개변수	설명	필수
Destination Database	데이터가 저장될 데이터베이스. Snowflake에 이미 존재해야 해요. 이름은 대소문자를 구분해요.	예
Destination Schema	데이터가 저장될 스키마. Snowflake에 이미 존재해야 해요. 이름은 대소문자를 구분해요.	예
Snowflake Authentication Strategy	사용 시: Snowflake Openflow 배포 또는 BYOC: SNOWFLAKE_MANAGED를 사용해요. BYOC 배포는 SNOWFLAKE_MANAGED를 사용하기 위해 이전에 execute-as 역할을 구성해야 해요. BYOC: 대안으로 KEY_PAIR를 사용할 수 있어요.	예
Snowflake Account Identifier	사용 시: SNOWFLAKE_MANAGED: 비워 둠. KEY_PAIR: [조직 이름]-[계정 이름] 형식.	예
Snowflake Private Key	사용 시: SNOWFLAKE_MANAGED: 비워 둠. KEY_PAIR: PKCS8 표준의 RSA 프라이빗 키.	아니요
Snowflake Private Key File	사용 시: SNOWFLAKE_MANAGED: 비워 둠. KEY_PAIR: 인증용 RSA 프라이빗 키가 들어 있는 파일.	아니요
Snowflake Private Key Password	사용 시: SNOWFLAKE_MANAGED: 비워 둠. KEY_PAIR: 프라이빗 키 파일과 연결된 비밀번호.	아니요
Snowflake Role	SNOWFLAKE_MANAGED: 런타임의 execute-as 역할(또는 하위 역할). KEY_PAIR: 서비스 사용자에 대한 유효한 역할.	예
Snowflake Username	사용 시: SNOWFLAKE_MANAGED: 비워 둠. KEY_PAIR: Snowflake 연결 사용자 이름.	예
Snowflake Warehouse	쿼리를 실행하는 Snowflake 웨어하우스.	예

Box Ingest Metadata 수집 매개변수

매개변수	설명
Box Folder ID	파일을 읽어올 폴더의 ID. 0으로 설정하면 Box 앱이 접근할 수 있는 모든 폴더를 동기화. ID는 예를 들어 https://app.box.com/folder/FOLDER_ID URL에서 가져올 수 있음.
Box File Identifier Column	주어진 메타데이터를 파일과 연결하기 위해 Box 파일 ID를 저장할 메타데이터 테이블의 열. 이 열은 VARCHAR 유형이어야 하며 Box 메타데이터 저장용 Snowflake 테이블에서 만든 테이블의 일부여야 해요.
Destination Metadata Table	수집할 메타데이터의 열이 있는, 이전에 만든 Snowflake 테이블.

플로우 실행

캔버스를 오른쪽 클릭하고 모든 컨트롤러 서비스 활성화를 선택해요.
가져온 프로세스 그룹을 오른쪽 클릭하고 시작을 선택해요. 커넥터가 데이터 수집을 시작해요.

Box 파일 메타데이터 인스턴스를 Snowflake 테이블과 동기화

커넥터 정의를 사용해 Snowflake 테이블의 Box 메타데이터에 대한 데이터 변환을 수행하고 변경 사항을 Box 메타데이터 인스턴스에 다시 추가해요.

Box 메타데이터 저장용 Snowflake 스트림 만들기

사용할 메타데이터 테이블에 대한 Snowflake 스트림을 만들어요. 이 스트림은 Box 파일을 동기화하려는 테이블에서 발생하는 변경을 모니터링하는 데 사용돼요. Box 메타데이터 저장용 테이블을 만드는 방법은 Box 메타데이터 저장용 Snowflake 테이블 만들기를 참조하세요. 커넥터가 데이터 보존 기간을 넘어 중지되어 스트림이 오래되면(stale) 스트림을 다시 만들고 이전 것을 교체해야 해요. 스트림 관리에 대한 자세한 내용은 스트림 관리를 참조하세요.

이 커넥터에 만들 수 있는 스트림의 예는 다음과 같아요.

CREATE OR REPLACE STREAM OPENFLOW.BOX_METADATA_SCHEMA.LOAN_AGREEMENT_METADATA_STREAM
ON TABLE OPENFLOW.BOX_METADATA_SCHEMA.LOAN_AGREEMENT_METADATA

메타데이터 테이블에 Box 파일 ID를 저장할 열이 있고 그 유형이 VARCHAR인지 확인하세요. 이 열의 이름은 이후 단계에서 Box File Identifier Column 매개변수로 입력해야 해요. 메타데이터 테이블에 지원되는 열 유형 목록은 VARCHAR, STRING, TEXT, FLOAT, DOUBLE, DATE예요.

커넥터 설정

데이터 엔지니어로서 커넥터를 설치·구성하려면 다음 작업을 수행하세요.

커넥터 설치

Openflow의 커넥터 라이브러리 탭으로 이동해요.
Openflow 커넥터 페이지에서 커넥터를 찾아 설치를 선택해요.
런타임 선택 대화상자에서 사용 가능한 런타임 드롭다운 목록에서 런타임을 선택하고 설치를 클릭해요.

참고

커넥터를 설치하기 전에 커넥터가 수집한 데이터를 저장할 데이터베이스와 스키마를 Snowflake에 만들어 두었는지 확인하세요.

Snowflake 계정 자격 증명으로 배포에 인증하고, 런타임 애플리케이션이 Snowflake 계정에 접근하도록 허용하라는 메시지가 표시되면 허용을 선택해요. 커넥터 설치 프로세스는 완료하는 데 몇 분 걸려요.
Snowflake 계정 자격 증명으로 런타임에 인증해요. Openflow 캔버스가 커넥터 프로세스 그룹과 함께 나타나요.

커넥터 구성

가져온 프로세스 그룹을 오른쪽 클릭하고 매개변수를 선택해요.
Box Publish Metadata 소스 매개변수, Box Publish Metadata 대상 매개변수, Box Publish Metadata 수집 매개변수에 설명된 대로 필수 매개변수 값을 입력해요.

Box Publish Metadata 소스 매개변수

매개변수	설명
Source Database	변경을 수집하는 Snowflake Stream이 포함된 스키마를 포함하는 Snowflake 데이터베이스.
Source Schema	변경을 수집하는 Snowflake Stream이 포함된 스키마.
Snowflake Account Identifier	SNOWFLAKE_MANAGED 인증 전략 사용 시 비워 둠. KEY_PAIR 사용 시 데이터가 저장될 [조직 이름]-[계정 이름] 형식의 Snowflake 계정 이름을 제공.
Snowflake Authentication Strategy	사용 시: Snowflake Openflow 배포 또는 BYOC: SNOWFLAKE_MANAGED를 사용해요. BYOC 배포는 SNOWFLAKE_MANAGED를 사용하기 위해 이전에 execute-as 역할을 구성해야 해요. BYOC: 대안으로 KEY_PAIR를 사용할 수 있어요.
Snowflake Private Key	SNOWFLAKE_MANAGED 사용 시 비워 둠. KEY_PAIR 사용 시 PKCS8 표준에 따라 형식화되고 표준 PEM 헤더·푸터를 가진 인증용 RSA 프라이빗 키를 제공. Snowflake Private Key File 또는 Snowflake Private Key 중 하나를 정의해야 해요.
Snowflake Private Key File	SNOWFLAKE_MANAGED 사용 시 비워 둠. KEY_PAIR 사용 시 인증에 사용되는 RSA 프라이빗 키가 들어 있는 파일을 업로드. 헤더 줄은 -----BEGIN PRIVATE로 시작. Reference asset 확인란을 선택해 업로드.
Snowflake Private Key Password	SNOWFLAKE_MANAGED 사용 시 비워 둠. KEY_PAIR 사용 시 Snowflake Private Key File과 연결된 비밀번호 제공.
Snowflake Role	SNOWFLAKE_MANAGED 인증 전략 사용 시 런타임의 execute-as 역할(또는 하위 역할) 사용. 키 페어 인증 전략 사용 시 서비스 사용자에 대해 구성된 유효한 역할 사용.
Snowflake Username	SNOWFLAKE_MANAGED 사용 시 비워 둠. KEY_PAIR 사용 시 Snowflake 인스턴스에 연결하는 데 사용되는 사용자 이름 제공.
Snowflake Warehouse	쿼리를 실행하는 Snowflake 웨어하우스.
Snowflake Stream Name	소스 Snowflake 테이블의 변경 수집에 사용되는 Snowflake 스트림 이름. 커넥터를 시작하기 전에 만들어 테이블에 연결해야 해요.

Box Publish Metadata 대상 매개변수

매개변수	설명
Box App Config JSON	앱 생성 중 다운로드한 애플리케이션 JSON 구성.
Box App Config File	앱 생성 중 다운로드한 애플리케이션 JSON 파일. "Box App Config File" 또는 "Box App Config JSON" 중 하나를 설정해야 해요. Reference asset 확인란을 선택해 업로드하세요.

Box Publish Metadata 수집 매개변수

매개변수	설명
Box File Identifier Column	주어진 메타데이터를 파일과 연결하기 위해 Box 파일 ID를 저장할 메타데이터 테이블의 열. 이 열은 VARCHAR 유형이어야 하며 Box 메타데이터 저장용 Snowflake 테이블에서 만든 테이블의 일부여야 해요.
Box Metadata Template Name	Box 파일에 추가될 Box 메타데이터 템플릿의 템플릿 이름. 커넥터를 시작하기 전에 템플릿을 수동으로 만들 필요가 없어요. 이 매개변수에 값을 입력하면 이 템플릿 이름으로 템플릿이 자동 생성돼요. 제공된 이름은 Box 환경에서 이미 만든 템플릿과 겹치면 안 돼요.
Box Metadata Template Key	Box 파일에 추가될 Box 메타데이터 템플릿의 Box 템플릿 키. 이 키는 Box API에서 템플릿을 참조하는 데 사용돼요. 커넥터를 시작하기 전에 템플릿을 수동으로 만들 필요가 없어요. 이 매개변수에 값을 입력하면 이 템플릿 키로 템플릿이 자동 생성돼요. 제공된 키는 Box 환경에서 이미 만든 템플릿과 겹치면 안 돼요.

플로우 실행

캔버스를 오른쪽 클릭하고 모든 컨트롤러 서비스 활성화를 선택해요.
가져온 프로세스 그룹을 오른쪽 클릭하고 시작을 선택해요. 커넥터가 데이터 수집을 시작해요.

플로우를 실행한 후에는 Cortex Search 서비스를 쿼리할 수 있어요. Cortex Search 서비스 쿼리 방법은 Cortex Search 서비스 쿼리를 참조하세요.

스테이지에서 파일 찾기

스테이지에 저장된 파일은 읽을 수 없는 이름을 가질 수 있어요. 특정 파일을 찾으려면 메타데이터 테이블을 신뢰할 수 있는 소스로 사용하세요. 이 테이블에는 파일 이름과 스테이지의 해당 파일 ID 간 매핑이 포함돼요.

Cortex 활성화 설정의 경우 다음 쿼리를 사용해 파일을 찾으세요.

SELECT DISTINCT METADATA:id FROM DOCS_CHUNKS WHERE METADATA:fullName LIKE '%<file_name>';

Cortex가 아닌 설정의 경우 다음 쿼리를 사용하세요.

SELECT FILE_ID FROM DOC_METADATA WHERE FILE_NAME = '<file_name>';

<file_name>을 찾는 파일의 이름 또는 부분 이름으로 바꾸세요.

스테이지의 파일은 이러한 쿼리에서 반환된 ID로 시작해요.

출처: Snowflake Box용 Openflow 커넥터 설정