Conectar funciones a recursos externos

Las Funciones Desplegadas llaman a recursos externos de Azure y Fabric como identidad de la aplicación mediante autenticación de aplicaciones. Declara las audiencias que necesita una función y usa tokens proporcionados por la plataforma, con ámbito de recurso, a través de ctx.Tokens.

El inicio de sesión en la CLI para desarrolladores y la detección de endpoints durante la fase de creación son independientes del acceso al entorno de ejecución implementado. Verifica los permisos de la identidad de la aplicación desplegada incluso cuando un desarrollador pueda acceder al recurso.

Prerequisites

  • Una aplicación Fabric con Funciones inicializadas. Para las instrucciones de configuración, consulta Usar funciones en aplicaciones de Fabric.
  • services.functions.auth.type configurado en application en rayfin/rayfin.yml. Para detalles de configuración, véase Autenticación de aplicaciones.
  • La identidad de la aplicación otorgaba acceso a cada recurso externo que el código Functions llama.

Declarar una conexión externa

Declare las audiencias en la anotación RayfinContext, y luego lea el token de ámbito de 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';
  },
  [],
);

La anotación es la declaración. Listar una audiencia en RayfinContext<Schema, Audiences> registra la vinculación de conexión. Mantén el tercer argumento de udf.func() como [].

ctx.Tokens se limita a las audiencias que defines. Una audiencia no declarada provoca un error de compilación:

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

Los valores de los tokens son de tipo string. Declarar una audiencia registra su vinculación, pero no garantiza la disponibilidad del token ni el acceso a recursos. Si el host no suministra un token declarado, leer su ctx.Tokens propiedad genera un error.

Especificar el argumento del esquema

RayfinContext usa primero el esquema de tu aplicación. Usa el mismo esquema al que pasas RayfinClient<AppSchema> para que el cliente de datos permanezca escrito cuando añades audiencias:

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

Si una función necesita audiencias pero no accede a Rayfin DB, pasa explícitamente el esquema por defecto:

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

Público apoyado

AudienceType es la fuente de verdad para las audiencias apoyadas:

Recurso externo AudienceType
Fabric lakehouse, almacén, base de datos SQL en Fabric, base de datos espejada o Azure SQL Database Sql
archivos de Fabric OneLake, Azure Blob Storage, almacenamiento de tablas de Azure o Azure Queue Storage Storage
API REST de Microsoft Fabric Fabric
Azure AI Foundry AzureAI
Azure DevOps ADO

Un modelo semántico de Power BI no está disponible a través de ctx.Tokens. Usa el fabric-semanticmodel conector en su lugar. Para orientación sobre conectores, consulte Conectar a datos de Fabric.

Comprender los metadatos de despliegue

Los argumentos de tipo se borran antes de que una función se ejecute. Durante npx rayfin up, el compilador TypeScript resuelve las audiencias declaradas y escribe la unión en los metadatos de despliegue. El trabajador de Funciones utiliza esos metadatos para vincular las conexiones.

Un alias de tipo funciona cuando el proyecto Functions tiene un tsconfig.json:

type SqlAccess = AudienceType.Sql;

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

Prefiero valores literales AudienceType.X . Si el proyecto de Functions no tsconfig.json, la CLI no puede usar el compilador y, en su lugar, interpreta la sintaxis de anotación. En ese modo, un alias se resuelve con su propio nombre en lugar de con la audiencia que representa. Toma la advertencia de la CLI sobre este fallback como un error que hay que corregir.

El parámetro de contexto debe tener una anotación explícita RayfinContext<...> . La generación de tipos identifica el parámetro de contexto mediante esta anotación. Sin él, el parámetro se trata como un parámetro de cuerpo de solicitud.

Conceder permisos de recursos

En las aplicaciones actuales de Fabric, la identidad de la aplicación corresponde al propietario del elemento de aplicación de Fabric. Las conexiones externas usan esta identidad y sus permisos, no la identidad ni los permisos del usuario de la aplicación que invoca la función.

Concede a la identidad de la app los permisos requeridos por cada recurso y API que el código Functions llame. Declarar una audiencia y desplegar Funciones registra un enlace de token pero no concede permisos sobre el recurso objetivo.

Conserva los tokens de acceso a recursos en el servidor. Nunca los devuelvas como resultados de funciones ni los envíes al frontend.

El inicio de sesión en la app y la autorización para invocar una función son independientes del acceso de la identidad de la app a recursos externos.

Identidad de la base de datos de rayfin

La base de datos Rayfin utiliza una ruta de autenticación separada. ctx.getDataClient() utiliza el token Rayfin de la invocación, por lo que el acceso a la base de datos preserva la identidad del llamante y los permisos de la base de datos. La autenticación de aplicaciones para Funciones no cambia el acceso a la base de datos Rayfin a la identidad de la aplicación.

Usa un token con un SDK de Azure

Muchos clientes de SDK de Azure esperan una TokenCredential cadena de token en lugar de una en bruto. Definamos un adaptador que devuelva el token desde el contexto:

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,
    };
  }
}

Pase new ContextTokenCredential(ctx.Tokens.Storage) o el token declarado adecuado a un cliente del SDK que requiera una credencial. Instala los paquetes del SDK de recursos en rayfin/functions/package.json, no en la raíz del proyecto.

Desarrollo local

npx rayfin dev y npx rayfin dev functions apply inician un host local de Azure Functions Core Tools. En el host local de Functions, los tokens de recursos externos utilizan la identidad y los permisos de la cuenta que utiliza el constructor de aplicaciones para iniciar sesión.

Las Funciones Desplegadas usan en su lugar la identidad de la app. Por tanto, una llamada local exitosa no prueba que la identidad de la aplicación desplegada tenga permiso para acceder al recurso. Prueba la función desplegada después de conceder a la identidad de la app los permisos requeridos.

Contenido relacionado

  • Se actualizó por última vez el