#ctx.request()

Inicie una solicitud HTTP con autenticación en RunJS. La solicitud incluirá automáticamente el baseURL, Token, locale, role, etc., de la aplicación actual, y seguirá la lógica de interceptación de solicitudes y manejo de errores de la aplicación.

#Escenarios de uso

Aplicable a cualquier escenario en RunJS donde sea necesario iniciar una solicitud HTTP remota, como JSBlock, JSField, JSItem, JSColumn, flujo de trabajo, vinculación (linkage), JSAction, etc.

#Definición de tipos

request(options: RequestOptions): Promise<AxiosResponse<any>>;

RequestOptions extiende AxiosRequestConfig de Axios:

type RequestOptions = AxiosRequestConfig & {
  skipNotify?: boolean | ((error: any) => boolean);  // Indica si se deben omitir los avisos de error globales cuando la solicitud falla
  skipAuth?: boolean;                                 // Indica si se debe omitir la redirección de autenticación (por ejemplo, no redirigir a la página de inicio de sesión en un error 401)
};

#Parámetros comunes

#URL de estilo de recurso

La API de recursos de NocoBase admite un formato abreviado recurso:acción:

Las rutas relativas se concatenarán con el baseURL de la aplicación (normalmente /api); las solicitudes de origen cruzado (cross-origin) deben usar una URL completa, y el servicio de destino debe estar configurado con CORS.

#Estructura de la respuesta

El valor de retorno es un objeto de respuesta de Axios. Los campos comunes incluyen:

• response.data: Cuerpo de la respuesta
• Las interfaces de lista suelen devolver data.data (matriz de registros) + data.meta (paginación, etc.)
• Las interfaces de registro único/creación/actualización suelen devolver el registro en data.data

#Ejemplos

#Consulta de lista

const { data } = await ctx.request({
  url: 'users:list',
  method: 'get',
  params: { pageSize: 10, page: 1 },
});

const rows = Array.isArray(data?.data) ? data.data : [];
const meta = data?.meta; // Información de paginación y otros datos

#Enviar datos

const res = await ctx.request({
  url: 'users:create',
  method: 'post',
  data: { nickname: 'Juan Pérez', email: 'juanperez@example.com' },
});

const newRecord = res?.data?.data;

#Con filtrado y ordenamiento

const res = await ctx.request({
  url: 'users:list',
  method: 'get',
  params: {
    pageSize: 20,
    sort: ['-createdAt'],
    filter: { status: 'active' },
  },
});

#Omitir notificación de error

const res = await ctx.request({
  url: 'some:action',
  method: 'get',
  skipNotify: true,  // No mostrar el mensaje global al fallar
});

// O decidir si omitir según el tipo de error
const res2 = await ctx.request({
  url: 'some:action',
  method: 'get',
  skipNotify: (err) => err?.name === 'CanceledError',
});

#Solicitud de origen cruzado (Cross-Origin)

Al usar una URL completa para solicitar otros dominios, el servicio de destino debe estar configurado con CORS para permitir el origen de la aplicación actual. Si la interfaz de destino requiere su propio token, este puede pasarse a través de los encabezados:

const res = await ctx.request({
  url: 'https://api.example.com/v1/data',
  method: 'get',
});

const res2 = await ctx.request({
  url: 'https://api.other.com/items',
  method: 'get',
  headers: {
    Authorization: 'Bearer <token_del_servicio_destino>',
  },
});

#Visualización con ctx.render

const { data } = await ctx.request({
  url: 'users:list',
  method: 'get',
  params: { pageSize: 5 },
});
const rows = Array.isArray(data?.data) ? data.data : [];

ctx.render([
  '<div style="padding:12px">',
  '<h4>' + ctx.t('Lista de usuarios') + '</h4>',
  '<ul>',
  ...rows.map((r) => '<li>' + (r.nickname ?? r.username ?? '') + '</li>'),
  '</ul>',
  '</div>',
].join(''));

#Notas

• Manejo de errores: El fallo de la solicitud lanzará una excepción y, por defecto, aparecerá un aviso de error global. Utilice skipNotify: true para capturarlo y manejarlo usted mismo.
• Autenticación: Las solicitudes al mismo origen llevarán automáticamente el Token, el idioma (locale) y el rol del usuario actual; las solicitudes de origen cruzado requieren que el destino admita CORS y que se pase el token en los encabezados según sea necesario.
• Permisos de recursos: Las solicitudes están sujetas a las restricciones de ACL y solo pueden acceder a los recursos para los que el usuario actual tiene permiso.

#Relacionado

• ctx.message - Mostrar avisos ligeros después de completar la solicitud
• ctx.notification - Mostrar notificaciones después de completar la solicitud
• ctx.render - Renderizar los resultados de la solicitud en la interfaz
• ctx.makeResource - Construir un objeto de recurso para la carga de datos encadenada (alternativa a ctx.request)