PowerShell'den Microsoft Graph API'sine Nasıl Bağlanılır?

giriiş

Microsoft Graph API, çeşitli Microsoft 365 hizmetlerine erişimi birleştirerek geliştiricilerin Azure Active Directory, SharePoint, OneDrive, Outlook ve daha fazlası dahil olmak üzere birden fazla platformdaki verilerle etkileşim kuran uygulamalar oluşturmasına olanak tanıyan bir RESTful web API'sidir. Microsoft Graph PowerShell, Windows, macOS ve Linux dahil tüm platformlarda çalışır. Modern kimlik doğrulamayı destekler. Yaygın olarak kullanılan bir komut dosyası dili ve otomasyon aracı olan PowerShell, Graph API'ye bağlanmak ve onunla etkileşimde bulunmak için kullanılabilir ve bu da onu BT uzmanları için önemli bir beceri haline getirir. Bu başlangıç kılavuzunda Graph API'ye kapsamlı bir genel bakış sunacağız, ona bağlanmak için önkoşulları, kurulumu ve yapılandırmayı, kimlik doğrulamayı ele alacağız ve PowerShell kullanarak Graph API'ye bağlanmak için örnekler sunarak adım adım bir kılavuz sunacağız. ve yol boyunca açıklamalar.

Microsoft.Graph PowerShell Modülünü Yükleme

Başlamak için Microsoft Graph PowerShell modülünü yüklemeniz gerekir. Bu modül, Graph API ile etkileşim kurmanıza olanak tanıyan bir dizi cmdlet sağlar. Yükseltilmiş bir PowerShell oturumunda aşağıdaki komutu çalıştırın:

Bu PowerShell komutunu kullanarak Microsoft Graph PowerShell modülünün önceden kurulu olup olmadığını kontrol edin:


Get-InstalledModule | Where-Object {$_.Name -match "Microsoft.Graph"}

Microsoft Graph PowerShell modülünü yükleyin:


Install-Module -Name "Microsoft.Graph"

Geçerli kullanıcı kapsamına yönelik Microsoft graph PowerShell SDK'sını yüklemek için:


Install-Module Microsoft.Graph -Scope CurrentUser

Bu, Microsoft Graph'ı ve alt modülleri (bugün itibariyle 38) yükler. Kurulumun tamamlanmasını bekleyin.

Microsoft Graph PowerShell Modülünü Güncelleyin

Mevcut modülü güncellemek için aşağıdakileri kullanın:


Update-Module Microsoft.Graph

Microsoft Graph PowerShell Modülünü Kaldırma

Microsoft Graph'ın bir ana modülü ve birden fazla alt modülü vardır. Graph modülünü kaldırmak için önce ana modülü kaldırmamız gerekir:


Uninstall-Module Microsoft.Graph

Daha sonra Microsoft Graph'ın tüm alt modüllerini kaldırın. Diğer modüller ona bağlı olduğundan, Kimlik Doğrulama modülünün en son kaldırılması gerekir.


#Uninstall all Sub-modules of Graph
Get-InstalledModule Microsoft.Graph.* | ForEach-Object { if($_.Name -ne "Microsoft.Graph.Authentication") {
    Uninstall-Module $_.Name } 
}

#Uninstall the dependant module
Uninstall-Module Microsoft.Graph.Authentication

Grafik API'sini Çağırmak için PowerShell nasıl kullanılır?

Microsoft.Graph modülü yüklendiğinde çeşitli görevleri gerçekleştirmek için Graph API'yi kullanmaya başlayabilirsiniz. Kullanıcıların oturum açabileceği ve izin verebileceği yetkilendirilmiş erişimi ve katılımsız senaryolar için yalnızca uygulama erişimini destekler. Gerekli kapsamlarla oturum açmak için Connect-MgGraph komutunu kullanın. Bağlandıktan sonra mevcut herhangi bir Graph API yöntemini çağırabilirsiniz.

Yöntem 1: PowerShell'den Temsilci Erişimi ile Grafik API'sine bağlanma

Kullanıcı olarak oturum açmak, SDK'nın sizin adınıza hareket etmesi için gerekli kapsamlara izin vermek ve Microsoft Graph'ı çağırmak için temsilci erişimi kullanacaksınız. PowerShell kullanarak Kullanıcı Bilgilerini almanın bir örneği:


#Connect to Microsoft Graph
Connect-MgGraph -Scopes "User.Read.All"

#Get All users
$users = Get-MgUser
$users | Select-Object DisplayName, UserPrincipalName, Mail

Bu, kimlik doğrulamayı isteyecek ve gerekli kapsamlara izin vermek için bir yönetici hesabıyla oturum açmanız gerekecek.

Bağlandıktan sonra komut, Microsoft Graph'a Hoş Geldiniz! mesajıyla başarıyı belirtir. Get-MgUser komutu da Microsoft 365 kuruluşunuzdaki kullanıcıların listesinin çıktısını verir.

Graph API'nin Beta sürümüne bağlanmak istiyorsanız Select-MgProfile -Name "beta" cmdlet'ini kullanın. Kullanıcının son oturum açma tarihi ve zaman damgalarını almanın başka bir örneği:


#Connect to Microsoft Graph
Connect-MgGraph -Scopes "AuditLog.Read.All", "User.Read.All"

#Set the Graph Profile
Select-MgProfile -Name "beta"

#Properties to Retrieve
$Properties = @(
    'Id','DisplayName','UserPrincipalName','UserType', 'AccountEnabled', 'SignInActivity'    
)

#Get All users along with the properties
$AllUsers = Get-MgUser -All -Property $Properties

$SigninLogs = @()
ForEach ($User in $AllUsers)
{
    $SigninLogs += [PSCustomObject][ordered]@{
            LoginName       = $User.UserPrincipalName
            DisplayName     = $User.DisplayName
            UserType        = $User.UserType
            AccountEnabled  = $User.AccountEnabled
            LastSignIn      = $User.SignInActivity.LastSignInDateTime
    }
}

$SigninLogs

#Disconnect MS Graph
Disconnect-MgGraph

Benzer şekilde, Microsoft Graph API ile bir SharePoint Online sitesine bağlanmak için bu PowerShell'i kullanın:


#Parameters
$SiteID = "0defaa16-1fc5-4a55-bbec-a06d10de2a42"

#Connect to Microsoft Graph
Connect-MgGraph -Scopes "Sites.FullControl.All"

#Get a SharePoint Site collection
$Site = Get-MGSite -SiteId $SiteId

#Get All document libraries from the site
Get-MgSiteDrive -SiteId $SiteId

Microsoft Graph API'sini PowerShell ile kullanma örnekleri

Size Microsoft Graph API ve PowerShell ile nelerin mümkün olduğu hakkında bir fikir vermek. Toplu işlemleri de gerçekleştirebilirsiniz. İşte birkaç örnek:

Bağlamı elde etmek için şunu kullanın: Get-MgContext
Office 365'teki tüm kullanıcıların listesi alınıyor: Get-MgUser
Yeni bir SharePoint sitesi oluşturma: New-MgSite
Belirli bir kullanıcı için tüm OneDrive dosyalarının listesini alma: Get-MgDriveItem -DriveId -DriveItemId

Gördüğünüz gibi Microsoft Graph API ve PowerShell ile olanaklar sonsuzdur.

Grafik Komutları için Gerekli izin kapsamını bulun

Oturum açan kullanıcının veya Microsoft Graph'e bağlanmak için kullandığımız istemci kimliğinin belirli bir kapsama erişim izninin olması gerekir. Örneğin, Update-MgUser komutunu kullanarak bir kullanıcı profilini güncellemek istiyorsanız bunu “User.ReadWrite.All” kapsamıyla yapabilirsiniz. Gerekli kapsamı bulmak için Find-MgGraphCommand cmdlet'ini kullanın. Örneğin.,


Find-MgGraphCommand -command Update-MgUser | Select -First 1 -ExpandProperty Permissions

Microsoft Graph PowerShell modülündeki tüm mevcut cmdlet'leri almak için aşağıdakileri kullanabilirsiniz:


Get-command -Module Microsoft.Graph*

Microsoft Graph 1.25 sürümünde 9275 cmdlet bulunmaktadır!

Yöntem 2: PowerShell'den Uygulama Kimliğini kullanarak Grafik API'sine bağlanma

Başlamadan önce yerine getirmeniz gereken birkaç ön koşul var:

Azure AD'ye bir uygulama kaydetmeniz gerekir.
Graph API'ye erişim için uygulamaya izin vermeniz gerekir.
Uygulama Kimliğine bir sertifika veya istemci sırrı ekleyin. Sertifika kendinden imzalı olabilir veya bir yetkili tarafından imzalanabilir.

Azure AD'de Uygulama Kaydetme

PowerShell ile Grafik API'sine bağlanmadan önce gerekli izinleri ve kimlik bilgilerini almak için Azure AD'ye bir uygulama kaydetmeniz gerekir.

Azure AD'ye bir uygulamayı kaydetmek için şu adımları izleyin:

Azure AD Portalında (https://aad.portal.azure.com/) oturum açın.
Soldaki menüden “Azure Active Directory”ye tıklayın >> “Uygulama kayıtları”na tıklayın >> “Yeni kayıt”a tıklayın.
Uygulamanız için bir ad girin ve desteklenen hesap türü olarak "Yalnızca bu kuruluş dizinindeki hesaplar"ı seçin.
“Kayıt Ol”a tıklayın.

Uygulamayı kaydettikten sonra uygulamanın kontrol paneline yönlendirileceksiniz. Daha sonra ihtiyacımız olacağından "Uygulama (istemci) kimliğini" ve "Dizin (kiracı) kimliğini" not edin.

Uygulamaya İzin Verme

Graph API'ye erişmek için uygulamanızın uygun izinlere sahip olması gerekir. Uygulamaya izin vermek için şu adımları izleyin:

Oluşturduğunuz Uygulamanın soldaki menüsünden "API izinleri"ne tıklayın >> "İzin ekle"ye tıklayın.
API olarak “Microsoft Graph”ı seçin.
Gerekli izinleri arayın ve seçin (örneğin, tüm SharePoint Online sitelerinde tam kontrol elde etmek için "Sites.FullControl.All").
“İzin ekle”ye tıklayın.
"

Microsoft Graph'e bağlanırken belirtebileceğiniz tüm mevcut izinlerin tam bir dökümü için Microsoft'un izinler referans sayfasına göz atın: https://learn.microsoft.com/en-us/graph/permissions-reference

AppID'ye Sertifika ve/veya İstemci Sırrı Ekleme

Uygulamaya güvenli bir şekilde bağlanmak için Uygulamaya bir istemci sırrı (Şifre) veya bir sertifika (veya her ikisini de!) eklemeniz gerekir. Uygulamaya sertifika eklemek için ya kendinden imzalı bir sertifikaya ya da bir yetkilinin standart SSL sertifikasına ihtiyacımız var.

Uygulamaya Sertifika Ekle

"Belgeler" klasörünüzde kendinden imzalı bir sertifika oluşturmak için bu PowerShell betiğini kullanın. Bu, sertifikaya dayalı kimlik doğrulama için kullanılacaktır.


#Parameters
$CertificateName = "Graph API Cert"
$CertificatePassword = "Password1"
 
#Get the "Documents" folder
$DocumentsFolder = [Environment]::GetFolderPath("MyDocuments")
 
#Generate a Self-signed Certificate
$Certificate = New-SelfSignedCertificate -Subject $CertificateName -CertStoreLocation "Cert:\CurrentUser\My" -KeyExportPolicy Exportable -KeySpec Signature -KeyLength 2048 -KeyAlgorithm RSA -HashAlgorithm SHA256
 
#Export the Certificate to "Documents" Folder in your computer
Export-Certificate -Cert $Certificate -FilePath $DocumentsFolder\$CertificateName.cer
 
#Export the PFX File
Export-PfxCertificate -Cert $Certificate -FilePath "$DocumentsFolder\$CertificateName.pfx" -Password (ConvertTo-SecureString -String $CertificatePassword -Force -AsPlainText)

Bu sertifikanın, betiği çalıştıracağınız makinedeki "Güvenilir mağazaya" yüklenmesi gerekir.

Sertifikayı Uygulamaya Yükleyin

Sertifika hazır olduğunda uygulamanıza sertifika eklemek için şu adımları izleyin:

Azure uygulamanıza gidin >> “Sertifikalar ve Sırlar”a tıklayın >> “Sertifikalar” sekmesine tıklayın.
“Sertifikayı yükle”ye tıklayın.
Oluşturulan CER dosyasına göz atın ve “Ekle” düğmesine tıklayın.
“Parmak İzini” not edin. Bu, uygulamada kimlik doğrulaması yapmak için kullanılan sertifikayla ilişkili güvenli anahtarınızdır.

Uygulamaya Müşteri Sırrını Ekle

Benzer şekilde, uygulamaya bir istemci sırrı eklemek için aşağıdakileri yapın:

“Sertifikalar ve sırlar”a tıklayın >> “Müşteri Sırları” sekmesine ve ardından “Yeni müşteri sırrı”na tıklayın.
“Açıklama” ve “Sona Erme” geçerliliğini ayarlayın. Bitirdiğinizde Ekle'yi tıklayın.
Graph API'ye bağlanmak için kullanacağımız istemci sırrını not edin.

Sertifikayı kullanarak PowerShell'den Uygulama Kimliğiyle Grafik API'sine bağlanın

Artık bir uygulamayı kaydettik, izinler verdik ve ona istemci sırrını ve sertifikasını ekledik. PowerShell'den Graph API'ye bağlanmaya hazırız. Sertifika parmak izini kullanarak Microsoft Graph API'ye nasıl bağlanacağınız aşağıda açıklanmıştır:


#Parameters for Tenant ID and Client ID
$TenantID = "c1c2b173-4240-4775-a49a-6351b30cd2f6"
$ClientID = "3c1540f7-9565-4aae-b398-f47ac91cfc06" #App ID
$CertThumbPrint = "63FDD807AE01C1EB34CE5647D164E3C153C0FA7"

#Connect to Microsoft Graph using App
Connect-MgGraph -ClientID $ClientID -TenantId $TenantID -CertificateThumbprint $CertThumbPrint

İstemci Sırrı'nı kullanarak Graph API'ye bağlanın

İstemci sırrını kullanmak istiyorsanız İşte PowerShell betiği tam size göre!


#App Registration details
$TenantID = "c1c2b173-4240-4775-a49a-6351b30cd2f6"
$ClientID = "3c1540f7-9565-4aae-b398-f47ac91cfc06"
$ClientSecret = "9Ad2Q~DA-yLotNvvaplkchnnf__6D5zdFJi1mb4l"

$Body =  @{
    Grant_Type    = "client_credentials"
    Scope         = "https://graph.microsoft.com/.default"
    Client_Id     = $ClientID
    Client_Secret = $ClientSecret
}

$Connection = Invoke-RestMethod `
    -Uri https://login.microsoftonline.com/$TenantID/oauth2/v2.0/token `
    -Method POST `
    -Body $body

#Get the Access Token 
$Token = $Connection.access_token

#Connect to Microsoft Graph 
Connect-MgGraph -AccessToken $Token

Microsoft Graph cmdlet'leri Rest API çağrılarının sarmalayıcılarıdır. Temel REST API yöntemleriyle etkileşim kurmak için Invoke-Webrequests yöntemini de çağırabilirsiniz.


#App Registration details
$TenantID = "c1c2b173-4240-4775-a49a-6351b30cd2f6"
$ClientID = "3c1540f7-9565-4aae-b398-f47ac91cfc06"
$ClientSecret = "9dd8Q~DA-yLotavvabkchnnf__6c5VdFJi0mb1l"
$Domain = "Crescent"

$Body =  @{
    Grant_Type    = "client_credentials"
    Scope         = "https://graph.microsoft.com/.default"
    Client_Id     = $ClientID
    Client_Secret = $ClientSecret
}

$Connection = Invoke-RestMethod `
    -Uri https://login.microsoftonline.com/$TenantID/oauth2/v2.0/token `
    -Method POST `
    -Body $body

#Get the Access Token 
$AuthHeader = @{
'Authorization'="Bearer $($Connection.access_token)"
}

#Get all sites
$URI = "https://graph.microsoft.com/v1.0/sites"
$WebRequest = Invoke-WebRequest -Headers $AuthHeader -Uri $URI
$Result = ($WebRequest.Content | ConvertFrom-Json).Value

#Get all site collections of the domain
$Result | Where {$_.siteCollection.Hostname -eq "$Domain.sharepoint.com"} | select name,webUrl,id

Grafik Gezgini

Görev için doğru API yöntemini bulmak yeni başlayanlar için zorlayıcı olabilir. Başlangıç noktası olarak Graph Explore veya Rest API Reference'ı kullanabilirsiniz.

Yaygın hatalar ve sorun giderme ipuçları

Azure AD Graph API'sini ve Microsoft Graph API'sini PowerShell ile kullanmak genel olarak basit olsa da karşılaşabileceğiniz bazı yaygın hatalar vardır. Yaygın hatalardan biri "Uzak sunucu bir hata döndürdü: (401) Yetkisiz." Ayrıca “İşlemi tamamlamak için yeterli ayrıcalık yok” mesajıyla da karşılaşabilirsiniz. Bu genellikle kimlik bilgilerinizin yanlış olduğu veya Graph API'ye erişim için uygun izinlere sahip olmadığınız anlamına gelir. Doğru olduklarından emin olmak için kimlik bilgilerinizi ve izinlerinizi bir kez daha kontrol edin.

Diğer bir yaygın hata ise "'Cmdlet adı' terimi bir cmdlet'in adı olarak tanınmıyor." Bu genellikle uygun PowerShell modülünün kurulmadığı veya yüklenmediği anlamına gelir. Kullanmaya çalıştığınız cmdlet'e uygun modülü kurup yüklediğinizden emin olun.

Çözüm

Bu başlangıç kılavuzunda, ortamınızı ayarlamak ve kimlik doğrulamaktan API çağrıları yapmaya kadar PowerShell kullanarak Microsoft Graph API'sine bağlanmanın temellerini ele aldık. Ayrıca Azure AD'de bir uygulamanın nasıl kaydedileceğini, bu uygulamaya nasıl izin verileceğini ve uygulamaya istemci gizli dizilerinin nasıl ekleneceğini de gördük. Bu kılavuzda edinilen bilgilerle görevleri otomatikleştirmeye ve Microsoft 365 ortamınızı daha verimli bir şekilde yönetmeye başlayabilirsiniz.

Sonraki adımlar, Microsoft Graph API PowerShell modülü tarafından sağlanan daha fazla cmdlet'i keşfetmek veya ortak görevleri otomatikleştirmek için kendi PowerShell komut dosyalarınızı oluşturmaya başlamak olabilir. Olasılıklar sonsuzdur, o yüzden bugün başlayın!

Sıkça Sorulan Sorular:

Microsoft Graph'ın amacı nedir?

Microsoft Graph API, geliştiricilerin Microsoft Bulut'ta bulunan verilere, zekalara ve hizmetlere erişmesine ve bunlarla etkileşimde bulunmasına olanak tanıyan birleşik bir RESTful API uç noktasıdır. Office 365, Azure Active Directory, Enterprise Mobility ve gibi birden fazla Microsoft hizmetinde kullanıcılar, gruplar, e-postalar, takvimler, görevler, dosyalar, cihazlar ve daha fazlası gibi çok çeşitli kaynaklara erişmek için tek bir giriş noktası görevi görür. Güvenlik, Windows ve daha fazlası.

Microsoft Graph'ı PowerShell'e nasıl yüklerim?

Microsoft Graph PowerShell SDK'sını yüklemek için PowerShell oturumunuzda aşağıdaki komutu çalıştırın:

Install-Module -Name Microsoft.Graph

Bu komut, Microsoft.Graph modülünü yükler ve PowerShell'de Microsoft Graph API ile etkileşime geçmek için cmdlet'ler sağlar.

Microsoft Graph PowerShell için hangi izinler gereklidir?

Erişmek istediğiniz belirli API uç noktalarına ve kaynaklara bağlıdır! Genel olarak Microsoft Graph'ta iki tür izin vardır:
1. Yetki verilen izinler: Oturum açan kullanıcılar adına hareket etmek için.
2. Uygulama izinleri: Bu izinler, arka plan hizmetleri gibi kullanıcı etkileşimi olmadan çalışan uygulamalara verilir.
Azure portalında bir uygulamayı kaydetmeniz, uygulamaya izinler atamanız, yönetici izni vermeniz ve ardından kayıtlı uygulamanın izinlerini kullanmanız gerekir. PowerShell betiğinizdeki kimlik bilgileri.

Neden Microsoft Graph API PowerShell SDK'sına geçmeliyiz?

Çünkü AzureAD, MSOnline ve AzureADPreviewPowerShell modüllerinin kullanımdan kaldırılması planlanıyor. Hazırlanmak için yöneticilerin yeni Microsoft Graph PowerShell SDK modülünü kullanmaya başlaması gerekir.