Collega le funzioni a risorse esterne

Le funzioni distribuite chiamano risorse esterne di Azure e Fabric usando l'identità dell'app tramite l'autenticazione dell'applicazione. Dichiara i destinatari di cui una funzione necessita e usa token forniti dalla piattaforma con ambito limitato alle risorse tramite ctx.Tokens.

L'accesso alla CLI per sviluppatori e il rilevamento degli endpoint in fase di authoring sono separati dall'accesso al runtime distribuito. Verifica i permessi dell'identità dell'app distribuita anche quando uno sviluppatore può accedere alla risorsa.

Prerequisites

  • Un'app Fabric con Funzioni inizializzata. Per le istruzioni di configurazione, vedi Usa le funzioni nelle app Fabric.
  • services.functions.auth.type impostato su application in rayfin/rayfin.yml. Per i dettagli di configurazione, vedi Autenticazione applicativa.
  • L'identità dell'app concedeva l'accesso a ogni risorsa esterna che il codice Functions chiamava.

Dichiarare una connessione esterna

Dichiara i destinatari nell'annotazione RayfinContext, quindi leggi il token con ambito definito da 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';
  },
  [],
);

L'annotazione è la dichiarazione. Elencare un pubblico in RayfinContext<Schema, Audiences> registra il vincolo della connessione. Mantenere il terzo argomento di udf.func() come [].

ctx.Tokens è limitato ai segmenti di pubblico che specifichi. Un pubblico non dichiarato causa un errore di compilazione:

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

I valori dei token hanno il string tipo. Dichiarare un pubblico registra il suo vincolamento, ma non garantisce la disponibilità dei token o l'accesso alle risorse. Se l'host non fornisce un token dichiarato, leggere la sua ctx.Tokens proprietà genera un errore.

Specificare l'argomento dello schema

RayfinContext usa prima lo schema della tua app. Usa lo stesso schema che passi a RayfinClient<AppSchema> in modo che il client dati rimanga tipizzato quando aggiungi segmenti di pubblico:

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

Se una funzione ha bisogno di pubblico ma non accede a Rayfin DB, passa esplicitamente lo schema predefinito:

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

Tipi di pubblico supportati

AudienceType è la fonte di verità per il pubblico supportato:

Risorsa esterna AudienceType
Fabric lakehouse, magazzino, database SQL in Fabric, database speculare o database SQL di Azure Sql
file di Fabric OneLake, Archiviazione BLOB di Azure, Azure Table Storage o archiviazione code di Azure Storage
Microsoft Fabric REST API Fabric
Fonderia Azure AI AzureAI
Azure DevOps ADO

Un modello semantico Power BI non è disponibile tramite ctx.Tokens. Usa invece il fabric-semanticmodel connettore. Per indicazioni relative ai connettori, consulta Connettersi ai dati di Fabric.

Comprendere i metadati di distribuzione

Gli argomenti di tipo vengono cancellati prima che una funzione venga eseguita. Durante npx rayfin up, il compilatore TypeScript risolve i destinatari dichiarati e scrive l'unione nei metadati di distribuzione. Il worker di Functions usa questi metadati per associare le connessioni.

Un alias di tipo funziona quando il progetto Functions ha un tsconfig.json:

type SqlAccess = AudienceType.Sql;

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

Preferisco valori letterali AudienceType.X . Se il progetto Functions non ha tsconfig.json, la CLI non può usare il compilatore e legge invece la sintassi di annotazione. In quella modalità, un alias si risolve con il proprio nome piuttosto che sul pubblico che rappresenta. Considera l'avviso della CLI su questo fallback come un errore da risolvere.

Il parametro di contesto deve avere un'annotazione esplicita RayfinContext<...> . La generazione del tipo identifica il parametro di contesto tramite questa annotazione. Senza di esso, il parametro viene trattato come un parametro del corpo della richiesta.

Concedere permessi di risorsa

Per le app Fabric attuali, l'identità dell'app è il proprietario dell'oggetto Fabric app. Le connessioni esterne utilizzano questa identità e i suoi permessi, non l'identità o i permessi dell'utente dell'app che invoca la funzione.

Concedi all'identità dell'app le autorizzazioni richieste da ogni risorsa e API a cui il codice di Functions accede. La dichiarazione di un'audience e la distribuzione di Functions registrano un token binding, ma non concedono autorizzazioni sulla risorsa di destinazione.

Tieni i token delle risorse sul server. Non restituirli mai come risultati di funzione o inviarli al frontend.

L'accesso all'app e l'autorizzazione a invocare una funzione sono separati dall'accesso dell'identità dell'app alle risorse esterne.

Identità di Rayfin DB

Il database Rayfin utilizza un percorso di autenticazione separato. ctx.getDataClient() utilizza il token Rayfin dell'invocazione, così l'accesso al database preserva l'identità del chiamante e i permessi del database. L'autenticazione applicativa per Funzioni non commuta l'accesso al database Rayfin all'identità dell'applicazione.

Usa un token con un Azure SDK

Molti client dell'SDK di Azure si aspettano un TokenCredential invece di una stringa di token grezza. Definiamo un adattatore che restituisce il token dal contesto:

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

Passa new ContextTokenCredential(ctx.Tokens.Storage) o il token dichiarato appropriato a un client SDK che richiede una credenziale. Installa i pacchetti SDK di risorse in rayfin/functions/package.json, non nella radice del progetto.

Sviluppare in locale

npx rayfin deve npx rayfin dev functions apply avviare un host locale di Funzioni di Azure Core Tools. Nell'host Functions locale, i token di risorse esterni utilizzano l'identità e i permessi dell'account che l'app builder utilizza per accedere.

Le Funzioni Distribuite invece utilizzano l'identità dell'app. Una chiamata locale riuscita quindi non dimostra che l'identità dell'app distribuita abbia il permesso di accedere alla risorsa. Verifica la funzione distribuita dopo aver concesso all'identità dell'app le autorizzazioni richieste.

Contenuti correlati

  • Ultimo aggiornamento: