Łącz funkcje z zewnętrznymi zasobami

Wdrożone funkcje wywołują zewnętrzne zasoby platform Azure i Fabric przy użyciu tożsamości aplikacji, korzystając z uwierzytelniania aplikacyjnego. Określ odbiorców wymaganych przez funkcję i używaj dostarczanych przez platformę tokenów ograniczonych do zasobu za pomocą ctx.Tokens.

Logowanie w narzędziu Developer CLI oraz wykrywanie punktów końcowych na etapie tworzenia są oddzielone od dostępu w środowisku uruchomieniowym po wdrożeniu. Weryfikuj uprawnienia wdrożonej aplikacji nawet wtedy, gdy deweloper ma dostęp do zasobu.

Wymagania wstępne

  • Aplikacja Fabric z inicjalizowanymi funkcjami. Instrukcje konfiguracji znajdziesz w sekcji Używaj funkcji w Fabric Apps.
  • services.functions.auth.type ustaw na application w rayfin/rayfin.yml. Szczegóły konfiguracji można znaleźć w artykule o uwierzytelnianiu aplikacji.
  • Tożsamość aplikacji dawała dostęp do każdego zewnętrznego zasobu wywoływanego przez kod Funkcji.

Zadeklaruj połączenie zewnętrzne

Zadeklaruj odbiorców w adnotacji RayfinContext, a następnie odczytaj token o ograniczonym zakresie z 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';
  },
  [],
);

Adnotacja to deklaracja. Wpisanie odbiorcy w RayfinContext<Schema, Audiences> rejestruje powiązanie połączenia. Pozostaw trzeci argument elementu udf.func() jako [].

ctx.Tokens jest ograniczone do odbiorców, których określasz. Niezadeklarowana publiczność powoduje błąd kompilacji:

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

Wartości tokenów mają string typ. Deklarowanie odbiorców rejestruje jego powiązanie, ale nie gwarantuje dostępności tokenów ani dostępu do zasobów. Jeśli host nie dostarczy zadeklarowanego tokena, odczytanie jego ctx.Tokens właściwości powoduje błąd.

Określ argument schematu

RayfinContext najpierw pobiera schemat aplikacji. Użyj tego samego schematu, który przekazujesz do RayfinClient<AppSchema>, aby klient danych pozostawał typowany podczas dodawania grup odbiorców:

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

Jeśli funkcja potrzebuje odbiorców, ale nie ma dostępu do Rayfin DB, należy wprost przekazać schemat domyślny:

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

Obsługiwane grupy odbiorców

AudienceType jest wiarygodnym źródłem informacji o obsługiwanych odbiorcach:

Zasób zewnętrzny AudienceType
Fabric lakehouse, magazyn, baza danych SQL w Fabric, baza danych lustrzana lub Azure SQL Database Sql
Fabric OneLake files, Azure Blob Storage, Azure Table storage lub Azure Queue Storage Storage
Microsoft Fabric REST API Fabric
Azure AI Foundry AzureAI
Azure DevOps ADO

Model semantyczny Power BI nie jest dostępny przez ctx.Tokens. Użyj zamiast tego złącza fabric-semanticmodel . Aby uzyskać wskazówki dotyczące złączy, zobacz Connect to Fabric data.

Zrozum metadane wdrożeń

Argumenty typowe są usuwane przed uruchomieniem funkcji. Podczas npx rayfin up, kompilator TypeScript rozwiązuje deklarowane grupy odbiorców i zapisuje unację w metadanych wdrożenia. Pracownik Funkcji wykorzystuje te metadane do wiązania połączeń.

Alias typu działa, gdy projekt Functions ma element tsconfig.json:

type SqlAccess = AudienceType.Sql;

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

Wolę wartości dosłowne AudienceType.X . Jeśli projekt Functions nie ma tsconfig.json, interfejs CLI nie może używać kompilatora i zamiast tego odczytuje składnię adnotacji. W tym trybie pseudonim jest interpretowany jako własna nazwa, a nie jako grupa odbiorców, którą reprezentuje. Traktuj ostrzeżenie CLI o tym fallbacku jako błąd do naprawy.

Parametr kontekstu musi mieć jawną adnotację RayfinContext<...>. Generowanie typów identyfikuje parametr kontekstu za pomocą tej adnotacji. Bez niego parametr jest traktowany jako parametr treści żądania.

Przyznaj uprawnienia do zasobów

W obecnych aplikacjach Fabric tożsamość aplikacji jest właścicielem elementu aplikacji Fabric. Połączenia zewnętrzne wykorzystują tę tożsamość i jej uprawnienia, a nie tożsamość ani uprawnienia użytkownika aplikacji, który wywołuje tę funkcję.

Przyznaj tożsamości aplikacji uprawnienia wymagane dla każdego zasobu i interfejsu API wywoływanych przez kod usługi Functions. Deklarowanie odbiorcy i wdrażanie funkcji rejestruje wiązanie tokenów, ale nie przyznaje uprawnień do docelowego zasobu.

Trzymaj tokeny zasobów na serwerze. Nigdy nie zwracaj ich jako wyników funkcji ani nie wysyłaj ich do frontendu.

Logowanie aplikacji i autoryzacja do wywołania funkcji są oddzielne od dostępu tożsamości aplikacji do zewnętrznych zasobów.

Identyfikator Rayfin DB

Rayfin DB używa osobnej ścieżki uwierzytelniania. ctx.getDataClient() używa tokenu Rayfin wywołania, dzięki czemu dostęp do bazy danych zachowuje tożsamość wywołującego oraz uprawnienia do bazy danych. Uwierzytelnianie aplikacji w usłudze Functions nie przełącza dostępu do bazy danych Rayfin na tożsamość aplikacji.

Użyj tokena z Azure SDK

Wielu klientów Azure SDK oczekuje elementu TokenCredential, a nie surowego ciągu tokenu. Zdefiniuj adapter, który zwraca token z kontekstu:

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

Przekaż new ContextTokenCredential(ctx.Tokens.Storage) lub odpowiedni zadeklarowany token do klienta SDK, który wymaga poświadczeń. Pakiety resource SDK instaluj w rayfin/functions/package.json, a nie w korzu projektu.

Rozwijaj lokalnie

npx rayfin dev oraz npx rayfin dev functions apply uruchamiają lokalny host Azure Functions Core Tools. W lokalnym hostie Functions zewnętrzne tokeny zasobów wykorzystują tożsamość i uprawnienia konta, którego użytkownik aplikacji używa do logowania.

Funkcje wdrożone zamiast tego używają tożsamości aplikacji. Udane lokalne połączenie nie dowodzi więc, że wdrożona tożsamość aplikacji ma uprawnienia do dostępu do zasobu. Przetestuj wdrożoną funkcję po przyznaniu tożsamości aplikacji wymaganych uprawnień.

Treści powiązane

  • Ostatnia aktualizacja o