Pretvaranje ID-ova Get-MailboxFolderStatistics za korištenje s Graph API-jem

Programeri jednostavno vole identifikatore. Jedino što više vole je njihovo vlastiti okus identifikatora, pretpostavljam da ih sve čini posebnima. Što je sve u redu, sve dok niste prisiljeni sami se kretati labirintom. Kao što je slučaj s Exchangeom, gdje se moramo nositi s nekoliko vrsta identifikatora ovisno o zadatku koji imamo, posao kojemu ne pomaže nedostatak odgovarajuće (ili bilo koje) dokumentacije, odbacivanje bez rješavanja pitanja pariteta i tako dalje.

O tome smo već ranije govorili, npr ovaj članak. U to je vrijeme zastarjelost EWS-a tek trebala biti objavljena, tako da je novi Graph-based translateExchangeIds metoda je bila samo novost za pokrivanje. Međutim, s nadolazećom propašću EWS-a i bez očekivanja da će se vidjeti podrška za pretvorbu StoreId vrijednosti putem grafikona, sada je dobro vrijeme da ponovno pogledate temu i pružite neke dodatne pojedinosti/metode koje bi vam mogle pomoći u nastavku.

Imajte na umu da je rasprava u ovom članku usredotočena samo na identifikatore mapa, budući da se slučajevi upotrebe koje ispitujemo vrte oko tipičnog “administratorskog” (ili IT Pro) iskustva, gdje je PowerShell glavni alat. Drugim riječima, počinjemo s StoreId vrijednosti, dobivene putem Get-ExOMailboxFolderStatistics ili ekvivalentne cmdlete (Get-MailboxFolderStatistics ili Get-MailboxFolder). The StoreId zatim se pretvara u unosIdšto MAPI klijenti koriste. The unosId zauzvrat podržava Graph’s translateExchangeIds metoda koja nam omogućuje dobivanje RestIdšto je ono što koriste API-ji Grafa “Outlook”. Slični se koraci mogu slijediti za stavke umjesto mapa, ako se ukaže potreba.

Kao primjer, recimo da želimo raditi s određenom mapom u svom poštanskom sandučiću. The Get-ExOMailboxFolderStatistics cmdlet nam može dati početnu točku, mapu StoreId vrijednost, putem FolderId svojstvo:

Get-ExOMailboxFolderStatistics vasil | ? $_.Name -eq "Xbox" | select Name,FolderId

Name FolderId
---- --------
Xbox LgAAAAChKSJAhlnUTIHtKSso30ThAQBIPfDMxyP/RYhY8M8xmAPVAAS8XYoAAAAB

Jedna praktična upotreba StoreId vrijednost je za eDiscovery/Content pretraživanja putem tzv ciljane zbirke značajka. Čini se da je iz nekog razloga Microsoft ukinuo odgovarajuću dokumentaciju, pa se možete pozvati na moju prethodni članak na temu, odn Tonyjeva verzija ovdje. TL;DR – možete koristiti KeyQL-ove folderId ključna riječ za opseg operacije za pokrivanje samo određene mape (ili skupa mapa, uz također podržane iznimke). Da biste to učinili, prvo trebate pretvoriti StoreId vrijednost, kako je gore dobivena, u očekivani format. Evo primjera koda za to:

$folderId = [Convert]::FromBase64String($folderId)

$encoding = [System.Text.Encoding]::GetEncoding("us-ascii")
$nibbler = $encoding.GetBytes("0123456789ABCDEF")

$indexIdBytes = New-Object byte[] 48; $indexIdIdx = 0
$folderId | select -skip 23 -first 24 | %  $indexIdBytes[$indexIdIdx++] = $nibbler[$_ -shr 4]; $indexIdBytes[$indexIdIdx++] = $nibbler[$_ -band 0x0F] 

return $encoding.GetString($indexIdBytes)

U našem primjeru, mapa Xbox StoreId vrijednost se transformira na sljedeći način:

#storeId
LgAAAAChKSJAhlnUTIHtKSso30ThAQBIPfDMxyP/RYhY8M8xmAPVAAS8XYoAAAAB

#eDiscovery folderId
483DF0CCC723FF458858F0CF319803D50004BC5D8A000000

Sada možemo koristiti ovu vrijednost za pokretanje eDiscovery pretraživanja s opsegom samo za mapu Xbox. Kao što je prikazano na snimci zaslona, ​​rezultati koje vraća upit odgovaraju broju stavki koje se trenutno nalaze u navedenoj mapi, prema izvješću Outlooka.

Osim za eDiscovery, možda ćete trebati identifikator za izvođenje raznih operacija putem cmdleta iz Graph SDK-a za PowerShell ili odgovarajućih Graph API metoda. Dok možete koristiti dobro poznat vrijednosti za zadane mape, tj Inbox ili RecoverableItemsDeletionsrad s mapama koje su izradili korisnici zahtijeva još jednu vrstu identifikatora – RestId. Nažalost, translateExchangeIds metoda trenutno ne podržava način pretvaranja StoreId dobili smo putem PowerShell-a do a restId vrijednost, tako da ovdje moramo implementirati međukorak.

Donji kod je ljubaznošću Martina Macháčeka preko at Stack Overflow. Preobražava a StoreId vrijednost za an unosId jedan.

function FolderIdToEntryId 

    param([Parameter(Mandatory=$true)]$folderId)

    # convert from base64 to bytes
    $folderIdBytes = [Convert]::FromBase64String($folderId)

    # convert byte array to string, remove '-' and ignore first byte
    $folderIdHexString = [System.BitConverter]::ToString($folderIdBytes).Replace('-','')
    $folderIdHexStringLength = $folderIdHexString.Length

    # get hex entry id string by removing first and last byte
    $entryIdHexString = $folderIdHexString.SubString(2,($folderIdHexStringLength-4))

    # convert to byte array - two chars represents one byte
    $entryIdBytes = [byte[]]::new($entryIdHexString.Length / 2)

    For($i=0; $i -lt $entryIdHexString.Length; $i+=2)
        $entryIdTwoChars = $entryIdHexString.Substring($i, 2)
        $entryIdBytes[$i/2] = [convert]::ToByte($entryIdTwoChars, 16)
    

    # convert bytes to base64 string
    $entryIdBase64 = [Convert]::ToBase64String($entryIdBytes)

    # count how many '=' contains base64 entry id
    $equalCharCount = $entryIdBase64.Length - $entryIdBase64.Replace('=','').Length

    # trim '=', replace '/' with '-', replace '+' with '_' and add number of '=' at the end
    $entryId = $entryIdBase64.TrimEnd('=').Replace('/','_').Replace('+','-')+$equalCharCount

    return $entryId

Jednom kada imamo unosId vrijednost, možemo koristiti grafikon translateExchangeIds metoda za dobivanje restIdili bilo koji drugi podržani identifikator (imajte na umu immutableEntryId i restImmutableEntryId nisu podržani za mape). Potreban je još jedan korak za pretvaranje restId u format koji koristi OWA.

Kombinirajući sve ovo, možemo stvoriti jednostavnu skriptu za generiranje izvješća o svim mapama unutar određenog poštanskog sandučića, zajedno s njihovim ID-ovima. možete preuzmi skriptu iz mog GitHub repoa. Trebat će vam moduli Exchange Online i Graph da biste ga pokrenuli, a trenutna verzija podržava samo dopuštenja delegata. To bi i dalje trebalo biti dovoljno za generiranje ID-ova u svim poštanskim sandučićima, sve dok korisnik kod kojeg se autentificirate ima User.ReadBasic.All dopuštenje. Na strani Exchangea, jedini cmdlet koji nam treba je Get-ExOMailboxFolderStatistics.

Skripta ima jedan obavezan parametar, –poštanski sandučićza označavanje poštanskog sandučića koji nas zanima. Možete koristiti ili GUID (ExternalDirectoryObjectId) ili primarna SMTP adresa. Potonji se može koristiti samo ako se podudara s UPN-om, zbog dizajna Grapha. Podržan je jedan dodatni parametar koji signalizira da želite obraditi sve mape unutar poštanskog sandučića, uključujući one u ne-IPM stablu. Imajte na umu da je u Exchange Onlineu normalno da poštanski sandučići obuhvaćaju tisuće i tisuće mapa koje nisu dostupne korisniku, stoga koristite odgovarajući parametar (-UključiNonIPM) samo kada ste sigurni.

Evo nekoliko primjera kako pokrenuti skriptu:

#Run the script against the user@domain.com mailbox
.\Mailbox_Folder_IDs.ps1' -Mailbox user@domain.com

#Alternatively, you can specify ExternalDirectoryObjectId value as input
.\Mailbox_Folder_IDs.ps1' -Mailbox 4ebd5057-4d61-4ca0-beb7-df3f1ebd1aa7

#Generate IDs for folders in the non-IMP tree
.\Mailbox_Folder_IDs.ps1' -Mailbox user@domain.com -IncludeNonIPM

Osnovna funkcija povezivanja uključena je u skriptu, koja bi također trebala potvrditi da su prisutna potrebna Graph API dopuštenja (User.ReadBasic.All). Budući da je provjera pogrešaka minimalna, a mi se ne zamaramo pokrivanjem svih mogućih scenarija, slobodno je zamijenite svojim preferiranim načinom povezivanja na uslugu (redci 11-42).

Nakon povezivanja, skripta će dohvatiti sve mape unutar navedenog poštanskog sandučića, uključujući mape u ne-IPM stablu kada -IncludeNonIPM korišten je prekidač. Vraćeni popis mapa tada se obogaćuje s eDiscoveryId i EntryId vrijednosti, za koje ne trebamo vršiti nikakve dodatne pozive. Sljedeći korak je pozivanje Graph-a translateExchangeIds metoda protiv skupa generiranih unosId vrijednosti, što se radi u serijama od 1000. Dobiveni RestId vrijednosti se pohranjuju u hash tablicu i koriste za obogaćivanje konačnog izlaza.

Kad smo već kod toga, izlaz se zapisuje u CSV datoteku unutar radnog direktorija, koja sadrži sljedeće stupce:

• Ime – naziv mape.
• FolderType – vrsta mape.
• Identitet – mapa “path”. Imajte na umu da će poštanski sandučić biti označen identifikatorom koji ste unijeli kao unos, stoga možete očekivati ​​da ćete ovdje vidjeti GUID-ove, ako ste ih unijeli.
• FolderId – ono StoreId vrijednost mape.
• eDiscoveryId – vrijednost koju možete koristiti za ciljanu zbirku eDiscovery.
• EntryId – MAPI id
• RestId – ID koji koristi Graph API
• OWAId – ID koji koristi OWA

Osim toga, generira se osnovna HTML datoteka s istim podacima, pakiranim u tablicu koja se može sortirati. Dva su mala dodatka dodana HTML-u: gumb koji otvara alat Graph explorer s upitom za dobivanje dotične mape i još jedan za navigaciju do mape izravno u OWA. Imajte na umu da će posljednji raditi samo za korisničke mape pošte, bez kalendara, bez mapa s kontaktima, bez onih sistemskih. I to samo ako ste koristili UPN/Primarnu SMTP adresu kao identifikator poštanskog sandučića.

The Otvori u OWA gumb neće ispravno funkcionirati ako ste dali ExternalDirectoryObjectId vrijednost kao ulaz. Ako namjeravate koristiti spomenuti gumb, uvijek proslijedite UPN/primarnu SMTP adresu. I, kao dodatni bonus, poveznica će također raditi za sve poštanske sandučiće za koje su vam dodijeljene potpune dozvole za pristup, ako ste odabrali mapu dostupnu korisniku. Za gumb Otvori u grafikonu, scenariji “delegiranja” podržani su samo ako imate Mail.ReadBasic.Shared dopuštenja dodijeljena.

I time možemo zatvoriti trenutni članak. Reci mi što misliš o scenariju. Vidite li potrebu za uključivanjem drugih identifikatora? Što je s podrškom za dopuštenja aplikacija? Još nešto?