Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
Fabric Apps proporciona un cliente GraphQL con seguridad de tipos que permite realizar operaciones de creación, lectura, actualización y eliminación sin tener que escribir consultas directamente. El cliente genera GraphQL automáticamente a partir de las llamadas a tus métodos y devuelve entidades tipadas según las definiciones de tu modelo de datos.
Prerequisites
- Un proyecto de Fabric Apps con modelos de datos definidos. Consulte Definición de modelos de datos.
- Los servicios back-end que se ejecutan localmente o se implementan en Fabric.
Inicialización del cliente
Cree RayfinClient una instancia con la dirección URL de back-end, la clave que se puede publicar y el tipo de esquema:
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,
});
El argumento de tipo genérico permite a TypeScript ofrecer autocompletado y verificación de tipos en todas las operaciones de datos.
Estos ejemplos suponen que activaste los datos y registraste Note y Notebook en el contrato de esquema compartido y packages/data/src/index.ts de la aplicación universal. En una plantilla plana, importa tu tipo de esquema desde rayfin/data/schema.ts en su lugar. Consulte Definición de modelos de datos.
Lectura de datos
Acceda a colecciones de entidades a través de client.data.<EntityName>. La API fluida proporciona métodos para consultar, filtrar, ordenar y paginar.
Consigue una página de registros
execute() solo devuelve una página, con 100 registros por defecto. No devuelve los metadatos del cursor ni recupera páginas posteriores. Utiliza la paginación hacia delante para listas que puedan crecer más allá de una página.
const notes = await client.data.Note.select([
'id',
'title',
'content',
'createdAt',
'isPinned',
]).execute();
Captura de un único registro por clave principal
const note = await client.data.Note.findById('00000000-0000-0000-0000-000000000000');
findById() devuelve null si no existe ningún registro. La implementación publicada selecciona solo la clave primaria, así que no asumas que los demás campos de la entidad estén poblados. Selecciona campos explícitamente cuando necesites sus valores:
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;
Filtrar registros
Use el where() método para filtrar los resultados:
const pinnedNotes = await client.data.Note.select([
'id',
'title',
'isPinned',
])
.where({ isPinned: { eq: true } })
.execute();
Operadores de filtro
| Operador | Descripción | Ejemplo |
|---|---|---|
eq |
Es igual | { status: { eq: 'active' } } |
neq |
No es igual | { status: { neq: 'archived' } } |
gt |
Mayor que | { age: { gt: 18 } } |
gte |
Mayor o igual que | { age: { gte: 21 } } |
lt |
Menor que | { price: { lt: 100 } } |
lte |
Menor o igual que | { price: { lte: 50 } } |
contains |
Contiene subcadena | { title: { contains: 'draft' } } |
Ordenar resultados
Use orderBy() para ordenar los resultados de la consulta:
const notes = await client.data.Note.select([
'id',
'title',
'createdAt',
])
.orderBy({ createdAt: 'desc' })
.execute();
Ordenar por varias columnas:
const notes = await client.data.Note.select([
'id',
'title',
'isPinned',
'createdAt',
])
.orderBy({ isPinned: 'desc' })
.orderBy({ createdAt: 'desc' })
.execute();
Explorar relaciones
Al definir relaciones con @one() y @many() decoradores, puede incluir campos de entidad relacionados en la misma consulta:
const notes = await client.data.Note.select([
'id',
'title',
'content',
'notebook.id',
'notebook.name',
])
.execute();
Cada nota incluye sus datos de cuaderno asociados sin necesidad de una consulta independiente.
Paginar grandes conjuntos de resultados
Use la paginación basada en cursores para listas grandes:
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);
Capture la página siguiente con el cursor:
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
El backend no rellena la propiedad totalCount del tipo PagedResult. El page.items.length valor solo cuenta la página actual, no todos los registros coincidentes.
Para procesar cada registro coincidente, continúa adelante hasta que hasNextPage sea false. Mantén las selecciones, filtros y orden de clasificación sin cambios entre solicitudes.
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);
La paginación no proporciona una instantánea entre solicitudes. Los cambios simultáneos pueden afectar los registros que lees y cuentas.
Agregar y agrupar datos
Use aggregate() para totales del lado del servidor y groupBy() para resúmenes por grupo. El método fluido count() independiente no está disponible, pero count está soportado dentro de una especificación de agregación.
Las cinco operaciones agregadas (sum, avg, min, max, y count) requieren un campo numérico. No cuentes un UUID id ni un campo de texto. Por ejemplo, la siguiente consulta supone una entidad registrada Product con un campo numérico stockQuantity requerido:
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 cuenta los valores no nulos del campo numérico especificado. Utiliza un campo numérico requerido para contar las filas que coinciden. Si tu entidad no tiene un campo adecuado, cuenta los identificadores en todas las páginas como se mostró antes, no solo en una página.
Para totales agrupados:
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);
}
Los resultados de agregación son arrays con fields y aggregations objetos. Un total general tiene una fila con un objeto vacío fields .
count devuelve un number; las demás operaciones devuelven number | null para entradas vacías o totalmente nulas.
Aplica where() antes de la agregación. No combines la agregación con selección de filas, ordenación ni paginación a través de select(), orderBy(), first(), o after().
Crear registros
Use el create() método para insertar nuevos registros:
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',
});
El método devuelve el registro creado, incluyendo su registro autogenerado id Usa una explicit selected read cuando necesites campos almacenados adicionales.
Creación de registros con relaciones
Al crear entidades que tienen relaciones, pase el objeto relacionado completo o un objeto con solo la clave principal:
// 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(),
});
Ambas formas generan el mismo resultado. Use el primer formulario cuando ya conozca el identificador de la entidad relacionada y quiera evitar una captura adicional.
El cliente utiliza la clave primaria del objeto relacionado para establecer la relación. Pasar un objeto no crea ni actualiza el bloc de notas relacionado.
Actualizar registros
Use el update() método para modificar los registros existentes. Pase un objeto de filtro y un objeto que contenga los campos que se van a actualizar:
await client.data.Note.update(
{ id: 'note-123' },
{
title: 'Updated title',
updatedAt: new Date(),
}
);
Actualización de relaciones
Para cambiar una relación, pase la nueva entidad relacionada o simplemente su identificador:
// Move a note to a different notebook
await client.data.Note.update(
{ id: 'note-123' },
{ notebook: { id: 'new-notebook-789' } }
);
Eliminar registros
Use el delete() método para quitar registros que coincidan con un filtro:
await client.data.Note.delete({ id: 'note-123' });
El método se resuelve cuando el back-end confirma la eliminación. Si no hay registros que coincidan con el filtro, el método sigue funcionando correctamente.
Crea o actualiza un registro
Usa upsert(where, create, update) para crear un registro que falta o actualizar uno existente. Proporciona el mismo ID en la búsqueda y la entrada de creación:
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 },
);
Este helper realiza una lectura seguida de una creación o actualización separada. No es atómico, y las llamadas simultáneas pueden producir una condición de carrera. No lo utilices como garantía de transacción o concurrencia.
Gestionar la autenticación
Inicia sesión antes de realizar operaciones con datos protegidos. Para un backend desplegado, utiliza el flujo de inicio de sesión de Microsoft Entra configurado de la app. El siguiente ejemplo de correo electrónico y contraseña es solo para un backend local:
await client.auth.signIn({ email, password });
// All subsequent data calls include authentication context
const notes = await client.data.Note.select(['id', 'title']).execute();
El cliente adjunta automáticamente la sesión de autenticación a todas las llamadas api de datos. No es necesario pasar tokens manualmente.
procedimientos recomendados
- Seleccionar solo los campos necesarios : capture solo los campos que use para reducir el tamaño de la carga y mejorar el rendimiento.
-
Usar paginación para listas grandes : evite capturar miles de registros a la vez mediante
first()yexecutePaginated(). - Consultas de relaciones por lotes – Incluya los campos de entidades relacionadas en la misma consulta en lugar de realizar solicitudes separadas.
- Almacenar datos a los que se accede con frecuencia : almacene datos de referencia estáticos en memoria para reducir las llamadas API.
Limitaciones actuales
- No existe un método independiente
count(). Utiliza una agregación de campo numérico, o cuenta registros en todas las páginas. La longitud de un array solo cuenta los registros devueltos en esa página. - No se admiten relaciones de varios a varios. Use una entidad de combinación explícita con dos
@one()decoradores de navegación. - La propiedad
totalCountdePagedResultno la completa el backend.