Die Microsoft GraphAPI ist ein leistungsfähiges Werkzeug zu haben. Nicht nur können wir es verwenden, um erstellen Werkzeuge zur Automatisierung unserer workloads, wir können auch den Zugriff auf neue Funktionen früher.
In diesem Artikel werden wir lernen, zu erkunden und verwenden Sie das Microsoft GraphAPI für Azure AD.
Voraussetzungen
Sie zu erfüllen, müssen ein paar Voraussetzungen, bevor wir anfangen können. Bevor Sie beginnen mit dem in diesem Artikel beschriebenen Schritte, werden Sie sicher, dass Sie erfüllen oder über die folgenden:
- Eine App-Registrierung in AzureAD mit den folgenden GraphAPI Berechtigungen:
- – Verzeichnis.Lesen.Alle
- – Verzeichnis.ReadWrite.Alle
- Anwendungs-Id (client-id) und das client-Geheimnis für die oben genannten App-Registrierung
- Der Tenant-name
- Ein computer mit PowerShell version 5.1 oder höher
Mit diesem aus dem Weg—lasst uns lernen, wie zu erkunden, die GraphAPI.
Lesen Sie die Dokumentation
Die Microsoft GraphAPI ist gut dokumentiert, und der beste Ort zu beginnen, wenn Sie finden heraus, wie eine neue Funktion ist der start in die Referenz-Dokumentation für das Microsoft Graph-API.
Dieser gibt an, wie eine bestimmte Funktion und welche Berechtigungen Sie benötigen, um es zu benutzen. Derzeit gibt es zwei Versionen der GraphAPI: v1.0 und die beta-API. Sie kann identisch Aussehen auf den ersten, aber die beta-API enthält eine Vielzahl von neuen Funktionen, die sind noch nicht freigegeben. Auch bewusst sein, dass die Funktionen in der beta-API unterliegen jederzeit ändern.
Berechtigungen
Berechtigungen sind ein wichtiger Teil der Erforschung und Verwendung der Graph-API-Berechtigungen—zum Glück sind alle die Berechtigungen, die Sie benötigen, um eine bestimmte Aktion durchzuführen, sind in der Referenz-Dokumentation für die Funktion.
Der folgende screenshot zeigt die Erlaubnis brauchte, um das getDirectoryObject Funktion. Und weil Sie es als eine Anwendung ist, müssen Sie das Verzeichnis.ReadAll Berechtigung.
Jetzt haben Sie die Grundlagen, lassen Sie uns beginnen, indem Sie entweder eine access—token eine temporäre Geheimnis, dass wir verwenden, um den Zugriff auf die Microsoft Graph-API.
Anforderung eines Access Tokens
Der Zugriffstoken ist ein Geheimnis, dass Sie verlangen können, mit unseren client-id und client-secret. Es ist das token, das müssen Sie in den Anforderungen an die GraphAPI.
Auf Anfrage einen access-token, die Sie brauchen, zu autorisieren, sich gegen die Mieter der oauth2-Endpunkt, indem Sie Ihre Anwendungs-Id und der Application Secret.
Bearbeiten Sie das folgende Skript, das austauschen von Anwendungs -, AppSecret und Mieter name, und führen Sie es in der PowerShell auf Anfrage einen access token:
Add-Type -AssemblyName System.Web
$AppId = ‘CHANGEME’
$AppSecret = ‘CHANGEME’
$Scope = “https://graph.microsoft.com/.default”
$TenantName = “CHANGEME.onmicrosoft.com”
$Url = “https://login.microsoftonline.com/$TenantName/oauth2/v2.0/Tokens”
$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
}
# Request token!
$Anfrage = ” Invoke-RestMethod @PostSplat
Nun, wenn man einen Blick auf die $Request-variable, können Sie sehen, dass es enthält unsere access-token, sowie Art und Ablauf der Zeit.
PS51> $Anfrage
token_type expires_in ext_expires_in access_token
———- ———- ————– ————
Träger 3599 3599 eyJ……………
Die expires_in ist in Sekunden, was bedeutet, dass Sie auf Anfrage ein neues token, innerhalb einer Stunde oder es wird aufhören zu arbeiten.
Lassen Sie uns speichern Sie die access-token in einer variable für die zukünftige Verwendung und dann beginnen, Anforderungen an die GraphApi:
PS51> $AccessToken = $Request.access_token
Ihre Erste GraphAPI-Anfrage
Es ist Zeit für deine erste Grafik Anfrage! Die einfachste Anfragen zu starten, sind die Anforderungen, die verwendet HTTP GET. Die GET-Befehle sind nur für das abrufen von Informationen, so dass Sie nicht brauchen, um sorgen über die Unordnung nichts nach.
Wir beginnen mit einer einfachen Anfrage die Auflistung der domains gebunden an unsere Mieter. Und denken Sie daran—Lesen Sie die Dokumentation. Alle Informationen zur Benutzung der GraphAPI-Funktionen ist in der Dokumentation.
Sie haben vielleicht bemerkt, die in der Dokumentation für die Liste Domänen-Befehl, den Sie aufrufen können, indem Sie mithilfe von HTTP-GET—Methode, die standardmäßig bei der Verwendung von Invoke-RestMethod:
Mit diesen Informationen können Sie anfangen, die Anfrage. Für die, die wir brauchen, um erstellen Sie einen Authorization-Header, der enthält die “Bearer <token>” und verwenden Sie eine GET-Anforderung in Richtung der URL im Bild oben:
$Headers = @{
Autorisierung = “Träger $AccessToken”
}
$Uri = “https://graph.microsoft.com/v1.0/domains”
$Ergebnis = Invoke-RestMethod -Header $Header -Uri $Uri
Sie haben nun die Liste der domains in die $Result variable, sondern versuchen, die Ausgabe von Werten an die $Result-variable wird zu diesem Ergebnis führen:
PS51> $Ergebnis
@odata.Kontext-Wert
————– —–
<https://graph.microsoft.com/v1.0/$metadata#domains> {@{authenticationType=Verwaltet; availabilityStatus=; id=contoso.com; isAdminManaged=True; isD..
Das Ergebnis der Abfrage ist in der Regel die value-Eigenschaft des Ergebnisses. Sie können sich das gesamte Ergebnis nur durch die Ausgabe, die Eigenschaft statt:
PS51> $Ergebnis.Wert
authenticationType : Managed
availabilityStatus :
id : contoso.com
isAdminManaged : True
isDefault : True
isInitial : False
isRoot : True
isVerified : True
supportedServices : {E-Mail, Intune}
Zustand :
passwordValidityPeriodInDays : 2147483647
passwordNotificationWindowInDays : 14
authenticationType : Managed
availabilityStatus :
id : contoso.onmicrosoft.com
isAdminManaged : True
isDefault : False
isInitial : True
isRoot : True
isVerified : True
supportedServices : {E-Mail, OfficeCommunicationsOnline}
Zustand :
passwordValidityPeriodInDays : 2147483647
passwordNotificationWindowInDays : 14
Nun, da Sie gelernt haben, die Grundlagen, um Informationen mit der GraphAPI, es ist Zeit zu lernen, wie die Verwendung von filtern.
Mithilfe Der Filter
Es ist großartig, in der Lage sein zu Holen alle Daten, die verfügbar sind. Und während es kann funktionieren, es ist furchtbar ineffektiv. Eine gute Praxis ist es, nur die Daten anzufordern, die Sie benötigen. Um dies zu erreichen in der GraphAPI, können wir den Filter benutzen.
Ein guter Kandidat für das ausprobieren von filtern ist durch das Holen von Benutzern. Sie haben eine Menge von gemeinsamen Attribut-Namen, um on-prem Active Directory, und Sie haben in der Regel mindestens ein paar von Ihnen.
Der URI für den Abruf aller Nutzer ist *https://graph.microsoft.com/v1.0/users*, aber wir wollen filtern diese Anfrage. Sie können tun, dass durch das hinzufügen der $filter=<filter> – parameter an die URI.
Ein filter (in der Regel) besteht aus Immobilien-operator und einen Wert wie diese:
Eigenschaft operator ‘Wert’
Wenn Sie jetzt geholt werden sollen alle Nutzer mit der ” givenName “John”, die folgende URI verwendet werden soll:
https://graph.microsoft.com/v1.0/users?$filter=givenName eq ‘John’
Also, wenn Sie wollen, verwenden Sie PowerShell, um diese Anforderung zu senden, sollte der code wie folgt Aussehen:
$Uri = “https://graph.microsoft.com/v1.0/users?`$filter=givenName eq ‘John'”
$Ergebnis = Invoke-RestMethod -Header $Header -Uri $Uri
Beachten Sie die “backtick”, bevor ” $filter—das ist zu entkommen, dass die dollar-Zeichen—sonst PowerShell-würde ich interpretiert es als variable.
Werfen Sie einen Blick auf die value-Eigenschaft, und Sie werden sehen, alle Benutzer mit einem ” givenName “John” in Azure Active Directory:
PS51> $Ergebnis.Wert
businessPhones : {5554012}
displayName : John Doe
Vorname : John
jobTitle :
E-mail : jdoe@contoso.com
Handy :
officeLocation :
preferredLanguage : de
Familienname : Mustermann
“userPrincipalName”: jdoe@contoso.com
id : 7fd22087-ec0a-47a1-91fb-0a7d8e6f0c
‘EQ’ ist nicht der einzige Betreiber, haben Sie noch nicht (ne), entsprechen, enthält, weniger/mehr als (lt/gt), und eine ganze Menge mehr. Während aus dem Rahmen dieses Artikels sprengen, weitere Informationen über die Betreiber gibt es in der Dokumentation. Auch weitere ausführliche Dokumentation über die verschiedenen filter-Eigenschaften steht in der Eigenschaft Dokumentation zu jedem Objekt geben.
Einen Benutzer anlegen
Nun, du hast die Grundlagen, die wir durchführen einer schreib-operation und erstellen eines Benutzers. Für, müssen Sie wissen, wie zu konstruieren, die Daten und wo, um es zu VERÖFFENTLICHEN. Sie können sehen, ein Beispiel, wie man führen, dass, indem Sie auf das Microsoft Graph-API-Dokumentation und Blick auf “Benutzer Erstellen”:
Sie können sehen, dass Sie benötigen, senden Sie die Daten als POST-request, und dass der content-Typ sollte application/json. Sie können auch sehen, eine JSON Repräsentation der Daten—das Ziel hier ist, erstellen Sie ein PowerShell-Objekt, das erstellt das JSON-wenn ConvertTo-Json wird es verwendet.
Wir haben es:
$Body = [PSCustomObject]@{
accountEnabled = $True
displayName = “Jane Doe”
mailNickname = “janedoe”
userPrincipalName = “jane.doe@automativity.com”
passwordProfile = @{
forceChangePasswordNextSignIn = $True
Passwort = “Hunter221!”
}
}
Running $Body | ConvertTo-Json wird das Ergebnis in einem JSON-ähnliche Symbol finden Sie in der Dokumentation. Was jetzt übrig bleibt, ist, es zu konvertieren, um JSON und per POST an die GraphAPI URI mit dem richtigen content-type:
$Body = [PSCustomObject]@{
accountEnabled = $True
displayName = “Jane Doe”
mailNickname = “janedoe”
userPrincipalName = “jane.doe@contoso.com”
passwordProfile = @{
forceChangePasswordNextSignIn = $True
Passwort = “Hunter221!”
}
}
$BodyJson = $Body | ConvertTo-Json
$Uri = “https://graph.microsoft.com/v1.0/users”
Invoke-RestMethod -Uri $Uri -Header $Header -Methode, POST -ContentType application/json -Body $BodyJson
Wenn Sie jetzt gehen Sie auf unsere Azure Active Directory-Konsole und schauen Sie, finden Sie den neu angelegten Benutzer:
Sie haben nun erstellt Ihr erste user, der sich mit GraphAPI!
Fazit
Die Microsoft GraphAPI ist ein mächtiges Werkzeug, und ermöglicht Ihnen die Automatisierung Ihrer Umgebung noch weiter. Und nicht nur, wenn es um die Azure Active Directory—, sondern auch für die Mehrheit der SaaS-Dienste, die Microsoft anbietet.
Auch in Anbetracht der “serverlose” – Bewegung, die mithilfe von Azure-Funktionen oder AWS Lambda in einem Ereignis, ist es möglich, minimalistisch und event-driven-Funktionen zu automatisieren, so viel wie möglich in Ihrer Umgebung. Alle, ohne die Notwendigkeit, große Bibliotheken in Ihren Funktionen.