Gegevens lezen en schrijven met GraphQL in Fabric Apps

Fabric Apps biedt een typeveilige GraphQL-client waarmee u bewerkingen voor maken, lezen, bijwerken en verwijderen kunt uitvoeren zonder onbewerkte query's te schrijven. De client genereert GraphQL automatisch vanuit uw methode-aanroepen en retourneert getypte entiteiten op basis van uw gegevensmodeldefinities.

Prerequisites

• Een Fabric Apps-project met gegevensmodellen gedefinieerd. Zie Gegevensmodellen definiëren.
• De back-endservices die lokaal worden uitgevoerd of geïmplementeerd in Fabric.

De client initialiseren

Instantieer RayfinClient met uw back-end-URL, publiceerbare sleutel en schematype:

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

Met het generieke typeargument kan TypeScript automatische aanvulling en typecontrole bieden voor alle gegevensbewerkingen.

Gegevens lezen

Toegang tot entiteitsverzamelingen via client.data.<EntityName>. De fluent-API biedt methoden voor het uitvoeren van query's, filteren, sorteren en paginering.

Alle records ophalen

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

Eén record ophalen op basis van primaire sleutel

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

Hiermee wordt de volledige entiteit geretourneerd of null als er geen record met die id bestaat.

Records filteren

Gebruik de where() methode om resultaten te filteren:

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

Filter-operators

Resultaten sorteren

Gebruik orderBy() dit om queryresultaten te sorteren:

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

Sorteren op meerdere kolommen:

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

Navigeren in relaties

Wanneer u relaties met @one() en @many() decorators definieert, kunt u gerelateerde entiteitsvelden opnemen in dezelfde query:

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

Elke notitie bevat de bijbehorende notebookgegevens zonder dat er een afzonderlijke query nodig is.

Grote resultatensets pagineren

Op cursor gebaseerde paginering gebruiken voor grote lijsten:

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

Haal de volgende pagina op met behulp van de cursor:

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

Records maken

Gebruik de create() methode om nieuwe records in te voegen:

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

De methode retourneert de gemaakte entiteit met alle velden ingevuld, inclusief de automatisch gegenereerde identiteit.

Records aanmaken met relaties

Wanneer u entiteiten met relaties maakt, geeft u het volledige gerelateerde object of een object door met alleen de primaire sleutel:

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

Beide vormen produceren hetzelfde resultaat. Gebruik het eerste formulier wanneer u de id van de gerelateerde entiteit al kent en een extra ophaaloptie wilt voorkomen.

Records bijwerken

Gebruik de update() methode om bestaande records te wijzigen. Geef een filterobject en een object met de velden door die moeten worden bijgewerkt:

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

Relaties bijwerken

Als u een relatie wilt wijzigen, geeft u de nieuwe gerelateerde entiteit of alleen de bijbehorende id door:

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

Gegevens verwijderen

Gebruik de delete() methode om records te verwijderen die overeenkomen met een filter:

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

De methode wordt voltooid wanneer de backend de verwijdering bevestigt. Als er geen records overeenkomen met het filter, slaagt de methode nog steeds.

Authenticatie afhandelen

Wanneer verificatie is ingeschakeld, meldt u zich aan voordat u gegevensbewerkingen uitvoert:

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

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

De client koppelt de verificatiesessie automatisch aan alle gegevens-API-aanroepen. U hoeft tokens niet handmatig door te geven.

Beste praktijken

• Selecteer alleen benodigde velden : haal alleen de velden op die u gebruikt om de nettolading te verkleinen en de prestaties te verbeteren.
• Paginering gebruiken voor grote lijsten : vermijd het ophalen van duizenden records tegelijk met behulp van first() en executePaginated().
• Batchrelatiequery's: gerelateerde entiteitsvelden opnemen in dezelfde query in plaats van afzonderlijke aanvragen te maken.
• Veelgebruikte gegevens in de cache opslaan: sla statische referentiegegevens op in het geheugen om API-aanroepen te verminderen.

Huidige beperkingen

• De count() methode is niet beschikbaar op de fluent-client. Selecteer minimale velden en gebruik in plaats daarvan results.length .
• Veel-op-veel-relaties worden niet ondersteund. Gebruik een expliciete koppelentiteit met twee @one() navigatiedecorators.
• De eigenschap totalCount op PagedResult wordt niet gevuld door de backend.

Verwante inhoud

• Gegevensmodellen definiëren
• Verificatie configureren
• Implementeren naar Fabric