Brzi pregled novih dodataka Exchange Admin API-ja

Microsoft nam već godinama govori da planira obustaviti EWS API, ali je vrlo spor u rješavanju nedostataka koje bi takvo obustavljanje ostavilo s Graph API-jem. S približavanjem roka za listopad 2026. konačno vidimo napore da se premoste navedene praznine, od kojih je jedna upravo dostigla prekretnicu javnog pregleda. Upoznajte “Admin API”, naziv koji može dovesti u zabludu koliko god to uopće mogao biti… ali o tome malo više.

Kao što je jasno objašnjeno u službeni post na blogunovi skup krajnjih točaka dizajniran je samo za rješavanje određenih nedostataka povezanih s EWS-om. Uključuje sljedeće:

• OrganizationConfig — Čitajte konfiguraciju koja se odnosi na MailTips za cijelog stanara.
• Prihvaćena domena — Popis prihvaćenih domena i osnovnih postavki domene za zakupca.
• poštanski sandučić — Čitajte svojstva poštanskog sandučića i upravljajte njima Poslati u ime delegati (pregled/ažuriranje).
• MailboxFolderPermission — Popis, dodjela, izmjena i uklanjanje dopuštenja na razini mape (Inbox, Calendar, podmape).
• DistributionGroupMember — Dohvaćanje članstva za distribucijske grupe.
• DynamicDistributionGroupMember — Dohvaćanje članstva za dinamičke distribucijske grupe.

Od gore navedenog, samo dvije krajnje točke “poštanskog sandučića” imaju podršku za operacije nečitanja, naime za upravljanje Pošalji u ime dopuštenja kao i dozvole mape poštanskog sandučića. Dakle, nazvati ovo “admin API-jem” prilično je nategnuto, čak i za Microsoftov marketinški tim. Zapravo, odgovarajuće EWS metode također su omogućile krajnjim korisnicima da upravljaju svojim delegatima, tako da čak možemo tvrditi da je primarni cilj bila podrška (klijenta) operacijama samoupravljanja.

Sama provedba također izaziva određene nedoumice. Čini se da je Microsoft nastojao pružiti iskustvo vrlo slično onom InvokeCommand metoda, koja se danas koristi za proxy sve Exchange Online PowerShell cmdlete, kao što mi prethodno pokriveno. Dakle, svaka od gornjih krajnjih točaka prihvaća samo POST zahtjev s korisnim sadržajem formatiranim u JSON-u koji navodi cmdlet i njegove parametre. Međutim, ovaj pristup postavlja pitanje zašto nam je potrebno šest odvojenih krajnjih točaka?

Zatim, imamo konvenciju o imenovanju. Krajnje točke nalaze se ispod https://outlook.office365.com/adminapi/v2.0/budući da je iz nekog razloga bila potrebna zasebna krajnja točka. Nazivajući to /v2.0 vjerojatno će donijeti zabunu jer nema naznaka bilo kakve kompatibilnosti s prethodnim verzijama s bilo čim što se trenutno nalazi pod /v1.0 (da ne spominjemo najnoviju verziju ExO PowerShell modula koji se još uvijek koristi /beta).

Slično, imenovane su dozvole potrebne za pristup novim krajnjim točkama Exchange.ManageV2 (za scenarije dopuštenja delegata) i Exchange.ManageAsAppV2 (za dopuštenja aplikacije jedan). Nadimak V2 opet ne podrazumijeva nikakvu kompatibilnost s postojećim opsegom bez “V2” (morao sam :D), a vjerojatno će također biti izvor zabune. Da biste završili s dopuštenjima, poput bilo koje druge krajnje točke povezane s Exchangeom koju imamo na raspolaganju, morate nadopuniti navedene opsege odgovarajućim dodjeljivanjem uloga na strani ExO. Možete upotrijebiti jednu od ugrađenih uloga, grupa uloga ili Entra uloga koje im se preslikavaju ili možete ići granularno i prema potrebi dodijeliti ograničeni pristup. Budući da nove krajnje točke učinkovito pozivaju postojeće cmdlete, nove uloge nisu uvedene na ExO strani da ih podrže.

Posljednji dio koji trebamo pokriti prije nego isprobamo neke primjere je savjet za usmjeravanje, tzv X-AnchorMailbox zaglavlje. Obavezno ga uključite u svoje zahtjeve, inače biste mogli uočiti neko neželjeno ponašanje. Za sve pojedinosti o njemu, potrebnim dopuštenjima i sintaksi krajnjih točaka, možete se obratiti na službena dokumentacijaneću to ponavljati ovdje.

Bez daljnjeg odlaganja, evo nekoliko primjera korištenja novih krajnjih točaka. Počnimo s dva “poštanska sandučića”, jer su to jedine krajnje točke koje dopuštaju izvođenje stvarnih promjena. Što je još važnije, mogu ih iskoristiti i krajnji korisnici, pod uvjetom da pristanu na Exchange.ManageV2 djelokrug im je nadohvat ruke. To je omogućeno zahvaljujući zadanoj politici dodjele uloga u sustavu Exchange Online, koja dopušta neke samouslužne operacije za krajnje korisnike, zauzvrat pokretane odgovarajućim (ograničenim verzijama ugrađenih) cmdleta.

Primjer ispod koristi MSAL metode za dobivanje tokena pristupa u kontekstu delegata za danog korisnika. Opseg je samo zadani za izvor Exchange Online. Zatim postavljamo zaglavlje za provjeru autentičnosti, koje također uključuje vrijednost za savjet za usmjeravanje. Na kraju, pripremamo teret, koji je u našem slučaju za Get-MailboxFolderPermission cmdlet.

#App details
$app2 = [Microsoft.Identity.Client.PublicClientApplicationBuilder]::Create("xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx").WithRedirectUri("http://localhost").Build()

#Use the default scope for the ExO Admin API resource
$Scopes = New-Object System.Collections.Generic.List[string]
$Scope = "https://outlook.office365.com/.default"
$Scopes.Add($Scope)

#Get the token
$token2 = $app2.AcquireTokenInteractive($Scopes).ExecuteAsync().Result

# Auth header
$authHeader2 = @
'Content-Type'='application/json'
'Authorization'="Bearer $($token2.AccessToken)"
'X-AnchorMailbox' = "UPN:user@domain.com"


# Cmdlet payload
$body = @
    CmdletInput = @
        CmdletName="Get-MailboxFolderPermission"
        Parameters=@Identity="user:\Calendar"
    
 | ConvertTo-Json -Depth 5

# Sample request
$uri = 'https://outlook.office365.com/adminapi/v2.0/tenant.onmicrosoft.com/MailboxFolderPermission'
$res = Invoke-WebRequest -Method POST -Uri $uri -Headers $authHeader2 -Body $body
($res.Content | ConvertFrom-Json).Value

# Sample output
Identity                : user:\Calendar
FolderName              : Calendar
User                    : Default
AccessRights@odata.type : #Collection(String)
AccessRights            : LimitedDetails
SharingPermissionFlags  : 
IsValid                 : True

Identity                : user:\Calendar
FolderName              : Calendar
User                    : AnotherUser
AccessRights@odata.type : #Collection(String)
AccessRights            : Reviewer
SharingPermissionFlags  : 
IsValid                 : True

Identity                : user:\Calendar
FolderName              : Calendar
User                    : secgrp
AccessRights@odata.type : #Collection(String)
AccessRights            : Editor
SharingPermissionFlags  : Delegate, CanViewPrivateItems
IsValid                 : True

Možda ste primijetili da smo navedeni poštanski sandučić prema Ime (ili Alias) u gornjem zahtjevu, a ne svojom SMTP adresom. Zapravo, bilo koji važeći identifikator prepoznat od strane PowerShell cmdlet-a bit će sasvim u redu, što nam daje malo fleksibilnosti. Za označavanje mape svakako koristite lokalizirani naziv, npr. “Kalender” za njemački i tako dalje. Rješavanje pogrešaka je pomalo nered, kao što biste i očekivali od cmdleta koji se proksiju preko više krajnjih točaka. Na istoj napomeni, svi primjeri u službenoj dokumentaciji koriste “\\” za izbjegavanje znaka “\”, što nije neophodno za naš gornji primjer temeljen na PowerShell-u.

Kao što je već spomenuto, krajnji korisnici također mogu upravljati vlastitim postavkama delegiranja, to jest dozvolama na razini mape, plus popisom Pošalji u ime, oboje zahvaljujući ugrađenom MyBaseOptions uloga. U sljedećem primjeru ažuriramo dopuštenja za mapu Kalendar. Kao što je navedeno u dokumentacijaza ovaj scenarij možete koristiti puni skup “standardnih” parametara za Set-MailboxFolderPermission cmdlet, uključujući -SharingPermissionFlags jedan za kontrolu pristupa privatnim stavkama i -SendNotificationToUser jedan za pokretanje obavijesti putem e-pošte. A možete čak i ažurirati razinu zadanih dopuštenja:

# Cmdlet payload
$body = @
    CmdletInput = @
        CmdletName="Set-MailboxFolderPermission"
        Parameters=@Identity="user@domain.com:\Calendar";User="Default";AccessRights=@("LimitedDetails")
    
 | ConvertTo-Json -Depth 5

# Sample request
$uri = 'https://outlook.office365.com/adminapi/v2.0/tenant.onmicrosoft.com/MailboxFolderPermission'
$res = Invoke-WebRequest -Method POST -Uri $uri -Headers $authHeader2 -Body $body

Imajte na umu da bilo koji od ne Dobiti- cmdleti vraćaju prazan izlaz nakon uspješnog izvođenja.

Kao drugi primjer, možemo upravljati Pošalji u ime popis za korisnika. To se radi putem poštanski sandučić krajnja točka i (smanjena verzija) Set-Poštanski sandučić cmdlet. Krajnji korisnici trebaju pristup MyMailboxDelegation ulogu za ovu operaciju, dok administrator mora imati Primatelji pošte ili dodijeljena ekvivalentna uloga. Možemo čak koristiti notaciju hash-tablice za dodavanje/uklanjanje pojedinačnih unosa, bez prepisivanja popisa:

# Cmdlet payload
$body = @
    CmdletInput = @
        CmdletName="Set-Mailbox"
        Parameters=@
            Identity="user@domain.com"
            GrantSendOnBehalfTo=@
                remove=@("user@tenant.onmicrosoft.com")
                '@odata.type' = "#Exchange.GenericHashTable"
            
        
    
 | ConvertTo-Json -Depth 5

# Sample request
$uri = 'https://outlook.office365.com/adminapi/v2.0/tenant.onmicrosoft.com/Mailbox'
$res = Invoke-WebRequest -Method POST -Uri $uri -Headers $authHeader2 -Body $body

Kao i prije, uspješno izvršenje označeno je statusnim kodom 200 i praznim izlazom.

Možemo istražiti primjere za preostale krajnje točke, ali iskreno, svi su prilično dosadni i dovoljno detaljno obrađeni u dokumentaciji. Umjesto toga, postavimo veliko pitanje: kako se sve to može usporediti s onim što imamo u EWS API-ju? Pa radi, što je najvažnije. Što se tiče upotrebljivosti, stvari su sigurno bile lakše s EWS API-jem, gdje je jedan poziv bio dovoljan da vam se daju svi relevantni detalji o delegiranju, na primjer. Uz implementaciju “admin API-ja”, morat ćete uputiti zaseban poziv svakoj “standardnoj” mapi kako biste pokrili istu razinu detalja. Osim toga, nemamo analogiju za jedno od svojstava obuhvaćenih EWS-om. GetDelegates() metoda, naime MeetingRequestsDeliveryScope.

Također postoji očit nesrazmjer kada je riječ o pristupu krajnjeg korisnika. Dok se odabrana implementacija i dalje oslanja na skup ugrađenih cmdlet-a, kao što je predstavljeno politikom dodjele uloga dodijeljenih korisniku, oni su sada zatvoreni iza jedne dodatne prepreke, Exchange.ManageV2 djelokrug. Bez njega pristupni token neće biti poštovan od pozadine i svaki zahtjev prema novim krajnjim točkama jednostavno će odbiti pristup. Iako za spomenuti opseg nije potreban pristanak administratora, malo je vjerojatno da će ostati dostupan krajnjim korisnicima, s obzirom na trenutnu prijetnju.

Na kraju dana, lijepo je vidjeti kako Microsoft konačno rješava neke od dugotrajnih nedostataka s EWS API-jem. Iako se konvencije imenovanja i cjelokupna implementacija čine pomalo traljavima, na kraju krajeva, važno je da sve funkcionira i da može pomoći u uklanjanju nekih od navedenih nedostataka. Nastavimo sad čekati Graph API podršku za Online arhivu…