Power BI y Microsoft Fabric

AthenaHQ no incluye un conector nativo para Power BI o Microsoft Fabric, pero la API REST pública funciona directamente con Power Query M, el mismo lenguaje que utilizan Power BI Desktop, Power BI Service y Fabric Dataflow Gen2.

Requisitos previos

Una clave de API de AthenaHQ (Organización → pestaña API). Consulta la página de Autenticación.
El website_id sobre el que quieres informar. Obtenlo con GET /api/v1/websites.
Power BI Desktop o un espacio de trabajo de Microsoft Fabric con Dataflow Gen2 activado.

Configuración

Crear una clave de API

Ve a la página de claves de API del panel de AthenaHQ. Selecciona los sitios web a los que debe acceder la clave, créala y guárdala de forma segura.

Gestionar claves de API

Crea y gestiona claves de API en la configuración de tu organización

Buscar tu website_id

Ejecuta lo siguiente desde tu terminal:

curl https://api.athenahq.ai/api/v1/websites \
  -H "x-api-key: YOUR_API_KEY"

Copia el id del sitio web cuyos datos quieres obtener en Power BI o Fabric.

Añadir la consulta en Power BI Desktop o Fabric

Power BI Desktop: Inicio → Obtener datos → Consulta en blanco → Editor avanzado.
Microsoft Fabric: Espacio de trabajo → Nuevo → Dataflow Gen2 → Obtener datos → Consulta en blanco → Editor avanzado.

Pega el siguiente fragmento M y sustituye YOUR_API_KEY, YOUR_WEBSITE_ID y el intervalo de fechas. start_date / end_date aceptan cadenas de fecha y hora ISO-8601 (UTC).

let
  ApiKey   = "YOUR_API_KEY",
  Website  = "YOUR_WEBSITE_ID",
  // Adjust to your reporting window. Format: ISO-8601 UTC.
  Body     = Json.FromValue([
               website_id = Website,
               filters    = [
                 start_date = "2024-01-01T00:00:00.000Z",
                 end_date   = "2024-01-31T23:59:59.999Z"
               ]
             ]),
  Source   = Web.Contents(
               "https://api.athenahq.ai",
               [
                 RelativePath = "/api/v1/metrics/share-of-voice/time-series",
                 Headers      = [
                   #"x-api-key"    = ApiKey,
                   #"Content-Type" = "application/json"
                 ],
                 Content      = Body
               ]
             ),
  Json     = Json.Document(Source),
  Data     = Json[data]
in
  Data

Para endpoints GET como /api/v1/prompts o /api/v1/competitors, omite Content y pasa los parámetros mediante Query:

let
  ApiKey   = "YOUR_API_KEY",
  Website  = "YOUR_WEBSITE_ID",
  Source   = Web.Contents(
               "https://api.athenahq.ai",
               [
                 RelativePath = "/api/v1/prompts",
                 Query        = [ website_id = Website ],
                 Headers      = [ #"x-api-key" = ApiKey ]
               ]
             ),
  Json     = Json.Document(Source),
  Data     = Json[data]
in
  Data

Convertir la respuesta en una tabla

Cada endpoint de métricas devuelve { "data": [...] }. La respuesta de la serie temporal de cuota de voz es una matriz de filas organizadas por fecha, con un registro por empresa. Expándela así:

let
  AsTable  = Table.FromList(Data, Splitter.SplitByNothing(), {"row"}),
  Expanded = if List.IsEmpty(Data) then
               AsTable
             else
               Table.ExpandRecordColumn(
                 AsTable,
                 "row",
                 Record.FieldNames(AsTable{0}[row])
               )
in
  Expanded

La comprobación List.IsEmpty evita que las actualizaciones programadas fallen cuando el intervalo de fechas no devuelve filas. Ajusta el paso de expansión a la estructura de respuesta del endpoint al que llames.

Configurar las credenciales en Power BI Service o Fabric

Al publicar el conjunto de datos o flujo de datos, establece las credenciales de la fuente de datos https://api.athenahq.ai en Anónimo. La clave de API se envía en la cabecera de la solicitud y no mediante el almacén de credenciales de Power BI, ya que el tipo de credencial integrado Web API de Power BI solo admite una cabecera Authorization y no puede almacenar una cabecera personalizada x-api-key.Si tu organización exige puertas de enlace de datos locales para el tráfico externo, dirige la conexión a través de la puerta de enlace configurada.

Consideraciones de seguridad

Cuando la clave de API está incorporada en una consulta M, cualquier usuario con acceso de edición, compilación o colaborador al conjunto de datos, flujo de datos o archivo .pbix puede abrir Power Query y leer la clave. Guardarla como parámetro de Power BI supone la misma exposición: los parámetros son visibles para los editores. Trata la clave como una credencial compartida y aplica las siguientes medidas de protección.

Prácticas recomendadas:

Utiliza una clave de API dedicada, limitada a sitios web, para esta integración. Crea una clave distinta de las de otras automatizaciones y limita su acceso únicamente a los sitios web sobre los que necesitas informar. Consulta Ámbito de las claves de API. No reutilices una clave con acceso amplio a la organización.
Restringe el acceso al espacio de trabajo. Limita los permisos de edición, compilación y colaborador del espacio de trabajo de Power BI, conjunto de datos, flujo de datos y .pbix de origen al menor número posible de usuarios de confianza. Los lectores de Power BI Service no pueden leer el código M, pero cualquiera que tenga acceso al archivo .pbix puede abrirlo en Desktop y leerlo.
Rota la clave si sospechas que se ha expuesto. Si cambian los miembros del espacio de trabajo, se comparte un .pbix externamente o sospechas una filtración, rota la clave desde la página de claves de API.
Evita guardar archivos .pbix que contengan la clave en el control de versiones. Elimina la clave (o utiliza un parámetro que se sustituya en el servicio) antes de guardarlos.

Alternativas con mayores garantías (para equipos con requisitos estrictos de gestión de secretos):

Ejecuta un proxy ligero que controles. Aloja un pequeño endpoint (Azure Function, Cloud Function o servicio interno) que incorpore la clave de API de AthenaHQ desde un almacén seguro antes de reenviar la solicitud. El propio proxy debe exigir su propia autenticación (por ejemplo, una cuenta de Entra ID / Microsoft, un token por solicitante o mTLS) o ser accesible únicamente desde una red interna o mediante la puerta de enlace de datos local de Power BI. Si el proxy se deja anónimo en Internet, cualquiera que conozca su URL puede llamar a AthenaHQ en tu nombre, extraer tus datos y agotar tu cuota. La clave nunca reside en la consulta M, pero queda sujeta a los controles de acceso que sitúes delante del proxy.
Desarrolla un conector personalizado de Power BI (.mez). Los conectores personalizados pueden utilizar el almacén de credenciales de Power BI para cabeceras arbitrarias y mantener la clave fuera del código fuente del informe. Esto requiere desarrollar el conector y distribuirlo mediante un administrador.

Endpoints

Puedes llamar a cualquier endpoint de la referencia de la API desde Power Query. Puntos de partida habituales:

Endpoint	Método	Propósito
`/api/v1/metrics/share-of-voice/time-series`	POST	Cuota de voz diaria de la marca y sus competidores
`/api/v1/metrics/mention-rate/time-series`	POST	Porcentaje de menciones en respuestas de LLM a lo largo del tiempo
`/api/v1/metrics/citation-rate/time-series`	POST	Porcentaje de citas a lo largo del tiempo
`/api/v1/metrics/position/time-series`	POST	Posición media en las respuestas a lo largo del tiempo
`/api/v1/prompts`	GET	Listar las consultas en seguimiento
`/api/v1/competitors`	GET	Listar los competidores configurados

Cada endpoint de métricas también tiene una variante /cumulative que devuelve un único valor agregado para el intervalo de fechas. Utiliza el fragmento POST para los endpoints de métricas y el fragmento GET para prompts / competitors.

Autenticación

Todas las solicitudes utilizan la cabecera x-api-key. Consulta Autenticación para conocer todos los detalles, incluido el ámbito de las claves de API.

Límites de solicitudes

Las solicitudes de API están sujetas a los límites documentados en la página Límites de solicitudes. Las actualizaciones programadas de Power BI consumen la misma cuota, por lo que conviene escalonarlas si conectas muchos informes.

Resolución de problemas

401 Unauthorized: la clave de API falta, se ha revocado o no tiene acceso al website_id solicitado.
Peticiones de credenciales en bucle en Power BI Service: comprueba que las credenciales de la fuente de datos están configuradas como Anónimo para https://api.athenahq.ai. Power BI no puede almacenar por sí mismo la cabecera x-api-key, por lo que debe estar en la consulta M.
Aviso de URL dinámica de Web.Contents: mantén la URL base fija en el código y pasa las partes dinámicas mediante las opciones RelativePath y Query. El fragmento anterior ya sigue este patrón.
405 Method Not Allowed: llamar a un endpoint GET (por ejemplo, /api/v1/prompts) con Content definido fuerza un POST y se rechaza. Utiliza la variante GET del fragmento.

Descripción general

Integraciones

Recursos principales

Analítica

Contenido y conocimiento

Administración

Power BI y Microsoft Fabric

Requisitos previos

Configuración

Gestionar claves de API

Consideraciones de seguridad

Endpoints

Autenticación

Límites de solicitudes

Resolución de problemas

​Requisitos previos

​Configuración

Gestionar claves de API

​Consideraciones de seguridad

​Endpoints

​Autenticación

​Límites de solicitudes

​Resolución de problemas

Requisitos previos

Configuración

Consideraciones de seguridad

Endpoints

Autenticación

Límites de solicitudes

Resolución de problemas