Consultar datos de entidades para informes

Objetivo

Leer los datos de una tabla de un entorno a través del origen de datos de informes de solo lectura, para que una integración externa de informes o análisis pueda listar las tablas que puede leer, descubrir las columnas de una tabla, obtener páginas de filas y ejecutar una consulta guardada, sin ningún acceso de escritura.

Requisitos previos

• Un registro de aplicación externa con el ámbito reporting.read (o modelapps.read, que también concede lecturas de informes) y un rol que pueda leer las tablas que necesita. Consulte Registrar una aplicación externa.
• Un token de acceso obtenido para ese registro, pidiendo el ámbito por su nombre.
• El identificador del entorno cuyos datos quiere leer.

La superficie de informes

Todas las operaciones se limitan a un entorno y son de solo lectura. Dos cosas deciden lo que obtiene: el ámbito abre la superficie, y el rol de la aplicación decide qué tablas y qué filas, exactamente como para una persona que usa una aplicación. Un token con el ámbito y sin rol no alcanza ninguna fila.

Operación	Solicitud	Devuelve
Listar tablas	GET /environments/{environmentId}/reporting/entities	Las tablas que su rol puede leer (nombre lógico, nombre para mostrar, nombre en plural).
Describir las columnas de una tabla	GET /environments/{environmentId}/reporting/entities/{entity}/schema	Cada columna: nombre lógico, nombre para mostrar, tipo de dato, si es el campo principal y la tabla de destino de una búsqueda.
Leer un conjunto de datos	POST /environments/{environmentId}/reporting/entities/{entity}/dataset	columns y rows, además de totalCount, pageNumber y pageSize.
Ejecutar una consulta guardada	POST /environments/{environmentId}/saved-queries/{logicalName}/run	Los registros o grupos de la consulta guardada.

Una solicitud de conjunto de datos

El cuerpo es una consulta: select (las columnas que quiere), filter (un conector y condiciones, cada una con campo, operador y valor), order (campos, ascendentes o descendentes) y page (number y size):

{
  "select": ["nw_name", "nw_company"],
  "filter": { "connector": "And",
              "conditions": [{ "field": "nw_company", "operator": "Equals", "value": "Analytical Engines" }] },
  "order": [{ "field": "nw_name", "descending": false }],
  "page": { "number": 1, "size": 50 }
}

Con select, columns describe exactamente esas columnas en ese orden. Una columna de opciones vuelve como su número y, a su lado, su etiqueta en <columna>__text. Con totalCount sabe cuántas páginas hay.

Una consulta guardada

Una consulta que un creador diseñó y guardó se ejecuta por su nombre lógico. El cuerpo es opcional y solo puede acotarla: un filter adicional se suma al guardado, nunca lo sustituye, y page elige una página. Una consulta agrupada responde con sus grupos y sus medidas, de modo que una integración puede pedir totales en lugar de sumar filas por su cuenta.

Qué ocurre entre bastidores

El origen de datos de informes no crea, actualiza ni elimina. Cada solicitud comprueba primero el ámbito del token y luego lee por el mismo camino que usan las pantallas de la plataforma, así que los permisos del rol y sus directivas deciden las filas. Solo se lee el entorno indicado en la ruta.

Solución de problemas

• 403 con modelapps.reporting.forbidden. El token no lleva reporting.read ni modelapps.read. Pida el ámbito por su nombre al solicitar el token: un token pedido sin scope no lleva ninguno.
• 403 con modelapps.record.forbidden. El ámbito está, pero el rol de la aplicación no puede leer esa tabla. Conceda al rol Lectura sobre ella en este entorno.
• Falta una tabla en la lista. El rol no puede leerla o no existe en este entorno.
• 400 por un campo desconocido. Un campo de select, filter u order no pertenece a la tabla. Use un campo del esquema de la tabla.

Escenarios relacionados

• Registrar una aplicación externa.
• Vincular un informe a una tabla (creador).