Functions를 외부 리소스에 연결

배포된 함수는 애플리케이션 인증을 사용하여 외부 Azure 및 Fabric 리소스를 앱 식별자로 호출합니다. 함수에 필요한 대상을 선언하고 ctx.Tokens를 통해 플랫폼에서 제공하는 리소스 범위로 한정된 토큰을 사용하세요.

개발자 CLI의 로그인과 작성 시 엔드포인트 탐색은 배포된 런타임 접근과 별개입니다. 개발자가 리소스에 접근할 수 있더라도 배포된 앱 아이덴티티의 권한을 확인하세요.

사전 요구 사항

  • 함수가 초기화된 Fabric 앱입니다. 설정 지침은 'Fabric 앱에서 기능 사용'을 참조하세요.
  • rayfin/rayfin.yml에서 services.functions.auth.type를 application(으)로 설정. 구성 세부 사항은 애플리케이션 인증을 참조하세요.
  • 앱 아이덴티티는 함수 코드가 호출하는 각 외부 자원에 대한 접근 권한을 부여했습니다.

외부 연결을 선언하세요

RayfinContext 주석에서 대상 사용자를 선언한 다음, ctx.Tokens에서 범위가 지정된 토큰을 읽습니다:

import {
  UserDataFunctions,
  AudienceType,
  type RayfinContext,
} from '@microsoft/fabric-user-data-functions';

const udf = new UserDataFunctions();

udf.func(
  'accessStorage',
  async (
    ctx: RayfinContext<AppSchema, AudienceType.Storage>,
  ): Promise<string> => {
    const token: string = ctx.Tokens.Storage;
    // Use the token with the resource SDK or REST API.
    return 'ok';
  },
  [],
);

주석은 선언입니다. 대상 RayfinContext<Schema, Audiences> 을(를) 나열하면 연결 바인딩이 등록됩니다. udf.func()의 세 번째 인수를 []로 유지하세요.

ctx.Tokens는 당신이 지정한 대상에 한정됩니다. 선언되지 않은 청중은 컴파일 오류를 일으킵니다:

async (
  ctx: RayfinContext<AppSchema, AudienceType.Sql | AudienceType.Storage>,
) => {
  const sqlToken: string = ctx.Tokens.Sql;
  const storageToken: string = ctx.Tokens.Storage;
};

토큰 값은 string 타입입니다. 청중을 선언하면 그 결속이 등록되지만, 토큰 가용성이나 자원 접근이 보장되지는 않습니다. 호스트가 선언된 토큰을 제공하지 않으면, 그 ctx.Tokens 속성을 읽으면 오류가 발생합니다.

스키마 인자를 명시하세요

RayfinContext 먼저 앱 스키마를 확인하세요. 오디언스를 추가할 때도 데이터 클라이언트의 타입이 유지되도록 RayfinClient<AppSchema>에 전달하는 것과 동일한 스키마를 사용하세요:

async (ctx: RayfinContext<AppSchema, AudienceType.Sql>) => {
  const data = ctx.getDataClient();
  const token = ctx.Tokens.Sql;
};

함수가 청중이 필요하지만 Rayfin DB에 접근하지 않는다면, 기본 스키마를 명시적으로 전달하세요:

async (ctx: RayfinContext<Record<string, any>, AudienceType.Fabric>) => {
  const token = ctx.Tokens.Fabric;
};

지원 관객

AudienceType 지지받는 청중에게 진실의 출처입니다:

외부 자료 AudienceType
Fabric 레이크하우스, 웨어하우스, Fabric 내 SQL 데이터베이스, 미러드 데이터베이스, 또는 Azure SQL Database Sql
Fabric OneLake 파일, Azure Blob 스토리지, Azure Table 스토리지 또는 Azure Queue 스토리지 Storage
Microsoft Fabric REST API Fabric
Azure AI Foundry (에이아이 파운드리) AzureAI
Azure DevOps ADO

Power BI 시맨틱 모델은 ctx.Tokens를 통해 사용할 수 없습니다. 대신 fabric-semanticmodel 커넥터를 사용하세요. 커넥터 지침은 Fabric 데이터에 연결을(를) 참조하세요.

배포 메타데이터 이해하기

타입 인자는 함수가 실행되기 전에 지워집니다. 이 시간 동안 npx rayfin upTypeScript 컴파일러는 선언된 오디언스를 해결하고 유니언을 배포 메타데이터에 기록합니다. Functions 작업자는 그 메타데이터를 이용해 연결을 바인딩합니다.

타입 별칭은 함수 프로젝트에 다음과 같은 조건 tsconfig.json을 가질 때 작동합니다:

type SqlAccess = AudienceType.Sql;

async (ctx: RayfinContext<AppSchema, SqlAccess>) => {
  const token = ctx.Tokens.Sql;
};

문자 그대로 AudienceType.X 의 가치를 선호하세요. Functions 프로젝트에 tsconfig.json이(가) 없으면 CLI는 컴파일러를 사용할 수 없으며 대신 어노테이션 구문을 읽습니다. 이 모드에서는 별명이 자신이 대표하는 청중이 아니라 자신의 이름으로 해석됩니다. 이 대체 동작에 대한 CLI 경고를 오류로 간주하고 수정하세요.

문맥 매개변수에는 명시적인 RayfinContext<...> 주석이 있어야 합니다. 타입 생성은 이 주석을 통해 문맥 매개변수를 식별합니다. 이 매개변수가 없으면 매개변수는 요청-본체 매개변수로 취급됩니다.

자원 권한 부여

현재 Fabric 앱의 경우, 앱 정체성은 Fabric 앱 항목의 소유자입니다. 외부 연결은 이 신원과 그 권한을 사용하며, 기능을 호출하는 앱 사용자의 신원이나 권한은 사용하지 않습니다.

Functions 코드가 호출하는 모든 리소스와 API가 요구하는 권한을 앱 아이덴티티에 부여하세요. 대상을 선언하고 Functions를 배포하면 토큰 바인딩이 등록되지만 대상 리소스에 대한 권한은 부여되지 않습니다.

자원 토큰은 서버에 보관하세요. 함수 결과로 반환하거나 프론트엔드로 보내지 마세요.

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

Rayfin DB 식별자

Rayfin DB는 별도의 인증 경로를 사용합니다. ctx.getDataClient()는 호출에 사용된 Rayfin 토큰을 사용하므로 데이터베이스 액세스 시 호출자의 신원과 데이터베이스 권한이 유지됩니다. 함수에 대한 애플리케이션 인증은 Rayfin DB 접근을 애플리케이션 아이덴티티로 전환하지 않습니다.

Azure SDK와 함께 토큰을 사용하세요

많은 Azure SDK 클라이언트는 원시 토큰 문자열 대신 TokenCredential를 기대합니다. 컨텍스트에서 토큰을 반환하는 어댑터를 정의합니다:

import type { TokenCredential, AccessToken } from '@azure/identity';

class ContextTokenCredential implements TokenCredential {
  constructor(private readonly token: string) {}

  async getToken(): Promise<AccessToken> {
    return {
      token: this.token,
      expiresOnTimestamp: Date.now() + 3600_000,
    };
  }
}

자격 증명이 필요한 SDK 클라이언트에 적절한 선언 토큰을 전달 new ContextTokenCredential(ctx.Tokens.Storage) 하세요. 리소스 SDK 패키지는 rayfin/functions/package.json프로젝트 루트가 아니라 에 설치하세요.

로컬로 개발

npx rayfin dev그리고 npx rayfin dev functions apply 로컬 Azure Functions Core Tools 호스트를 시작하세요. 로컬 Functions 호스트에서는 외부 리소스 토큰이 앱 빌더가 로그인할 때 사용하는 계정의 신원과 권한을 사용합니다.

배포된 기능은 대신 앱 아이덴티티를 사용합니다. 따라서 성공적인 로컬 호출이 배포된 앱 신원이 자원에 접근할 권한이 있음을 증명하지 않습니다. 앱 신원에 필요한 권한을 부여한 후 배포된 기능을 테스트하세요.

관련 콘텐츠

  • 에 마지막으로 업데이트됨