> For the complete documentation index, see [llms.txt](https://docs.powermonitor.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.powermonitor.com.br/es/power-monitor/auditoria/seguranca-em-nivel-de-linha.md).
# Seguridad de Nivel de Fila
Roles de seguridad de nivel de fila (RLS) de cada modelo semántico, con miembros y filtros DAX, y los hallazgos de riesgo, modelo con etiqueta de confidencialidad y sin RLS, roles sin miembros y roles
La pantalla **Seguridad de Nivel de Fila** muestra, para cada modelo semántico de su entorno, si tiene **seguridad de nivel de fila (RLS, *****Row-Level Security*****)**, qué roles están definidos, quién es miembro de cada rol y qué filtro DAX aplica cada rol en cada tabla. También destaca los **hallazgos** que suelen indicar una falla de protección: modelos con etiqueta de confidencialidad y sin RLS, roles sin ningún miembro y roles que no filtran ninguna tabla.
**Cómo acceder:** *Auditoría › Seguridad de Nivel de Fila* (título de la página: **Seguridad de nivel de fila (RLS)**). Disponible para todos los perfiles. La pantalla es de solo lectura: no hay acciones de escritura.
Cobertura de RLS, roles y hallazgos por modelo semántico
## Para qué sirve
* **Validar la protección de los datos clasificados.** Un modelo con etiqueta de confidencialidad (por ejemplo, *Confidencial*) y sin RLS entrega **todas las filas** a cualquier persona con permiso de lectura en el modelo. Es el hallazgo más grave de la pantalla.
* **Revisar los roles de RLS** (recertificación): exportar quién está en cada rol y qué filtro aplica para que los responsables de los datos lo validen.
* **Encontrar configuraciones incompletas:** roles creados pero sin ningún miembro (nadie recibe ese recorte de datos) y roles sin filtro (quien está en ellos ve todas las filas, como si no hubiera RLS).
* **Medir la cobertura de RLS** del entorno: cuántos modelos recopilados tienen RLS y cuántos no.
{% hint style="info" %}
Esta pantalla muestra **lo que está configurado en el modelo**. No evalúa si el filtro DAX es correcto para su regla de negocio ni quién tiene permiso de lectura en el modelo. Para saber quién puede leer el modelo, use la [Auditoría de Permisos](/es/power-monitor/auditoria/auditoria-de-permissoes.md).
{% endhint %}
## Funcionalidades
### Tarjetas de indicadores
**Qué es:** tres tarjetas en la parte superior: **Cobertura de RLS**, **Roles** y **Etiqueta sin RLS**.
**Para qué sirve:** medir la cobertura de RLS del entorno y dimensionar los riesgos antes de abrir la lista.
Indicadores de cobertura, roles y hallazgos
| Tarjeta | Valor principal | Detalles |
| -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Cobertura de RLS**: *Modelos recopilados que tienen RLS* | **Cobertura**: porcentaje de modelos con RLS entre los modelos cuyos roles ya se recopilaron (redondeado). Muestra "—" cuando no se recopiló ningún modelo. | **Con RLS**, **Sin RLS** y **Aún no recopilados** (*Llegan con el próximo escaneo completo.*). Los modelos aún no recopilados no se incluyen en el cálculo del porcentaje. |
| **Roles**: *Roles de RLS en los modelos recopilados* | **Total de roles** sumando todos los modelos recopilados | **Miembros asignados** (total de miembros en todos los roles), **Roles sin miembros** y **Roles sin filtro** (resaltados como alerta cuando son mayores que cero) |
| **Etiqueta sin RLS**: *Modelos con etiqueta de confidencialidad y sin RLS* | **Con etiqueta y sin RLS**: cantidad de modelos recopilados que tienen etiqueta de confidencialidad y ningún rol | Pie: *Datos clasificados visibles por completo para quien tiene lectura en el modelo.* La tarjeta se vuelve roja cuando hay al menos un modelo en esa situación y verde cuando no hay ninguno. |
**Cómo usar:**
1. Lea **Cobertura de RLS**: el porcentaje considera solo los modelos ya recopilados; vea en **Aún no recopilados** cuántos quedaron fuera del cálculo.
2. En **Roles**, verifique si **Roles sin miembros** o **Roles sin filtro** están por encima de cero.
3. En **Etiqueta sin RLS**, una tarjeta roja indica el hallazgo más grave: filtre la lista por ese hallazgo (consulte *Filtros RLS y Hallazgos*).
**Cómo funciona:** las tarjetas consideran **todos los modelos** de su alcance, independientemente de los filtros aplicados en la lista, y no son seleccionables.
### Búsqueda y filtro de Área de trabajo
**Qué es:** el cuadro *Buscar modelo...* en el encabezado **Modelo semántico** y la selección múltiple **Área de trabajo** en el encabezado de la columna del mismo nombre.
**Para qué sirve:** localizar un modelo específico o revisar los modelos de un workspace con el responsable.
Búsqueda y filtros en el encabezado de la lista
**Cómo usar:**
1. Escriba parte del nombre en **Buscar modelo...**.
2. En **Área de trabajo**, abra el panel, use la búsqueda propia del campo y marque uno o más workspaces.
3. Para eliminarlos, borre el texto de la búsqueda o desmarque los workspaces.
**Cómo funciona:** los filtros se combinan y cada cambio devuelve la lista a la primera página. Las opciones de **Área de trabajo** son los workspaces presentes en la lista.
### Filtros RLS y Hallazgos
**Qué es:** las listas de selección de los encabezados **RLS** (*Cualquier situación*, **Con RLS**, **Sin RLS**, **Aún no recopilado**) y **Hallazgos** (*Cualquier hallazgo*, **Roles sin miembros**, **Roles sin filtro**, **Con etiqueta y sin RLS**).
**Para qué sirve:** ir directamente a los modelos de riesgo: por ejemplo, los que tienen datos clasificados y ningún rol.
**Cómo usar:**
1. En el encabezado **Hallazgos**, elija el hallazgo (por ejemplo, **Con etiqueta y sin RLS**).
2. Si lo desea, combínelo con **RLS** (por ejemplo, **Sin RLS**).
3. Para eliminarlos, vuelva la selección a *Cualquier situación* / *Cualquier hallazgo*.
**Situación de RLS (columna RLS):**
| Situación | Significado |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Con RLS** | El modelo tiene al menos un rol de RLS definido |
| **Sin RLS** | Los roles del modelo se recopilaron y no tiene ningún rol: quien tiene lectura en el modelo ve todas las filas |
| **Aún no recopilado** | El Power Monitor aún no recibió los roles de este modelo. Esto **no** significa que el modelo no tenga RLS: los roles llegan con el próximo escaneo completo |
**Hallazgos (columna Hallazgos):**
| Hallazgo | Cuándo aparece | Por qué importa |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| **Con etiqueta y sin RLS** (indicador rojo) | El modelo tiene etiqueta de confidencialidad, sus roles se recopilaron y no tiene ningún rol. Los modelos **Aún no recopilados** nunca reciben este hallazgo, porque no es posible afirmar la ausencia de RLS | Los datos clasificados como sensibles quedan visibles por completo para quien tiene lectura en el modelo |
| **Sin miembros: {N}** / **Roles sin miembros** | {N} roles del modelo no tienen ningún miembro asignado | El rol existe pero no protege a nadie; en general, indica una configuración olvidada tras la publicación del modelo |
| **Sin filtro: {N}** / **Roles sin filtro** | {N} roles del modelo no tienen filtro DAX en ninguna tabla (ninguna tabla filtrada o todas con expresión vacía) | Quien está en ese rol ve todas las filas, como si no hubiera RLS |
{% hint style="info" %}
Un rol sin filtro no siempre es un error: es común tener un rol del tipo "Acceso total" para gerentes. Use el hallazgo como punto de revisión, confirmando con el responsable del modelo si el acceso irrestricto es intencional.
{% endhint %}
### Lista de modelos semánticos
**Qué es:** la tabla con un modelo por fila, 10 modelos por página de forma predeterminada (el selector **Elementos por página** del pie ofrece 10, 25, 50 y 100), con la sugerencia *Haga clic en una fila para ver los roles, los miembros y los filtros DAX.* sobre ella.
**Para qué sirve:** ver, modelo por modelo, la situación de RLS, cuántos roles y miembros existen y qué hallazgos se aplican.
| Columna | Contenido | Ordenable |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| **Modelo semántico** | Nombre del modelo. Cuando el modelo tiene etiqueta de confidencialidad y el nombre de la etiqueta se pudo resolver, aparece debajo del nombre, con un ícono de etiqueta | Sí |
| **Área de trabajo** | Workspace del modelo | Sí |
| **RLS** | **Con RLS**, **Sin RLS** o **Aún no recopilado** | Sí |
| **Roles** | Cantidad de roles de RLS del modelo ("-" cuando aún no se recopiló) | Sí |
| **Miembros** | Total de miembros sumando todos los roles ("-" cuando aún no se recopiló) | Sí |
| **Hallazgos** | Indicadores **Con etiqueta y sin RLS** (rojo), **Sin miembros: {N}** y **Sin filtro: {N}** (amarillo) | No |
| *(acciones)* | Botón **Ver roles**, que abre el detalle del modelo. Queda deshabilitado cuando el modelo aún no se recopiló o no tiene roles | — |
**Cómo usar la ordenación:** haga clic en el título de una columna ordenable; haga clic de nuevo para invertir el orden. La lista comienza ordenada por **Modelo semántico** (A–Z). Por ejemplo, ordene por **Miembros** para encontrar los modelos con más personas en roles. Use la paginación en el pie para navegar.
**Estados especiales:** cuando ningún modelo cumple los filtros, aparece *No se encontraron modelos semánticos*. Si la consulta falla, aparece *No se pudo cargar la auditoría* con el botón **Intentar de nuevo**.
### Detalle del modelo (roles, miembros y filtros DAX)
**Qué es:** la ventana que se abre al hacer clic en una fila o en el botón **Ver roles**, con el nombre del modelo como título y el workspace como subtítulo.
**Para qué sirve:** revisar, rol por rol, quién recibe cada recorte de datos y qué expresión DAX limita las filas de cada tabla.
**Cómo usar:**
1. Haga clic en la fila del modelo o en **Ver roles**. (El botón queda deshabilitado cuando el modelo no tiene roles o aún no se recopiló; en esos casos, hacer clic en la fila abre el detalle con la explicación correspondiente).
2. En cada bloque de rol, lea:
* **Nombre del rol** e indicadores: el permiso del rol en el modelo (por ejemplo, *Read*), **Sin miembros** y **Sin filtro**, cuando corresponda;
* **Miembros**: usuarios y grupos asignados, con el tipo y el proveedor de identidad entre paréntesis (por ejemplo, *user · AzureAD*). Sin miembros, aparece *Ningún miembro asignado a este rol.*;
* **Filtros por tabla (DAX)**: cada tabla filtrada y la expresión aplicada. Sin filtros, aparece *Este rol no filtra ninguna tabla: sus miembros ven todas las filas.*
3. Cierre con la **X**, presionando **Esc** o haciendo clic fuera de la ventana.
**Mensajes especiales del detalle:**
* *Este modelo exige identidad efectiva (roles) en consultas insertadas.*: las aplicaciones que insertan el contenido (por ejemplo, Power BI Embedded) deben informar la identidad efectiva y los roles en cada consulta.
* *Este modelo no tiene roles de RLS.*: modelo recopilado y sin ningún rol.
* *Los roles de este modelo aún no se han recopilado. Llegan con el próximo escaneo completo.*: modelo **Aún no recopilado**.
### Ocultar datos
**Qué es:** el botón **Ocultar datos**, junto a **Exportar**. Una vez activado, pasa a mostrar **Mostrar datos**.
**Para qué sirve:** compartir la pantalla, grabar demostraciones o tomar capturas sin exponer a las personas.
**Cómo usar:** haga clic en **Ocultar datos**: los nombres de los miembros de cada rol en el detalle del modelo quedan enmascarados en la pantalla y en los archivos exportados. Para volver a ver los valores, haga clic en **Mostrar datos**. Si no se puede enmascarar el archivo, la descarga se interrumpe y la pantalla avisa *No se pudo enmascarar el archivo exportado. Vuelva a mostrar los datos o inténtelo de nuevo.* La elección se guarda en el navegador y vale para las demás pantallas que tienen el botón. Es una comodidad de presentación, no un control de acceso.
### Exportar
**Qué es:** el botón **Exportar**, sobre la lista, con las opciones **CSV** y **JSON**.
**Para qué sirve:** enviar la recertificación de RLS a los responsables de los datos o hacer una revisión detallada de las expresiones DAX fuera de la herramienta.
**Cómo usar:**
1. Aplique los filtros deseados (la exportación respeta los filtros y la ordenación actuales).
2. Haga clic en **Exportar** y elija **CSV** o **JSON**.
3. La descarga de `seguranca-nivel-linha-AAAA-MM-DD.csv` (o `.json`) comienza automáticamente.
**Cómo funciona:** se exportan **todos los modelos que cumplen los filtros** (todas las páginas). El botón queda deshabilitado cuando la lista está vacía.
| Formato | Contenido |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **CSV** | Una fila por modelo, con las columnas **Modelo semántico**, **Área de trabajo**, **RLS**, **Roles**, **Miembros**, **Roles sin miembros** (cantidad), **Roles sin filtro** (cantidad) y **Con etiqueta y sin RLS** (*Sí*/*No*) |
| **JSON** | Los datos completos de cada modelo, **incluidos los roles, los miembros y las expresiones DAX** de cada tabla |
{% hint style="warning" %}
La exportación contiene **nombres y correos de usuarios** (miembros de los roles) y, en el JSON, las **reglas de negocio** expresadas en los filtros DAX. Trate el archivo como información interna, compártalo solo con quien lo necesite y tenga cuidado al pegar este contenido en otras herramientas.
{% endhint %}
## Reglas y comportamiento
* **Origen de los datos.** Los roles, los miembros y los filtros provienen de la API de escáner de metadatos de Power BI/Fabric, recopilados por el [Escaneo de Inventario](/es/power-monitor/mapeamento/inventarios.md) (el Escaneo Completo se ejecuta automáticamente todos los días a las 00:00, hora de Brasilia, UTC-3). Esta pantalla no tiene una recopilación propia: lee lo que guardó el último escaneo. La etiqueta de confidencialidad de cada modelo también proviene del escaneo.
* **Requisito previo en el tenant.** El escáner solo devuelve el esquema y los roles de los modelos cuando la configuración de inquilino **Mejorar las respuestas de las API de administración con metadatos detallados** (*Enhance admin APIs responses with detailed metadata*) está habilitada para el Service Principal del Power Monitor. Sin ella, los modelos permanecen como **Aún no recopilado**.
* **"Aún no recopilado" nunca se convierte en "Sin RLS" por falta de información.** Un modelo solo pasa a **Sin RLS** cuando el escaneo trae el esquema del modelo sin ningún rol. Si una recopilación llega sin información de esquema, se conservan los roles guardados anteriormente. Los modelos que ya existían antes de esta funcionalidad aparecen como **Aún no recopilado** hasta el próximo escaneo completo. Los workspaces marcados como no monitoreados no tienen sus artefactos analizados en profundidad, por lo que sus modelos pueden seguir como **Aún no recopilado**.
* **Nombre de la etiqueta de confidencialidad.** El escaneo trae solo el identificador de la etiqueta; el nombre se consulta en Microsoft Purview mediante Microsoft Graph, con una caché de 1 hora, y solo cuando algún modelo tiene etiqueta. Para mostrar el nombre, la aplicación registrada de la organización necesita el permiso de **aplicación** `InformationProtectionPolicy.Read.All`, con consentimiento de administrador del tenant. Sin ese permiso, el nombre de la etiqueta no aparece debajo del modelo, pero el hallazgo **Con etiqueta y sin RLS** se sigue identificando y contabilizando normalmente.
* **Los modelos eliminados** (detectados como eliminados por el escaneo) no aparecen en la lista.
* **Alcance de workspace.** Usted ve solo los modelos de los workspaces que puede visualizar; las tarjetas también se calculan solo sobre ellos.
* **Carga.** La pantalla carga todo de una vez al abrirse; los filtros, la ordenación, la paginación y la exportación se realizan en el navegador, sin una nueva consulta. Para ver los datos de un escaneo que terminó después, recargue la página.
* **Falla de carga.** Si la consulta falla, la pantalla muestra *No se pudo cargar la auditoría* con el botón **Intentar de nuevo**.
* **Bloqueo de página.** Un administrador puede ocultar esta página a un usuario en [Usuarios](/es/power-monitor/usuarios.md); desaparece del menú y el acceso directo por la dirección lleva a la pantalla **No permitido**.
## Paso a paso: escenarios comunes
Todos los pasos parten de *Auditoría › Seguridad de Nivel de Fila* y están disponibles para cualquier perfil, siempre dentro de los workspaces de su alcance.
### Cómo encontrar modelos con datos clasificados y sin RLS
Úselo para priorizar la corrección de los modelos de mayor riesgo.
{% stepper %}
{% step %}
### Revise la tarjeta Etiqueta sin RLS
En la tarjeta **Etiqueta sin RLS**, vea cuántos modelos tienen etiqueta de confidencialidad y ningún rol. Si la tarjeta está verde (cero), no hay modelos en esa situación entre los ya recopilados.
{% endstep %}
{% step %}
### Filtre por el hallazgo
En el encabezado de la columna **Hallazgos**, seleccione **Con etiqueta y sin RLS**. La lista pasa a mostrar solo esos modelos, con el indicador rojo.
{% endstep %}
{% step %}
### Identifique la etiqueta y el workspace
Debajo del nombre de cada modelo aparece la etiqueta de confidencialidad (cuando se concedió el permiso `InformationProtectionPolicy.Read.All`). La columna **Área de trabajo** indica dónde está publicado el modelo.
{% endstep %}
{% step %}
### Encamine la corrección
Exporte la lista (**Exportar › CSV**) y envíela a los responsables de los modelos. La corrección se realiza en el propio modelo (creando roles de RLS en Power BI Desktop o en el servicio) o revisando si la etiqueta aplicada es correcta. Después de la publicación, el próximo escaneo completo actualiza la pantalla.
{% endstep %}
{% endstepper %}
### Cómo ver los roles, los miembros y los filtros de un modelo
{% stepper %}
{% step %}
### Localice el modelo
Escriba parte del nombre en el campo **Buscar modelo...** del encabezado **Modelo semántico** y, si es necesario, restrinja con el filtro **Área de trabajo**.
{% endstep %}
{% step %}
### Abra el detalle
Haga clic en la fila del modelo o en el botón **Ver roles**. El botón queda deshabilitado cuando el modelo no tiene roles o aún no se recopiló; en esos casos, hacer clic en la fila abre el detalle con la explicación correspondiente.
{% endstep %}
{% step %}
### Revise cada rol
Para cada rol, verifique en **Miembros** quién recibe ese recorte de datos y en **Filtros por tabla (DAX)** qué expresión limita las filas de cada tabla. Los indicadores **Sin miembros** y **Sin filtro** señalan puntos de atención.
{% endstep %}
{% step %}
### Cierre el detalle
Haga clic en la **X**, presione **Esc** o haga clic fuera de la ventana para volver a la lista.
{% endstep %}
{% endstepper %}
### Cómo encontrar roles sin miembros o sin filtro
1. En el encabezado de la columna **Hallazgos**, seleccione **Roles sin miembros** (o **Roles sin filtro**).
2. La columna **Hallazgos** muestra cuántos roles de cada modelo están en esa situación (*Sin miembros: {N}* o *Sin filtro: {N}*).
3. Haga clic en la fila para abrir el detalle e identificar cuáles son; tienen el indicador **Sin miembros** o **Sin filtro**.
4. Confírmelo con el responsable del modelo: un rol sin miembros suele ser una configuración olvidada; un rol sin filtro puede ser intencional (acceso total) o un error.
### Cómo medir la cobertura de RLS
1. Lea la tarjeta **Cobertura de RLS**: el porcentaje considera solo los modelos cuyos roles ya se recopilaron.
2. Vea en **Aún no recopilados** cuántos modelos quedaron fuera del cálculo. Si el número es alto, verifique si el Escaneo Completo se está ejecutando y si la configuración de inquilino de metadatos detallados está habilitada (consulte [Reglas y comportamiento](#reglas-y-comportamiento)).
3. Para listar los modelos de cada grupo, use el filtro de la columna **RLS** (**Con RLS**, **Sin RLS** o **Aún no recopilado**).
## Preguntas frecuentes
Mi modelo tiene RLS, pero aparece como "Aún no recopilado".
Los roles llegan con el Escaneo Completo. Espere el próximo escaneo diario (00:00, hora de Brasilia, UTC-3) o pida a un administrador que dispare un escaneo en *Mapeo › Inventario*. Si el modelo sigue sin recopilarse, verifique si la configuración de inquilino **Mejorar las respuestas de las API de administración con metadatos detallados** está habilitada para el Service Principal y si el workspace está monitoreado.
Modifiqué los roles en Power BI, pero la pantalla no cambió.
La pantalla muestra lo que recopiló el último escaneo. Los cambios aparecen después del próximo Escaneo Completo. Si el escaneo ya terminó, recargue la página.
El modelo tiene etiqueta, pero el nombre de la etiqueta no aparece.
El nombre de la etiqueta se consulta en Microsoft Purview y requiere el permiso de aplicación `InformationProtectionPolicy.Read.All` para la aplicación registrada de la organización. Sin él, el nombre no se muestra, pero el modelo se sigue contabilizando en el hallazgo **Con etiqueta y sin RLS**. Las etiquetas recién publicadas pueden tardar hasta 1 hora en aparecer, debido a la caché.
¿Un rol "Sin filtro" es siempre un problema?
No. Los roles de acceso total (por ejemplo, para la dirección) son comunes. El hallazgo sirve para la revisión: confirme si el acceso irrestricto es intencional.
¿Los miembros de un grupo aparecen expandidos?
No. La pantalla muestra los miembros exactamente como están asignados al rol: cuando el miembro es un grupo, aparece el nombre del grupo. Para ver quién forma parte de un grupo con acceso al modelo, use la [Auditoría de Permisos](/es/power-monitor/auditoria/auditoria-de-permissoes.md).
¿La RLS impide que los administradores del workspace vean los datos?
No. En Power BI, la RLS se aplica a quienes tienen acceso de lectura (por ejemplo, Visor o uso compartido del informe/app). Los Administradores, Miembros y Colaboradores del workspace no se filtran por la RLS. Por eso, revise también quién tiene esos roles en la [Auditoría de Permisos](/es/power-monitor/auditoria/auditoria-de-permissoes.md).
## Páginas relacionadas
* [Auditoría de Permisos](/es/power-monitor/auditoria/auditoria-de-permissoes.md): quién tiene acceso de lectura a los modelos
* [Service Principals](/es/power-monitor/auditoria/service-principals.md) y [Uso Compartido Directo](/es/power-monitor/auditoria/compartilhamento-direto.md): las otras auditorías de acceso
* [Gobernanza › Cumplimiento › Etiquetas y Certificación](/es/power-monitor/governanca/conformidade/rotulos-e-certificacao.md): etiquetas de confidencialidad, respaldo y exposición
* [Gobernanza › Modelos Semánticos](/es/power-monitor/governanca/modelos-semanticos.md)
* [Mapeo › Inventario](/es/power-monitor/mapeamento/inventarios.md): recopilación de los roles y requisitos previos de tenant
* [Configuración › Permisos adicionales](/es/power-monitor/configuracoes/permissoes-adicionais.md): permisos de Microsoft Graph
* [Usuarios](/es/power-monitor/usuarios.md): bloqueo de páginas por usuario
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.powermonitor.com.br/es/power-monitor/auditoria/seguranca-em-nivel-de-linha.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
