Usar funções em aplicativos do Fabric

Funções são funções TypeScript que rodam no servidor dentro do seu aplicativo Fabric. Use funções para lógica que não devem rodar no navegador, como trabalhar com segredos, acessar dados privilegiados e chamar serviços posteriores com a identidade do app.

Cada função é registrada com um nome e exposta como um endpoint HTTP chamável. Seu frontend React chama a função por meio do cliente Rayfin tipado, então você não precisa implementar requisições, roteamento nem tratamento de tokens.

Note

Os comandos deste artigo utilizam uma versão de pré-visualização da CLI do Rayfin.

Quando usar uma função

Use uma função Rayfin para:

  • Chame uma API externa com um token de aplicação. Exemplos incluem Fábrica de IA do Azure, Azure DevOps, Fabric, Armazenamento do Azure e Azure Key Vault.
  • Leia ou escreva o banco de dados do aplicativo com segurança em nível de linha imposta pelo servidor.
  • Mantenha chaves de API, nomes de implantação de modelos e outros segredos fora do código do cliente.
  • Execute tarefas de orquestração, como chamadas fan-out, agregação ou solicitações a IA, perto dos dados.

Pré-requisitos

Antes de começar, instale ou crie os seguintes recursos:

  • Node.js 20 ou posterior e npm.
  • Um andaime de aplicativo Fabric criado com a CLI Rayfin.
  • Azure Functions Core Tools, que o host local das funções usa para depuração.

Instale o Azure Functions Core Tools versão 4:

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

Crie um aplicativo com funções

Crie a estrutura de um app e inicialize seu projeto do Functions:

npm create @microsoft/rayfin@latest

cd my-app

npx rayfin functions init

O rayfin functions init comando adiciona o projeto de funções, sua configuração TypeScript e um arquivo de função inicial ao aplicativo existente.

Construa o app com o GitHub Copilot

O andaime inclui as instruções do GitHub Copilot e as habilidades necessárias para trabalhar com o projeto. Abra o projeto no Visual Studio Code e descreva o aplicativo que você quer construir no GitHub Copilot Chat.

Por exemplo, use o seguinte prompt para construir um assistente de revisão de pull requests por IA:

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.

O GitHub Copilot pode gerar e atualizar os arquivos e componentes necessários. Você também pode pedir para o agente rodar o app, depurar funções localmente e implantar o app.

Entenda o layout do projeto

O comando de inicialização do functions atualiza rayfin/rayfin.yml e cria rayfin/functions. Um aplicativo típico com funções possui a seguinte estrutura:

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

Os arquivos servem aos seguintes propósitos:

Caminho Purpose
rayfin/rayfin.yml Configura autenticação, dados, funções e serviços de hospedagem estática.
rayfin/data/ Contém os modelos de dados e exportações de esquemas do app.
rayfin/functions/package.json Define dependências e scripts de construção para o projeto de funções.
rayfin/functions/tsconfig.json Configura o build do TypeScript para funções.
rayfin/functions/src/function_app.ts Contém suas implementações de funções.
rayfin/functions/src/types.ts Contém os tipos geradosAppFunctionsSchema. Não edite esse arquivo manualmente.
src/ Contém a interface React e quaisquer tipos de domínio ou wrappers compartilhados.

Quando você habilita as funções, rayfin/rayfin.yml inclui o serviço de funções:

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

Autenticação do aplicativo

Funções habilitadas requerem autenticação explícita de aplicação em:rayfin/rayfin.yml

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

Novas funções definem o conjunto de estruturas auth.type: application.

Funções desativadas podem omitir auth. No entanto, se você fornecer auth, deve incluir:

auth:
  type: application

Uma execução completa npx rayfin up e o fluxo normal npx rayfin dev validam essa configuração antes de aplicar as configurações do projeto ao backend do Fabric ou do Docker.

Execute uma npx rayfin up completa para aplicar o modo de autenticação YAML a um aplicativo remoto existente.

Caminhos de autenticação usados por Funções implantadas

As Funções Implantadas usam dois caminhos de autenticação separados:

Caminho de acesso Credencial Identidade e permissões
Conexões externas através de ctx.Tokens.* Token de recurso fornecido pela plataforma Identidade da aplicação e suas permissões no recurso externo
Rayfin DB por meio de ctx.getDataClient() token Rayfin de Invocation Identidade do chamador e permissões no banco de dados Rayfin

Para os aplicativos Fabric atuais, a identidade do aplicativo é o proprietário do item BaaS.

Conexões externas, portanto, usam as permissões do proprietário do item, não as permissões do usuário do aplicativo que invoca a função. Conceda à identidade do aplicativo as permissões necessárias para cada recurso externo e cada API chamados pelo código do Functions.

Definir um público ou implantar Funções não concede ao aplicativo permissões de identidade para um recurso externo.

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.

O acesso ao banco de dados Rayfin sempre usa o token Rayfin e preserva a identidade do chamador e as permissões do banco de dados. A configuração services.functions.auth.type: application não troca o acesso do Rayfin DB para a identidade da aplicação.

Para declarações de audiência, tokens de recursos, permissões e comportamento de desenvolvimento local, veja Conectar Funções a recursos externos.

Executar o aplicativo localmente

Da pasta raiz do app, faça login:

cd my-app
npx rayfin login

Inicie o frontend e o host local das funções:

npm run dev

Em um projeto com funções habilitadas, npm run dev mapeia para rayfin dev. Esse comando aplica o esquema, inicia o host de funções locais e inicia o servidor de desenvolvimento Vite. Abra a URL local impressa no terminal e mantenha o terminal funcionando enquanto desenvolve e depura o app.

Para iniciar apenas o host de funções, por exemplo, quando você roda a interface separadamente, use o seguinte comando:

cd my-app
npx rayfin dev

Implantar no Fabric

Implante os dados, o site estático e as funções do app:


npx rayfin up --workspace <workspace-name>

Substitua <WORKSPACE> pelo nome do espaço de trabalho Fabric de destino.

Adicionar funções a um aplicativo existente

A partir da raiz de um aplicativo Fabric existente, ative o recurso e inicialize o projeto de funções uma vez:


npx rayfin functions init

Após a inicialização, adicione implementações de funções a rayfin/functions/src/function_app.ts.

Limitations

  • Propriedade da função: Somente o proprietário do item de funções de dados do usuário pode modificar e publicar o código das funções.
  • Tempo de recarga para publicação: Espere pelo menos dois minutos após publicar antes de publicar novamente. Esse tempo de recarga se aplica ao publicar a partir do portal Functions no navegador, da extensão Visual Studio Code das Funções de dados do usuário, da ação de importação do Git ou dos pipelines de implantação.
  • Tamanho do pacote de implantação: O arquivo ZIP de Funções não pode exceder 30 MB.
  • Tamanho da carga útil da solicitação: O serviço de funções de dados do usuário documenta um máximo de 4 MB para todos os parâmetros de requisição combinados. Espera-se que esse limite se aplique às Funções Rayfin, mas ainda não foi verificado.
  • Tempo limite de execução: Uma função pode rodar por até 240 segundos.
  • Retenção de registros de invocação: Registros históricos de invocação são mantidos por padrão por 30 dias.
  • Identidade do aplicativo: A identidade do aplicativo é atualmente o proprietário do item BaaS.

Para requisitos regionais de disponibilidade e mais detalhes sobre limitações das funções de dados do usuário, veja Detalhes do serviço e limitações das funções de dados do usuário do Fabric.

Conteúdo relacionado

  • Última atualização em