Używaj funkcji w aplikacjach Fabric

Funkcje to funkcje TypeScript, które działają na serwerze w Twojej aplikacji Fabric. Używaj funkcji do obsługi logiki, która nie powinna działać w przeglądarce, na przykład do obsługi wpisów tajnych, uzyskiwania dostępu do uprzywilejowanych danych oraz wywoływania usług podrzędnych przy użyciu tożsamości aplikacji.

Każda funkcja jest rejestrowana pod nazwą i udostępniana jako wywoływalny punkt końcowy HTTP. Twój frontend React wywołuje funkcję przez typowy klient Rayfin, więc nie musisz implementować żądań, routowania ani obsługi tokenów.

Note

Polecenia w tym artykule wykorzystują wersję podglądową CLI Rayfin.

Kiedy użyć funkcji

Użyj funkcji Rayfina, aby:

  • Wywołaj zewnętrzne API za pomocą tokena aplikacji. Przykładami są Azure AI Foundry, Azure DevOps, Fabric, Azure Storage oraz Azure Key Vault.
  • Odczytuj lub zapisuj bazę danych aplikacji z zabezpieczeniami na poziomie wierszy wymuszanymi przez serwer.
  • Trzymaj klucze API, nazwy wdrożeń modeli i inne sekrety z dala od kodu klienta.
  • Uruchamiaj orkiestrację, taką jak rozgałęzione wywołania, agregacja lub tworzenie promptów dla AI, blisko danych.

Wymagania wstępne

Zanim zaczniesz, zainstaluj lub stwórz następujące zasoby:

  • Node.js 20 lub nowszy oraz npm.
  • Szkielet aplikacji Fabric utworzony za pomocą narzędzia Rayfin CLI.
  • Azure Functions Core Tools, które lokalny host funkcji wykorzystuje do debugowania.

Install Azure Functions Core Tools wersja 4:

npm install --global azure-functions-core-tools@4

Stwórz aplikację z funkcjami

Konstruuj aplikację i inicjalizuj jej funkcje projektu:

npm create @microsoft/rayfin@latest

cd my-app

npx rayfin functions init

Polecenie rayfin functions init dodaje do istniejącej aplikacji projekt usługi Functions, jego konfigurację TypeScript oraz początkowy plik funkcji.

Zbuduj aplikację w GitHub Copilot

Szkielet projektu zawiera instrukcje GitHub Copilot oraz umiejętności potrzebne do pracy nad projektem. Otwórz projekt w Visual Studio Code i opisz aplikację, którą chcesz zbudować w GitHub Copilot Chat.

Na przykład użyj poniższego polecenia, aby utworzyć asystenta AI do przeglądu pull requestów:

Build an app that helps business analysts track sales performance across
regions. Show key metrics, let analysts ask questions about trends, and
use Functions to securely retrieve data from our sales API with application
authentication.

GitHub Copilot może generować i aktualizować wymagane pliki oraz komponenty. Możesz też poprosić agenta o uruchomienie aplikacji, debugowanie funkcji lokalnie i wdrożenie aplikacji.

Zrozum układ projektu

Polecenie inicjalizacji funkcji aktualizuje rayfin/rayfin.yml i tworzy rayfin/functions. Typowa aplikacja z funkcjami ma następującą strukturę:

my-app/
├── rayfin/
│   ├── rayfin.yml
│   ├── data/
│   │   ├── TripPlan.ts
│   │   └── schema.ts
│   └── functions/
│       ├── package.json
│       ├── tsconfig.json
│       └── src/
│           ├── function_app.ts
│           └── types.ts
└── src/
    └── services/

Akta te służą następującym celom:

Path Purpose
rayfin/rayfin.yml Konfiguruje uwierzytelnianie, dane, funkcje oraz usługi statycznego hostingu.
rayfin/data/ Zawiera modele danych aplikacji oraz eksporty schematów.
rayfin/functions/package.json Definiuje zależności i buduje skrypty dla projektu funkcji.
rayfin/functions/tsconfig.json Konfiguruje kompilację TypeScript dla funkcji.
rayfin/functions/src/function_app.ts Zawiera implementacje twoich funkcji.
rayfin/functions/src/types.ts Zawiera wygenerowane AppFunctionsSchema typy. Nie edytuj tego pliku ręcznie.
src/ Zawiera frontend Reacta oraz wszelkie typy domen współdzielonych lub wrapperów.

Po włączeniu funkcji rayfin/rayfin.yml zawiera usługę Functions:

services:
  functions:
    enabled: true
    auth:
      type: application
    buildCommand: npm run build

Uwierzytelnianie aplikacji

Włączone funkcje wymagają wyraźnej uwierzytelniania aplikacji w rayfin/rayfin.yml:

services:
  functions:
    enabled: true
    auth:
      type: application
    buildCommand: npm run build

Nowe funkcje tworzą szkielet auth.type: application.

Wyłączone funkcje mogą nie zawierać auth. Jednak jeśli dostarczasz auth, musi to obejmować:

auth:
  type: application

Pełny npx rayfin up oraz normalny przepływ npx rayfin dev sprawdzają poprawność tego ustawienia przed zastosowaniem ustawień projektu do backendu Fabric lub Docker.

Uruchom pełny npx rayfin up test, aby zastosować tryb uwierzytelniania YAML do istniejącej aplikacji zdalnej.

Ścieżki uwierzytelniania używane przez wdrożone funkcje

Wdrożone funkcje używają dwóch oddzielnych ścieżek uwierzytelniania:

Ścieżka dostępu Credential Tożsamość i uprawnienia
Połączenia zewnętrzne za pomocą ctx.Tokens.* Token zasobów dostarczany przez platformę Tożsamość aplikacji i jej uprawnienia do zewnętrznego zasobu
Rayfin DB przez ctx.getDataClient() Token Rayfin Invocation Tożsamość dzwoniącego i uprawnienia do bazy danych Rayfin

W aktualnych aplikacjach Fabric tożsamość aplikacji jest właścicielem elementu BaaS.

Połączenia zewnętrzne korzystają zatem z uprawnień właściciela elementu, a nie uprawnień użytkownika aplikacji, który wywołuje tę funkcję. Nadaj tożsamości aplikacji uprawnienia wymagane do uzyskania dostępu do wszystkich zasobów zewnętrznych i interfejsów API wywoływanych przez kod usługi Functions.

Deklarowanie odbiorców lub wdrażanie Funkcji nie przyznaje aplikacji uprawnień tożsamości do zewnętrznego zasobu.

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

Dostęp do bazy Rayfin zawsze korzysta z tokena Rayfin i zachowuje tożsamość dzwoniącego oraz uprawnienia do bazy danych. Ustawienie services.functions.auth.type: application nie przełącza dostępu do bazy Rayfin na tożsamość aplikacji.

Aby uzyskać informacje o deklaracjach odbiorców, tokenach zasobów, uprawnieniach i zachowaniu podczas programowania lokalnego, zobacz temat Łączenie usługi Functions z zasobami zewnętrznymi.

Uruchamianie aplikacji lokalnie

Z folderu głównego aplikacji zaloguj się:

cd my-app
npx rayfin login

Uruchom frontend i lokalny host funkcji:

npm run dev

W projekcie z obsługą funkcji npm run dev jest odwzorowywane na rayfin dev. To polecenie stosuje schemat, uruchamia lokalnego hosta funkcji oraz uruchamia serwer deweloperski Vite. Otwórz lokalny adres URL wydrukowany w terminalu i utrzymuj terminal włączony, podczas gdy rozwijasz i debugujesz aplikację.

Aby uruchomić tylko hosta funkcji, na przykład gdy uruchamiasz frontend osobno, użyj następującego polecenia:

cd my-app
npx rayfin dev

Wdrażanie w Fabric

Wdróż dane aplikacji, witrynę statyczną i funkcje:


npx rayfin up --workspace <workspace-name>

Zastąp <WORKSPACE> nazwą docelowego obszaru roboczego Fabric.

Dodaj funkcje do istniejącej aplikacji

W katalogu głównym istniejącej aplikacji Fabric włącz tę funkcję i jednorazowo zainicjalizuj projekt Functions:


npx rayfin functions init

Po inicjalizacji dodaj implementacje funkcji do rayfin/functions/src/function_app.ts.

Limitations

  • Własność funkcji: Tylko właściciel elementu funkcji danych użytkownika może modyfikować i publikować kod Funkcji.
  • Okres oczekiwania po publikacji: Odczekaj co najmniej dwie minuty po publikacji, zanim opublikujesz ponownie. Ten okres karencji ma zastosowanie podczas publikowania z portalu Functions w przeglądarce, z rozszerzenia funkcji danych użytkownika dla programu Visual Studio Code, z akcji importu Git lub z potoków wdrażania.
  • Rozmiar pakietu wdrożenia: Plik ZIP Functions nie może przekraczać 30 MB.
  • Rozmiar ładunku żądania: Usługa funkcji danych użytkownika dokumentuje maksymalnie 4 MB dla wszystkich parametrów żądania łącznie. Oczekuje się, że ten limit będzie dotyczył funkcji Rayfina, ale nie został zweryfikowany.
  • Czas wykonania: Funkcja może działać do 240 sekund.
  • Przechowywanie dziennika wywołań: Historyczne dzienniki wywołań są domyślnie przechowywane przez 30 dni.
  • Tożsamość aplikacji: Tożsamość aplikacji jest obecnie właścicielem elementu BaaS.

Aby uzyskać regionalne wymagania dotyczące dostępności oraz więcej szczegółów dotyczących ograniczeń funkcji danych użytkownika, zobacz szczegóły usług i ograniczenia funkcji danych użytkownika Fabric.

Treści powiązane

  • Ostatnia aktualizacja o