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 { UniversalAppSchema } from '@rayfin-app/shared';

const client = new RayfinClient<UniversalAppSchema>({
  baseUrl: import.meta.env.VITE_RAYFIN_API_URL,
  publishableKey: import.meta.env.VITE_RAYFIN_PUBLISHABLE_KEY,
});

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

De här exemplen förutsätter att du har aktiverat Data och registrerat Note och Notebook i Universal App:s packages/data/src/index.ts och delade schema-kontrakt. I en flat template importerar du i stället din schematyp från rayfin/data/schema.ts. Se Definiera datamodeller.

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 en sida med poster

execute() returnerar endast en sida, med 100 poster som standard. Den returnerar inte markörmetadata eller hämtar efterföljande sidor. Använd framåtriktad paginering för listor som kan växa längre än en sida.

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.findById('00000000-0000-0000-0000-000000000000');

findById() returnerar null om ingen post finns. Den släppta implementationen väljer endast primärnyckeln, så anta inte att andra entitetsfält fylls i. Välj fält explicit när du behöver deras värden:

const notes = await client.data.Note.select(['id', 'title', 'content'])
  .where({ id: { eq: '00000000-0000-0000-0000-000000000000' } })
  .first(1)
  .execute();

const note = notes[0] ?? null;

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

Operator Description Example
eq Lika med { status: { eq: 'active' } }
neq Inte lika med { status: { neq: 'archived' } }
gt Större än { age: { gt: 18 } }
gte Större än eller lika med { age: { gte: 21 } }
lt Mindre än { price: { lt: 100 } }
lte Mindre än eller lika med { price: { lte: 50 } }
contains Innehåller delsträng { title: { contains: 'draft' } }

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

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',
])
  .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' })
  .orderBy({ id: 'asc' })
  .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) {
  if (!page.endCursor) {
    throw new Error('The next page is missing its cursor.');
  }
  const nextPage = await client.data.Note.select([
    'id',
    'title',
    'createdAt',
  ])
    .orderBy({ createdAt: 'desc' })
    .orderBy({ id: 'asc' })
    .first(25)
    .after(page.endCursor)
    .executePaginated();
}

Note

Backenden fyller inte i egenskapen totalCount på typen PagedResult. Värdet page.items.length avser endast den aktuella sidan, inte alla matchande poster.

För att bearbeta varje matchande post, fortsätt framåt tills hasNextPage är false. Behåll urval, filter och sorteringsordning oförändrade över olika förfrågningar.

let cursor: string | undefined;
let matchingRecords = 0;

while (true) {
  let query = client.data.Note.select(['id'])
    .where({ isArchived: { eq: false } })
    .orderBy({ id: 'asc' })
    .first(100);

  if (cursor !== undefined) {
    query = query.after(cursor);
  }

  const page = await query.executePaginated();
  matchingRecords += page.items.length;

  if (!page.hasNextPage) {
    break;
  }
  if (!page.endCursor) {
    throw new Error('The next page is missing its cursor.');
  }
  cursor = page.endCursor;
}

console.log('Records read across all pages:', matchingRecords);

Paging ger ingen snapshot över flera förfrågningar. Samtidiga ändringar kan påverka de poster du läser och räknar.

Aggregera och gruppera data

Använd aggregate() för server-side-totaler och groupBy() för sammanfattningar per grupp. Den fristående fluent-metoden count() finns inte tillgänglig, men count stöds i en aggregeringsspecifikation.

Alla fem aggregerade operationer (sum, avg, max, min, och count) kräver ett numeriskt fält. Räkna inte med ett UUID id eller ett textfält. Till exempel antar följande fråga en registrerad Product enhet med ett obligatoriskt numeriskt stockQuantity fält:

const totals = await client.data.Product.where({ isAvailable: { eq: true } })
  .aggregate({
    matchingProducts: { count: 'stockQuantity' },
    totalStock: { sum: 'stockQuantity' },
    averageStock: { avg: 'stockQuantity' },
    lowestStock: { min: 'stockQuantity' },
    highestStock: { max: 'stockQuantity' },
  })
  .execute();

console.log(totals[0].aggregations.matchingProducts);

count räknar icke-nullvärden av det angivna numeriska fältet. Använd ett obligatoriskt numeriskt fält för att räkna matchande rader. Om din enhet inte har något lämpligt fält, räkna identifierare över alla sidor såsom visats tidigare, inte bara på en sida.

För grupperade totaler:

const groups = await client.data.Product.groupBy(['status'])
  .aggregate({
    matchingProducts: { count: 'stockQuantity' },
    totalStock: { sum: 'stockQuantity' },
  })
  .execute();

for (const row of groups) {
  console.log(row.fields.status, row.aggregations.totalStock);
}

Aggregeringsresultat är arrayer med fields och aggregations objekt. En totalsumma har en rad med ett tomt fields objekt. count returnerar en number; de andra operationerna returnerar number | null för tomma eller indata som enbart består av null-värden.

Applicera where() innan aggregering. Kombinera inte aggregering med radval, sortering eller bläddring genom select(), orderBy(), first(), eller after().

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 posten, inklusive dess autogenererade id. Använd ett explicit selected read när du behöver ytterligare lagrade fält.

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: '22222222-3333-4444-5555-666666666666' },
  isPinned: false,
  isArchived: false,
  createdAt: new Date(),
  updatedAt: new Date(),
});

// Option 2: Select the related fields you need before creating the note.
const notebooks = await client.data.Notebook.select(['id', 'name'])
  .where({ id: { eq: '22222222-3333-4444-5555-666666666666' } })
  .first(1)
  .execute();
const notebook = notebooks[0];
if (!notebook) {
  throw new Error('Notebook not found.');
}

const noteWithNotebook = await client.data.Note.create({
  title: 'Weekly summary',
  content: 'Summary of this week',
  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.

Klienten använder det relaterade objektets primära nyckel för att sätta relationen. Att skicka med ett objekt skapar eller uppdaterar inte den relaterade anteckningsbok.

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.

Skapa eller uppdatera en post

Använd upsert(where, create, update) för att skapa en post som saknas eller uppdatera en befintlig. Ange samma ID i uppslaget och indata för skapandet:

const id = '11111111-2222-3333-4444-555555555555';
const now = new Date();

await client.data.Note.upsert(
  { id },
  {
    id,
    title: 'Daily summary',
    content: 'Summary of today',
    isPinned: false,
    isArchived: false,
    createdAt: now,
    updatedAt: now,
    user_id: 'user-123',
  },
  { title: 'Daily summary', updatedAt: now },
);

Denna hjälpmetod utför en läsning följd av en separat skapande- eller uppdateringsåtgärd. Det är inte atomärt, och samtidiga anrop kan orsaka en kapplöpningssituation. Använd det inte som en transaktion eller garanti för samtidighet.

Hantera autentisering

Logga in innan du utför skyddade dataoperationer. För en distribuerad backend, använd appens konfigurerade Microsoft Entra-inloggningsflöde. Följande exempel på e-postadress och lösenord gäller endast för en lokal backend:

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

  • En fristående count() metod finns inte tillgänglig. Använd en numerisk fältaggregering, eller räkna poster över alla sidor. En arrays längd räknar endast de poster som återges på den sidan.
  • 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.