Microsoft GraphAPI ist ein leistungsstarkes Tool. Wir können damit nicht nur Tools erstellen, um unsere Workloads zu automatisieren, wir können auch vorher auf neue Funktionen zugreifen.
In diesem Beitrag, Wir werden lernen, Microsoft GraphAPI für Azure AD zu erkunden und zu verwenden.
Voraussetzungen
Du musst einige Voraussetzungen erfüllen, bevor wir starten können. Bevor Sie mit den in diesem Beitrag beschriebenen Schritten beginnen, Stellen Sie sicher, dass Sie Folgendes treffen oder haben:
- ein Bewerbungsregistrierung in AzureAD mit den folgenden GraphAPI-Berechtigungen:
- Verzeichnis.Alles.lesen
- Verzeichnis.ReadWrite.All
- Ausweis. Bewerbung (Ich würde. Vom Kunden) und Client-Geheimnis für die obige Anwendungsregistrierung
- Ihr Mietername
- Ein Computer mit PowerShell-Version 5.1 Der Vorgesetzte
Damit aus dem Weg, Lassen Sie uns lernen, GraphAPI zu erkunden.
Lesen Sie die Dokumentation
Microsoft GraphAPI ist gut dokumentiert und der beste Ausgangspunkt, wenn Sie herausfinden möchten, wie eine neue Funktion verwendet wird, ist, mit dem zu beginnen Referenzdokumentation de la API von Microsoft Graph.
Dies gibt an, wie Sie eine bestimmte Funktion verwenden und welche Berechtigungen Sie benötigen, um sie zu verwenden. Momentan gibt es zwei Versionen von GraphAPI: v1.0 und die Beta-API. Sie mögen auf den ersten Blick identisch erscheinen, aber die Beta-API enthält viele neue Funktionen, die noch nicht veröffentlicht wurden. Beachten Sie auch, dass Beta-API-Funktionen jederzeit geändert werden können.
Berechtigungen
Berechtigungen sind ein wichtiger Bestandteil beim Erkunden und Verwenden der Graph API-Berechtigungen; Glücklicherweise, Alle Berechtigungen, die Sie zum Ausführen einer bestimmten Aktion benötigen, sind in der Referenzdokumentation dieser Funktion.
Der nächste Screenshot zeigt die erforderliche Berechtigung zur Verwendung des getDirectoryObject Funktion. Und wie Sie als Anwendung darauf zugreifen, braucht den Verzeichnis.ReadAll Verzeihung.
Jetzt haben Sie die Grundlagen, Beginnen wir mit der Anforderung eines Zugriffstokens, ein temporäres Geheimnis, mit dem wir auf die Microsoft Graph-API zugreifen.
Fordern Sie ein Zugriffstoken an
Der Zugriffstoken ist ein Geheimnis, das Sie mit unserer Kundenidentifikation und unserem Kundengeheimnis anfordern können. Dies ist das Token, das Sie in den Anfragen an GraphAPI . benötigen.
So fordern Sie ein Zugriffstoken an, muss für den oauth2-Endpunkt des Mandanten autorisiert werden, indem seine App-ID und sein App-Geheimnis veröffentlicht werden.
Bearbeiten Sie das folgende Skript, Ersetzen von AppId, AppSecret y Tenant-Name, und führen Sie es in PowerShell aus, um ein Zugriffstoken anzufordern:
Add-Type -AssemblyName System.Web
$AppId = 'CHANGEME'
$AppSecret="CHANGEME"
$Scope = "https://graph.microsoft.com/.default"
$TenantName = "CHANGEME.onmicrosoft.com"
$Dirección 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 = $Dirección url
}
# Request the token!
$Request = Invoke-RestMethod @PostSplat
Jetzt, wenn du dir das anschaust $Request Variable, Sie können sehen, was unser Zugriffstoken enthält, sowie die Art und die Ablaufzeit.
PS51> $Request
token_type expires_in ext_expires_in access_token
---------- ---------- -------------- ------------
Bearer 3599 3599 eyJ...............
das Läuft ab in es ist in sekunden, Das bedeutet, dass Sie in einer Stunde ein neues Token anfordern müssen, oder es funktioniert nicht mehr.
Speichern wir das Zugriffstoken in einer Variablen für die zukünftige Verwendung und stellen Sie dann Anfragen an GraphApi:
PS51> $AccessToken = $Request.access_token
Ihre erste GraphAPI-Anfrage
Es ist Zeit für Ihre erste Kartenanfrage!! Die einfachsten Anfragen sind Anfragen, die HTTP GET verwenden. GET-Befehle dienen nur zur Information, Sie müssen sich also keine Sorgen machen, etwas zu verderben.
Wir beginnen mit einer einfachen Anfrage, die die mit unserem Mandanten verknüpften Domains auflistet. Und merke dir, Lesen Sie die Dokumentation. Alle Informationen zur Nutzung der GraphAPI-Funktionen finden Sie im Dokumentation.
Sie haben es vielleicht in der Dokumentation des Liste der Domänen Befehl, den Sie über HTTP GET aufrufen können, die Standardmethode bei der Verwendung Invoke-RestMethod:
Mit diesen Informationen, Sie können mit der Erstellung der Anfrage beginnen. Dafür, wir müssen eine erstellen Autorisierungskopf enthält “Träger
$Headers = @{
Authorization = "Bearer $AccessToken"
}
$Uri = "https://graph.microsoft.com/v1.0/domains"
$Result = Invoke-RestMethod -Headers $Headers -Uri $Uri
Sie haben jetzt die Liste der Domänen in der $Result Variable, aber versuchen, den Wert der zu generieren $Result Die Variable wird dazu führen:
PS51> $Result
@odata.context value
-------------- -----
<https://graph.microsoft.com/v1.0/$metadata#domains> {@{authenticationType=Managed; availabilityStatus=; id=contoso.com; isAdminManaged=True; isD..
Das Ergebnis der Abfrage befindet sich normalerweise in der Wert Ergebnis Eigenschaft. Sie können das vollständige Ergebnis erhalten, indem Sie stattdessen einfach diese Eigenschaft generieren:
PS51> $Result.value
authenticationType : Managed
availabilityStatus :
id : contoso.com
isAdminManaged : True
isDefault : True
isInitial : False
isRoot : True
isVerified : True
supportedServices : {Email, Intune}
state :
passwordValidityPeriodInDays : 2147483647
passwordNotificationWindowInDays : 14
authenticationType : Managed
availabilityStatus :
id : contoso.onmicrosoft.com
isAdminManaged : True
isDefault : False
isInitial : True
isRoot : True
isVerified : True
supportedServices : {Email, OfficeCommunicationsOnline}
state :
passwordValidityPeriodInDays : 2147483647
passwordNotificationWindowInDays : 14
Nachdem Sie nun die Grundlagen des Abrufens von Informationen mit GraphAPI . kennengelernt haben, Es ist Zeit zu lernen, wie man Filter verwendet.
Filter verwenden
Es ist großartig, alle verfügbaren Daten wiederherstellen zu können. Und selbst wenn es funktionieren kann, es ist furchtbar wirkungslos. Eine bewährte Vorgehensweise besteht darin, nur die Daten anzufordern, die Sie benötigen. Um dies in GraphAPI . zu erreichen, Wir können Filter verwenden.
Ein guter Kandidat zum Testen von Filtern ist die Suche Benutzer. Sie haben viele gemeinsame Attributnamen für das lokale Active Directory und, im Allgemeinen, hat zumindest einige davon.
Der URI zum Abrufen aller Benutzer lautet *https://graph.microsoft.com/v1.0/users*, aber wir möchten diese Anfrage filtern. Sie können dies tun, indem Sie die hinzufügen $ filtern =
Ein Filter (allgemein) besteht aus einem Eigenschaftsoperator und einem Wert wie diesem:
property operator 'value'
Wenn Sie nun nach allen Benutzern suchen möchten mit dem Vorname “Klo”, die folgende URI sollte verwendet werden:
https://graph.microsoft.com/v1.0/users?$filter=givenName eq 'John'
Dann, wenn Sie PowerShell verwenden möchten, um diese Anfrage zu stellen, der Code sollte so aussehen:
$Uri = "https://graph.microsoft.com/v1.0/users?`$filter=givenName eq 'John'"
$Result = Invoke-RestMethod -Headers $Headers -Uri $Uri
Beachten Sie den Backtick früher $filter—Das um dem Dollarzeichen zu entkommen - sonst, PowerShell hätte es als Variable interpretiert.
Werfen Sie einen Blick auf die value-Eigenschaft und Sie sehen alle Benutzer mit einem bestimmten Namen von “Klo” de Azure Active Directory:
PS51> $Result.value
businessPhones : {5554012}
displayName : John Doe
givenName : John
jobTitle :
mail : [email protected]
mobilePhone :
officeLocation :
preferredLanguage : en
surname : Doe
userPrincipalName : [email protected]
id : 7fd22087-ec0a-47a1-91fb-0a7d8e6f0c
‘EQ’’ ist nicht der einzige Betreiber, hat nicht (geboren), übereinstimmen, enthält, weniger / größer als (lt / gt), und vieles mehr. Obwohl es außerhalb des Rahmens dieses Beitrags liegt, Weitere Informationen zu den Betreibern finden Sie im Dokumentation. Darüber hinaus ist eine ausführliche Dokumentation zu den verschiedenen Eigenschaften des Filters in der Eigenschaft . verfügbar. Dokumentation über jede Art von Objekt.
Erstellen Sie einen Benutzer
Jetzt haben Sie die Grundlagen, Lassen Sie uns eine Schreiboperation durchführen und einen Benutzer erstellen. Dafür, Sie müssen wissen, wie Sie die Daten erstellen und wo Sie sie VERÖFFENTLICHEN. Ein Beispiel dafür finden Sie in der Dokumentation zur Microsoft Graph-API und unter “Benutzer erstellen”:
Sie sehen, dass Sie die Daten als POST-Anfrage senden müssen und dass der Inhaltstyp sein muss App / json. Sie können auch eine JSON-Darstellung der Daten sehen; Das Ziel hier ist es, ein PowerShell-Objekt zu erstellen, das diesen JSON erstellt, wenn ConvertTo-Json wird darin verwendet.
Lass es uns versuchen:
$Body = [PSCustomObject]@{
accountEnabled = $True
displayName = "Jane Doe"
mailNickname = "janedoe"
userPrincipalName = "[email protected]"
passwordProfile = @{
forceChangePasswordNextSignIn = $True
password = "Hunter221!"
}
}
In Eile $Body | ConvertTo-Json führt zu einem JSON ähnlich dem in der Dokumentation gezeigten. Jetzt müssen Sie es in JSON konvertieren und mit dem richtigen Inhaltstyp in den GraphAPI-URI POST:
$Body = [PSCustomObject]@{
accountEnabled = $True
displayName = "Jane Doe"
mailNickname = "janedoe"
userPrincipalName = "[email protected]"
passwordProfile = @{
forceChangePasswordNextSignIn = $True
password = "Hunter221!"
}
}
$BodyJson = $Body | ConvertTo-Json
$Uri = "https://graph.microsoft.com/v1.0/users"
Invoke-RestMethod -Uri $Uri -Headers $Headers -Method POST -ContentType application/json -Body $BodyJson
Wenn Sie jetzt zu unserer Azure Active Directory Console gehen und einen Blick darauf werfen, findet den neu erstellten Benutzer:
Sie haben bereits Ihren ersten Benutzer mit GraphAPI . erstellt!
Fazit
Microsoft GraphAPI ist ein leistungsstarkes Tool, mit dem Sie Ihre Umgebung weiter automatisieren können. Und das nicht nur, wenn es um Azure Active Directory geht, aber zusätzlich zu den meisten SaaS-Diensten von Microsoft.
Zur selben Zeit, unter Berücksichtigung der Bewegung “kein Server” die Azure Functions oder AWS Lambda in einem Ereignis verwendet, Es ist möglich, minimalistische und ereignisgesteuerte Funktionen zu erstellen, um so viel wie in Ihrer Umgebung möglich zu automatisieren. Alles ohne große Bibliotheken in Ihre Funktionen einbinden zu müssen.
