Fabric 앱에서 함수 사용

함수는 Fabric 앱 내에서 서버에서 실행되는 TypeScript 함수입니다. 브라우저에서 실행되어서는 안 되는 논리, 예를 들어 비밀 처리, 특권 데이터 접근, 앱 식별로 하류 서비스를 호출하는 기능 등을 사용하세요.

각 함수는 이름으로 등록되어 호출 가능한 HTTP 엔드포인트로 노출됩니다. React 프론트엔드는 타입이 지정된 Rayfin 클라이언트를 통해 함수를 호출하기 때문에 요청, 라우팅, 토큰 처리를 구현할 필요가 없습니다.

메모

이 글의 명령어들은 Rayfin CLI의 미리보기 버전을 사용합니다.

함수를 사용할 때

레이핀 함수를 사용하여 다음을 수행합니다:

• 애플리케이션 토큰으로 외부 API를 호출하세요. 예시로는 Azure AI Foundry, Azure DevOps, Fabric, Azure Storage, Azure Key Vault 등이 있습니다.
• 서버가 강제하는 행 수준의 보안을 적용해 앱의 데이터베이스를 읽거나 쓰는 기능.
• API 키, 모델 배포 이름 및 기타 비밀은 클라이언트 코드에서 제외하세요.
• 팬아웃 호출, 집계 또는 AI 프롬프트 생성과 같은 오케스트레이션을 데이터 가까이에서 실행하세요.

사전 요구 사항

시작하기 전에 다음 자료를 설치하거나 생성하세요:

• Node.js 20 이상 및 npm.
• Rayfin CLI로 만든 Fabric 앱 스캐폴드입니다.
• 로컬 함수 호스트가 디버깅에 사용하는 Azure Functions Core Tools입니다.

Install Azure Functions Core Tools version 4:

npm install --global azure-functions-core-tools@4

함수가 있는 앱을 만드세요

앱을 스캐폴드하고 그 함수 프로젝트를 초기화하기:

npm create @microsoft/rayfin@latest

cd my-app

npx rayfin functions init

이 명령어는 rayfin functions init 기존 앱에 함수 프로젝트, TypeScript 구성, 스타터 함수 파일을 추가합니다.

GitHub Copilot으로 앱을 구축하세요

이 스캐폴드는 프로젝트 작업에 필요한 GitHub Copilot의 지침과 기술을 포함합니다. Visual Studio Code에서 프로젝트를 열고, GitHub Copilot Chat에서 만들고 싶은 앱을 설명하세요.

예를 들어, 다음 프롬프트를 사용해 AI 풀 리퀘스트 검토 어시스턴트를 만들어보세요:

Build an app that helps business analysts track sales performance across
regions. Show key metrics, let analysts ask questions about trends, and
use Functions to securely retrieve data from our sales API with application
authentication.

GitHub Copilot은 필요한 파일과 컴포넌트를 생성하고 업데이트할 수 있습니다. 에이전트에게 앱을 실행하고, 로컬에서 기능을 디버깅하며, 앱을 배포하도록 요청할 수도 있습니다.

프로젝트 레이아웃을 이해하세요

함수 초기화 명령은 rayfin/rayfin.yml을 업데이트하고 rayfin/functions을 생성합니다. 일반적인 기능이 있는 앱은 다음과 같은 구조를 가집니다:

my-app/
├── rayfin/
│   ├── rayfin.yml
│   ├── data/
│   │   ├── TripPlan.ts
│   │   └── schema.ts
│   └── functions/
│       ├── package.json
│       ├── tsconfig.json
│       └── src/
│           ├── function_app.ts
│           └── types.ts
└── src/
    └── services/

이 파일들은 다음과 같은 목적을 수행합니다:

Path	Purpose
rayfin/rayfin.yml	인증, 데이터, 기능, 정적 호스팅 서비스를 구성합니다.
rayfin/data/	앱의 데이터 모델과 스키마 내보내기가 포함되어 있습니다.
rayfin/functions/package.json	함수 프로젝트에 대한 의존성과 빌드 스크립트를 정의합니다.
rayfin/functions/tsconfig.json	함수에 맞게 TypeScript 빌드를 구성합니다.
rayfin/functions/src/function_app.ts	함수 구현을 포함합니다.
rayfin/functions/src/types.ts	생성된 AppFunctionsSchema 타입을 포함하고 있습니다. 이 파일을 수동으로 편집하지 마세요.
src/	React 프론트엔드와 공유 도메인 유형 또는 래퍼를 포함합니다.

함수를 활성화할 때, rayfin/rayfin.yml 함수 서비스가 포함됩니다:

services:
  functions:
    enabled: true
    auth:
      type: application
    buildCommand: npm run build

애플리케이션 인증

활성화된 기능은 명시적인 애플리케이션 인증을 요구합니다 rayfin/rayfin.yml:

services:
  functions:
    enabled: true
    auth:
      type: application
    buildCommand: npm run build

새로운 Functions 스캐폴드를 설정합니다 auth.type: application.

비활성화된 기능은 auth를 생략할 수 있습니다. 하지만 auth를 제공하는 경우, 다음이 포함되어 있어야 합니다:

auth:
  type: application

전체 npx rayfin up 플로우와 일반 npx rayfin dev 플로우가 이 설정을 검증한 후 프로젝트 설정을 Fabric이나 Docker 백엔드에 적용합니다.

기존 원격 앱에 YAML 인증 모드를 적용하기 위해 전체 npx rayfin up 모드를 실행하세요.

배포된 함수에서 사용되는 인증 경로

배포된 함수는 두 개의 별도 인증 경로를 사용합니다:

액세스 경로	Credential	ID 및 권한
외부 연결을 통한 ctx.Tokens.*	플랫폼 제공 자원 토큰	애플리케이션 식별 및 외부 자원에 대한 권리
Rayfin DB를 통해 ctx.getDataClient()	인보케이션의 레이핀 토큰	Rayfin DB에서 발신자의 신원 및 권한

현재 Fabric 앱의 경우, 애플리케이션 아이덴티티는 BaaS 아이템의 소유자입니다.

따라서 외부 연결은 기능을 호출하는 앱 사용자의 권한이 아니라 아이템 소유자의 권한을 사용합니다. Functions 코드가 호출하는 모든 외부 리소스와 API가 요구하는 권한을 앱 식별자에게 부여하세요.

오디언을 선언하거나 Functions를 배포한다고 해서 앱 정체성 권한이 외부 자원에 부여되는 것은 아닙니다.

앱 로그인과 기능 호출 권한은 앱 아이덴티티드의 외부 자원 접근과는 별개입니다.

Rayfin DB 접근은 항상 Rayfin 토큰을 사용하며 호출자의 신원과 데이터베이스 권한을 보존합니다. 설정은 services.functions.auth.type: application Rayfin DB 접근을 애플리케이션 아이덴티티로 전환하지 않습니다.

청중 선언, 자원 토큰, 권한, 로컬 개발 동작에 대해서는 외부 자원과의 기능 연결 항목을 참조하세요.

로컬로 앱 실행

앱의 루트 폴더에서 로그인하세요:

cd my-app
npx rayfin login

프론트엔드를 시작하고 로컬 함수를 호스트합니다:

npm run dev

함수 사용이 가능한 프로젝트에서 npm run dev는 rayfin dev에 매핑됩니다. 이 명령어는 스키마를 적용하고, 로컬 함수 호스트를 시작하며, Vite 개발 서버를 시작합니다. 터미널에 인쇄된 로컬 URL을 열고, 앱을 개발하고 디버깅하는 동안 터미널을 계속 켜두세요.

예를 들어 프론트엔드를 별도로 실행할 때처럼 호스트 함수만 시작하려면 다음 명령어를 사용하세요:

cd my-app
npx rayfin dev 

Fabric에 배포

앱의 데이터, 정적 사이트 및 기능을 배포하세요:

npx rayfin up --workspace <workspace-name>

대상 Fabric 작업 공간 이름으로 대체 <WORKSPACE> 하세요.

기존 앱에 기능 추가하기

기존 Fabric 앱의 루트에서 기능을 활성화하고 함수 프로젝트를 한 번만 초기화하세요:

npx rayfin functions init

초기화 후에는 함수 구현을 rayfin/functions/src/function_app.ts에 추가합니다.

Limitations

• 함수 소유권: 사용자 데이터 함수 항목의 소유자만이 함수 코드를 수정하고 게시할 수 있습니다.
• 출판 쿨다운: 출판 후 최소 2분은 기다렸다가 다시 출판하세요. 이 쿨다운은 브라우저 내 Functions 포털, 사용자 데이터 함수의 Visual Studio Code 확장 기능, Git 가져오기 작업, 배포 파이프라인에서 게시할 때 적용됩니다.
• 배포 패키지 크기: Functions ZIP 파일은 30MB를 초과할 수 없습니다.
• 요청 페이로드 크기: 사용자 데이터 함수 서비스는 모든 요청 매개변수를 합쳐 최대 4MB를 문서화합니다. 이 한계는 Rayfin 함수에도 적용될 것으로 예상되지만, 아직 검증되지는 않았습니다.
• 실행 타임아웃: 함수는 최대 240초까지 실행할 수 있습니다.
• 호출 로그 보존: 과거 호출 로그는 기본적으로 30일간 유지됩니다.
• 애플리케이션 식별자: 애플리케이션 식별자는 현재 BaaS 항목의 소유자입니다.

지역 가용성 요구사항과 사용자 데이터 기능 제한에 대한 자세한 내용은 서비스 세부사항 및 Fabric 사용자 데이터 기능 제한 사항을 참조하세요.

관련 콘텐츠

• Fabric Apps 프로젝트 구조를 이해하기
• Fabric 앱의 인증
• Functions를 외부 리소스에 연결
• 함수 비밀 관리
• Fabric 앱을 Fabric에 배포
• Rayfin CLI 참조