Skip to main content

Powershell ile Microsoft Graph API Kullanımı – Bölüm 1

· 5 min read
Hasan Gural

Bildiğiniz gibi artık API kullanımının meşhur olduğu bir dünyada yaşıyoruz. Hemen hemen her incelediğim projede bir yerinde bir ucunda API ile iletişim haline geçip iş yapmaya çalışıyoruz. Bu yazı içerisinde biraz eğlenceli ve tuhaf ama keyifli bir konuyu aktarmak istiyorum. Microsoft Graph API bizlere Azure Active Directory, Office 365 Bileşenleri, Intune, Planner etc, içerisindeki istediğimiz kullanıcının özniteliklerine ulaşmayı ve bunları alarak raporlar oluşturmamıza olanak sağlanıyor. Bunu sadece kullanıcı bazında sınırlamamak lazım, Intune, Mobile Device Report gibi genişletebiliriz. Her türlü raporları bu API sorgular yaparak alma şansınız var. Office 365 tarafı ile ilgilinen arkadaşlar için, şimdilerde Powershell Module geçişleri yapıyorlar, ya da daha önceki yazdıkları kod bloklarını dönüştürmeleri lazım. Bunun başında, MSOnline adındaki module artık, AzureAD adındaki olan ve arka tarafta Microsoft Graph API v2.0 ( Beta ) olarak kullanılan sürüme dâhil edilerek geliştirilmiştir. Bu yüzden iki farklı Powershell Modulunu kullandığınız zaman farklı öznitelikler(propertyler) görebilirsiniz.

Powershell ile Microsoft Graph API kullanırken yukarıda bahsettiğim sadece belirli bir objeleri değerlerini getirmek ve raporlamak için değil daha farklı yöntemler içinde kullanabilirsiniz. Microsoft Graph API en basit haliyle REST API olarak Azure Active Directory erişim sağlayabilirsiniz. Bu sayede Azure Active Directory içerisindeki Applicationlar ( App Registrations) verdiğiniz izinlere göre, Azure Active Directory içerisindeki verileri okur, nesneler oluşturur, onların değerlini okur ve güncelleme ve silme işlemlerini gerçekleştirmek tamamiyle Azure AD Graph API'sini kullanabilir. Örneğin, Microsoft Graph API'na sorgu yaparak bir kullanıcı nesnesi için aşağıdaki değerleri döndürebilirsiniz; Bunları bir süreç olarak düşenebilirsiniz.

  • User oluşturma, lisans ve manager atama, mobile device provision etmek,
  • Assign to Office 365 Groups or Assign to Azure Active Directory Groups etc.

Özetle bu API sayesinde bir süreç haline getirip hayatımızı kolaylaştırabilirsiniz. Microsoft Graph API ile erişebileceğiniz servislerin hepsini özetlemek gerekir ise,

  • Azure Active Directory
  • Office 365 services
    • SharePoint, OneDrive, Outlook/Exchange, Microsoft Teams, OneNote, Planner, Excel
  • Enterprise Mobility and Security services
    • Identity Manager, Intune, Advanced Threat Analytics, Advanced Threat Protection
  • Windows 10 services
    • Activities, Devices
  • Education

Daha farklı bir senaryo ise, siz Software as a Service veren bir firma olarak bu API müşterleriniz için kullanarak onların süreçleri için değişik uygulamalar geliştirme şansınız var. Daha önce farklı isimler ile duymuş olabilirsiniz, yada yukarıdaki tüm servislere farklı şekilde API sorgulamaları yapmış olabilirsiniz, artık Microsoft Graph API' olarak geliştirmeye devam edecek. Yavaştan nasıl bağlanacağımızı Powershell ile REST API sorgular yaparak neler yapabildiğimizi görelim, öncelikle bir adet Service Principal ihtiyacımız var. Bunu oluşturmak için, Azure Active Directory içerisinde, App Registration sekmesine giderek oluşturabilirsiniz, Aslında bu yaratacağımız Application ile Microosft Graph API RestFull istekler yaparak istediğimiz oluşturma, silme, güncelleme gibi talepleri gönderiyor olacağız.

Yukarıdaki resimde adımları anlatmak için bir ekran görüntüsü paylaşıyorum, yeni bir adet Application Registration oluşturmak çok zor bir süreç değil. Sadece oluşturduktan sonra gereken yetkileri vermeniz gerekiyor. Dilerseniz şu makaleyi takip ederek yapabilirsiniz. Link : Microsoft Graph API Started. Benim hali hazırda oluşturduğum kendi Azure Active Directory için bir adet Application Registration bilgilerim var ve bu Application için Azure Active Directory üzerinde Graph API ve diğer servisler için gereken yetkilendirmeleri yaptım. Şimdi Powershell tarafında ilk başta nasıl bir değişkenlere ihtiyacımız var hızlıca tanıyalım.

$tennantid        = 'tenantId'         ## Tenant bilginiz
$ApplicationID    = 'AppClientdId'     ## Application Id ( App Registration )
$ApplicationKey   = 'AppClientSecret'  ## Application Secret
$TokenEndpoint    = {https://login.windows.net/{0}/oauth2/token} -f $tennantid 
$ARMResource      = "https://graph.microsoft.com"

Yukarıdaki değişkenleri oluşturduktan sonra karşınıza gerekli değerleri girmeniz gerekmektedir. Çünkü bu değerlerin hepsini Powershell içerisinden Rest API istek yaparken kullanıyor olacağız. Aşağıdaki örnek içerisinde nasıl bir değerler geldiğini anlayabilirsiniz.

Aslında bu tarz istekleri yapmadan önce PostMan veya HttpMaster kullanarak test etme şansınız var. Ayrıca Microsoft bu kısımda devreye giriyor ve bize Microsoft Graph API Explorer sunuyor. Bu sayede yapacağınız sorguları daha öncesinden anlamanıza yardımcı olur ve nasıl parametreler kullanamanız gerektiğine karar verebilirsiniz. Aşağıdaki sayfaya giderek yukaıdaki belirttiğimiz tüm servisler için sorgulamalar yapma şansınız var. Eğer Microsoft Idniz ile oturum açarsanız ve izin verdikten sonra çok daha farklı deneyimler yaşabilirsiniz. Burası işin tamamen kendinizi bu API kullanımında ne tür bilgiler ve aksiyonlar alabileceğiniz için sizlere yol göstermesi için hizmet vermektedir.

Powershell tarafında kaldığımız yerden devam edelim, Application Id ve Application Secret bilgilerini aldıktan sonra artık API içerisine authorization/authentication olmak için gereken değerlerimizi gönderelim. Bu işlemleri hepsi tamamen token alıp Microsoft Graph API erişmeye devam etmek olacak.

$tennantid        = 'tenantId'         ## Tenant bilginiz
$ApplicationID    = 'AppClientdId'     ## Application Id ( App Registration )
$ApplicationKey   = 'AppClientSecret'  ## Application Secret
$TokenEndpoint    = {https://login.windows.net/{0}/oauth2/token} -f $tennantid 
$ARMResource      = "https://graph.microsoft.com"

#request Body for Microsoft API
$Body = @{
        'resource'= $ARMResource
        'client\_id' = $ApplicationID
        'grant\_type' = 'client\_credentials'
        'client\_secret' = $ApplicationKey
}

Yukarıdaki kod bloğundan sonra aşağıdakileri yazıp artık REST API üzerinende gereken token alma işlemizi tamamlayalım.

$tennantid        = 'tenantId'         ## Tenant bilginiz
$ApplicationID    = 'AppClientdId'     ## Application Id ( App Registration )
$ApplicationKey   = 'AppClientSecret'  ## Application Secret
$TokenEndpoint    = {https://login.windows.net/{0}/oauth2/token} -f $tennantid 
$ARMResource      = "https://graph.microsoft.com"

#request Body for Microsoft API
$Body = @{
        'resource'= $ARMResource
        'client\_id' = $ApplicationID
        'grant\_type' = 'client\_credentials'
        'client\_secret' = $ApplicationKey
}

$params = @{
    ContentType = 'application/x-www-form-urlencoded'
    Headers = @{'accept'='application/json'}
    Body = $Body
    Method = 'Post'
    URI = $TokenEndpoint
}

$token = Invoke-RestMethod @params

Yukarıdaki Powershell satırları sayesinde Microsoft Graph API istek yaptığınız zaman token almış olacaksınız. Bu token yine gördüğünüz gibi '$token' değişkenine atanmış olacak. Şimdi ise artık bu token alıp başına authorization sürecini bitirmek için, Header ekleyip Rest API tarafına göndereceğiz. Bu sayede artık sorgulamak istediğimiz herşeye sahip olacağız.

$headers = @{}
$headers.Add("authorization","Bearer $($token.access\_token)")

Neredeyse API tarafında istek yapabilir konumdayız. Serimizin bir sonraki bölümünde birkaç sorgular ve istekler ile Microsoft Graph API kullanımı örnekler ile genişletmeye çalışalım.