Leggere e scrivere dati con GraphQL nelle app Fabric

Fabric Apps offre un client GraphQL tipizzato in modo sicuro che consente di eseguire operazioni di creazione, lettura, aggiornamento ed eliminazione senza scrivere query grezze. Il client genera automaticamente GraphQL dalle chiamate al metodo e restituisce entità tipate in base alle definizioni del modello di dati.

Prerequisiti

  • Progetto app di Fabric con modelli di dati definiti. Vedere Definire i modelli di dati.
  • Servizi back-end in esecuzione in locale o distribuiti in Fabric.

Inizializzare il client

Crea un'istanza di RayfinClient con l'URL del backend, la chiave pubblicabile e il tipo di schema:

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

L'argomento di tipo generico consente a TypeScript di fornire il completamento automatico e il controllo del tipo per tutte le operazioni sui dati.

Questi esempi presuppongono che tu abbia abilitato i dati e abbia registrato Note e Notebook nel contratto dello schema condiviso packages/data/src/index.ts dell'Universal App. In un template flat, importa invece il tipo di schema da rayfin/data/schema.ts. Vedere Definire i modelli di dati.

Leggi i dati

Accedere alle raccolte di entità tramite client.data.<EntityName>. L'API Fluent fornisce metodi per eseguire query, filtrare, ordinare e impaginazione.

Recupera una pagina di record

execute() restituisce una sola pagina, con 100 record di default. Non restituisce i metadati del cursore né recupera le pagine successive. Usa la paginazione progressiva per liste che possono crescere oltre una pagina.

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

Recupera un singolo record per chiave primaria

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

findById() restituisce null se non esiste alcun record. L'implementazione rilasciata seleziona solo la chiave primaria, quindi non presumere che siano popolati altri campi di entità. Seleziona esplicitamente i campi quando hai bisogno dei loro valori:

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;

Filtrare i record

Utilizza il metodo where() per filtrare i risultati:

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

Operatori di filtro

Operatore Description Example
eq Uguale a { status: { eq: 'active' } }
neq Non uguale a { status: { neq: 'archived' } }
gt Maggiore di { age: { gt: 18 } }
gte Maggiore di o uguale a { age: { gte: 21 } }
lt Minore di { price: { lt: 100 } }
lte Minore o uguale a { price: { lte: 50 } }
contains Contiene la sottostringa { title: { contains: 'draft' } }

Ordinare i risultati

Usare orderBy() per ordinare i risultati delle query:

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

Ordinare in base a più colonne:

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

Quando si definiscono le relazioni con @one() e @many() decorator, è possibile includere i campi di entità correlati nella stessa query:

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

Ogni nota include i dati del relativo notebook senza la necessità di eseguire una query separata.

Impaginare set di risultati di grandi dimensioni

Usare la paginazione basata su cursore per elenchi di grandi dimensioni:

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

Recuperare la pagina successiva usando il cursore:

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

Il backend non popola la totalCount proprietà sul PagedResult tipo. Il conteggio page.items.length include solo la pagina corrente, non tutti i record corrispondenti.

Per elaborare ogni record corrispondente, prosegui fino a quando hasNextPage non è false. Mantieni invariate le selezioni, i filtri e l’ordinamento tra una richiesta e l’altra.

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

Il paging non fornisce un'istantanea coerente tra le richieste. Cambiamenti simultanei possono influenzare i record che leggi e conti.

Aggrega e raggruppa i dati

Da usare aggregate() per i totali lato server e groupBy() per i riassunti per gruppo. Il metodo fluido count() standalone non è disponibile, ma count è supportato all'interno di una specifica di aggregazione.

Tutte e cinque le operazioni aggregate (sum, avg, min, max, e count) richiedono un campo numerico. Non contare un UUID id o un campo di testo. Ad esempio, la seguente query presuppone un'entità registrata Product con un campo numerico stockQuantity obbligatorio:

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 conta i valori non nulli del campo numerico specificato. Usa un campo numerico richiesto per contare le righe corrispondenti. Se la tua entità non ha un campo adatto, conta gli identificatori su tutte le pagine come mostrato prima, non solo su una pagina.

Per i totali raggruppati:

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

I risultati dell'aggregazione sono array di oggetti fields e aggregations. Un totale generale ha una riga con un oggetto vuoto fields . count restituisce un number; le altre operazioni restituiscono number | null per input vuoti o completamente nulli.

Applica where() prima dell'aggregazione. Non combinare l'aggregazione con la selezione delle righe, l'ordinamento o la paginazione attraverso select(), orderBy(), first() o after().

Creazione di record

Usare il create() metodo per inserire nuovi record:

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

Il metodo restituisce il record creato, incluso il suo ID autogenerato id. Usa una selected read esplicita quando hai bisogno di ulteriori campi memorizzati.

Creare record con relazioni

Quando si creano entità con relazioni, passare l'oggetto correlato completo o un oggetto con solo la chiave primaria:

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

Entrambe le forme producono lo stesso risultato. Usare il primo modulo quando si conosce già l'ID dell'entità correlata e si vuole evitare un recupero aggiuntivo.

Il client utilizza la chiave primaria dell'oggetto correlato per impostare la relazione. Passare un oggetto non crea né aggiorna il notebook correlato.

Aggiorna record

Utilizzare il update() metodo per modificare i record esistenti. Passare un oggetto filtro e un oggetto contenente i campi da aggiornare:

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

Aggiornare le relazioni

Per modificare una relazione, passare la nuova entità correlata o semplicemente il relativo ID:

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

Eliminazione di record

Usare il delete() metodo per rimuovere i record corrispondenti a un filtro:

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

Il metodo viene risolto quando il back-end conferma l'eliminazione. Se nessun record corrisponde al filtro, il metodo ha comunque esito positivo.

Crea o aggiorna un record

Usa upsert(where, create, update) per creare un record mancante o aggiornarne uno esistente. Fornisci lo stesso ID nel lookup e nell'input di creazione:

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

Questa funzione di supporto esegue una lettura seguita da una creazione o aggiornamento separato. Non è atomica e le chiamate contemporanee possono entrare in conflitto. Non usarlo come garanzia di transazione o di accesso concorrente.

Gestire l'autenticazione

Accedi prima di eseguire operazioni sui dati protetti. Per un backend distribuito in produzione, utilizza il flusso di accesso Microsoft Entra configurato dall'app. Il seguente esempio di email e password è solo per un backend locale:

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

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

Il client collega automaticamente la sessione di autenticazione a tutte le chiamate API dati. Non è necessario passare manualmente i token.

Procedure consigliate

  • Selezionare solo i campi necessari : recuperare solo i campi usati per ridurre le dimensioni del payload e migliorare le prestazioni.
  • Usare la paginazione per elenchi di grandi dimensioni : evitare di recuperare migliaia di record contemporaneamente usando first() e executePaginated().
  • Query di relazione batch : includere campi di entità correlati nella stessa query anziché effettuare richieste separate.
  • Memorizzare nella cache i dati a cui si accede di frequente : archiviare i dati di riferimento statici in memoria per ridurre le chiamate API.

Limitazioni correnti

  • Non è disponibile un metodo indipendente count(). Usa un'aggregazione di campi numerici, oppure conta i record su tutte le pagine. La lunghezza di un array conta solo i record restituiti in quella pagina.
  • Le relazioni molti-a-molti non sono supportate. Usare un'entità di join esplicita con due @one() decoratori di navigazione.
  • La totalCount proprietà in PagedResult non viene popolata dal back-end.