Verbind functies met externe bronnen

Deployed Functions roepen externe Azure- en Fabric-resources aan als de app-identiteit door applicatieauthenticatie te gebruiken. Geef op welke doelgroepen een functie nodig heeft en gebruik door het platform verstrekte resourcetokens met beperkt bereik via ctx.Tokens.

Aanmelden bij de Developer CLI en het detecteren van eindpunten tijdens het ontwikkelen staan los van runtime-toegang na implementatie. Controleer de rechten van de geïmplementeerde app-identiteit, zelfs wanneer een ontwikkelaar toegang heeft tot de bron.

Prerequisites

  • Een Fabric-app waarin Functions is geïnitialiseerd. Voor installatie-instructies, zie Use Functions in Fabric Apps.
  • services.functions.auth.type Ingesteld op application in rayfin/rayfin.yml. Voor configuratiedetails, zie Application authentication.
  • De app-identiteit gaf toegang tot elke externe resource die de Functions-code aanroept.

Verklaar een externe verbinding

Verklaar doelgroepen in de RayfinContext annotatie en lees vervolgens het scoped token uit :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';
  },
  [],
);

De annotatie is de verklaring. Het vermelden van een publiek in RayfinContext<Schema, Audiences> registreert de verbindingsbinding. Houd het derde argument als udf.func()[].

ctx.Tokens is beperkt tot de doelgroepen die je aangeeft. Een niet-gedeclareerd publiek veroorzaakt een compileerfout:

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

Tokenwaarden hebben het type string . Het declareren van een publiek registreert de binding ervan, maar garandeert geen tokenbeschikbaarheid of toegang tot bronnen. Als de host geen gedeclareerd token levert, levert het lezen van de eigenschap een ctx.Tokens foutmelding op.

Specificeer het schema-argument

RayfinContext Neemt eerst je app-schema. Gebruik hetzelfde schema dat je doorgeeft aan RayfinClient<AppSchema>, zodat de dataclient getypeerd blijft wanneer je doelgroepen toevoegt:

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

Als een functie doelgroepen nodig heeft maar geen toegang heeft tot Rayfin DB, geef dan expliciet het standaardschema door:

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

Ondersteunde doelgroepen

AudienceType is de bron van waarheid voor ondersteunde doelgroepen:

Externe bron AudienceType
Fabric lakehouse, magazijn, SQL-database in Fabric, gespiegelde database, of Azure SQL Database Sql
Fabric OneLake files, Azure Blob Storage, Azure Table storage, eller Azure Queue Storage Storage
Microsoft Fabric REST API Fabric
Azure AI Foundry AzureAI
Azure DevOps ADO

Een Power BI semantisch model is niet beschikbaar via ctx.Tokens. Gebruik in plaats daarvan de fabric-semanticmodel connector. Voor connectorrichtlijnen, zie Connect to Fabric-gegevens.

Begrijp implementatiemetadata

Typeargumenten worden gewist voordat een functie wordt uitgevoerd. Tijdens npx rayfin up, lost de TypeScript-compiler de gedeclareerde audiences op en schrijft de unie in deploymentmetadata. De Functions-worker gebruikt die metadata om de verbindingen te binden.

Een typealias functioneert als het Functions-project een tsconfig.json-verwijzing heeft:

type SqlAccess = AudienceType.Sql;

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

Geef de voorkeur aan letterlijke AudienceType.X waarden. Als het Functions-project geen tsconfig.json heeft, kan de CLI de compiler niet gebruiken en leest deze in plaats daarvan de annotatiesyntaxis. In die modus verwijst een alias naar zijn eigen naam in plaats van naar de doelgroep die het vertegenwoordigt. Behandel de CLI-waarschuwing over deze fallback als een fout om te herstellen.

De contextparameter moet een expliciete RayfinContext<...> annotatie hebben. Typegeneratie identificeert de contextparameter via deze annotatie. Zonder deze parameter wordt de parameter behandeld als een request-body parameter.

Machtigingen voor resources verlenen

Voor huidige Fabric-apps is de app-identiteit de eigenaar van het Fabric-app-item. Externe verbindingen gebruiken deze identiteit en de bijbehorende rechten, niet de identiteit of de rechten van de app-gebruiker die de functie aanroept.

Verleen de app-identiteit de rechten die vereist zijn door elke resource en API die de Functions-code aanroept. Het declareren van een publiek en het deployen van Functions registreert een tokenbinding, maar geeft geen rechten op de doelresource.

Houd resourcetokens op de server. Stuur ze nooit terug als functieresultaten of stuur ze naar de frontend.

App-aanmelden en autorisatie om een functie aan te roepen staan los van de toegang van de app-identiteit tot externe bronnen.

Rayfin DB-identiteit

Rayfin DB gebruikt een apart authenticatiepad. ctx.getDataClient() gebruikt het Rayfin-token van de aanroeping, zodat database-toegang de identiteit en databaserechten van de aanroeper behoudt. Applicatieauthenticatie voor Functions schakelt de toegang van Rayfin DB niet over naar de applicatieidentiteit.

Gebruik een token met een Azure SDK

Veel Azure SDK-clients verwachten een TokenCredential tokenstring in plaats van een ruwe tokenstring. Definieer een adapter die het token uit de context terugstuurt:

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

Geef new ContextTokenCredential(ctx.Tokens.Storage) of geef het juiste gedeclareerde token door aan een SDK-client die een credential vereist. Installeer resource SDK-pakketten in rayfin/functions/package.json, niet in de projectroot.

Lokaal ontwikkelen

npx rayfin dev en npx rayfin dev functions apply starten een lokale host voor Azure Functions Core Tools. In de lokale Functions-host gebruiken externe resourcetokens de identiteit en rechten van het account waarmee de appbuilder inloggt.

Deployed Functions gebruiken in plaats daarvan de app-identiteit. Een succesvolle lokale oproep bewijst daarom niet dat de gedeployte app-identiteit toestemming heeft om toegang te krijgen tot de bron. Test de geïmplementeerde functie nadat je de applicatie-identiteit de vereiste rechten hebt gegeven.

Verwante onderwerpen

  • Laatst bijgewerkt om