Koble funksjoner til eksterne ressurser

Deployerte funksjoner kaller eksterne Azure- og Fabric-ressurser som applikasjonsidentitet ved å bruke applikasjonsautentisering. Erklær målgruppene som en funksjon trenger, og bruk plattformleverte, ressursbaserte tokens gjennom ctx.Tokens.

Utvikler-CLI-innlogging og sluttpunktsoppdagelse under forfattertid er separate fra distribuert kjøretidstilgang. Verifiser tillatelsene til den distribuerte appens identitet selv når en utvikler kan få tilgang til ressursen.

Forutsetninger

  • En Fabric-app med Functions initialisert. For oppsettsinstruksjoner, se Bruk funksjoner i Fabric Apps.
  • services.functions.auth.type Satt til application i rayfin/rayfin.yml. For konfigurasjonsdetaljer, se applikasjonsautentisering.
  • App-identiteten ga tilgang til hver ekstern ressurs som Functions-koden kaller.

Erklær en ekstern tilkobling

Deklarer publikum i annotasjonen RayfinContext , og les deretter den scoped token fra 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';
  },
  [],
);

Annotasjonen er erklæringen. Å liste opp et publikum i RayfinContext<Schema, Audiences> registrerer forbindelsesbindingen. Behold det tredje argumentet som udf.func()[].

ctx.Tokens er snevret inn til målgruppene du erklærer. Et udeklarert publikum forårsaker en kompileringsfeil:

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

Token-verdier har typen string . Å erklære et publikum registrerer bindingen, men garanterer ikke token-tilgjengelighet eller ressurstilgang. Hvis verten ikke leverer en deklarert token, gir lesing av egenskapen en ctx.Tokens feilmelding.

Spesifiser skjemaargumentet

RayfinContext Tar appens skjema først. Bruk det samme skjemaet du sender til RayfinClient<AppSchema> , slik at dataklienten forblir typet når du legger til målgrupper:

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

Hvis en funksjon trenger audiences, men ikke får tilgang til Rayfin DB, send standardskjemaet eksplisitt:

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

Støttepublikum

AudienceType er kilden til sannhet for støttede målgrupper:

Ekstern ressurs AudienceType
Fabric lakehouse, lager, SQL-database i Fabric, speilet database, eller 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

En Power BI-semantisk modell er ikke tilgjengelig gjennom ctx.Tokens. Bruk kontakten fabric-semanticmodel i stedet. For veiledning om kontakter, se Connect to Fabric-data.

Forstå distribusjonsmetadata

Typeargumenter slettes før en funksjon kjøres. Under npx rayfin up, løser TypeScript-kompilatoren de deklarerte audiencene og skriver unionen inn i distribusjonsmetadata. Functions-arbeideren bruker denne metadataen til å binde forbindelsene.

Et typealias fungerer når Functions-prosjektet har en tsconfig.json:

type SqlAccess = AudienceType.Sql;

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

Foretrekk bokstavelige AudienceType.X verdier. Hvis Functions-prosjektet ikke har , tsconfig.jsonkan ikke CLI-en bruke kompilatoren, men leser i stedet annotasjonssyntaksen. I den modusen løses et alias til sitt eget navn i stedet for publikumet det representerer. Behandle CLI-advarselen om denne fallbacken som en feil som må fikses.

Kontekstparameteren må ha en eksplisitt RayfinContext<...> annotasjon. Typegenerering identifiserer kontekstparameteren ved denne annotasjonen. Uten den behandles parameteren som en forespørselsparameter.

Gi ressurstillatelser

For dagens Fabric-apper er app-identiteten eieren av Fabric-app-elementet. Eksterne tilkoblinger bruker denne identiteten og dens tillatelser, ikke identiteten eller tillatelsene til appbrukeren som kaller funksjonen.

Gi app-identiteten de tillatelsene som kreves av hver ressurs og API som Functions-koden kaller. Å erklære et publikum og distribuere Functions registrerer en tokenbinding, men gir ikke tillatelser til målressursen.

Hold ressurstokens på serveren. Returner dem aldri som funksjonsresultater eller send dem til frontend.

App-innlogging og autorisasjon for å starte en funksjon er adskilt fra appidentitetens tilgang til eksterne ressurser.

Rayfin DB-identitet

Rayfin DB bruker en separat autentiseringsvei. ctx.getDataClient() bruker invokasjonens Rayfin-token, slik at databasetilgang bevarer kallerens identitet og databasetillatelser. Applikasjonsautentisering for Functions bytter ikke Rayfin DB-tilgang til applikasjonsidentiteten.

Bruk en token med et Azure SDK

Mange Azure SDK-klienter forventer en TokenCredential token-streng i stedet for en rå token-streng. Definer en adapter som returnerer tokenet fra konteksten:

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

Send new ContextTokenCredential(ctx.Tokens.Storage) eller det aktuelle deklarerte tokenet til en SDK-klient som krever en legitimasjon. Installer ressurs-SDK-pakker i rayfin/functions/package.json, ikke i prosjektroten.

Utvikle lokalt

npx rayfin devog npx rayfin dev functions apply starte en lokal Azure Functions Core Tools-vert. I den lokale Functions-verten bruker eksterne ressurstokens identiteten og tillatelsene til kontoen som appbyggeren bruker for å logge inn.

Distribuerte funksjoner bruker i stedet app-identiteten. Et vellykket lokalt kall beviser derfor ikke at den distribuerte app-identiteten har tillatelse til å få tilgang til ressursen. Test den distribuerte funksjonen etter at du har gitt appens identitet de nødvendige tillatelsene.

Relatert innhold

  • Sist oppdatert