Läsa och skriva data med GraphQL i Fabric Apps

Fabric Apps tillhandahåller en typsäker GraphQL-klient som låter dig utföra åtgärderna skapa, läsa, uppdatera och ta bort utan att skriva råa frågor. Klienten genererar GraphQL automatiskt från dina metodanrop och returnerar inskrivna entiteter baserat på dina datamodelldefinitioner.

Förutsättningar

• Ett Fabric Apps-projekt med definierade datamodeller. Se Definiera datamodeller.
• Serverdelstjänsterna som körs lokalt eller distribueras till Fabric.

Initiera klienten

Instansiera RayfinClient med din serverdels-URL, publiceringsbar nyckel och schematyp:

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

Argumentet generisk typ gör att TypeScript kan tillhandahålla automatisk komplettering och typkontroll för alla dataåtgärder.

Läsa data

Få åtkomst till entitetssamlingar via client.data.<EntityName>. Api:et fluent innehåller metoder för frågor, filtrering, sortering och sidnumrering.

Hämta alla poster

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

Hämta en enskild post efter primärnyckel

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

Detta returnerar den fullständiga entiteten eller null om det inte finns någon post med det ID:t.

Filtrera poster

where() Använd metoden för att filtrera resultat:

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

Filteroperatorer

Sortera resultat

Använd orderBy() för att sortera frågeresultat:

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

Sortera efter flera kolumner:

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

Navigera i relationer

När du definierar relationer med @one() och @many() dekoratörer kan du inkludera relaterade entitetsfält i samma fråga:

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

Varje anteckning innehåller tillhörande notebook-data utan att en separat fråga krävs.

Paginera stora resultatuppsättningar

Använd markörbaserad sidnumrering för stora listor:

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);

Hämta nästa sida med hjälp av markören:

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

Skapa poster

Använd metoden create() för att infoga nya poster:

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

Metoden returnerar den skapade entiteten med alla fält ifyllda, inklusive den automatiskt genererade id.

Skapa poster med relationer

När du skapar entiteter som har relationer skickar du antingen det fullständiga relaterade objektet eller ett objekt med bara primärnyckeln:

// 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(),
});

Båda formulären ger samma resultat. Använd det första formuläret när du redan känner till den relaterade entitetens ID och vill undvika extra hämtning.

Uppdateringsposter

Använd metoden update() för att ändra befintliga poster. Skicka ett filterobjekt och ett objekt som innehåller de fält som ska uppdateras:

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

Uppdatera relationer

Om du vill ändra en relation skickar du den nya relaterade entiteten eller bara dess ID:

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

Ta bort poster

delete() Använd metoden för att ta bort poster som matchar ett filter:

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

Metoden löses när serverdelen bekräftar borttagningen. Om inga poster matchar filtret lyckas metoden fortfarande.

Hantera autentisering

När autentisering är aktiverat loggar du in innan du utför dataåtgärder:

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

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

Klienten kopplar automatiskt autentiseringssessionen till alla data-API-anrop. Du behöver inte skicka token manuellt.

Metodtips

• Välj endast nödvändiga fält – Hämta endast de fält som du använder för att minska nyttolaststorleken och förbättra prestandan.
• Använd paginering för stora listor – Undvik att hämta tusentals poster på en gång genom att använda first() och executePaginated().
• Batch-relationsfrågor – Inkludera relaterade entitetsfält i samma fråga i stället för att göra separata begäranden.
• Cachelagrade data som används ofta – Lagra statiska referensdata i minnet för att minska API-anrop.

Aktuella begränsningar

• Metoden count() är inte tillgänglig på fluent-klienten. Välj minimala fält och använd results.length i stället.
• Många-till-många-relationer stöds inte. Använd en explicit kopplingsentitet med två @one() navigeringsdekoratörer.
• Egenskapen totalCount på PagedResult fylls inte i av serverdelen.

Relaterat innehåll

• Definiera datamodeller
• Konfigurera autentisering
• Distribuera till Fabric