A programozási modell áttekintése

A Rayfin SDK egy dekoratőralapú programozási modellt használ, amelyben az adatsémát egyszer adja meg TypeScriptben, és automatikusan fogad éles használatra kész API-kat, típusbiztos ügyfeleket és infrastruktúrát.

főbb fogalmak

A Rayfin SDK három alapvető elemet egyesít:

  • Dekoratőr-alapú séma: TypeScript-dekorátorok használatával definiálhat adatmodelleket, engedélyeket és kapcsolatokat.
  • Automatikus API-létrehozás: A kitüntetett osztályok GraphQL-végpontokká válnak vezérlőkód írása nélkül.
  • Típusbiztos ügyfelek: A létrehozott TypeScript-ügyfelek fordítási idejű ellenőrzést biztosítanak a lekérdezésekhez és a mutációkhoz.

Hogyan működik?

Fabric-alkalmazás létrehozásakor a kód az alábbi szakaszokon halad végig:

# Stage Mi történik?
1 fejlesztő Az alkalmazást a választott szerkesztőben szerkesztheti.
2 TypeScript Entitásosztályokat ír a TypeScriptben.
3 Decorators Az osztályokat és mezőket a(z) @entity, @uuid, @text, @role és más dekorátorok használatával annotálhatja.
4 Schema A parancssori felület a kitüntetett osztályokat adatbázisséma, engedélyszabályzatok és API-konfigurációkká állítja össze.
5 API-k A séma GraphQL-végpontként van közzétéve.
6 Client A generált RayfinClient egy típusbiztos adat- és hitelesítési klienst tesz elérhetővé ezeken a végpontokon keresztül.
7 Application A frontendalkalmazás a klienst használja az adatok olvasására és írására.

1. Adatmodellek definiálása dekorátorokkal

Az adatstruktúrát TypeScript-osztályokkal és dekorátorokkal határozhatja meg a következőből @microsoft/rayfin-core:

import { entity, uuid, text, int } from '@microsoft/rayfin-core';

@entity()
export class Product {
  @uuid() id!: string;
  @text() name!: string;
  @text({ optional: true }) description?: string;
  @int() price!: number;
}

2. Séma létrehozása

A Rayfin CLI (npx rayfin) elemzi a dekorált osztályokat, és a következőket hozza létre:

  • Adatbázisséma – Táblák, oszlopok, korlátozások és indexek
  • API-konfiguráció – GraphQL-végpontdefiníciók
  • Engedélyszabályzatok – Sorszintű biztonság és mezőszintű hozzáférés-vezérlés

4. A típusbiztos kliens használata

A GraphQL API-k a CRUD-műveletek adatbázison való végrehajtásához érhetők el. A Rayfin SDK egy adatügyfél-műveletet biztosít a dobozon kívül az adatok olvasásához vagy írásához vagy törléséhez.

import { RayfinClient } from '@microsoft/rayfin-client';

const client = new RayfinClient();

// TypeScript knows about Product fields
const products = await client.data.products.query()
  .select(['id', 'name', 'price'])
  .execute();

// Compile-time error if field doesn't exist
const invalid = await client.data.products.query()
  .select(['nonexistentField'])  // ❌ TypeScript error
  .execute();

Dekorátor referenciája

A Rayfin SDK dekorátorokat biztosít a gyakori adatmodellezési mintákhoz:

Entitás-dekorátorok

Lakberendező Alkalmazás célja Example
@entity() Osztály megjelölése adatbázis-entitásként @entity() class Product

Ingatlan dekorátorok

Lakberendező Adatbázis típusa TypeScript-típus
@uuid() UNIQUEIDENTIFIER string
@text() NVARCHAR string
@int() INT number
@decimal() TIZEDES number
@bool() BIT boolean
@date() DATETIME2 Date

Jogosultságdekorátorok

Lakberendező Alkalmazás célja
@role() Szerepköralapú engedélyek definiálása

Lásd: Adatengedélyek meghatározása az engedélyezési adatokhoz.

Functions

Hozz létre egy UserDataFunctions példányt, és regisztráljunk minden függvényt a hívással udf.func(name, handler, connections?).

Kövesse ezeket a szabályokat, amikor meghatározod egy függvényt:

  • Helyezze a RayfinContext paramétert a kezelő aláírás bármely helyére. A futtatókörnyezet típus alapján azonosítja, injektálja, és kizárja a generált függvény bemeneti paraméterei közül.
  • Deklaráljon egy kapcsolatot a függvény által igényelt minden delegált tokenhez. Hagyd ki a connections tömböt azoknál a függvényeknél, amelyek csak app adatokhoz férnek hozzá, vagy nem igényelnek delegált tokeneket.

Az alábbi példa egy egyszerű függvényt és egy olyan függvényt regisztrál, amely az invocation kontextust használja:

import {
  UserDataFunctions,
  type RayfinContext,
} from '@microsoft/fabric-user-data-functions';

// Match rayfin/data/schema.ts so getDataClient() is fully typed.
import type { TripPlan } from '../../data/TripPlan.js';

type AppSchema = { TripPlan: TripPlan };

const udf = new UserDataFunctions();

udf.func('greet', async (name: string): Promise<string> => {
  return `Hello, ${name}!`;
});

udf.func(
  'whoAmI',
  async (ctx: RayfinContext<AppSchema>): Promise<string> => {
    return ctx.accessToken ? 'authenticated' : 'anonymous';
  },
);

Biztosítja RayfinContext a funkció futási idejű szolgáltatásait:

Tag Alkalmazás célja
ctx.accessToken Biztosítja a bejelentkezett felhasználó Rayfin JSON Web Tokenjét (JWT). Dekódold a sub jogcímet a stabil felhasználói azonosító lekéréséhez.
ctx.Tokens.<Audience> Platform által biztosított erőforrás tokent kap egy annotációban bejelentett RayfinContext közönség számára. A telepített függvények az alkalmazás identitását és annak jogosultságait használják. Részletekért lásd: Kapcsolja a függvényeket külső erőforrásokhoz.
ctx.getSecret('NAME') Lekéri az aktuális meghívás titkát. undefined értéket ad vissza, ha a titok nincs beállítva.
ctx.getDataClient() Lekéri az entitásaihoz tartozó típusos adatok API-ját. A kliens támogatja a létrehozási, findMany frissítési, törlési és upsert műveleteket.
ctx.baseUrl Megadja a Rayfin végpontját az aktuális elemhez.
ctx.publishableKey Megadja a jelenlegi tétel publikálható kulcsát.

A beállítás, helyi hibakeresés és telepítési utasítások esetén lásd: Használd a funkciókat a Fabric Apps-ben.

Fejlesztési munkafolyamat

Egy tipikus fejlesztési ciklus a következő mintát követi:

  1. Adatmodellek definiálása vagy módosítása – TypeScript-osztályok hozzáadása vagy frissítése dekorátorokkal
  2. Helyi tesztelés távoli háttérrendszerrel - A npm run dev futtatásával tesztelheti a frontendkód módosításait a Fabricben található alkalmazás-háttérrendszerrel.
  3. Deploy to Fabric – Futtassa a npx rayfin up parancsot a felügyelt Fabric szolgáltatásban való üzembe helyezéshez, és alkalmazza a séma módosításait.

A TypeScript-modellek módosításai automatikusan végigterjednek a teljes technológiai rétegen — az adatbázissémától az API-végpontokon át a kliensoldali típusokig.

Authorization

A jogosultságok az adatmodellek mellett, a @role dekorátorral vannak definiálva:

@entity()
@role('authenticated', ['create', 'read', 'update', 'delete'], {
  policy: (claims, item) => claims.sub.eq(item.userId)
})
export class UserDocument {
  @uuid() id!: string;
  @text() userId!: string;
  @text() content!: string;
}

Ez a megközelítés a következőket biztosítja:

  • A biztonsági szabályok közvetlenül az általuk védett adatok mellett vannak.
  • A típusbiztos szabályzatkifejezések fordítási időben kiszűrik a hibákat
  • Az entitásmezők újrabontása automatikusan frissíti az engedélyellenőrzéseket

Kapcsolódó tartalom

  • Utolsó frissítés időpontja: