> ## Documentation Index
> Fetch the complete documentation index at: https://docs.athenahq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Power BI et Microsoft Fabric

> Récupérez les données AthenaHQ dans Power BI Desktop, Power BI Service ou Microsoft Fabric via l’API REST

AthenaHQ ne fournit pas de connecteur natif pour Power BI ou Microsoft Fabric, mais son API REST publique fonctionne directement avec Power Query M, le langage utilisé par Power BI Desktop, Power BI Service et Fabric Dataflow Gen2.

## Prérequis

* Une clé API AthenaHQ (Organisation → onglet API). Consultez la page [Authentification](https://docs.athenahq.ai/fr/api-reference/authentication.md).
* Le `website_id` du site sur lequel vous souhaitez établir des rapports. Récupérez-le avec `GET /api/v1/websites`.
* Power BI Desktop ou un espace de travail Microsoft Fabric avec Dataflow Gen2 activé.

## Configuration

**1. Créer une clé API**

Accédez à la [page Clés API](https://app.athenahq.ai/organization?tab=api) dans votre tableau de bord AthenaHQ. Sélectionnez les sites auxquels la clé doit accéder, créez-la et conservez-la en lieu sûr.

> [card] [Gérer les clés API](https://app.athenahq.ai/organization?tab=api)
>
> Créez et gérez les clés API dans les paramètres de votre organisation

**2. Trouver votre website\_id**

Exécutez la commande suivante dans votre terminal :

```bash theme={null}
curl https://api.athenahq.ai/api/v1/websites \
  -H "x-api-key: YOUR_API_KEY"
```

Copiez l’`id` du site web dont vous souhaitez récupérer les données dans Power BI ou Fabric.

**3. Ajouter la requête dans Power BI Desktop ou Fabric**

* **Power BI Desktop :** Accueil → Obtenir des données → Requête vide → Éditeur avancé.
* **Microsoft Fabric :** Espace de travail → Nouveau → Dataflow Gen2 → Obtenir des données → Requête vide → Éditeur avancé.

Collez l’extrait M ci-dessous en remplaçant `YOUR_API_KEY`, `YOUR_WEBSITE_ID` et la plage de dates. `start_date` / `end_date` acceptent des chaînes de date et d’heure ISO-8601 (UTC).

```m theme={null}
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
```

Pour les points de terminaison `GET` tels que `/api/v1/prompts` ou `/api/v1/competitors`, omettez `Content` et transmettez plutôt les paramètres dans `Query` :

```m theme={null}
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
```

**4. Transformer la réponse en table**

Chaque point de terminaison de métriques renvoie `{ "data": [...] }`. La réponse de série chronologique de part de voix est un tableau de lignes organisées par date, avec un enregistrement par entreprise. Développez-le ainsi :

```m theme={null}
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 condition `List.IsEmpty` évite les erreurs d’actualisation planifiée lorsque la plage de dates ne renvoie aucune ligne. Adaptez l’étape de développement à la structure de réponse du point de terminaison appelé.

**5. Configurer les informations d’identification dans Power BI Service ou Fabric**

Après publication du jeu de données ou du flux de données, définissez les informations d’identification de la source `https://api.athenahq.ai` sur **Anonyme**. La clé API passe dans l’en-tête de la requête plutôt que dans le magasin d’identifiants de Power BI : le type d’identification intégré **API Web** de Power BI prend uniquement en charge un en-tête `Authorization` et ne peut pas stocker un en-tête personnalisé `x-api-key`.

Si votre organisation exige des passerelles de données locales pour le trafic externe, faites passer la connexion par la passerelle configurée.

## Considérations de sécurité

> [!WARNING]
>
> Lorsqu’une clé API est intégrée à une requête M, **tout utilisateur disposant
> d’un accès de modification, de création ou de contribution au jeu de données,
> au flux de données ou au fichier `.pbix` peut ouvrir Power Query et lire la
> clé**. Stocker la clé comme paramètre Power BI l’expose de la même manière :
> les paramètres sont visibles par les éditeurs. Traitez la clé comme un
> identifiant partagé et appliquez les mesures ci-dessous.

Pratiques recommandées :

* **Utilisez une clé API dédiée à cette intégration et limitée aux sites concernés.** Créez une clé distincte de vos autres automatisations et limitez-la aux seuls sites nécessaires aux rapports. Consultez le [périmètre des clés API](https://docs.athenahq.ai/fr/api-reference/authentication.md#api-key-scoping). Ne réutilisez pas une clé d’organisation à périmètre étendu.
* **Restreignez l’accès à l’espace de travail.** Accordez les autorisations de modification, de création et de contribution sur l’espace Power BI, le jeu de données, le flux de données et le `.pbix` source au nombre minimal d’utilisateurs de confiance. Les lecteurs de Power BI Service ne peuvent pas consulter le code M, mais toute personne ayant accès au fichier `.pbix` peut l’ouvrir dans Desktop et le lire.
* **Remplacez la clé en cas d’exposition présumée.** Si les membres de l’espace de travail changent, si un `.pbix` est partagé à l’extérieur ou si vous suspectez une fuite, remplacez la clé depuis la [page Clés API](https://app.athenahq.ai/organization?tab=api).
* **Évitez de versionner les fichiers `.pbix` contenant la clé.** Retirez la clé (ou utilisez un paramètre remplacé dans le service) avant de les ajouter au contrôle de version.

Solutions offrant davantage de garanties (pour les équipes aux exigences strictes de gestion des secrets) :

* **Déployez un proxy léger que vous contrôlez.** Hébergez un petit point de terminaison (Azure Function, Cloud Function, service interne) qui injecte la clé API AthenaHQ depuis un stockage sécurisé avant de transférer la requête. Le proxy **doit** imposer sa propre authentification (par exemple un compte Entra ID / Microsoft, un jeton par appelant, mTLS), ou n’être accessible que depuis un réseau interne ou via la passerelle de données locale Power BI. Si le proxy reste anonyme sur Internet, toute personne connaissant son URL peut appeler AthenaHQ en votre nom, exfiltrer vos données et épuiser votre quota. La clé ne figure jamais dans la requête M, mais sa protection dépend des contrôles d’accès placés devant le proxy.
* **Créez un connecteur Power BI personnalisé (`.mez`).** Les connecteurs personnalisés peuvent utiliser le magasin d’identifiants Power BI pour des en-têtes arbitraires et ainsi garder la clé hors du code source des rapports. Cela nécessite de développer le connecteur et de le distribuer par un administrateur.

## Points de terminaison

Power Query peut appeler tous les points de terminaison de la [référence API](https://docs.athenahq.ai/fr/api-reference/introduction.md). Voici des points de départ courants :

| Point de terminaison | Méthode | Usage |
| - | - | - |
| `/api/v1/metrics/share-of-voice/time-series` | POST | Part de voix quotidienne de la marque et de ses concurrents |
| `/api/v1/metrics/mention-rate/time-series` | POST | Évolution du taux de mention dans les réponses des LLM |
| `/api/v1/metrics/citation-rate/time-series` | POST | Évolution du taux de citation |
| `/api/v1/metrics/position/time-series` | POST | Évolution de la position moyenne dans les réponses |
| `/api/v1/prompts` | GET | Liste des prompts suivis |
| `/api/v1/competitors` | GET | Liste des concurrents configurés |

Chaque point de terminaison de métriques possède aussi une variante `/cumulative` qui renvoie une seule valeur agrégée pour la plage de dates. Utilisez l’extrait POST pour les métriques et l’extrait GET pour `prompts` / `competitors`.

## Authentification

Toutes les requêtes utilisent l’en-tête `x-api-key`. Consultez [Authentification](https://docs.athenahq.ai/fr/api-reference/authentication.md) pour tous les détails, notamment le périmètre des clés API.

## Limites de débit

Les requêtes API sont soumises aux limites indiquées sur la page [Limites de débit](https://docs.athenahq.ai/fr/api-reference/rate-limits.md). Les actualisations planifiées Power BI consomment le même quota ; échelonnez-les si vous connectez de nombreux rapports.

## Dépannage

* **`401 Unauthorized`** : la clé API est absente, révoquée ou ne couvre pas le `website_id` demandé.
* **Demandes d’identifiants en boucle dans Power BI Service** : vérifiez que les informations d’identification de la source sont définies sur **Anonyme** pour `https://api.athenahq.ai`. Power BI ne peut pas stocker lui-même l’en-tête `x-api-key` ; la clé doit donc figurer dans la requête M.
* **Avertissement d’URL dynamique de `Web.Contents`** : conservez l’URL de base en dur et transmettez les parties dynamiques par les options `RelativePath` et `Query`. L’extrait ci-dessus suit déjà ce modèle.
* **`405 Method Not Allowed`** : appeler un point de terminaison `GET` (par exemple `/api/v1/prompts`) avec `Content` force une requête POST, qui est refusée. Utilisez la variante `GET` de l’extrait.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.