De Microsoft GraphAPI is een krachtige tool om te hebben. Niet alleen kunnen we gebruiken voor het maken van gereedschap voor het automatiseren van onze werkbelasting—we kunnen ook toegang tot nieuwe functies eerder.
In dit artikel zullen we leren hoe om te verkennen en gebruik maken van de Microsoft GraphAPI voor Azure AD.
Voorwaarden
U moet voldoen aan een aantal vereisten voordat we kunnen beginnen. Voordat u begint met de stappen die worden beschreven in dit artikel, moet u voldoen aan de volgende voorwaarden:
- Een App Registratie in AzureAD met de volgende GraphAPI machtigingen:
- Directory.Lees.Alle
- Directory.ReadWrite.Alle
- Toepassings-Id (client-id) en client-geheim voor bovengenoemde App Registratie
- Uw naam Huurder
- Een computer met PowerShell versie 5.1 of hoger
Met dat uit de weg—laten we leren hoe om te verkennen de GraphAPI.
Lees de Documentatie
De Microsoft GraphAPI is goed gedocumenteerd, en de beste plek om te beginnen bij het vinden van het gebruik van een nieuwe functie is om te beginnen in de documentatie van de Microsoft Graph-API.
Dit geeft aan hoe het gebruik van een specifieke functie en wat de machtigingen die u nodig hebt om het te gebruiken. Er zijn momenteel twee versies van de GraphAPI: v1.0 en de beta-API. Ze kunnen er identiek aan het eerste, maar de beta-API bevat veel nieuwe functies die nog niet zijn uitgebracht. Ook van bewust dat de functies in de beta-API zijn onderworpen aan veranderingen op elk moment.
Machtigingen
Machtigingen zijn een belangrijk onderdeel van de verkenning en het gebruik van de API van de Grafiek machtigingen—gelukkig alle machtigingen die u nodig hebt voor het uitvoeren van een bepaalde actie zijn opgegeven in de documentatie van die functie.
De volgende screenshot toont de toestemming nodig voor het gebruik van de getDirectoryObject functie. En omdat je als een toepassing, moet u de Map.ReadAll toestemming.
Nu dat je de basis, laat ons beginnen met het aanvragen van een token—een tijdelijke geheim dat we zullen gebruiken om toegang te krijgen tot de Microsoft Graph-API.
Het aanvragen van een Access Token
De access token is een geheim dat kunt u aanvragen met onze klant-id en client-geheim. Het is deze token moet u bij de aanvragen in de richting van de GraphAPI.
Voor het aanvragen van een access token, moet u machtigen jezelf tegen de huurder oauth2 eindpunt door het plaatsen van uw Toepassings-Id en de Toepassing Geheim.
Bewerk het volgende script, het vervangen van AppId, AppSecret, en de Huurder naam, en voer het uit in PowerShell voor het aanvragen van een access token:
Add-Type -AssemblyName Systeem.Web
$AppId = ‘CHANGEME’
$AppSecret = ‘CHANGEME’
$Scope = “https://graph.microsoft.com/.default”
$TenantName = “CHANGEME.onmicrosoft.com”
$Url = “https://login.microsoftonline.com/$TenantName/oauth2/v2.0/token”
$Body = @{
client_id = $AppId
client_secret = $AppSecret
scope = $Scope
grant_type = ‘client_credentials’
}
$PostSplat = @{
ContentType = “application/x-www-form-urlencoded’
Method = ‘POST’
Body = $Body
Uri = $Url
}
# Aanvraag van het token!
$Request = Beroepen-RestMethod @PostSplat
Als je nu een kijkje nemen op de $Request-variabele is, kunt u zien dat het bevat onze toegangstoken, evenals het type en de vervaldatum.
PS51> $Aanvraag
token_type expires_in ext_expires_in access_token
———- ———- ————– ————
Drager 3599 3599 eyJ……………
De expires_in is in seconden, wat betekent dat u voor de aanvraag van een nieuwe kaart binnen een uur of zal stoppen met werken.
Laat ons te redden van de access token in een variabele voor de toekomst en dan beginnen met het maken van de verzoeken naar de GraphApi:
PS51> $AccessToken = $Request.access_token
Uw Eerste GraphAPI Aanvraag
Het is tijd voor je eerste grafiek aanvraag! De eenvoudigste verzoeken om te beginnen met de verzoeken die gebruik maakt van HTTP KRIJGEN. De GET-commando ‘ s zijn alleen voor het ophalen van informatie, dus je hoeft je geen zorgen te maken over het knoeien iets omhoog.
We zullen beginnen met een eenvoudig verzoek een opsomming van de domeinen verbonden met onze huurder. En vergeet niet—de documentatie te lezen. Alle informatie over het gebruik van de GraphAPI functies is in de documentatie.
Je misschien hebt opgemerkt in de documentatie voor de Lijst met Domeinen opdracht die u kunt oproepen via HTTP GET—de standaard methode bij het gebruik van Beroepen-RestMethod:
Met deze informatie kunt u beginnen met de bouw van de aanvraag. Voor dat, we moeten een Autorisatie-Header bevat “aan Toonder <token>” en maak daar een GET-verzoek naar de URL in de afbeelding hierboven:
$Headers = @{
Toestemming = “Drager $AccessToken”
}
$Uri = “https://graph.microsoft.com/v1.0/domains”
$Resultaat = Beroepen-RestMethod -Headers $Headers -Uri $Uri
Je hebt nu de lijst met domeinen in het $Result variabele, maar proberen om de uitgang van de waarde van de $Result variabele zal leiden tot dit:
PS51> $Result
@odata.context de waarde
————– —–
<https://graph.microsoft.com/v1.0/$metagegevens#domeinen> {@{authenticationType=Geslaagd; availabilityStatus=; id=contoso.com; isAdminManaged=True; isD..
Het resultaat van de query wordt meestal in de value property van het resultaat. U kunt de gehele resultaat slechts door het uitvoeren van die goederen in de plaats:
PS51> $Result.waarde
authenticationType : Geslaagd
availabilityStatus :
id : contoso.com
isAdminManaged : True
isDefault : True
isInitial : False
isRoot : True
isVerified : True
supportedServices : {e-Mail, Intune}
staat :
passwordValidityPeriodInDays : 2147483647
passwordNotificationWindowInDays : 14
authenticationType : Geslaagd
availabilityStatus :
id : contoso.onmicrosoft.com
isAdminManaged : True
isDefault : False
isInitial : True
isRoot : True
isVerified : True
supportedServices : {e-Mail, OfficeCommunicationsOnline}
staat :
passwordValidityPeriodInDays : 2147483647
passwordNotificationWindowInDays : 14
Nu dat je hebt geleerd de basis van het verkrijgen van informatie met de GraphAPI, het is tijd om te leren hoe om filters te gebruiken.
Het Gebruik Van Filters
Het is geweldig om te kunnen ophalen van alle gegevens die beschikbaar zijn. En hoewel het kan werken, het is erg ineffectief. Een goede praktijk is, vragen dat de gegevens die u nodig hebt. Om dit te bereiken in de GraphAPI, kunnen we gebruik maken van filters.
Een goede kandidaat voor het uitproberen van filters is door het ophalen van gebruikers. Ze hebben veel gemeenschappelijke kenmerken van namen op-prem Active Directory, en meestal moet u ten minste een paar van hen.
De URI voor het ophalen van alle gebruikers is *https://graph.microsoft.com/v1.0/users*,, maar we willen filter dit verzoek. U kunt dat doen door het toevoegen van de $filter=<filter> parameter toe aan de URI.
Een filter (meestal) bestaat uit goederen van de operator en de waarde zoals deze:
eigendom operator ‘waarde’
Als je nu wilt ophalen voor alle gebruikers met de givenName “John,” de URI moet worden gebruikt:
https://graph.microsoft.com/v1.0/users?$filter=givenName eq ‘John’
Dus, als u wilt gebruik PowerShell om dit verzoek te maken, de code moet er als volgt uitzien:
$Uri = “https://graph.microsoft.com/v1.0/users?`$filter=givenName eq ‘John'”
$Resultaat = Beroepen-RestMethod -Headers $Headers -Uri $Uri
Let op de accent-achterover, voordat $filter—dat is om te ontsnappen aan de dollar-teken—anders PowerShell zou hebben geïnterpreteerd als een variabele.
Neem een kijkje op de waarde van goederen, en u ziet alle gebruikers met een givenName van “Johannes” in Azure Active Directory:
PS51> $Result.waarde
businessPhones : {5554012}
naam : John Doe
givenName : John
invoicestransamount :
mail : jdoe@contoso.com
mobilofoon :
officeLocation :
preferredLanguage : nl
achternaam : Jansen
userPrincipalName : jdoe@contoso.com
id : 7fd22087-ec0a-47a1-91fb-0a7d8e6f0c
‘EQ’ is niet de enige operator die u niet (ne), match, bevat minder/meer dan (lt/gt), en een heleboel meer. Terwijl buiten de scope van dit artikel, meer informatie over operators is beschikbaar in de documentatie. Ook meer uitgebreide documentatie over de verschillende filter-eigenschappen is beschikbaar in het pand documentatie over elk object type.
Een Gebruiker aanmaken
Nu heb je de basis, laten we het uitvoeren van een bewerking en het maken van een gebruiker. Voor dat je nodig hebt om te weten hoe te maken van de gegevens en waar te PLAATSEN. U kunt een voorbeeld zien op het uitvoeren van dat door te gaan naar de Microsoft Graph-API-documentatie en op zoek op “Gebruiker Aanmaken”:
U kunt zien dat u nodig hebt om de gegevens te verzenden als een POST-aanvraag, en dat de inhoud moet zijn van application/json. U kunt ook een JSON weergave van de gegevens—het doel is om hier een PowerShell-object dat maakt dat JSON wanneer ConvertTo-Json is verwerkt.
Laten we gaan naar het:
$Body = [PSCustomObject]@{
accountEnabled = $True
displayName = “Jane Doe”
mailNickname = “janedoe
userPrincipalName = “jane.doe@automativity.com”
passwordProfile = @{
forceChangePasswordNextSignIn = $True
wachtwoord = “Hunter221!”
}
}
Uitvoeren van $Lichaam | ConvertTo-Json zal resulteren in een soortgelijke JSON als weergegeven in de documentatie. Wat nu overblijft is om het te converteren naar JSON en POST-it op de GraphAPI URI met de juiste content-type:
$Body = [PSCustomObject]@{
accountEnabled = $True
displayName = “Jane Doe”
mailNickname = “janedoe
userPrincipalName = “jane.doe@contoso.com”
passwordProfile = @{
forceChangePasswordNextSignIn = $True
wachtwoord = “Hunter221!”
}
}
$BodyJson = $Body | ConvertTo-Json
$Uri = “https://graph.microsoft.com/v1.0/users”
Beroepen-RestMethod -Uri $Uri -Headers $Headers -Methode POST -ContentType application/json -Body $BodyJson
Als je nu naar onze Azure Active Directory-Console en neem een kijkje, je vindt de nieuw aangemaakte gebruiker:
U hebt nu uw eerste gebruiker met behulp van GraphAPI!
Conclusie
De Microsoft GraphAPI is een krachtige tool en zal u toelaten om het automatiseren van uw omgeving nog verder. En niet alleen als het gaat om Azure Active Directory—maar ook voor de meerderheid van de SaaS-diensten die Microsoft aanbiedt.
Ook gezien de “serverloze” beweging met Azure Functies of AWS Lambda in een gebeurtenis, het is mogelijk om te maken, minimalistisch en event-driven functies om zo veel mogelijk automatiseren in uw omgeving. Dit alles zonder de noodzaak om te voorzien in de grote bibliotheken in uw functies.