Čítajte a zapisujte dáta pomocou GraphQL v Fabric Apps

Fabric Apps poskytuje typovo bezpečný GraphQL klient, ktorý vám umožní vykonávať operácie vytvárania, čítania, aktualizácie a mazania bez písania surových dotazov. Klient automaticky generuje GraphQL z vašich volaní metód a vracia typované entity na základe definícií vášho dátového modelu.

Predpoklady

  • Projekt Fabric Apps s definovanými dátovými modelmi. Pozri Definovať dátové modely.
  • Backendové služby bežali lokálne alebo boli nasadené na Fabric.

Inicializujte klienta

Inštancujte RayfinClient pomocou vašej backend URL, publikovateľného kľúča a typu schémy:

import { RayfinClient } from '@microsoft/rayfin-client';
import type { Note } from '../rayfin/data/Note';
import type { Notebook } from '../rayfin/data/Notebook';

type AppSchema = { 
  Note: Note;
  Notebook: Notebook;
};

const client = new RayfinClient<AppSchema>({
  baseUrl: import.meta.env.VITE_RAYFIN_API_URL ?? 'http://localhost:5168',
  publishableKey: 'pk-your-project-key',
});

Generický typ argument umožňuje TypeScriptu poskytovať automatické dopĺňanie a kontrolu typov pre všetky dátové operácie.

Čítať údaje

Pristupujte k kolekciám entít cez client.data.<EntityName>. API Fluent poskytuje metódy na dotazovanie, filtrovanie, triedenie a stránkovanie.

Načítajte všetky záznamy

const notes = await client.data.Note.select([
  'id',
  'title',
  'content',
  'createdAt',
  'isPinned',
]).execute();

Získanie jedného záznamu pomocou primárneho kľúča

const note = await client.data.Note.findByPk('00000000-0000-0000-0000-000000000000');

Tým sa vráti úplná entita alebo null ak žiadny záznam s týmto ID neexistuje.

Filtračné záznamy

Použite metódu where() na filtrovanie výsledkov:

const pinnedNotes = await client.data.Note.select([
  'id',
  'title',
  'isPinned',
])
  .where({ isPinned: { eq: true } })
  .execute();

Operátory filtra

Operátor Description Príklad
eq Rovná sa { status: { eq: 'active' } }
ne Nie rovní { status: { ne: 'archived' } }
gt Väčšie { age: { gt: 18 } }
gte Väčšie alebo rovné { age: { gte: 21 } }
lt Menšie { price: { lt: 100 } }
lte Menšie alebo rovné { price: { lte: 50 } }
contains Obsahuje podreťazec { title: { contains: 'draft' } }

Zoradiť výsledky

Použitie orderBy() na triedenie výsledkov dotazov:

const notes = await client.data.Note.select([
  'id',
  'title',
  'createdAt',
])
  .orderBy({ createdAt: 'desc' })
  .execute();

Zoradiť podľa viacerých stĺpcov:

const notes = await client.data.Note.select([
  'id',
  'title',
  'isPinned',
  'createdAt',
])
  .orderBy({ isPinned: 'desc' })
  .orderBy({ createdAt: 'desc' })
  .execute();

Keď definujete vzťahy s @one() a @many() dekorátormi, môžete do toho istého dotazu zahrnúť súvisiace entity polia:

const notes = await client.data.Note.select([
  'id',
  'title',
  'content',
  'notebook.id',
  'notebook.name',
  'notebook.color',
])
  .execute();

Každá poznámka obsahuje priradené údaje z notebooku bez potreby samostatného dotazu.

Paginujte veľké množiny výsledkov

Používajte stránkovanie na báze kurzora pre veľké zoznamy:

const page = await client.data.Note.select([
  'id',
  'title',
  'createdAt',
])
  .orderBy({ createdAt: 'desc' })
  .first(25)
  .executePaginated();

console.log('Items:', page.items);
console.log('Has next page:', page.hasNextPage);
console.log('End cursor:', page.endCursor);

Načítajte ďalšiu stránku pomocou kurzora:

if (page.hasNextPage) {
  const nextPage = await client.data.Note.select([
    'id',
    'title',
    'createdAt',
  ])
    .orderBy({ createdAt: 'desc' })
    .first(25)
    .after(page.endCursor)
    .executePaginated();
}

Poznámka

Vlastnosť totalCount sa zobrazuje na type PagedResult mape, ale nie je obsadená backendom. Použite items.length na počítanie výsledkov na aktuálnej stránke.

Vytváraj záznamy

Použite metódu vkladania nových záznamov create() :

const newNote = await client.data.Note.create({
  title: 'Meeting notes',
  content: 'Discussion points from the team sync',
  isPinned: false,
  isArchived: false,
  createdAt: new Date(),
  updatedAt: new Date(),
  user_id: 'user-123',
});

Metóda vráti vytvorenú entitu so všetkými poliami vyplnenými, vrátane automaticky generovaného id.

Vytvárajte záznamy s vzťahmi

Pri vytváraní entít, ktoré majú vzťahy, odovzdajte buď celý súvisiaci objekt, alebo objekt len s primárnym kľúčom:

// Option 1: Pass just the ID
const note = await client.data.Note.create({
  title: 'Weekly summary',
  content: 'Summary of this week',
  notebook: { id: 'notebook-456' },
  isPinned: false,
  isArchived: false,
  createdAt: new Date(),
  updatedAt: new Date(),
});

// Option 2: Pass the full object
const notebook = await client.data.Notebook.findByPk('notebook-456');
const note = await client.data.Note.create({
  title: 'Weekly summary',
  content: 'Summary of this week',
  notebook: notebook,
  isPinned: false,
  isArchived: false,
  createdAt: new Date(),
  updatedAt: new Date(),
});

Obe formy vedú k rovnakému výsledku. Použite prvý formulár, keď už poznáte ID príbuzného subjektu a chcete sa vyhnúť ďalšiemu načítavaniu.

Aktualizačné záznamy

Použite túto metódu update() na úpravu existujúcich záznamov. Prejdite filter objekt a objekt obsahujúci polia na aktualizáciu:

await client.data.Note.update(
  { id: 'note-123' },
  {
    title: 'Updated title',
    updatedAt: new Date(),
  }
);

Vzťahy s aktualizáciou

Na zmenu vzťahu odovzdajte novú súvisiacu entitu alebo len jej ID:

// Move a note to a different notebook
await client.data.Note.update(
  { id: 'note-123' },
  { notebook: { id: 'new-notebook-789' } }
);

Vymazať záznamy

Použite metódu delete() na odstránenie záznamov zodpovedajúcich filtru:

await client.data.Note.delete({ id: 'note-123' });

Metóda sa vyrieši, keď backend potvrdí vymazanie. Ak žiadny záznam nezodpovedá filtru, metóda stále funguje.

Spracovanie autentifikácie

Keď je autentifikácia povolená, prihláste sa pred vykonaním dátových operácií:

await client.auth.signIn({ email, password });

// All subsequent data calls include authentication context
const notes = await client.data.Note.select(['id', 'title']).execute();

Klient automaticky pripája autentifikačnú reláciu ku všetkým dátovým API volaniam. Nemusíš manuálne odovzdávať žetóny.

Osvedčené postupy

  • Vyberte len potrebné polia – Načítajte len tie polia, ktoré používate, aby ste zmenšili veľkosť užitočného zaťaženia a zlepšili výkon.
  • Používajte stránkovanie pre veľké zoznamy – Vyhnite sa načítavaniu tisícov záznamov naraz použitím first() a executePaginated().
  • Dávkové dotazy na vzťahy – Zahrňte súvisiace entity do rovnakého dotazu namiesto samostatných požiadaviek.
  • Cache často pristupované dáta – Ukladajte statické referenčné dáta do pamäte, aby ste znížili API volania.

Aktuálne obmedzenia

  • Táto metóda count() nie je dostupná na klientovi Fluent. Vyberte minimálne polia a použite results.length ich namiesto toho.
  • Vzťahy medzi mnohými a mnohými nie sú podporované. Použite explicitnú spojovaciu entitu s dvoma @one() navigačnými dekorátormi.
  • Nehnuteľnosť totalCount na PagedResult nie je obsadená backendom.

Súvisiaci obsah

  • Last updated on