SharePoint API Usage Report : guide complet

Introduction au rapport SharePoint API Usage

Microsoft a récemment introduit dans le changelog de Microsoft Graph API un nouvel endpoint de reporting dédié à SharePoint Online : le SharePoint API Usage Report. Disponible uniquement sous l'endpoint /beta, ce rapport offre aux administrateurs une visibilité granulaire sur la consommation des API SharePoint par les applications enregistrées dans leur tenant Azure AD.

Cet article vous guide pas à pas à travers l'activation du rapport, la compréhension de ses données, et l'exploitation programmatique de ses endpoints via PowerShell et Graph Explorer. Il s'adresse aux ingénieurs cloud et administrateurs Microsoft 365 qui souhaitent instrumenter leur gouvernance des accès API SharePoint.

Pourquoi ce rapport est stratégique pour votre tenant

Avant l'introduction de ce rapport, la supervision de la consommation API sur SharePoint Online reposait essentiellement sur les journaux d'audit unifiés (Unified Audit Logs) et les données agrégées du portail d'administration Microsoft 365. Ces sources, bien qu'utiles, ne permettaient pas d'identifier facilement quelle application consomme le plus de bande passante ou effectue le plus de requêtes API sur une période donnée.

Le SharePoint API Usage Report comble ce manque en exposant des métriques précises par application, par jour, incluant :

• Le volume de données transférées (en Mo)
• Le nombre d'opérations API exécutées
• L'identification de chaque application par son AppId Azure AD

Ces informations sont précieuses pour les scénarios suivants :

• Audit de gouvernance : identifier les applications tierces ou internes sur-consommatrices
• Optimisation des performances : détecter les patterns de consommation anormaux
• Planification capacitaire : anticiper les pics de charge sur les API SharePoint
• Sécurité : repérer des applications inconnues ayant un accès API actif

Prérequis techniques et modèle de permissions

Permissions Microsoft Graph requises

Le rapport fonctionne actuellement exclusivement en mode délégué (Delegated permissions). Les permissions d'application (Application permissions) ne sont pas encore supportées selon la documentation officielle Microsoft.

Voici le tableau des permissions requises selon l'opération effectuée :

Rôles Azure AD recommandés

• Global Administrator : pour l'activation initiale de la collecte
• Reports Reader : pour la lecture des données de rapport (principe du moindre privilège)
• SharePoint Administrator : accès aux paramètres SharePoint avancés

Activation du rapport SharePoint API Usage

L'activation du rapport nécessite deux étapes distinctes : l'envoi d'une requête d'activation, puis la vérification du statut d'intégration.

1POST https://graph.microsoft.com/beta/admin/reportSettings/sharePoint/enableApiUsageReport
2Content-Type: application/json
3 
4{
5  "metric": "EgressReport"
6}

1GET https://graph.microsoft.com/beta/admin/reportSettings/sharePoint/apiUsageReportMetrics

1{
2  "@odata.context": "https://graph.microsoft.com/beta/$metadata#admin/reportSettings/sharePoint/apiUsageReportMetrics",
3  "metric": "EgressReport",
4  "onboardingStatus": "enabled",
5  "lastUpdatedDateTime": "2026-07-01T00:00:00Z"
6}

Implémentation PowerShell avec Microsoft.Graph SDK

Voici un script PowerShell complet pour automatiser l'activation et la récupération des données du rapport. Il utilise le module Microsoft.Graph PowerShell SDK.

Installation du module requis

1# Installation du module Microsoft Graph PowerShell SDK
2Install-Module -Name Microsoft.Graph -Scope CurrentUser -Force

Script d'activation du rapport

1# Connexion avec les scopes délégués requis
2Connect-MgGraph -Scopes "ReportSettings.ReadWrite.All", "Reports.Read.All"
3 
4# Activation de la collecte de métriques SharePoint API Usage
5$enableBody = @{
6    metric = "EgressReport"
7} | ConvertTo-Json
8 
9try {
10    $enableResponse = Invoke-MgGraphRequest `
11        -Method POST `
12        -Uri "https://graph.microsoft.com/beta/admin/reportSettings/sharePoint/enableApiUsageReport" `
13        -Body $enableBody `
14        -ContentType "application/json"
15 
16    Write-Host "[OK] Collecte activée. Statut : $($enableResponse.onboardingStatus)" -ForegroundColor Green
17} catch {
18    Write-Error "Erreur lors de l'activation : $($_.Exception.Message)"
19}
20 
21# Vérification du statut d'intégration
22$statusResponse = Invoke-MgGraphRequest `
23    -Method GET `
24    -Uri "https://graph.microsoft.com/beta/admin/reportSettings/sharePoint/apiUsageReportMetrics"
25 
26Write-Host "Statut actuel : $($statusResponse.onboardingStatus)"
27Write-Host "Dernière mise à jour : $($statusResponse.lastUpdatedDateTime)"

Script de récupération et d'analyse du rapport

1# Paramètres configurables
2$period = "D30"  # Valeurs possibles : D1, D7, D30
3$outputPath = "C:\Reports\SharePointAPIUsage_$(Get-Date -Format 'yyyyMMdd').csv"
4 
5# Connexion
6Connect-MgGraph -Scopes "Reports.Read.All"
7 
8try {
9    # Récupération des données du rapport
10    $reportData = Invoke-MgGraphRequest `
11        -Method GET `
12        -Uri "https://graph.microsoft.com/beta/reports/getSharePointApiUsage(period='$period')"
13 
14    # Vérification de la présence de données
15    if ($null -eq $reportData.value -or $reportData.value.Count -eq 0) {
16        Write-Warning "Aucune donnée disponible. Vérifiez que la collecte est activée et que le délai d'initialisation est écoulé."
17        exit
18    }
19 
20    # Transformation et export CSV
21    $report = $reportData.value | Select-Object `
22        @{N="Date"; E={$_.usageDateTime}},
23        @{N="ServiceArea"; E={$_.serviceArea}},
24        @{N="AppId"; E={$_.appId}},
25        @{N="UsageMB"; E={[math]::Round($_.usageMB, 2)}},
26        @{N="UsageRequests"; E={$_.usageRequests}}
27 
28    $report | Export-Csv -Path $outputPath -NoTypeInformation -Encoding UTF8
29    Write-Host "[OK] Rapport exporté : $outputPath" -ForegroundColor Green
30 
31    # Analyse : Top 10 des applications par consommation (Mo)
32    Write-Host "`n=== Top 10 Applications par ConsommationMB ==="
33    $report | Group-Object -Property AppId | `
34        Select-Object Name, @{N="TotalMB"; E={($_.Group | Measure-Object UsageMB -Sum).Sum}} | `
35        Sort-Object TotalMB -Descending | `
36        Select-Object -First 10 | `
37        Format-Table -AutoSize
38 
39} catch {
40    Write-Error "Erreur lors de la récupération : $($_.Exception.Message)"
41}

Analyse des données du rapport

Structure des données retournées

L'endpoint getSharePointApiUsage retourne par défaut un payload JSON dont voici la structure annotée :

1{
2  "@odata.context": "https://graph.microsoft.com/beta/$metadata#Collection(microsoft.graph.sharePointApiUsage)",
3  "value": [
4    {
5      "usageDateTime": "2026-06-30",
6      "serviceArea": "SharePoint",
7      "tenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
8      "appId": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
9      "usageMB": 1245.67,
10      "usageRequests": 98432,
11      "activeApps": null
12    }
13  ]
14}

Description détaillée des champs

• usageDateTime : Date de la période de reporting (granularité journalière, format ISO 8601)
• serviceArea : Zone de service concernée — actuellement SharePoint
• tenantId : GUID du tenant — redondant si vous interrogez votre propre tenant
• appId : GUID de l'application Azure AD ayant effectué les appels API SharePoint
• usageMB : Volume de données transférées en mégaoctets pour la journée
• usageRequests : Nombre total d'opérations API effectuées par l'application sur la journée
• activeApps : Champ documenté mais non encore retourné — indiquera à terme le nombre d'applications uniques actives sur la période

Paramètres de requête supportés

Architecture et considérations de gouvernance

Positionnement dans l'écosystème Microsoft Graph

Le SharePoint API Usage Report s'inscrit dans la famille des rapports d'utilisation Microsoft Graph, aux côtés de :

• getGraphApiUsage — consommation globale des API Microsoft Graph
• getSharePointActivityUserDetail — activité utilisateur SharePoint
• getSharePointSiteUsageDetail — utilisation par site SharePoint

Contrairement aux rapports d'activité utilisateur, ce nouveau rapport se concentre exclusivement sur la consommation applicative des API, ce qui en fait un outil de gouvernance complémentaire et non substituable.

Recommandations d'architecture pour la collecte

Pour industrialiser la collecte et l'analyse de ces données, il est recommandé de mettre en place le pipeline suivant :

1[Azure Automation / Logic App]
2        |
3        v
4[Graph API - getSharePointApiUsage]
5        |
6        v
7[Azure Storage Account / Log Analytics Workspace]
8        |
9        v
10[Power BI / Azure Workbooks]

Un Azure Automation Runbook planifié quotidiennement peut automatiser la collecte et l'archivage des données dans un Log Analytics Workspace, permettant ensuite des analyses via KQL et des alertes basées sur des seuils de consommation.

Exemple de requête KQL pour Log Analytics

Si vous ingérez les données dans Log Analytics via un Custom Log, voici une requête KQL pour identifier les applications les plus consommatrices :

1SharePointApiUsage_CL
2| where TimeGenerated >= ago(30d)
3| summarize TotalMB = sum(usageMB_d), TotalRequests = sum(usageRequests_d) by appId_s
4| top 10 by TotalMB desc
5| project AppId = appId_s,
6          TotalDataMB = round(TotalMB, 2),
7          TotalAPIRequests = TotalRequests
8| order by TotalDataMB desc

Limitations connues et points d'attention

• Préversion uniquement : L'endpoint /beta peut être modifié ou retiré sans préavis par Microsoft
• Permissions délégées exclusivement : L'absence de support des permissions applicatives limite l'automatisation non-interactive
• Délai de disponibilité : Les données ne sont pas disponibles en temps réel ; elles sont générées quotidiennement avec un délai potentiel de 24 à 72 heures
• Champ activeApps non fonctionnel : Documenté mais non retourné dans les réponses actuelles
• Pas de rétention configurable : La période maximale interrogeable est de 30 jours (D30)
• Uniformité Graph API : L'obligation d'activer manuellement la collecte et l'existence d'un endpoint dédié (plutôt qu'une intégration native dans getGraphApiUsage) reflète une fragmentation architecturale des équipes produit Microsoft

Ressources de référence officielles

• Documentation Microsoft Graph - enableApiUsageReport
• Documentation Microsoft Graph - getSharePointApiUsage
• Graph API Changelog
• Microsoft Graph PowerShell SDK
• Rôles Azure AD pour les rapports Microsoft 365
• Microsoft Graph Explorer

Conclusion

Le SharePoint API Usage Report est une addition bienvenue dans l'arsenal de reporting Microsoft Graph, notamment pour les organisations ayant de nombreuses applications tierces ou internes intégrées à SharePoint Online. Malgré ses limitations actuelles — absence de permissions applicatives, nécessité d'activation manuelle, données non temps-réel — il offre une visibilité jusqu'alors inexistante sur la consommation API au niveau applicatif.

La mise en place d'une collecte automatisée et d'un archivage dans Log Analytics dès maintenant permettra d'établir des baselines solides et de se préparer à d'éventuelles politiques de throttling que Microsoft pourrait introduire à l'avenir. C'est une bonne pratique de gouvernance que tout administrateur SharePoint Online sérieux devrait intégrer dans son outillage de supervision.