Exchange Admin API nasıl kullanılır ?

Microsoft, Exchange Admin API’sini 17 Kasım’da kullanıma sundu. API, geliştiricilerin Exchange Web Services’ta (EWS) yapabilecekleri ile Grafik API’leri kullanılarak yapılabilecekler arasındaki belirgin işlevsellik boşluklarını kapatmak için bir yama görevi görüyor. Microsoft, Ekim 2026’da EWS’yi Exchange Online’dan kaldıracağı için, geliştiricilerin EWS kodlarını desteklenen bir platforma taşımaları adına çok fazla zamanları yok. Exchange Admin API, bu çabaya yardımcı olmak için geliştirildi.

Amaç, kod tabanlarını EWS’den taşıyan e-posta istemcileri gibi uygulamaların, EWS’de sıklıkla kullanılan işlevleri yeniden oluşturmak için Exchange PowerShell cmdlet’lerini çalıştırmak üzere bir sarmalayıcı kullanarak kodlarını taşıyabilmesini sağlamaktır. Bu cmdlet’ler, uygulamaların işlemlerinde kullanabileceği verileri döndürür.

Exchange Admin API teknik olarak oldukça sınırlıdır ve tasarımı gereği mümkün olduğunu düşündüğünüz şeyler çoğu durumda gerçekleştirilemez. Microsoft, genel amaçlı Exchange Online yönetimi için yeni bir REST tabanlı API oluşturmayı amaçlamamıştır. Bunun yerine, Exchange Admin API, geliştiricilerin bir Grafik API’nin kullanılamadığı sınırlı durumlarda uygulamaları EWS’den taşımalarına olanak sağlayacak kadar destek sunar.

Çoğu durumda, Exchange Online için yönetim otomasyonu oluşturmak için doğru seçim, Exchange Online modülündeki cmdlet’lerin ve Microsoft Graph PowerShell SDK’sının bir karışımını kullanan PowerShell’dir. PowerShell betiği yazan herhangi birinin Exchange Admin API’sini kullanmayı düşünmesinin çok basit bir nedeni olduğunu sanmıyorum: betik, API tarafından desteklenen cmdlet’leri yerel olarak çalıştırabilir. Daha da iyisi, cmdlet’leri yerel olarak çalıştırmak, cmdlet’leri Exchange Admin API aracılığıyla çalıştırmaktan daha işlevsel ve güçlüdür.

Ancak, işlerin nasıl yürüdüğünü anlamak adına ve PowerShell aracılığıyla Microsoft Graph ile daha önce çalıştıysanız, yapılması gerekenlerin çoğu size tanıdık gelecektir. Exchange Admin API aracılığıyla Exchange ile nasıl etkileşim kuracağımıza bir bakalım.

Exchange Admin API ile Etkileşim Kuracak Uygulamaları Seçme

Uygulamalar ve hizmet modülü, Entra ID’de uygulama merkezli yetkilendirme ve kimlik doğrulamanın temelini oluşturur. Exchange Yönetici API’sini kullanan geliştiricilerin kendi uygulamaları olacaktır. PowerShell’deki durumu taklit etmek için ilk adım, kayıtlı bir uygulama oluşturmak (veya mevcut bir uygulamayı yeniden kullanmak)tır. Yeni bir uygulama, Entra yönetim merkezi aracılığıyla veya New-MgApplication cmdlet’ini çalıştırarak oluşturulabilir. Uygulama, API aracılığıyla Exchange Online ile etkileşim kurmak için kimlik görevi görür. Göreceğimiz gibi, uygulamanın hizmet sorumlusuna bir Exchange Online izni ve uygulamanın API aracılığıyla cmdlet’leri çalıştırabilmesi için bir veya daha fazla Exchange Online rolü atanmalıdır.

Hangi uygulamayı kullanacağınızı öğrendikten sonra, uygulamaya Office 365 Exchange Online uygulamasından Exchange.ManageAsAppV2 uygulama iznini kullanma izni verin (Şekil 1). İzni atama süreci, bir uygulamaya Grafik izni kullanma izni atama süreciyle aynıdır. Farklı olan, kaynak kaynak olan Office 365 Exchange Online’dır.

Ayrıca, uygulamaya bir X.509 sertifikası yükleyin (kendi kendine imzalanmış bir sertifika da uygundur). Sertifikayı, Entra Kimliği ile kimlik doğrulaması yapmak ve PowerShell’in Exchange Admin API’sini kullanmasına izin vermek için bir erişim belirteci almak için kullanacağız.

Uygulamaya Exchange Online RBAC Rolleri Atama

Bir sonraki adım, uygulamanın insan yöneticisi gibi çalışabilmesi için doğru Exchange Online yönetici rollerine sahip olduğundan emin olmaktır. Başlamak için, etkileşimli bir Grafik oturumu oluşturmak ve uygulamanın hizmet sorumlusunun ayrıntılarını almak üzere Connect-MgGraph cmdlet’ini çalıştırın:

Connect-MgGraph -scopes Application.ReadWrite.All -NoWelcome
$ExoAdminSP = Get-MgServicePrincipal -Filter "displayname eq 'ExoAdminAPI'"
$ExoAdminSP

DisplayName Id                                   AppId                                SignInAudience ServicePrincipalType
----------- --                                   -----                                -------------- --------------------
ExoAdminAPI 1c0cf40b-2c6c-4030-a0c3-70284bedf5b7 0559c362-c681-4108-86ff-d7c006643a9d AzureADMyOrg   Application

Exchange Online’da Entra ID hizmet sorumluları mevcut değildir. Entra ID ile Exchange Online arasında bir bağlantı oluşturmak için, Exchange Online’a bağlanarak Entra ID hizmet sorumlusu için bir Exchange hizmet sorumlusu oluşturun. Komutlar şunlardır:

Connect-ExchangeOnline -ShowBanner:$False -ErrorAction Stop

New-ServicePrincipal -Appid $ExoAdminSP.AppId -ServiceId $ExoAdminSP.Id -DisplayName 'Exo Admin API App'

DisplayName                              ObjectId                                                             AppId
-----------                              --------                                                             -----
Exo Admin API App                        1c0cf40b-2c6c-4030-a0c3-70284bedf5b7                                 0559c362-c681-4108-86ff-d7c006643a9d

İki hizmet sorumlusunun birbirine bağlanması, RBAC for Applications’da posta kutularına uygulama erişimini kontrol etmek için kullanılan mekanizmayla aynıdır. Gerekli Exchange RBAC rollerini atamak için Exchange hizmet sorumlusunu kullanacağız. Bir sonraki adımı kolaylaştırmak için, yeni Exchange hizmet sorumlusunun ayrıntılarıyla bir değişkeni dolduracağız.

$ExoAdminSPExo = Get-ServicePrincipal -Identity 'Exo Admin API App'

Şimdi Exchange hizmet sorumlusunu kullanarak uygulamayı Yalnızca Görüntüleme Kuruluş Yönetimi ve 
Alıcı Yönetimi rol gruplarına ekleyin. İlk rol grubu, kuruluş ve etki alanı uç noktalarına erişim sağlar. İkinci rol grubu ise diğer dört uç noktayla ilgilenir;

Update-RoleGroupMember -Identity "View-Only Organization Management" -Members @{Add="$ExoAdminSPEXO"}

Confirm
Are you sure you want to perform this action?
Updating the role group Identity:"View-Only Organization Management" with the member list "Add=1c0cf40b-2c6c-4030-a0c3-70284bedf5b7;".
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): y

Update-RoleGroupMember -Identity "Recipient Management" -Members @{Add="$ExoAdminSPEXO"}

Confirm
Are you sure you want to perform this action?
Updating the role group Identity:"Recipient Management" with the member list "Add=1c0cf40b-2c6c-4030-a0c3-70284bedf5b7;".
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): y

Erişim Belirtecinin Güvenliğini Sağlama

Uygulamaya doğru şekilde izin verildikten sonra kimlik doğrulamaya geçiyoruz. Uygulamanın Exchange Online ile nasıl kimlik doğrulanacağına dair ayrıntılar bu dokümanda yer almaktadır. Temel fikir, uygulamanın Exchange Admin API’sini çalıştırma hakkını kanıtlamak için kullanabileceği bir Entra Kimliği erişim belirteci elde etmektir.

PSMSALNet modülü , Entra ID’den erişim belirteci almanın kullanışlı bir yoludur ( modül belgelerini okuduğunuzdan emin olun ). Office 365 Exchange Online hizmet sorumlusunun uygulama tanımlayıcısı da dahil olmak üzere çeşitli parametre değerleri gereklidir. Bunları şu şekilde elde ederiz;

Get-MgServicePrincipal -filter "displayName eq 'Office 365 Exchange Online'" | Format-Table DisplayName, AppId

DisplayName                AppId
-----------                -----
Office 365 Exchange Online 00000002-0000-0ff1-ce00-000000000000

Diğer parametreler kiracı tanımlayıcısı, uygulamaya yüklenen sertifika ve uygulama tanımlayıcısıdır. Bu örnekte, sertifikanın ayrıntılarını almak için sertifikanın parmak izini kullanıyorum. Parametreler bir karma tabloya yerleştirilir ve Get-EntraToken cmdlet’i tarafından bir erişim belirteci elde etmek için kullanılır.

$Thumbprint = '0CF6CE3F3548FD73E7AC8CF20226ED447E125C71'
$AppId =  (Get-MgServicePrincipal -filter "displayName eq 'ExoAdminAPI'").AppId
$TenantId = (Get-MgOrganization).Id
$Certificate = Get-Item ("Cert:\CurrentUser\My\"+$Thumbprint)
$Parameters = @{}
$Parameters.Add("TenantId",$TenantId)
$Parameters.Add("ClientId",$AppId)
$Parameters.Add("CustomResource",'00000002-0000-0ff1-ce00-000000000000')
$Parameters.Add("ClientCertificate", $Certificate)
$Parameters.Add("Resource", "Custom")

$Token = Get-EntraToken -ClientCredentialFlowWithCertificate @Parameters

PSMSALNet modülü , Exchange Online modülüyle bir derleme çakışması yaşıyor . Sorunu önlemek için önce yeni bir PowerShell oturumunda Connect-MgGraph komutunu, ardından Get-EntraToken komutunu çalıştırın . Aşağıdaki gibi bir şey görürseniz, sorunun oluştuğunu anlarsınız:

Get-EntraToken: ‘PSMSALNet’ modülünde ‘Get-EntraToken’ komutu bulundu, ancak aşağıdaki hata nedeniyle modül yüklenemedi: [‘Microsoft.Identity.Client, Version=4.66.1.0, Culture=neutral, PublicKeyToken=0a613f4dd989e8ae’ dosyası veya derlemesi yüklenemedi. Aynı ada sahip derleme zaten yüklenmiş.]

Exchange Online Kuruluş Yapılandırmasına Erişim

Bir erişim belirteciyle Exchange Admin API’sini kullanabiliriz. Bu örnek, kiracı yapılandırmasının ayrıntılarını almak için Get-OrganizationConfig cmdlet’inin nasıl çalıştırılacağını gösterir. API’nin temelleri açıklanmaktadır. İstekler, bilgi almak için hedef uç noktaya gönderilir. Her istek, uygulamanın Exchange’den istediği bilgilerin ayrıntılarını içeren JSON biçimli bir gövde içerir. Exchange’den aldığı bilgilerle istediğini yapmak uygulamanın kendi sorumluluğundadır.

$Headers = @{"Authorization" = "Bearer "+ $Token.AccessToken}
$ContentType = "application/json"
$URI = ("https://outlook.office365.com/adminapi/v2.0/{0}/OrganizationConfig" -f $TenantId)

$Body = @"
{
    "CmdletInput": {
        "CmdletName": "Get-OrganizationConfig"
    }
}
"@

$ExoResult = (Invoke-RestMethod -URI $Uri -Headers $Headers -Method "POST" -Body $Body -ContentType $ContentType).Value
If ($ExoResult) {
   Write-Host (“The tenant identity is {0} and its SharePoint root is {1}” -f $ExoResult.Identity, $ExoResult.SharePointURL)
}

The tenant identity is Office365.onmicrosoft.com and its SharePoint root is https://office365.sharepoint.com/

Posta Kutularını Getirme

Alıcı yönetimi için, Exchange Online’a isteği hangi sunucunun işlemesi gerektiğini bildirmek üzere bir “bağlantı posta kutusu” gereklidir. Posta kutusu uç noktası oldukça sınırlıdır ve Get-Mailbox ve Set-Mailbox cmdlet’leri için yalnızca birkaç işlemi destekler ( Get-ExoMailbox’ın neden kullanılmadığı bilinmemektedir).

$XAnchorMailbox = "[email protected]"
$Headers = @{"Authorization" = "Bearer "+ $Token.AccessToken;"X-AnchorMailbox" = "UPN:$XAnchorMailbox"}
$ContentType = "application/json"
$URI = ("https://outlook.office365.com/adminapi/v2.0/{0}/Mailbox" -f $TenantId)
$Body = @"
{
  "CmdletInput": {
    "CmdletName": "Get-Mailbox",
    "Parameters": {       
      "ResultSize": "Unlimited"             
    }
  }
}
"@
[array]$Mailboxes = (Invoke-RestMethod -URI $Uri -Headers $Headers -Method "POST" -Body $Body -ContentType $ContentType).Value
If ($Mailboxes) {
  Write-Host ("{0} mailboxes fetched…" -f $Mailboxes.count)
}

Bu uç nokta hakkında çalışmadan önce, microsoft tarafındaki belgeleri okuyun. Microsoft’un, özellikle de belgeler birden fazla öğe alırken sayfalama ve özellik seçimi konusunu ele aldığında, filtrelemeyi neden devre dışı bıraktığını anlamak biraz zor.

Örneğin, yukarıdaki kod tüm posta kutularını alır. Sonuç 50 posta kutusu olabileceği gibi 50.000 de olabilir. Sunucu tarafı filtrelemenin kullanılamaması, paylaşılan posta kutuları kümesini bulmak için bir uygulamanın tüm posta kutularını istemesi ve ardından ilgili kümeyi çıkarmak için istemci tarafı filtresi uygulaması gerektiği anlamına gelir. Bu teknik olarak pekte yeterli değildir ve üretimde tamamen işe yaramaz bir test ortamında mükemmel çalıştığı da söylenemez.

Basit Ama Önemli Bir Bölüm

Exchange Admin API tarafından desteklenen diğer uç noktaların nasıl kullanılacağına dair daha fazla ayrıntı arıyorsanız, MVP Vasil Michev’in API’nin nasıl çalıştığına dair ilginç bir makalesi var, faydalı olabilir.

Exchange Yönetici API’si kod geçişlerini tamamlamaya yardımcı olan kullanışlı bir araçtır. EWS’den ayrılmak için kodlarını yükseltmeleri gerekenlerin ihtiyaç duyacağı Microsoft belgeleri Microsoftun sitesinde de mevcuttur. (https://learn.microsoft.com/en-gb/exchange/reference/admin-api-get-started?WT.mc_id=M365-MVP-9501#pagination)

Okuduğunuz için teşekkürler.