Microsoft GraphAPI är ett kraftfullt verktyg att ha. Vi kan inte bara använda det för att skapa verktyg för att automatisera vår arbetsbelastning—vi kan också få tillgång till nya funktioner som tidigare.
I denna artikel kommer vi att lära sig att utforska och använda Microsoft GraphAPI för Azure AD.
Förutsättningar
Du måste uppfylla ett antal förutsättningar innan vi kan börja. Innan du börjar med steg som beskrivs i denna artikel, se till att du uppfylla eller ha följande:
- En App Registrering i AzureAD med följande GraphAPI behörigheter:
- Katalog.Läs.Alla
- Katalog.ReadWrite.Alla
- Program-Id (kund-id) och klient-hemligt för ovan App Registrering
- Din Hyresgäst namn
- En dator med PowerShell version 5.1 eller högre
Med det ur vägen, låt oss lära oss hur man kan utforska GraphAPI.
Läs Dokumentationen
Microsoft GraphAPI är väl dokumenterat, och det bästa stället att börja då att ta reda på hur man använder en ny funktion är att börja i referens-dokumentation av Microsoft Graph API.
Detta anger hur man använder en viss funktion och vilka behörigheter som du behöver för att använda det. För närvarande finns det två versioner av GraphAPI: v1.0 och beta-API. De kan se identiska vid första, men beta-API innehåller en hel del nya funktioner som ännu inte släppts. Också vara medveten om att funktionerna i betaversionen API är föremål för ändring när som helst.
Behörigheter
Behörigheter är en viktig del av att utforska och använda Diagram API behörigheter—lyckligtvis har alla behörigheter som du behöver för att utföra en viss åtgärd som anges i referens-dokumentation av funktionen.
Följande skärmdump visar de tillstånd som behövs för att använda getDirectoryObject funktion. Och eftersom du kommer att få tillgång till det som en ansökan, behöver du en Katalog.ReadAll tillstånd.
Nu när du har grunderna, låt oss komma igång genom att begära en åtkomsttoken—en tillfällig hemlighet att vi kommer att använda för att komma åt Microsoft Graph API.
Begär en åtkomsttoken
Access token är en hemlighet som du kan begära med vår kund-id och klient-hemlighet. Det är detta tecken på att du ska på begäran mot GraphAPI.
För att begära en åtkomsttoken, du måste tillåta dig själv mot hyresgästens oauth2 slutpunkt genom att posta din Ansökan Id och Tillämpning Hemlighet.
Redigera följande skript, som ersätter AppId, AppSecret, och Hyresgäst namn, och köra det i PowerShell för att begära en åtkomsttoken:
Add-Type-AssemblyName System.Webb
$AppId = ‘CHANGEME’
$AppSecret = ‘CHANGEME’
$Tillämpningsområde = “https://graph.microsoft.com/.default”
$TenantName = “CHANGEME.onmicrosoft.com”
$Url = “https://login.microsoftonline.com/$TenantName/oauth2/v2.0/token”
$Kroppen = @{
client_id = $AppId
client_secret = $AppSecret
omfattningen = $Omfattning
grant_type = ‘client_credentials’
}
$PostSplat = @{
ContentType = “application/x-www-form-urlencoded’
Method = “POST”
Kroppen = $Kropp
Uri = $Url
}
# Begäran token!
$Request = Åberopa-RestMethod @PostSplat
Om du nu ta en titt på $Request variabel, kan du se att den innehåller våra åtkomsttoken, samt typ och förfallotid.
PS51> $Request
token_type expires_in ext_expires_in access_token
———- ———- ————– ————
Bärare 3599 3599 eyJ……………
Den expires_in är i sekunder, vilket betyder att du måste begära ett nytt token inom en timme eller kommer det att sluta fungera.
Låt oss spara access token i en variabel för framtida bruk och sedan börja göra förfrågningar mot GraphApi:
PS51> $Åtkomsttoken = $Begäran.access_token
Din Första GraphAPI Begäran
Det är dags för din första diagrammet begäran! Den enklaste begär att börja med är de förfrågningar som använder HTTP FÅ. GET-kommandon är endast för att hämta information, så att du inte behöver oroa dig för att jävlas upp något.
Vi kommer att börja med en enkel begäran lista domäner kopplat till våra hyresgäster. Och kom ihåg—läsa dokumentationen. All information om hur du använder GraphAPI funktioner finns i dokumentationen.
Du kanske har märkt i dokumentationen för Lista Domäner kommando som du kan kalla det genom att använda HTTP-GET—standard metod när du använder Åberopa-RestMethod:
Med denna information, du kan börja att bygga begäran. För att vi behöver skapa ett Tillstånd Rubrik som innehåller “Bärare <token>” och använda det för att göra en GET-request till URL: en på bilden ovan:
$Headers = @{
Godkännande = “Bärare $Åtkomsttoken”
}
$Uri = “https://graph.microsoft.com/v1.0/domains”
$Result = Åberopa-RestMethod -Rubriker $Headers -Uri $Uri
Du har nu en lista över domäner i $Resultat variabel, men försöker att produktionen värdet av $Resultat variabel kommer att resultera i detta:
PS51> $Result
@odata.sammanhang värde
————– —–
<https://graph.microsoft.com/v1.0/$metadata#domäner> {@{authenticationType=Förvaltas. availabilityStatus=; id=contoso.com; isAdminManaged=True; isD..
Resultatet av den frågan är vanligtvis det värde som egendom av resultatet. Du kan få hela resultatet genom att bara mata på att egendom i stället:
PS51> $Result.värde
authenticationType : Förvaltas
availabilityStatus :
id : contoso.com
isAdminManaged : Sanna
isDefault : Sanna
isInitial : Falskt
isRoot : Sanna
isVerified : Sanna
supportedServices : {E-post, Intune}
status :
passwordValidityPeriodInDays : 2147483647
passwordNotificationWindowInDays : 14
authenticationType : Förvaltas
availabilityStatus :
id : contoso.onmicrosoft.com
isAdminManaged : Sanna
isDefault : Falskt
isInitial : Sanna
isRoot : Sanna
isVerified : Sanna
supportedServices : {E-post, OfficeCommunicationsOnline}
status :
passwordValidityPeriodInDays : 2147483647
passwordNotificationWindowInDays : 14
Nu när du lärt dig grunderna för att få information med GraphAPI, är det dags att lära sig att använda filter.
Använda Filter
Det är bra att kunna hämta alla data som finns tillgängliga. Och medan det kan fungera, det är väldigt ineffektivt. En god praxis är att bara begära de data som du behöver. För att uppnå detta i GraphAPI, vi kan använda filter.
En bra kandidat för att försöka reda filter är genom att hämta användare. De har en hel del gemensamma attribut namn till on-prem Active Directory, och du har oftast minst ett par av dem.
URI: n för att hämta alla användare är *https://graph.microsoft.com/v1.0/users*, men vi vill filtrera denna begäran. Kan du göra det genom att lägga $filter=<filter> parameter till URI.
Ett filter (oftast) består av egendom operatör och ett värde som denna:
fastigheten operator ‘värde’
Om du nu vill hämta alla användare med givenName “John”, följande URI bör användas:
https://graph.microsoft.com/v1.0/users?$filter=givenName eq ‘John’
Så, om du vill använda PowerShell för att göra denna begäran, koden bör se ut ungefär så här:
$Uri = “https://graph.microsoft.com/v1.0/users?`$filter=givenName eq ‘John'”
$Result = Åberopa-RestMethod -Rubriker $Headers -Uri $Uri
Märker backtick innan $filter—det är att fly dollar tecken—annars PowerShell har tolkat det som en variabel.
Ta en titt på det värde som egendom, och du kommer att se alla användare med en givenName av “John” i Azure Active Directory:
PS51> $Result.värde
businessPhones : {5554012}
displayName : John Doe
givenName : John
jobTitle :
e-post : jdoe@contoso.com
mobiltelefon :
officeLocation :
preferredLanguage : sv
efternamn : Doe
userPrincipalName : jdoe@contoso.com
id : 7fd22087-ec0a-47a1-91fb-0a7d8e6f0c
‘EQ” är inte den enda operatör, du har inte (ne), match, innehåller mindre/större än (lt/gt), och en hel del mer. Medan omfattningen av denna artikel, mer information om operatörer som är tillgängliga i dokumentationen. Även mer omfattande dokumentation om de olika filter egenskaper är tillgängliga i fastigheten dokumentation om varje typ av objekt.
Skapa en Användare
Nu när du fått grunderna, låt oss utföra en skrivoperation och skapa en användare. För det, du behöver veta hur man konstruerar data och var man ska lägga upp det. Du kan se ett exempel på hur man utför det genom att gå till Microsoft Graph API-dokumentation och tittar på “Skapa Användare”:
Du kan se att du behöver skicka data som en POST-begäran och att den typ av innehåll ska vara application/json. Du kan också se en JSON representation av data—målet här är att skapa ett PowerShell-objekt som skapar JSON när ConvertTo-Json används på det.
Låt oss gå på det:
$Kroppen = [PSCustomObject]@{
accountEnabled = $True
displayName = “Jane Doe”
mailNickname = “persvensson”
userPrincipalName = “jane.doe@automativity.com”
passwordProfile = @{
forceChangePasswordNextSignIn = $True
lösenord = “Hunter221!”
}
}
Kör $Kropp | ConvertTo-Json kommer att resultera i en liknande JSON är en man som de visas i dokumentationen. Det som är kvar nu är att konvertera den till JSON och SKICKA den till GraphAPI URI med rätt innehåll-typ:
$Kroppen = [PSCustomObject]@{
accountEnabled = $True
displayName = “Jane Doe”
mailNickname = “persvensson”
userPrincipalName = “jane.doe@contoso.com”
passwordProfile = @{
forceChangePasswordNextSignIn = $True
lösenord = “Hunter221!”
}
}
$BodyJson = $Kropp | ConvertTo-Json
$Uri = “https://graph.microsoft.com/v1.0/users”
Invoke-RestMethod -Uri $Uri -Rubriker $Headers -Metoden EFTER ContentType application/json -Kropp $BodyJson
Om du nu gå till vår Azure Active Directory-Konsolen och ta en titt, du kommer att hitta den nyskapade användaren:
Du har nu skapat din första användaren med hjälp GraphAPI!
Slutsats
Microsoft GraphAPI är ett kraftfullt verktyg och kommer att göra det möjligt för dig att automatisera din miljö ännu mer. Och inte bara när det kommer till Azure Active Directory—men också för de flesta av SaaS-tjänster som Microsoft erbjuder.
Också med tanke på den “serverlösa” rörelse med hjälp av Azure Funktioner eller AWS Lambda i en händelse, det är möjligt att skapa en minimalistisk och event-drivna funktioner för att automatisera så mycket som möjligt i din miljö. Alla utan de behöver till att omfatta stora bibliotek i dina funktioner.