Ligue Funções a recursos externos

As funções implementadas acedem a recursos externos do Azure e do Fabric utilizando a identidade da aplicação, recorrendo à autenticação da aplicação. Declare os destinatários de que uma função precisa e utilize, através de ctx.Tokens, tokens fornecidos pela plataforma e delimitados ao recurso.

O início de sessão na CLI do programador e a descoberta de endpoints durante a criação são distintos do acesso ao runtime implementado. Verifique as permissões da identidade da aplicação implementada mesmo quando um programador possa aceder ao recurso.

Pré-requisitos

  • Uma aplicação Fabric com Funções inicializadas. Para instruções de configuração, consulte Usar Funções em Aplicações Fabric.
  • services.functions.auth.type definido como application em rayfin/rayfin.yml. Para detalhes de configuração, veja Autenticação de Aplicações.
  • A identidade da aplicação concedia acesso a cada recurso externo que o código Functions chama.

Declarar uma ligação externa

Declare audiências na RayfinContext anotação 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. Enumerar uma audiência em RayfinContext<Schema, Audiences> regista a associação de ligação. Mantenha o terceiro argumento de udf.func() como [].

ctx.Tokens está restringido aos públicos que declaras. Uma audiência não declarada 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 o tipo string. Declarar uma audiência regista a 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 a sua ctx.Tokens propriedade gera um erro.

Especificar o argumento do esquema

RayfinContext usa primeiro o esquema da sua aplicação. Use o mesmo esquema para o qual passa RayfinClient<AppSchema> para que o cliente de dados permaneça tipado quando adiciona audiências:

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

Se uma função precisa de audiências mas não acede ao 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 de verdade para audiências suportadas:

Recurso externo AudienceType
Fabric lakehouse, armazém, base de dados SQL em Fabric, base de dados espelhada ou Base de Dados SQL do Azure Sql
ficheiros do Fabric OneLake, Armazenamento de Blobs do Azure, Armazenamento de Tabelas do Azure ou Armazenamento de Filas do Azure Storage
Microsoft Fabric REST API Fabric
Azure AI Foundry AzureAI
Azure DevOps ADO

Um modelo semântico do Power BI não está disponível através de ctx.Tokens. Usa o fabric-semanticmodel conector em vez disso. Para orientação sobre conectores, consulte Ligar aos dados do Fabric.

Compreender os metadados de implementação

Os argumentos de tipo são apagados antes de uma função ser executada. Durante npx rayfin up, o compilador TypeScript resolve os destinatários declarados e regista a união nos metadados de implementação. O trabalhador de Funções usa esses metadados para vincular as ligações.

Um alias de tipo funciona quando o projeto Functions tem 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 pode usar o compilador e, em vez disso, lê a sintaxe de anotações. Nesse modo, um alias corresponde ao seu próprio nome, em vez dos destinatários que representa. Trate o aviso da CLI sobre esta alternativa como um erro que deve 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 através desta anotação. Sem ele, o parâmetro é tratado como um parâmetro de corpo de pedido.

Conceder permissões de recursos

Para as aplicações atuais do Fabric, a identidade da aplicação corresponde ao proprietário do item da aplicação do Fabric. As ligações externas usam esta identidade e as suas permissões, não a identidade ou permissões do utilizador da aplicação que invoca a função.

Conceda à identidade da aplicação as permissões exigidas por cada recurso e API que o código Functions chama. Declarar uma audiência e implementar Funções regista uma ligação de token mas não concede permissões ao recurso alvo.

Manter os tokens de acesso a recursos no servidor. Nunca os devolvas como resultados de função nem os envies para o frontend.

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

Identidade de base de dados Rayfin

A base de dados Rayfin utiliza um caminho de autenticação separado. ctx.getDataClient() utiliza o token Rayfin da invocação, pelo que o acesso à base de dados preserva a identidade do chamador e as permissões da base de dados. A autenticação de aplicações para Funções não altera o acesso à base de dados Rayfin para a identidade da aplicação.

Use um token com o SDK do Azure

Muitos clientes do SDK do Azure esperam um TokenCredential em vez de uma cadeia de tokens em bruto. Defina um adaptador que devolve 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,
    };
  }
}

Forneça new ContextTokenCredential(ctx.Tokens.Storage) ou o token declarado adequado a um cliente do SDK que exija uma credencial. Instala 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 Funções do Azure Core Tools. No anfitrião local do Functions, os tokens de recursos externos utilizam a identidade e as permissões da conta que o criador da aplicação utiliza para iniciar sessão.

As funções implementadas utilizam, em vez disso, a identidade da aplicação. Uma chamada local bem-sucedida, portanto, não prova que a identidade da aplicação implementada tem permissão para aceder ao recurso. Teste a função implementada depois de conceder à identidade da aplicação as permissões necessárias.

Conteúdo relacionado

  • Última atualização a