Weboldal keresés

Hogyan lehet csatlakozni a Microsoft Graph API-hoz a PowerShellből?

Bevezetés

A Microsoft Graph API egy RESTful webes API, amely egyesíti a különböző Microsoft 365-szolgáltatásokhoz való hozzáférést, lehetővé téve a fejlesztők számára, hogy olyan alkalmazásokat hozzanak létre, amelyek több platformon is interakcióba lépnek az adatokkal, beleértve az Azure Active Directory, SharePoint, OneDrive, Outlook stb. A Microsoft Graph PowerShell minden platformon működik, beleértve a Windowst, a macOS-t és a Linuxot is. Támogatja a modern hitelesítést. A PowerShell, egy széles körben használt szkriptnyelv és automatizálási eszköz használható a Graph API-hoz való csatlakozásra és azzal való interakcióra, így az IT-szakemberek számára elengedhetetlen készség. Ebben a kezdőknek szóló útmutatóban átfogó áttekintést adunk a Graph API-ról, megvitatjuk a hozzá való csatlakozás előfeltételeit, a telepítést és a konfigurációt, a hitelesítést, valamint egy lépésről lépésre bemutatjuk a Graph API-hoz való csatlakozáshoz PowerShell segítségével, példákkal. és magyarázatok az út mentén.

A Microsoft.Graph PowerShell modul telepítése

A kezdéshez telepítenie kell a Microsoft Graph PowerShell modult. Ez a modul parancsmagokat kínál, amelyek lehetővé teszik a Graph API-val való interakciót. Futtassa a következő parancsot egy emelt szintű PowerShell-munkamenetben:

Ellenőrizze, hogy a Microsoft Graph PowerShell modul telepítve van-e már a következő PowerShell-parancs segítségével:


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

Telepítse a Microsoft Graph PowerShell modult:


Install-Module -Name "Microsoft.Graph"

A Microsoft graph PowerShell SDK telepítése az aktuális felhasználói hatókörhöz:


Install-Module Microsoft.Graph -Scope CurrentUser

Ezzel telepíti a Microsoft Graphot és az almodulokat (a mai állapot szerint 38). Várja meg, amíg a telepítés befejeződik.

Frissítse a Microsoft Graph PowerShell modult

A meglévő modul frissítéséhez használja a következőket:


Update-Module Microsoft.Graph

Távolítsa el a Microsoft Graph PowerShell modult

A Microsoft Graph egy fő modullal és több almodullal rendelkezik. A Graph modul eltávolításához először a fő modult kell eltávolítanunk:


Uninstall-Module Microsoft.Graph

Ezután távolítsa el a Microsoft Graph összes almodulját. A hitelesítési modult végül el kell távolítani, mivel a többi modul attól függ.


#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

Hogyan kell használni a PowerShell to Call Graph API-t?

A Microsoft.Graph modul telepítésével elkezdheti használni a Graph API-t különféle feladatok végrehajtására. Támogatja a delegált hozzáférést, ahol a felhasználók bejelentkezhetnek és beleegyezhetnek, valamint csak az alkalmazásokhoz való hozzáférést felügyelet nélküli forgatókönyvek esetén. A Connect-MgGraph paranccsal jelentkezzen be a szükséges hatókörökkel. Csatlakozás után bármelyik elérhető Graph API metódust meghívhatja.

1. módszer: Csatlakozzon a Graph API-hoz a PowerShell delegált hozzáférésével

Felhatalmazott hozzáféréssel jelentkezhet be felhasználóként, beleegyezését adja a szükséges hatókörökbe az SDK számára, hogy eljárhasson az Ön nevében, és felhívja a Microsoft Graphot. Íme egy példa a felhasználói adatok PowerShell használatával történő lekérésére:


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

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

Ez hitelesítést kér, és be kell jelentkeznie egy rendszergazdai fiókkal, hogy hozzájáruljon a szükséges hatókörökhöz.

A csatlakozást követően a parancs egy Welcome to Microsoft Graph! üzenettel jelzi a sikert. A Get-MgUser parancs pedig megjeleníti a Microsoft 365 szervezet felhasználóinak listáját.

Ha csatlakozni szeretne a Graph API béta verziójához, használja a Select-MgProfile -Name "beta" parancsmagot. Íme egy másik példa a felhasználó utolsó bejelentkezési dátumának és időbélyegének lekérésére:


#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

Hasonlóképpen, ha Microsoft Graph API-val szeretne csatlakozni egy SharePoint Online webhelyhez, használja ezt a PowerShellt:


#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

Példák a Microsoft Graph API használatára a PowerShell-lel

Hogy képet kapjon arról, hogy mi lehetséges a Microsoft Graph API-val és a PowerShell-lel. Tömeges műveleteket is végezhet. Íme néhány példa:

  • A kontextus lekéréséhez használja: Get-MgContext
  • Az összes felhasználó listájának lekérése az Office 365-ben: Get-MgUser
  • Új SharePoint-webhely létrehozása: New-MgSite
  • Egy adott felhasználó összes OneDrive-fájljának lekérése: Get-MgDriveItem -DriveId -DriveItemId

Amint láthatja, a Microsoft Graph API és a PowerShell lehetőségei végtelenek.

Keresse meg a Graph Commandshoz szükséges engedélyek hatókörét

A bejelentkezett felhasználónak vagy a Microsoft Graphhoz való csatlakozáshoz használt ügyfél-azonosítónak rendelkeznie kell engedéllyel egy adott hatókör eléréséhez. Például, ha frissíteni szeretne egy felhasználói profilt az Update-MgUser paranccsal, megteheti a „User.ReadWrite.All” hatókörrel. A szükséges hatókör megkereséséhez használja a Find-MgGraphCommand parancsmagot. Például.,


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

A Microsoft Graph PowerShell modulban elérhető összes parancsmag letöltéséhez használja a következőket:


Get-command -Module Microsoft.Graph*

A Microsoft Graph 1.25-ös verziójában 9275 parancsmag érhető el!

2. módszer: Csatlakozás a Graph API-hoz a PowerShell alkalmazásazonosítójával

Mielőtt elkezdené, meg kell felelnie néhány előfeltételnek:

  1. Regisztrálnia kell egy alkalmazást az Azure AD-ben.
  2. Engedélyt kell adnia az alkalmazásnak a Graph API eléréséhez.
  3. Adjon hozzá egy tanúsítványt vagy ügyféltitkot az alkalmazásazonosítóhoz. A tanúsítvány lehet önaláírt vagy hatóságtól származó.

Regisztráljon egy alkalmazást az Azure AD-ben

Mielőtt csatlakozna a Graph API-hoz a PowerShell segítségével, regisztrálnia kell egy alkalmazást az Azure AD-ben, hogy megszerezze a szükséges engedélyeket és hitelesítési adatokat.

Egy alkalmazás Azure AD-ben való regisztrálásához kövesse az alábbi lépéseket:

  1. Jelentkezzen be az Azure AD Portalra (https://aad.portal.azure.com/).

  2. Kattintson az „Azure Active Directory” elemre a bal oldali menüben >> Kattintson az „Alkalmazásregisztrációk” >> Kattintson az „Új regisztráció” elemre.

  3. Adja meg az alkalmazás nevét, és támogatott fióktípusként válassza a „Csak ebben a szervezeti címtárban található fiókok” lehetőséget.

  4. Kattintson a „Regisztráció” gombra.

Az alkalmazás regisztrációja után a rendszer átirányítja az alkalmazás irányítópultjára. Vegye figyelembe az „Alkalmazás (ügyfél) azonosítót” és a „Címtár (bérlő) azonosítót”, mivel később szükségünk lesz rájuk.

Engedélyek megadása az alkalmazáshoz

A Graph API eléréséhez az alkalmazásnak rendelkeznie kell a megfelelő engedélyekkel. Az alkalmazás engedélyeinek megadásához kövesse az alábbi lépéseket:

  1. Kattintson az „API engedélyek” elemre a létrehozott alkalmazás bal oldali menüjében >> Kattintson az „Engedély hozzáadása” elemre.

  2. Válassza ki a „Microsoft Graph”-t API-ként.

  3. Keresse meg és válassza ki a szükséges engedélyeket (pl. „Sites.FullControl.All”, hogy teljes irányítást szerezzen az összes SharePoint Online webhelyen).

  4. Kattintson az „Engedélyek hozzáadása” gombra.

  5. Adja meg hozzájárulását a hozzáadott engedélyekhez az „Adminisztrátori hozzájárulás megadása a

A Microsoft Graphhoz való csatlakozáskor megadható összes rendelkezésre álló engedély teljes lebontásáért tekintse meg a Microsoft engedélyekre vonatkozó referencialapját: https://learn.microsoft.com/en-us/graph/permissions-reference

Adjon hozzá tanúsítványt és/vagy ügyféltitkot az AppID-hez

Az alkalmazáshoz való biztonságos csatlakozáshoz hozzá kell adnia az alkalmazáshoz egy kliens titkot (jelszót) vagy tanúsítványt (vagy mindkettőt!). Tanúsítvány hozzáadásához az alkalmazáshoz szükségünk van egy önaláírt tanúsítványra vagy egy szabványos SSL-tanúsítványra egy hatóságtól.

Tanúsítvány hozzáadása az alkalmazáshoz

Ezzel a PowerShell-szkripttel önaláírt tanúsítványt hozhat létre a „Dokumentumok” mappában. Ez a tanúsítvány alapú hitelesítéshez lesz használva.


#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)

Ezt a tanúsítványt a „Megbízható áruházban” kell telepíteni azon a gépen, amelyen a szkriptet futtatni fogja.

Töltse fel a tanúsítványt az alkalmazásba

Ha elkészült a tanúsítvány, kövesse az alábbi lépéseket, hogy hozzáadjon egy tanúsítványt az alkalmazáshoz:

  1. Nyissa meg az Azure-alkalmazást >> Kattintson a „Tanúsítványok és titkok” lehetőségre >> Kattintson a „Tanúsítványok” fülre.
  2. Kattintson a „Tanúsítvány feltöltése” gombra.

  3. Keresse meg a létrehozott CER fájlt, és kattintson a „Hozzáadás” gombra.

  4. Jegyezze fel a hüvelykujjlenyomatot. Ez a tanúsítványhoz társított biztonsági kulcsa az alkalmazás hitelesítéséhez.

Adja hozzá az ügyféltitkot az alkalmazáshoz

Hasonlóképpen, ha ügyféltitkot szeretne hozzáadni az alkalmazáshoz, tegye a következőket:

  1. Kattintson a „Tanúsítványok és titkok” elemre >> Kattintson az „Ügyféltitkok” fülre, majd az „Új ügyféltitkok” fülre.

  2. Állítsa be a „Leírás” és a „Lejárat” érvényességét. Ha végzett, kattintson a Hozzáadás gombra.

  3. Jegyezze fel az ügyfél titkosságát, amelyet a Graph API-hoz való csatlakozáshoz használunk.

Csatlakozzon a Graph API-hoz a PowerShell alkalmazásazonosítójával a tanúsítvány használatával

Most, hogy regisztráltunk egy alkalmazást és megadtuk az engedélyeket, és hozzáadtuk az ügyféltitkot és a tanúsítványt. Készen állunk a Graph API-hoz való csatlakozásra a PowerShellből. Így csatlakozhat a Microsoft Graph API-hoz a tanúsítvány ujjlenyomatával:


#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

Csatlakozzon a Graph API-hoz a Client Secret használatával

Ha szeretné használni a kliens titkát, itt van a PowerShell szkript az Ön számára!


#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

A Microsoft Graph-parancsmagok a Rest API-hívások burkolói. Meghívhatja az Invoke-Webrequests metódust is, hogy kölcsönhatásba léphessen bármely mögöttes REST API metódussal.


#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

Graph Explorer

A feladathoz megfelelő API-módszer megtalálása kihívást jelenthet a kezdőknek. A Graph Explore vagy a Rest API Reference használható kiindulási pontként.

Gyakori hibák és hibaelhárítási tippek

Bár az Azure AD Graph API és a Microsoft Graph API használata a PowerShell-lel általában egyszerű, előfordulhat néhány gyakori hiba. Az egyik gyakori hiba a következő: „A távoli szerver hibát adott vissza: (401) Nem engedélyezett.” Előfordulhat, hogy „nincs elegendő jogosultság a művelet befejezéséhez”. Ez általában azt jelenti, hogy a hitelesítési adatok helytelenek, vagy nem rendelkezik a megfelelő jogosultságokkal a Graph API eléréséhez. Ellenőrizze még egyszer a hitelesítő adatait és engedélyeit, hogy megbizonyosodjon arról, hogy helyesek.

Egy másik gyakori hiba: „A „parancsmag neve” kifejezést nem ismeri fel a rendszer egy parancsmag neveként. Ez általában azt jelenti, hogy a megfelelő PowerShell-modul nincs telepítve vagy betöltve. Győződjön meg arról, hogy telepítette és betöltötte a megfelelő modult a használni kívánt parancsmaghoz.

Következtetés

Ebben a kezdőknek szóló útmutatóban bemutattuk a Microsoft Graph API-hoz való PowerShell használatával történő csatlakozás alapvető elemeit, a környezet beállításától és a hitelesítéstől az API-hívásokig. Azt is láttuk, hogyan regisztrálhat egy alkalmazást az Azure AD-ben, hogyan adhat engedélyeket, és hogyan adhat hozzá ügyféltitkokat az alkalmazáshoz. Az ebben az útmutatóban megszerzett ismeretekkel megkezdheti a feladatok automatizálását és a Microsoft 365 környezet hatékonyabb kezelését.

A következő lépés a Microsoft Graph API PowerShell-modul által biztosított további parancsmagok felfedezése, vagy saját PowerShell-szkriptek létrehozásának megkezdése a gyakori feladatok automatizálása érdekében. A lehetőségek végtelenek, ezért kezdje el még ma!

Gyakran Ismételt Kérdések:

Mi a Microsoft Graph célja?

A Microsoft Graph API egy egységes RESTful API-végpont, amely lehetővé teszi a fejlesztők számára, hogy hozzáférjenek a Microsoft Cloudban elérhető adatokhoz, intelligenciához és szolgáltatásokhoz, és kapcsolatba lépjenek velük. Egyetlen belépési pontként működik, ahol sokféle erőforrást érhet el, például felhasználókat, csoportokat, e-maileket, naptárakat, feladatokat, fájlokat, eszközöket és egyebeket több Microsoft-szolgáltatáson keresztül, mint például az Office 365, az Azure Active Directory, az Enterprise Mobility és a többi. Biztonság, Windows és egyebek.

Hogyan telepíthetem a Microsoft Graph-ot a PowerShellben?

A Microsoft Graph PowerShell SDK telepítéséhez futtassa a következő parancsot a PowerShell-munkamenetben:

Install-Module -Name Microsoft.Graph

Ez a parancs telepíti a Microsoft.Graph modult, amely parancsmagokat biztosít a Microsoft Graph API-val való interakcióhoz a PowerShellben.

Milyen engedélyek szükségesek a Microsoft Graph PowerShellhez?

Ez az elérni kívánt API-végpontoktól és erőforrásoktól függ! A Microsoft Graphban általában kétféle engedély létezik:
1. Delegált engedélyek: A bejelentkezett felhasználók nevében történő tevékenység.
2. Alkalmazásengedélyek: Ezeket az engedélyeket olyan alkalmazások kapják meg, amelyek felhasználói beavatkozás nélkül futnak, például a háttérszolgáltatások.
Regisztrálnia kell egy alkalmazást az Azure Portalon, engedélyeket kell hozzárendelnie az alkalmazáshoz, meg kell adnia adminisztrátori hozzájárulást, majd használnia kell a regisztrált alkalmazás hitelesítő adatokat a PowerShell-szkriptben.

Miért érdemes áttérnünk a Microsoft Graph API PowerShell SDK-ra?

Mivel az AzureAD, MSOnline és AzureADPreview PowerShell modulok elavulása ütemezett. A felkészüléshez az adminisztrátoroknak meg kell kezdeniük az új Microsoft Graph PowerShell SDK modult.

Kapcsolódó cikkek