Conecte Funções a recursos externos

As Funções Implantadas chamam recursos externos do Azure e Fabric como identidade do aplicativo usando autenticação de aplicação. Declare os públicos que uma função precisa e use tokens fornecidos pela plataforma e com escopo de recursos através de ctx.Tokens.

O login na CLI do desenvolvedor e a descoberta de endpoints durante a autoria são separados do acesso ao runtime implantado. Verifique as permissões da identidade do aplicativo implantado mesmo que um desenvolvedor possa acessar o recurso.

Pré-requisitos

  • Um aplicativo do Fabric com Functions inicializado. Para instruções de configuração, veja Usar Funções em Apps Fabric.
  • services.functions.auth.type definido como application em rayfin/rayfin.yml. Para detalhes de configuração, veja Autenticação de Aplicação.
  • A identidade do app concedia acesso a cada recurso externo que o código Functions chamava.

Declare uma conexão externa

Declare os públicos na anotação RayfinContext e depois leia o token com escopo a partir 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';
  },
  [],
);

A anotação é a declaração. Especificar um público em RayfinContext<Schema, Audiences> registra o vínculo de conexão. Mantenha o terceiro argumento de udf.func() como [].

ctx.Tokens fica restrito aos públicos que você declara. Uma audiência não definida causa um erro de compilação:

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

Os valores dos tokens têm tipo string. Declarar uma audiência registra sua vinculação, mas não garante a disponibilidade do token ou o acesso a recursos. Se o host não fornecer um token declarado, ler sua ctx.Tokens propriedade gera um erro.

Especifique o argumento do esquema

RayfinContext usa primeiro o esquema do seu aplicativo. Use o mesmo esquema que você passa para RayfinClient<AppSchema> para que o cliente de dados permaneça tipado ao adicionar públicos:

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

Se uma função precisa de público, mas não acessa o Rayfin DB, passe explicitamente o esquema padrão:

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

Públicos apoiados

AudienceType é a fonte da verdade para o público apoiado:

Recurso externo AudienceType
Fabric lakehouse, armazém, banco de dados SQL no Fabric, banco de dados espelhado ou Banco de Dados SQL do Azure Sql
arquivos do Fabric OneLake, Armazenamento de Blobs do Azure, armazenamento de tabelas do Azure ou Armazenamento de Filas do Azure Storage
API REST do Microsoft Fabric Fabric
Fábrica de IA do Azure AzureAI
Azure DevOps ADO

Um modelo semântico do Power BI não está disponível por meio de ctx.Tokens. Use o fabric-semanticmodel conector em vez disso. Para orientações sobre conectores, veja Conectar aos dados do Fabric.

Entenda os metadados de implantação

Argumentos de tipo são apagados antes que uma função seja executada. Durante npx rayfin up, o compilador TypeScript determina os públicos declarados e registra a união nos metadados de implantação. O trabalhador de Funções usa esses metadados para vincular as conexões.

Um alias de tipo funciona quando o projeto Functions possui um tsconfig.json:

type SqlAccess = AudienceType.Sql;

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

Prefiro valores literais AudienceType.X . Se o projeto do Functions não tiver tsconfig.json, a CLI não poderá usar o compilador e, em vez disso, lerá a sintaxe de anotação. Nesse modo, um pseudônimo é resolvido como o próprio nome, em vez do público que ele representa. Trate o aviso da CLI sobre esse fallback como um erro a ser corrigido.

O parâmetro de contexto deve ter uma anotação explícita RayfinContext<...> . A geração de tipos identifica o parâmetro de contexto por meio dessa anotação. Sem ele, o parâmetro é tratado como um parâmetro de corpo de requisição.

Conceder permissões de recursos

Para os aplicativos Fabric atuais, a identidade do app é o proprietário do item do Fabric. Conexões externas usam essa identidade e suas permissões, não a identidade ou permissões do usuário do aplicativo que invoca a função.

Conceda à identidade do app as permissões exigidas por cada recurso e API que o código Functions chama. Declarar um público e implantar o Functions registram uma vinculação de token, mas não concedem permissões ao recurso de destino.

Mantenha os tokens de recurso no servidor. Nunca os devolva como resultados de função nem envie para o frontend.

O login do app e a autorização para invocar uma função são separados do acesso da identidade do app a recursos externos.

Identidade do Rayfin DB

O Rayfin DB utiliza um caminho de autenticação separado. ctx.getDataClient() usa o token Rayfin da invocação, de modo que o acesso ao banco de dados preserva a identidade do chamador e as permissões do banco de dados. A autenticação de aplicativo no Functions não altera o acesso ao banco de dados Rayfin para a identidade do aplicativo.

Use um token com um SDK do Azure

Muitos clientes do SDK do Azure esperam um(a) TokenCredential em vez de uma string de token bruta. Defina um adaptador que retorna o token a partir do 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,
    };
  }
}

Passe new ContextTokenCredential(ctx.Tokens.Storage) ou o token declarado adequado para um cliente do SDK que exija uma credencial. Instale os pacotes do SDK de recursos em rayfin/functions/package.json, não na raiz do projeto.

Desenvolver localmente

npx rayfin dev e npx rayfin dev functions apply iniciam um host local do Azure Functions Core Tools. No host local do Functions, os tokens de recursos externos usam a identidade e as permissões da conta que o criador do aplicativo usa para entrar.

As Funções Implantadas, em vez disso, usam a identidade do app. Portanto, uma chamada local bem-sucedida não prova que a identidade do aplicativo implantada tem permissão para acessar o recurso. Teste a função implantada após conceder à identidade do app as permissões necessárias.

Conteúdo relacionado

  • Última atualização em