Verbinden Sie Funktionen mit externen Ressourcen

Deployed Functions rufen externe Azure- und Fabric-Ressourcen als App-Identität durch Anwendungsauthentifizierung auf. Deklarieren Sie die Zielgruppen, die eine Funktion benötigt, und verwenden Sie plattformgestützte, ressourcenbezogene Tokens über ctx.Tokens.

Die Anmeldung bei der Entwickler-CLI und die Ermittlung des Endpunkts zur Erstellungszeit sind vom bereitgestellten Laufzeitzugriff getrennt. Verifizieren Sie die Berechtigungen der bereitgestellten App-Identität, selbst wenn ein Entwickler auf die Ressource zugreifen kann.

Prerequisites

  • Eine Fabric-App mit initialisierten Funktionen. Anweisungen zum Einrichten finden Sie unter Use Functions in Fabric Apps.
  • services.functions.auth.type in rayfin/rayfin.yml auf application festgelegt. Für Konfigurationsdetails siehe Anwendungsauthentifizierung.
  • Die App-Identität gewährte Zugriff auf jede externe Ressource, die der Funktionscode aufruft.

Erklären Sie eine externe Verbindung

Deklarieren Sie Zielgruppen in der RayfinContext Annotation und lesen Sie dann das Scoped Token aus 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';
  },
  [],
);

Die Annotation ist die Erklärung. Das Auflisten einer Zielgruppe in RayfinContext<Schema, Audiences> registriert die Verbindungsbindung. Behalten Sie das dritte Argument von udf.func() als [] bei.

ctx.Tokens ist auf die Zielgruppen beschränkt, die Sie angeben. Ein nicht deklariertes Publikum verursacht einen Kompilierungsfehler:

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

Token-Werte haben den Typ string . Die Deklaration eines Publikums registriert seine Bindung, garantiert aber keine Token-Verfügbarkeit oder Ressourcenzugriff. Wenn der Host kein deklariertes Token bereitstellt, wirft das Lesen seiner ctx.Tokens Eigenschaft einen Fehler.

Spezifizieren Sie das Schema-Argument

RayfinContext verwendet zuerst das Schema Ihrer App. Verwenden Sie dasselbe Schema, das Sie an RayfinClient<AppSchema> übergeben, damit der Data-Client beim Hinzufügen von Zielgruppen typisiert bleibt:

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

Wenn eine Funktion Audiences benötigt, aber keinen Zugriff auf die Rayfin-Datenbank hat, gib das Standardschema explizit weiter:

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

Unterstützte Zielgruppen

AudienceType ist die Quelle der Wahrheit für unterstützte Zielgruppen:

Externe Ressource AudienceType
Fabric Lakehouse, Warehouse, SQL-Datenbank in Fabric, gespiegelte Datenbank oder Azure SQL-Datenbank Sql
Fabric OneLake-Dateien, Azure Blob Storage, Azure Table Storage oder Azure Queue Storage Storage
Microsoft Fabric REST API Fabric
Azure AI Foundry AzureAI
Azure DevOps ADO

Ein Power BI-semantisches Modell ist nicht durch ctx.Tokensverfügbar. Benutze stattdessen den fabric-semanticmodel Stecker. Für Connector-Hinweise siehe Connect to Fabric-Daten.

Bereitstellungsmetadaten verstehen

Typargumente werden gelöscht, bevor eine Funktion ausgeführt wird. Während npx rayfin up, löst der TypeScript-Compiler die deklarierten Audiences auf und schreibt die Union in die Deployment-Metadaten. Der Funktionsarbeiter nutzt diese Metadaten, um die Verbindungen zu binden.

Ein Typalias funktioniert, wenn das Functions-Projekt über ein tsconfig.json verfügt:

type SqlAccess = AudienceType.Sql;

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

Bevorzuge wörtliche Werte AudienceType.X . Wenn das Functions-Projekt keine tsconfig.jsonhat, kann die CLI den Compiler nicht verwenden, sondern liest stattdessen die Annotationssyntax. In diesem Modus löst sich ein Alias auf seinen eigenen Namen auf, statt auf das Publikum, das es repräsentiert. Behandle die CLI-Warnung zu diesem Fallback als einen zu behebenden Fehler.

Der Kontextparameter muss eine explizite RayfinContext<...> Annotation haben. Die Typgenerierung identifiziert den Kontextparameter durch diese Annotation. Ohne sie wird der Parameter als Request-Body-Parameter behandelt.

Berechtigungen für Ressourcen gewähren

Bei den aktuellen Fabric-Apps ist die App-Identität der Besitzer des Fabric-App-Elements. Externe Verbindungen verwenden diese Identität und ihre Berechtigungen, nicht die Identität oder Berechtigungen des App-Benutzers, der die Funktion aufruft.

Gewähre der App-Identität die Berechtigungen, die jede Ressource und API benötigt, die der Functions-Code aufruft. Das Deklarieren einer Zielgruppe und das Bereitstellen von Functions registrieren eine Token-Bindung, gewähren aber keine Berechtigungen für die Zielressource.

Behalten Sie Ressourcentoken auf dem Server. Gib sie niemals als Funktionsergebnisse zurück oder schicke sie an das Frontend.

Die App-Anmeldung und die Autorisierung zum Aufrufen einer Funktion sind getrennt vom Zugriff der App-Identität auf externe Ressourcen.

Rayfin-DB-Identität

Die Rayfin-Datenbank verwendet einen separaten Authentifizierungspfad. ctx.getDataClient() verwendet das Rayfin-Token des Aufrufs, sodass der Datenbankzugriff die Identität und die Datenbankberechtigungen des Aufrufers bewahrt. Die Anwendungsauthentifizierung bei Functions stellt den Zugriff auf Rayfin DB nicht auf die Anwendungsidentität um.

Verwenden Sie ein Token mit einem Azure SDK

Viele Azure SDK-Clients erwarten ein TokenCredential anstelle eines reinen Token-Strings. Definieren Sie einen Adapter, der das Token aus dem Kontext zurückgibt:

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

Übergeben Sie new ContextTokenCredential(ctx.Tokens.Storage) oder das entsprechend deklarierte Token an einen SDK-Client, der Anmeldeinformationen erfordert. Installiere Resource SDK-Pakete in rayfin/functions/package.json, nicht im Projektroot.

Lokal entwickeln

npx rayfin dev und npx rayfin dev functions apply starten einen lokalen Azure Functions Core Tools-Host. Im lokalen Functions-Host verwenden externe Ressourcen-Token die Identität und Berechtigungen des Kontos, das der App-Builder zur Anmeldung verwendet.

Bereitgestellte Funktionen verwenden stattdessen die App-Identität. Ein erfolgreicher lokaler Aufruf beweist daher nicht, dass die bereitgestellte App-Identität die Berechtigung hat, auf die Ressource zuzugreifen. Teste die bereitgestellte Funktion, nachdem du der App-Identität die erforderlichen Berechtigungen erteilt hast.

Verwandte Inhalte

  • Zuletzt aktualisiert um