Microsoft Graph Reports Export API : industrialiser les exports Intune

L’essentiel

Le point d’entrée deviceManagement/reports/exportJobs reçoit un reportName et des options comme select, filter, format et localization selon le rapport. La liste des noms et propriétés disponibles est documentée séparément et évolue.

La création retourne un objet de job. Le client interroge ensuite son statut jusqu’à completion, récupère l’URL temporaire, télécharge l’archive et traite le CSV ou JSON ; il doit aussi gérer failed, expiration et réponses throttled.

Je sépare collecte brute, normalisation et restitution. Chaque fichier possède horodatage UTC, reportName, paramètres, version de schéma, hash et identifiant de corrélation, sans token ni URL signée conservés dans les logs.

Le point d’entrée deviceManagement/reports/exportJobs reçoit un reportName et des options comme select, filter, format et localization selon le rapport. La liste des noms et propriétés disponibles est documentée séparément et évolue.

Pourquoi cette technologie existe

L’API d’export unifie les rapports migrés vers la nouvelle infrastructure Intune. Je pars de la page des rapports et propriétés disponibles afin d’utiliser le reportName et les colonnes exacts plutôt que de deviner le schéma.

Le POST sur exportJobs contient le format, la sélection de colonnes, un filtre OData lorsque le rapport le supporte et éventuellement la localisation. Réduire select limite le volume, l’exposition de données et les ruptures de schéma.

Je définis l’objectif opérationnel avant de choisir le profil ou l’outil. Cette discipline sépare le besoin de sécurité, l’expérience utilisateur, l’autorité de gestion et la preuve attendue. Elle évite aussi qu’un paramètre soit activé uniquement parce qu’il apparaît dans la console.

Je compare toujours l’intention cloud, l’applicabilité, l’état reçu par Windows et le résultat réellement observé. Une affectation réussie, un état vert ou une requête HTTP acceptée ne prouve pas à lui seul que tout le parcours fonctionne.

Pour expliquer « Export API des rapports Intune », je commence par le besoin auquel la technologie répond, puis je sépare le plan de contrôle, le transport, les composants locaux, les états persistés et les données de résultat. Cette lecture évite d’attribuer au portail une décision prise par Windows ou à l’agent une limitation du service cloud.

Je distingue les interfaces supportées des détails internes observables. Les journaux, tâches et clés de registre aident à comprendre le fonctionnement, mais ils ne deviennent pas automatiquement des contrats stables sur lesquels bâtir une automatisation durable.

Enfin, je relie la théorie au cycle réel : déclenchement, traitement, résultat, nouvelle évaluation et comportement en cas de dérive. L’objectif est de comprendre ce qui se passe, pas seulement de reproduire une configuration.

Je qualifie la nature de chaque état : intention envoyée, valeur effective, inventaire, conformité, télémétrie ou simple cache d’affichage. Ces données n’ont ni la même fraîcheur ni la même autorité. Un résultat cohérent suppose de connaître qui produit l’information, à quel moment, dans quel contexte et selon quel mécanisme elle revient au service.

Je replace aussi la technologie dans son environnement. Les identités, certificats, licences, services réseau, versions clientes et autres outils de gestion peuvent modifier son comportement sans appartenir directement à son moteur. Cette frontière permet de distinguer une limitation intrinsèque d’une dépendance absente ou d’un conflit d’architecture.

Quand une observation terrain complète la documentation, je la présente comme un indice et non comme une garantie de support. Les noms de tâches, fichiers, événements ou rythmes internes peuvent changer. Je m’appuie sur eux pour expliquer et diagnostiquer, tandis que les décisions de conception reposent sur les interfaces et comportements officiellement documentés.

• À comprendre : comprendre l’architecture, les dépendances et les limites
• À comprendre : mettre en œuvre un pilote mesurable et reproductible
• À comprendre : construire un diagnostic et un rollback utilisables par l’exploitation
• Périmètre étudié : Microsoft Graph, Intune reports, Export API, Automation
• Périmètre étudié : postes Windows gérés et services Microsoft officiellement documentés
• Périmètre étudié : validation en laboratoire puis pilote représentatif avant généralisation

Architecture, composants et flux de données

L’API d’export unifie les rapports migrés vers la nouvelle infrastructure Intune. Je pars de la page des rapports et propriétés disponibles afin d’utiliser le reportName et les colonnes exacts plutôt que de deviner le schéma.

Le POST sur exportJobs contient le format, la sélection de colonnes, un filtre OData lorsque le rapport le supporte et éventuellement la localisation. Réduire select limite le volume, l’exposition de données et les ruptures de schéma.

Le service traite le job de manière asynchrone. La réponse fournit un identifiant ; le client interroge l’objet sans boucle agressive et respecte Retry-After ou un backoff exponentiel avec jitter.

Prérequis, compatibilité et limites de support

Je sépare les prérequis nécessaires à l’existence de la fonction de ceux qui ne concernent qu’un scénario d’administration. La présence d’une option dans une console ne prouve ni la prise en charge de la version cliente, ni l’éligibilité de la licence.

Les builds, éditions, rôles, dépendances réseau et contextes d’exécution doivent être confirmés avant d’interpréter un comportement. Les éléments internes observés mais non documentés comme interfaces publiques sont explicitement traités comme tels.

• licence Intune active
• identité Graph dédiée
• permissions minimales approuvées
• reportName et schéma documentés
• stockage temporaire protégé
• backoff et limites de taille
• contrôles qualité et rétention

Cycle de fonctionnement, étape par étape

Cette séquence décrit ce que font les différents composants, depuis le déclenchement jusqu’au résultat. Elle sert de modèle mental : selon le scénario, certaines étapes peuvent être asynchrones ou exécutées dans un autre contexte.

Je distingue l’action demandée, son transport, son traitement local et son accusé de résultat. Cette distinction explique pourquoi deux écrans peuvent afficher temporairement des états différents sans qu’il y ait nécessairement une panne.

Fonctionnement détaillé et responsabilités

L’API d’export unifie les rapports migrés vers la nouvelle infrastructure Intune. Je pars de la page des rapports et propriétés disponibles afin d’utiliser le reportName et les colonnes exacts plutôt que de deviner le schéma.

Le POST sur exportJobs contient le format, la sélection de colonnes, un filtre OData lorsque le rapport le supporte et éventuellement la localisation. Réduire select limite le volume, l’exposition de données et les ruptures de schéma.

Le service traite le job de manière asynchrone. La réponse fournit un identifiant ; le client interroge l’objet sans boucle agressive et respecte Retry-After ou un backoff exponentiel avec jitter.

• licence Intune active
• identité Graph dédiée
• permissions minimales approuvées
• reportName et schéma documentés

Configuration, exploitation et cas limites

Quand le statut est completed, la propriété url pointe vers une archive à durée limitée. Je la télécharge immédiatement dans un stockage temporaire protégé et je ne journalise pas l’URL, car elle peut embarquer une signature d’accès.

L’archive contient un ou plusieurs fichiers selon le rapport et le format. Le pipeline vérifie extension, taille maximale, hash, encodage, colonnes obligatoires et nombre de lignes avant de déplacer le fichier vers l’historique.

Un statut failed est conservé avec le message et les request-id, mais sans bearer token. Les erreurs 401 et 403 sont séparées d’un reportName invalide, d’un filtre non supporté, d’un 429 ou d’une indisponibilité 5xx.

• Valider archive et schéma
• Comparer un échantillon au portail
• Planifier avec alertes et rétention

Interpréter les résultats sans raccourci

L’identité d’automatisation reçoit la permission Graph la moins privilégiée indiquée pour l’API et, si nécessaire, les droits Intune associés. Managed identity ou certificat est préféré à un secret longue durée.

La fréquence tient compte des limites publiées, du volume et de la fraîcheur métier. Je ne lance pas un export complet toutes les minutes si une extraction quotidienne répond à l’objectif ; je répartis les jobs et historise les succès.

Le contrôle de qualité compare quelques appareils au portail, mesure la couverture, détecte les colonnes ajoutées ou supprimées et refuse de publier un dataset incomplet. La Data Warehouse reste plus adaptée à certaines analyses historiques et relationnelles.

Je distingue une donnée de configuration, une donnée d’inventaire et une preuve d’exécution. La première décrit ce qui devrait arriver, la deuxième décrit un état observé à un instant donné et la troisième montre ce qu’un composant a réellement tenté. Leur horodatage et leur contexte doivent converger avant toute conclusion.

Je documente les états non applicable, pending, conflict, error et success séparément. Un poste absent d’un rapport n’est pas nécessairement sain ou en échec : il peut être hors ligne, non éligible, non ciblé, en retard de télémétrie ou exclu par la politique de collecte.

Pilote, généralisation et maintien en conditions opérationnelles

Le pilote couvre plusieurs modèles matériels, versions de Windows, profils réseau, populations utilisateur et exceptions métier. Je conserve une cohorte témoin afin de différencier l’effet du changement d’une évolution globale du service, d’une mise à jour applicative ou d’un incident réseau.

Les critères GO sont définis avant le début : couverture, taux de succès, délai de convergence, incidents, tickets support, régressions et temps de rollback. Une moyenne satisfaisante ne masque pas un sous-groupe en échec ; les résultats sont donc segmentés par version, modèle, site et mode de gestion.

Les cas négatifs sont testés volontairement : appareil hors ligne, licence absente, identité non éligible, règle non applicable, réseau filtré et retour arrière. Un design exploitable doit échouer de manière visible, sûre et compréhensible pour le support.

Après généralisation, je programme une revue des exceptions, des permissions, des versions de profil et des dépendances. Le service cloud et Windows évoluent ; une décision correcte aujourd’hui doit rester traçable et être revalidée lorsqu’un prérequis ou une interface change.

Interfaces d’observation, commandes et exemples

Les commandes illustrent les objets et états décrits dans l’article. Les exemples de diagnostic restent non testés, en niveau 1 et sans modification volontaire. Ils servent à comprendre les données disponibles, pas à industrialiser une collecte.

Une automatisation durable doit employer une API ou une interface officiellement supportée. Une clé de registre, un fichier ou une tâche interne peut évoluer avec Windows, l’agent ou le service.

# Exemple pédagogique non testé — niveau 1
$ErrorActionPreference = 'Stop'
try {
  $uri = 'https://graph.microsoft.com/beta/deviceManagement/reports/exportJobs'
  $body = @{reportName='Devices';format='csv';select=@('DeviceId','DeviceName','OSVersion')} | ConvertTo-Json
  $job = Invoke-MgGraphRequest -Method POST -Uri $uri -Body $body -ContentType 'application/json'
  do { Start-Sleep -Seconds 10; $state = Invoke-MgGraphRequest -Method GET -Uri "$uri/$($job.id)" } while ($state.status -in @('notStarted','inProgress'))
  if ($state.status -ne 'completed') { throw "Export en échec : $($state.status)" }
  [pscustomobject]@{Id=$state.id;Status=$state.status;ExpirationDateTime=$state.expirationDateTime}
} catch { Write-Error "Export Intune impossible : $($_.Exception.Message)"; exit 1 }

Observabilité : où lire l’état réel

Je construis une chronologie unique avec l’heure de la demande, le check-in, l’événement local, la décision du composant et la remontée dans le portail. Je conserve UTC et heure locale, mais j’anonymise UPN, DeviceId, TenantId, noms internes, certificats, adresses et contenus métiers avant partage.

La collecte initiale reste en lecture seule. Je ne vide pas un cache, ne supprime pas une clé, ne réinitialise pas un agent et ne force pas un enrôlement avant d’avoir capturé les preuves. Ces actions changent l’état et peuvent rendre la cause première impossible à démontrer.

Les scripts publiés ici sont des exemples pédagogiques non testés de niveau 1. Toute remédiation réelle doit être au minimum de niveau 2, proposer une simulation, limiter sa cible, expliquer son impact et restaurer l’état précédent. Les opérations privilégiées ou à grande échelle exigent un niveau supérieur et une approbation formelle.

• Choisir reportName et colonnes officielles.
• Créer un exportJob pilote.
• Poller avec backoff jusqu’au statut terminal.
• Télécharger sans journaliser l’URL.
• Valider archive et schéma
• Comparer un échantillon au portail
• Planifier avec alertes et rétention

Validation du modèle et cas d’usage

Je vérifie le modèle sur un appareil représentatif en reliant la configuration du service, l’état reçu, le traitement local et la donnée remontée. L’objectif n’est pas de certifier la production, mais de confirmer que l’explication décrit bien le comportement observé.

Un cas d’usage est retenu lorsque la technologie répond au besoin sans ajouter une autorité concurrente, une dépendance non maîtrisée ou un niveau d’opacité incompatible avec l’exploitation.

• Choisir reportName et colonnes officielles.
• Créer un exportJob pilote.
• Poller avec backoff jusqu’au statut terminal.
• Télécharger sans journaliser l’URL.
• Valider archive et schéma
• Comparer un échantillon au portail
• Planifier avec alertes et rétention

Limites, modes de panne et lecture des erreurs

Cette matrice relie les limites du modèle aux symptômes observables. Elle ne transforme pas une technologie en article de dépannage : elle montre où le fonctionnement normal peut diverger et quelles preuves permettent de comprendre cette divergence.

Une erreur isolée doit être replacée dans sa phase et son contexte. Je privilégie les résultats documentés du service et du client avant les détails d’implémentation susceptibles de changer.

Adoption progressive, réversibilité et vigilance

Pour introduire la technologie, je commence par un scénario borné, des appareils pilotes et des critères d’observation définis. L’adoption progresse uniquement si les dépendances, la supervision et les responsabilités de support sont comprises.

Le retour arrière dépend souvent de la propriété de la ressource et du cycle de synchronisation. Je le teste avant généralisation et je ne déduis jamais la réversibilité de la seule disparition d’un profil dans le portail.

• Réversibilité : désactiver le déclencheur sans supprimer les exports validés
• Réversibilité : revenir au dernier parseur et schéma versionnés
• Réversibilité : révoquer la permission de l’identité si l’automatisation est abandonnée
• Limite ou vigilance : endpoint beta à revalider avant production
• Limite ou vigilance : ne jamais loguer token ou URL signée
• Limite ou vigilance : respecter Retry-After
• Limite ou vigilance : un export réussi ne garantit pas la couverture