Conversion des identifiants Get-MailboxFolderStatistics pour l'API Graph

Introduction

L'écosystème Microsoft Exchange Online utilise différents types d'identifiants selon le contexte d'utilisation, créant un véritable labyrinthe pour les administrateurs système. Avec la dépréciation d'Exchange Web Services (EWS) et la transition vers Microsoft Graph API, la conversion entre ces formats devient cruciale pour maintenir la continuité des opérations administratives.

Cet article détaille les mécanismes de conversion des identifiants de dossiers Exchange, depuis les valeurs storeId obtenues via PowerShell jusqu'aux RestId utilisés par Graph API, en passant par les formats requis pour eDiscovery et MAPI.

Contexte technique

Nous nous concentrons ici sur les identifiants de dossiers dans un contexte d'administration Exchange, où PowerShell constitue l'outil principal d'intervention.

Architecture des identifiants Exchange Online

Types d'identifiants et cas d'usage

Microsoft Exchange Online implémente plusieurs formats d'identifiants selon les APIs et services :

storeId : Format natif PowerShell (Get-ExOMailboxFolderStatistics)
entryId : Format MAPI pour les clients traditionnels
RestId : Format Microsoft Graph API ("Outlook" APIs)
eDiscoveryId : Format spécialisé pour les recherches ciblées

Type d'identifiant	Source	Usage principal	Format
storeId	PowerShell Exchange	Administration	Base64 standard
entryId	MAPI/EWS	Clients traditionnels	Base64 modifié
RestId	Graph API	Applications modernes	URL-safe Base64
eDiscoveryId	Compliance Center	Recherches légales	Hexadécimal

Extraction des identifiants sources

Récupération des storeId via PowerShell

La cmdlet Get-ExOMailboxFolderStatistics constitue le point de départ pour l'extraction des métadonnées de dossiers :

⚡PowerShell

1# Récupération du storeId d'un dossier spécifique
2Get-ExOMailboxFolderStatistics vasil | Where-Object {$_.Name -eq "Xbox"} | Select-Object Name,FolderId
3 
4# Sortie attendue :
5# Name FolderId
6# ---- --------
7# Xbox LgAAAAChKSJAhlnUTIHtKSso30ThAQBIPfDMxyP/RYhY8M8xmAPVAAS8XYoAAAAB

Alternatives PowerShell

D'autres cmdlets fournissent des données similaires :

⚡PowerShell

1# Via Exchange Management Shell (on-premises)
2Get-MailboxFolderStatistics -Identity "user@domain.com"
3 
4# Via cmdlet alternative
5Get-MailboxFolder -Identity "user@domain.com" -Recurse

Conversion pour eDiscovery (Targeted Collections)

Transformation storeId vers eDiscoveryId

Les recherches ciblées eDiscovery nécessitent une conversion spécifique du format storeId :

⚡PowerShell

1function ConvertTo-EDiscoveryId {
2    param(
3        [Parameter(Mandatory=$true)]
4        [string]$StoreId
5    )
6    
7    # Décodage Base64 du storeId
8    $folderId = [Convert]::FromBase64String($StoreId)
9    
10    # Initialisation de l'encodage ASCII
11    $encoding = [System.Text.Encoding]::GetEncoding("us-ascii")
12    $nibbler = $encoding.GetBytes("0123456789ABCDEF")
13    
14    # Allocation du buffer de sortie (48 bytes)
15    $indexIdBytes = New-Object byte[] 48
16    $indexIdIdx = 0
17    
18    # Extraction et conversion des bytes 23-47 (24 bytes)
19    $folderId | Select-Object -Skip 23 -First 24 | ForEach-Object { 
20        $indexIdBytes[$indexIdIdx++] = $nibbler[$_ -shr 4]
21        $indexIdBytes[$indexIdIdx++] = $nibbler[$_ -band 0x0F]
22    }
23    
24    # Retour de la chaîne hexadécimale
25    return $encoding.GetString($indexIdBytes)
26}
27 
28# Exemple d'utilisation
29$storeId = "LgAAAAChKSJAhlnUTIHtKSso30ThAQBIPfDMxyP/RYhY8M8xmAPVAAS8XYoAAAAB"
30$eDiscoveryId = ConvertTo-EDiscoveryId -StoreId $storeId
31# Résultat : 483DF0CCC723FF458858F0CF319803D50004BC5D8A000000

Utilisation KeyQL

L'identifiant eDiscovery peut être utilisé avec le mot-clé folderId dans les requêtes KeyQL pour cibler des dossiers spécifiques lors des recherches de conformité.

Requête eDiscovery ciblée

Une fois l'identifiant converti, intégrez-le dans vos requêtes Content Search :

⚡PowerShell

1# Création d'une recherche ciblée
2New-ComplianceSearch -Name "Xbox-Folder-Search" `
3    -ExchangeLocation "user@domain.com" `
4    -ContentMatchQuery "folderId:483DF0CCC723FF458858F0CF319803D50004BC5D8A000000"

Conversion pour Microsoft Graph API

Transformation storeId vers entryId

La méthode translateExchangeIds de Graph API ne supporte pas directement les storeId. Une conversion intermédiaire vers entryId est nécessaire :

⚡PowerShell

1function ConvertTo-EntryId {
2    param(
3        [Parameter(Mandatory=$true)]
4        [string]$StoreId
5    )
6    
7    # Décodage Base64 vers tableau de bytes
8    $folderIdBytes = [Convert]::FromBase64String($StoreId)
9    
10    # Conversion en chaîne hexadécimale sans séparateurs
11    $folderIdHexString = [System.BitConverter]::ToString($folderIdBytes).Replace('-','')
12    $folderIdHexStringLength = $folderIdHexString.Length
13    
14    # Extraction de l'entryId (suppression premier et dernier byte)
15    $entryIdHexString = $folderIdHexString.SubString(2,($folderIdHexStringLength-4))
16    
17    # Reconversion en tableau de bytes
18    $entryIdBytes = [byte[]]::new($entryIdHexString.Length / 2)
19    
20    for($i=0; $i -lt $entryIdHexString.Length; $i+=2) {
21        $entryIdTwoChars = $entryIdHexString.Substring($i, 2)
22        $entryIdBytes[$i/2] = [convert]::ToByte($entryIdTwoChars, 16)
23    }
24    
25    # Encodage Base64 avec modifications URL-safe
26    $entryIdBase64 = [Convert]::ToBase64String($entryIdBytes)
27    
28    # Comptage des caractères de padding
29    $equalCharCount = $entryIdBase64.Length - $entryIdBase64.Replace('=','').Length
30    
31    # Format final URL-safe avec compteur de padding
32    $entryId = $entryIdBase64.TrimEnd('=').Replace('/','_').Replace('+','-')+$equalCharCount
33    
34    return $entryId
35}

Utilisation de translateExchangeIds

Une fois l'entryId obtenu, utilisez l'API Graph pour la conversion finale :

⚡PowerShell

1# Préparation de la requête Graph
2$translateRequest = @{
3    inputIds = @($entryId)
4    sourceIdType = "entryId"
5    targetIdType = "restId"
6}
7 
8# Appel à l'API Graph
9$result = Invoke-MgGraphRequest -Method POST `
10    -Uri "https://graph.microsoft.com/v1.0/me/translateExchangeIds" `
11    -Body ($translateRequest | ConvertTo-Json)
12 
13# Extraction du RestId
14$restId = $result.value[0].targetId

Limitations API

La méthode translateExchangeIds ne supporte pas les formats immutableEntryId et restImmutableEntryId pour les dossiers. Ces limitations affectent certains scénarios d'intégration.

Script d'automatisation complet

Fonctionnalités du script

Le script Mailbox_Folder_IDs.ps1 automatise l'ensemble du processus de conversion :

Connexion aux services

Le script établit les connexions nécessaires à Exchange Online et Microsoft Graph avec vérification des permissions requises :

⚡PowerShell

1# Permissions Graph requises
2# - User.ReadBasic.All (obligatoire)
3# - Mail.ReadBasic.Shared (optionnel pour délégation)

Extraction des métadonnées

Récupération de tous les dossiers via Get-ExOMailboxFolderStatistics avec option d'inclusion des dossiers non-IPM :

⚡PowerShell

1# Dossiers utilisateur uniquement
2.\Mailbox_Folder_IDs.ps1 -Mailbox user@domain.com
3 
4# Inclusion des dossiers système (non-IPM)
5.\Mailbox_Folder_IDs.ps1 -Mailbox user@domain.com -IncludeNonIPM

Conversion par lots

Le script traite les conversions translateExchangeIds par lots de 1000 identifiants pour optimiser les performances et respecter les limites d'API.

Génération des rapports

Production de fichiers CSV et HTML contenant l'ensemble des identifiants avec fonctionnalités interactives pour Graph Explorer et OWA.

Paramètres du script

⚡PowerShell

1# Utilisation avec adresse SMTP (recommandée pour OWA)
2.\Mailbox_Folder_IDs.ps1 -Mailbox user@domain.com
3 
4# Utilisation avec GUID ExternalDirectoryObjectId
5.\Mailbox_Folder_IDs.ps1 -Mailbox 4ebd5057-4d61-4ca0-beb7-df3f1ebd1aa7
6 
7# Traitement complet incluant les dossiers système
8.\Mailbox_Folder_IDs.ps1 -Mailbox user@domain.com -IncludeNonIPM

Attention aux performances

L'option -IncludeNonIPM peut traiter plusieurs milliers de dossiers système. Utilisez cette option uniquement quand c'est absolument nécessaire.

Structure des rapports générés

Format CSV

Le fichier CSV contient les colonnes suivantes :

Name : Nom du dossier
FolderType : Type de dossier Exchange
Identity : Chemin complet du dossier
FolderId : Valeur storeId originale
eDiscoveryId : Identifiant pour recherches ciblées
EntryId : Identifiant MAPI
RestId : Identifiant Graph API
OWAId : Identifiant Outlook Web App

Interface HTML interactive

Le rapport HTML inclut :

Tableau triable avec tous les identifiants
Bouton Graph Explorer : Lance directement une requête Graph API
Bouton OWA : Navigation directe vers le dossier (dossiers utilisateur uniquement)

Limitations OWA

Les liens OWA fonctionnent uniquement pour les dossiers mail utilisateur et nécessitent l'utilisation de l'adresse SMTP principale comme paramètre d'entrée.

Considérations architecturales

Gestion des permissions

Le script supporte actuellement les permissions déléguées uniquement. Pour un déploiement en production, considérez :

Application permissions pour les traitements automatisés
Certificate-based authentication pour les services
Managed Identity dans les environnements Azure

Optimisations possibles

⚡PowerShell

1# Mise en cache des tokens d'authentification
2$graphSession = @{
3    TenantId = "your-tenant-id"
4    ClientId = "your-app-id"
5    CacheTokens = $true
6}
7 
8# Traitement parallèle pour les gros volumes
9$folders | ForEach-Object -Parallel {
10    # Logique de conversion
11} -ThrottleLimit 5

Cas d'usage avancés

Intégration avec Azure Automation

⚡PowerShell

1# Configuration pour Azure Automation Runbook
2param(
3    [Parameter(Mandatory=$true)]
4    [string]$TargetMailbox,
5    
6    [Parameter(Mandatory=$false)]
7    [switch]$IncludeSystemFolders
8)
9 
10# Authentification via Managed Identity
11Connect-MgGraph -Identity
12Connect-ExchangeOnline -ManagedIdentity

Surveillance et logging

⚡PowerShell

1# Implémentation de logging structuré
2$logEntry = @{
3    Timestamp = Get-Date -Format "yyyy-MM-ddTHH:mm:ss.fffZ"
4    Operation = "FolderIdConversion"
5    Mailbox = $TargetMailbox
6    FoldersProcessed = $folders.Count
7    ConversionErrors = $errors.Count
8}
9 
10$logEntry | ConvertTo-Json | Out-File -Append "conversion-log.json"

Conclusion

La conversion d'identifiants entre les différents systèmes Exchange représente un défi technique complexe mais maîtrisable avec les bons outils. Ce guide fournit une base solide pour automatiser ces conversions dans vos environnements de production.

La transition vers Microsoft Graph API nécessite une planification minutieuse, particulièrement pour les organisations dépendantes des outils PowerShell traditionnels. L'automatisation de ces processus de conversion devient cruciale pour maintenir la continuité opérationnelle.

Introduction

Contexte technique

Nous nous concentrons ici sur les identifiants de dossiers dans un contexte d'administration Exchange, où PowerShell constitue l'outil principal d'intervention.

Architecture des identifiants Exchange Online

Types d'identifiants et cas d'usage

Microsoft Exchange Online implémente plusieurs formats d'identifiants selon les APIs et services :

storeId : Format natif PowerShell (Get-ExOMailboxFolderStatistics)
entryId : Format MAPI pour les clients traditionnels
RestId : Format Microsoft Graph API ("Outlook" APIs)
eDiscoveryId : Format spécialisé pour les recherches ciblées

Type d'identifiant	Source	Usage principal	Format
storeId	PowerShell Exchange	Administration	Base64 standard
entryId	MAPI/EWS	Clients traditionnels	Base64 modifié
RestId	Graph API	Applications modernes	URL-safe Base64
eDiscoveryId	Compliance Center	Recherches légales	Hexadécimal

Extraction des identifiants sources

Récupération des storeId via PowerShell

La cmdlet Get-ExOMailboxFolderStatistics constitue le point de départ pour l'extraction des métadonnées de dossiers :

⚡PowerShell

1# Récupération du storeId d'un dossier spécifique
2Get-ExOMailboxFolderStatistics vasil | Where-Object {$_.Name -eq "Xbox"} | Select-Object Name,FolderId
3 
4# Sortie attendue :
5# Name FolderId
6# ---- --------
7# Xbox LgAAAAChKSJAhlnUTIHtKSso30ThAQBIPfDMxyP/RYhY8M8xmAPVAAS8XYoAAAAB

Alternatives PowerShell

D'autres cmdlets fournissent des données similaires :

⚡PowerShell

1# Via Exchange Management Shell (on-premises)
2Get-MailboxFolderStatistics -Identity "user@domain.com"
3 
4# Via cmdlet alternative
5Get-MailboxFolder -Identity "user@domain.com" -Recurse

Conversion pour eDiscovery (Targeted Collections)

Transformation storeId vers eDiscoveryId

Les recherches ciblées eDiscovery nécessitent une conversion spécifique du format storeId :

⚡PowerShell

1function ConvertTo-EDiscoveryId {
2    param(
3        [Parameter(Mandatory=$true)]
4        [string]$StoreId
5    )
6    
7    # Décodage Base64 du storeId
8    $folderId = [Convert]::FromBase64String($StoreId)
9    
10    # Initialisation de l'encodage ASCII
11    $encoding = [System.Text.Encoding]::GetEncoding("us-ascii")
12    $nibbler = $encoding.GetBytes("0123456789ABCDEF")
13    
14    # Allocation du buffer de sortie (48 bytes)
15    $indexIdBytes = New-Object byte[] 48
16    $indexIdIdx = 0
17    
18    # Extraction et conversion des bytes 23-47 (24 bytes)
19    $folderId | Select-Object -Skip 23 -First 24 | ForEach-Object { 
20        $indexIdBytes[$indexIdIdx++] = $nibbler[$_ -shr 4]
21        $indexIdBytes[$indexIdIdx++] = $nibbler[$_ -band 0x0F]
22    }
23    
24    # Retour de la chaîne hexadécimale
25    return $encoding.GetString($indexIdBytes)
26}
27 
28# Exemple d'utilisation
29$storeId = "LgAAAAChKSJAhlnUTIHtKSso30ThAQBIPfDMxyP/RYhY8M8xmAPVAAS8XYoAAAAB"
30$eDiscoveryId = ConvertTo-EDiscoveryId -StoreId $storeId
31# Résultat : 483DF0CCC723FF458858F0CF319803D50004BC5D8A000000

Utilisation KeyQL

L'identifiant eDiscovery peut être utilisé avec le mot-clé folderId dans les requêtes KeyQL pour cibler des dossiers spécifiques lors des recherches de conformité.

Requête eDiscovery ciblée

Une fois l'identifiant converti, intégrez-le dans vos requêtes Content Search :

⚡PowerShell

1# Création d'une recherche ciblée
2New-ComplianceSearch -Name "Xbox-Folder-Search" `
3    -ExchangeLocation "user@domain.com" `
4    -ContentMatchQuery "folderId:483DF0CCC723FF458858F0CF319803D50004BC5D8A000000"

Conversion pour Microsoft Graph API

Transformation storeId vers entryId

La méthode translateExchangeIds de Graph API ne supporte pas directement les storeId. Une conversion intermédiaire vers entryId est nécessaire :

⚡PowerShell

1function ConvertTo-EntryId {
2    param(
3        [Parameter(Mandatory=$true)]
4        [string]$StoreId
5    )
6    
7    # Décodage Base64 vers tableau de bytes
8    $folderIdBytes = [Convert]::FromBase64String($StoreId)
9    
10    # Conversion en chaîne hexadécimale sans séparateurs
11    $folderIdHexString = [System.BitConverter]::ToString($folderIdBytes).Replace('-','')
12    $folderIdHexStringLength = $folderIdHexString.Length
13    
14    # Extraction de l'entryId (suppression premier et dernier byte)
15    $entryIdHexString = $folderIdHexString.SubString(2,($folderIdHexStringLength-4))
16    
17    # Reconversion en tableau de bytes
18    $entryIdBytes = [byte[]]::new($entryIdHexString.Length / 2)
19    
20    for($i=0; $i -lt $entryIdHexString.Length; $i+=2) {
21        $entryIdTwoChars = $entryIdHexString.Substring($i, 2)
22        $entryIdBytes[$i/2] = [convert]::ToByte($entryIdTwoChars, 16)
23    }
24    
25    # Encodage Base64 avec modifications URL-safe
26    $entryIdBase64 = [Convert]::ToBase64String($entryIdBytes)
27    
28    # Comptage des caractères de padding
29    $equalCharCount = $entryIdBase64.Length - $entryIdBase64.Replace('=','').Length
30    
31    # Format final URL-safe avec compteur de padding
32    $entryId = $entryIdBase64.TrimEnd('=').Replace('/','_').Replace('+','-')+$equalCharCount
33    
34    return $entryId
35}

Utilisation de translateExchangeIds

Une fois l'entryId obtenu, utilisez l'API Graph pour la conversion finale :

⚡PowerShell

1# Préparation de la requête Graph
2$translateRequest = @{
3    inputIds = @($entryId)
4    sourceIdType = "entryId"
5    targetIdType = "restId"
6}
7 
8# Appel à l'API Graph
9$result = Invoke-MgGraphRequest -Method POST `
10    -Uri "https://graph.microsoft.com/v1.0/me/translateExchangeIds" `
11    -Body ($translateRequest | ConvertTo-Json)
12 
13# Extraction du RestId
14$restId = $result.value[0].targetId

Limitations API

La méthode translateExchangeIds ne supporte pas les formats immutableEntryId et restImmutableEntryId pour les dossiers. Ces limitations affectent certains scénarios d'intégration.

Script d'automatisation complet

Fonctionnalités du script

Le script Mailbox_Folder_IDs.ps1 automatise l'ensemble du processus de conversion :

Connexion aux services

Le script établit les connexions nécessaires à Exchange Online et Microsoft Graph avec vérification des permissions requises :

⚡PowerShell

1# Permissions Graph requises
2# - User.ReadBasic.All (obligatoire)
3# - Mail.ReadBasic.Shared (optionnel pour délégation)

Extraction des métadonnées

Récupération de tous les dossiers via Get-ExOMailboxFolderStatistics avec option d'inclusion des dossiers non-IPM :

⚡PowerShell

1# Dossiers utilisateur uniquement
2.\Mailbox_Folder_IDs.ps1 -Mailbox user@domain.com
3 
4# Inclusion des dossiers système (non-IPM)
5.\Mailbox_Folder_IDs.ps1 -Mailbox user@domain.com -IncludeNonIPM

Conversion par lots

Le script traite les conversions translateExchangeIds par lots de 1000 identifiants pour optimiser les performances et respecter les limites d'API.

Génération des rapports

Production de fichiers CSV et HTML contenant l'ensemble des identifiants avec fonctionnalités interactives pour Graph Explorer et OWA.

Paramètres du script

⚡PowerShell

1# Utilisation avec adresse SMTP (recommandée pour OWA)
2.\Mailbox_Folder_IDs.ps1 -Mailbox user@domain.com
3 
4# Utilisation avec GUID ExternalDirectoryObjectId
5.\Mailbox_Folder_IDs.ps1 -Mailbox 4ebd5057-4d61-4ca0-beb7-df3f1ebd1aa7
6 
7# Traitement complet incluant les dossiers système
8.\Mailbox_Folder_IDs.ps1 -Mailbox user@domain.com -IncludeNonIPM

Attention aux performances

L'option -IncludeNonIPM peut traiter plusieurs milliers de dossiers système. Utilisez cette option uniquement quand c'est absolument nécessaire.

Structure des rapports générés

Format CSV

Le fichier CSV contient les colonnes suivantes :

Name : Nom du dossier
FolderType : Type de dossier Exchange
Identity : Chemin complet du dossier
FolderId : Valeur storeId originale
eDiscoveryId : Identifiant pour recherches ciblées
EntryId : Identifiant MAPI
RestId : Identifiant Graph API
OWAId : Identifiant Outlook Web App

Interface HTML interactive

Le rapport HTML inclut :

Tableau triable avec tous les identifiants
Bouton Graph Explorer : Lance directement une requête Graph API
Bouton OWA : Navigation directe vers le dossier (dossiers utilisateur uniquement)

Limitations OWA

Les liens OWA fonctionnent uniquement pour les dossiers mail utilisateur et nécessitent l'utilisation de l'adresse SMTP principale comme paramètre d'entrée.

Considérations architecturales

Gestion des permissions

Le script supporte actuellement les permissions déléguées uniquement. Pour un déploiement en production, considérez :

Application permissions pour les traitements automatisés
Certificate-based authentication pour les services
Managed Identity dans les environnements Azure

Optimisations possibles

⚡PowerShell

1# Mise en cache des tokens d'authentification
2$graphSession = @{
3    TenantId = "your-tenant-id"
4    ClientId = "your-app-id"
5    CacheTokens = $true
6}
7 
8# Traitement parallèle pour les gros volumes
9$folders | ForEach-Object -Parallel {
10    # Logique de conversion
11} -ThrottleLimit 5

Cas d'usage avancés

Intégration avec Azure Automation

⚡PowerShell

1# Configuration pour Azure Automation Runbook
2param(
3    [Parameter(Mandatory=$true)]
4    [string]$TargetMailbox,
5    
6    [Parameter(Mandatory=$false)]
7    [switch]$IncludeSystemFolders
8)
9 
10# Authentification via Managed Identity
11Connect-MgGraph -Identity
12Connect-ExchangeOnline -ManagedIdentity

Surveillance et logging

⚡PowerShell

1# Implémentation de logging structuré
2$logEntry = @{
3    Timestamp = Get-Date -Format "yyyy-MM-ddTHH:mm:ss.fffZ"
4    Operation = "FolderIdConversion"
5    Mailbox = $TargetMailbox
6    FoldersProcessed = $folders.Count
7    ConversionErrors = $errors.Count
8}
9 
10$logEntry | ConvertTo-Json | Out-File -Append "conversion-log.json"

Conversion des identifiants Get-MailboxFolderStatistics pour l'API Graph

Connexion aux services

Extraction des métadonnées

Conversion par lots

Génération des rapports

Houssem MAKHLOUF

Articles similaires

Auditer et Gérer les Applications AI avec PowerShell

Convertir les IDs Exchange pour l'API Graph Microsoft 365

Choisir le bon type d’extension dans Microsoft Entra

Conversion des identifiants Get-MailboxFolderStatistics pour l'API Graph

Connexion aux services

Extraction des métadonnées

Conversion par lots

Génération des rapports

Houssem MAKHLOUF

Articles similaires

Auditer et Gérer les Applications AI avec PowerShell

Convertir les IDs Exchange pour l'API Graph Microsoft 365

Choisir le bon type d’extension dans Microsoft Entra