Connecter les fonctions à des ressources externes

Les fonctions déployées appellent des ressources externes Azure et Fabric comme identité d’application en utilisant l’authentification applicative. Déclarez les audiences requises par une fonction et utilisez, via ctx.Tokens, des jetons fournis par la plateforme à portée limitée aux ressources.

La connexion via la CLI du développeur et la découverte des points de terminaison lors de la phase de création sont distinctes de l’accès à l’environnement d’exécution déployé. Vérifiez les autorisations de l’identité de l’application déployée même lorsqu’un développeur peut accéder à la ressource.

Prerequisites

  • Une application Fabric dont les fonctions ont été initialisées. Pour les instructions de configuration, voir Utiliser les fonctions dans les applications Fabric.
  • services.functions.auth.type défini sur application dans rayfin/rayfin.yml. Pour les détails de configuration, voir Authentification des applications.
  • L’identité de l’application donnait accès à chaque ressource externe appelée par le code Functions.

Déclarer une connexion externe

Déclarez les audiences dans l’annotation RayfinContext, puis lisez le jeton délimité à partir de 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’annotation est la déclaration. Indiquer une audience dans RayfinContext<Schema, Audiences> enregistre la liaison de connexion. Conservez le troisième argument de udf.func() comme [].

ctx.Tokens est limité aux audiences que vous définissez. Un public non déterminé provoque une erreur de compilation :

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

Les valeurs des jetons ont ce string type. Déclarer une audience enregistre son association, mais ne garantit pas la disponibilité des jetons ni l’accès aux ressources. Si l’hôte ne fournit pas de jeton déclaré, lire sa ctx.Tokens propriété génère une erreur.

Spécifier l’argument du schéma

RayfinContext Prends d’abord le schéma de ton application. Utilisez le même schéma que vous transmettez à RayfinClient<AppSchema> pour que le client de données reste typé lorsque vous ajoutez des audiences :

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

Si une fonction a besoin d’audiences mais n’accéde pas à Rayfin DB, passez explicitement le schéma par défaut :

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

Public de soutien

AudienceType est la source de vérité pour les publics soutenus :

Ressource externe AudienceType
Fabric lakehouse, entrepôt de données, base de données SQL dans Fabric, base de données en miroir ou Azure SQL Database Sql
Fabric OneLake files, Stockage Blob Azure, Azure Table Storage, ou Stockage File d'attente Azure Storage
API Microsoft Fabric REST Fabric
Azure AI Foundry AzureAI
Azure DevOps ADO

Un modèle sémantique Power BI n'est pas disponible via ctx.Tokens. Utilisez plutôt le fabric-semanticmodel connecteur. Pour des conseils sur les connecteurs, voir Connect to Fabric data.

Comprendre les métadonnées de déploiement

Les arguments de type sont effacés avant qu’une fonction ne soit exécutée. Lors de npx rayfin up, le compilateur TypeScript résout les audiences déclarées et inscrit l’union dans les métadonnées de déploiement. L’ouvrier Fonctions utilise ces métadonnées pour lier les connexions.

Un alias de type fonctionne lorsque le projet Fonctions possède un tsconfig.json:

type SqlAccess = AudienceType.Sql;

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

Je préfère les valeurs littérales AudienceType.X . Si le projet Functions n’a pas tsconfig.json, la CLI ne peut pas utiliser le compilateur et lit plutôt la syntaxe des annotations. Dans ce mode, un alias se résout à son propre nom plutôt qu’au public qu’il représente. Considérez l’avertissement CLI concernant ce repli comme une erreur à corriger.

Le paramètre de contexte doit comporter une annotation explicite RayfinContext<...> . La génération de type identifie le paramètre de contexte par cette annotation. Sans cela, le paramètre est traité comme un paramètre de corps de requête.

Accorder des autorisations de ressources

Pour les applications Fabric actuelles, l’identité de l’application est le propriétaire de l’élément Fabric app. Les connexions externes utilisent cette identité et ses permissions, et non l’identité ou les permissions de l’utilisateur de l’application qui invoque la fonction.

Accordez à l’identité de l’application les autorisations requises par chaque ressource et API que le code Fonctions appelle. Déclarer une audience et déployer des fonctions enregistre une liaison de jeton mais n’accorde pas d’autorisations sur la ressource cible.

Gardez des jetons de ressources sur le serveur. Ne les retournez jamais comme résultats de fonction ni ne les envoyez au frontend.

La connexion à l’application et l’autorisation d’invoquer une fonction sont distinctes de l’accès de l’identité de l’application aux ressources externes.

Identité de la base de données Rayfin

La base de données Rayfin utilise un chemin d’authentification séparé. ctx.getDataClient() utilise le jeton Rayfin de l’invocation, de sorte que l’accès à la base de données préserve l’identité de l’appelant et les permissions de la base de données. L’authentification des applications pour les fonctions ne modifie pas l’accès à la base de données Rayfin vers l’identité de l’application.

Utilisez un jeton avec un Kit de développement logiciel (SDK) Azure

De nombreux clients du SDK Azure attendent TokenCredential plutôt qu’une chaîne de jeton brute. Définissez un adaptateur qui renvoie le jeton à partir du contexte :

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

Passer new ContextTokenCredential(ctx.Tokens.Storage) ou le jeton déclaré approprié à un client SDK qui nécessite une accréditation. Installez les paquets SDK de ressources dans rayfin/functions/package.json, pas dans la racine du projet.

Développer localement

npx rayfin dev et npx rayfin dev functions apply démarrent un hôte local Azure Functions Core Tools. Dans l’hôte Fonctions local, les jetons de ressources externes utilisent l’identité et les permissions du compte que le constructeur d’applications utilise pour se connecter.

Les fonctions déployées utilisent plutôt l’identité de l’application. Un appel local réussi ne prouve donc pas que l’identité de l’application déployée a la permission d’accéder à la ressource. Testez la fonction déployée après avoir accordé à l’identité de l’application les autorisations requises.

Contenu connexe

  • Dernière mise à jour :