Microsoft GraphAPI è uno strumento potente. Non possiamo usarlo solo per creare strumenti per automatizzare i nostri carichi di lavoro, possiamo anche avere accesso a nuove funzioni prima.
In questo post, Impareremo a esplorare e utilizzare Microsoft GraphAPI per Azure AD.
Prerequisiti
Devi soddisfare alcuni prerequisiti prima di poter iniziare. Prima di iniziare con i passaggi descritti in questo post, assicurati di incontrare o avere quanto segue:
- un Registrazione dell'applicazione in AzureAD con le seguenti autorizzazioni GraphAPI:
- Directory.Leggi.tutto
- Directory.ReadWrite.All
- ID. di applicazione (ID. Dal cliente) e segreto del cliente per la registrazione dell'applicazione di cui sopra
- Il tuo nome inquilino
- Un computer con versione PowerShell 5.1 il superiore
Con quello fuori mano, impariamo ad esplorare GraphAPI.
Leggi la documentazione
Microsoft GraphAPI è ben documentato e il miglior punto di partenza per scoprire come utilizzare una nuova funzione è iniziare dal documentazione di riferimento dell'API di Microsoft Graph.
Questo specifica come utilizzare una funzione specifica e quali autorizzazioni sono necessarie per utilizzarla. In questo momento ci sono due versioni di GraphAPI: v1.0 e l'API beta. All'inizio potrebbero sembrare identici, ma l'API beta contiene molte nuove funzionalità che non sono ancora state rilasciate. Si noti inoltre che le funzioni dell'API beta sono soggette a modifiche in qualsiasi momento.
permessi
Le autorizzazioni sono una parte importante dell'esplorazione e dell'utilizzo delle autorizzazioni dell'API Graph; fortunatamente, Tutti i permessi necessari per eseguire una determinata azione sono specificati nel documentazione di riferimento di quella funzione.
La schermata successiva mostra l'autorizzazione necessaria per utilizzare il getDirectoryObject funzione. E come accederai ad esso come applicazione, bisogno di Directory.LeggiTutto Mi scusi.
Ora che hai le basi, iniziamo richiedendo un token di accesso, un segreto temporaneo che utilizzeremo per accedere all'API Microsoft Graph.
Richiedi un token di accesso
Il token di accesso è un segreto che puoi richiedere con la nostra identificazione del cliente e il segreto del cliente. Questo è il token che devi inserire nelle richieste verso GraphAPI.
Per richiedere un token di accesso, deve essere autorizzato per l'endpoint oauth2 del tenant pubblicando l'ID app e il segreto dell'app.
Modifica il seguente script, sostituendo AppId, AppSecret e nome inquilino, ed eseguilo in PowerShell per richiedere un token di accesso:
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
Ora, se dai un'occhiata a $Request variabile, puoi vedere cosa contiene il nostro token di accesso, così come il tipo e il tempo di scadenza.
PS51> $Request
token_type expires_in ext_expires_in access_token
---------- ---------- -------------- ------------
Bearer 3599 3599 eyJ...............
il scade tra è in pochi secondi, il che significa che devi richiedere un nuovo token entro un'ora o smetterà di funzionare.
Salviamo il token di accesso in una variabile per un uso futuro e quindi iniziamo a fare richieste a GraphApi:
PS51> $AccessToken = $Request.access_token
La tua prima applicazione GraphAPI
È il momento della tua prima richiesta di grafico!! Le richieste più semplici per iniziare sono le richieste che utilizzano HTTP Get. I comandi GET sono solo a scopo informativo, quindi non devi preoccuparti di rovinare nulla.
Inizieremo con una semplice richiesta che elenca i domini collegati al nostro tenant. E ricorda, leggi la documentazione. Tutte le informazioni su come utilizzare le funzioni graphAPI sono disponibili nella sezione documentazione.
È possibile che tu abbia notato nella documentazione del Elenco dei domini che è possibile chiamare tramite HTTP GET, Il metodo predefinito quando utilizzato Invoke-RestMethod:
Con queste informazioni, È possibile iniziare a compilare la richiesta. Per quello, abbiamo bisogno di creare un Intestazione di autorizzazione che contiene “Portatore
$Headers = @{
Authorization = "Bearer $AccessToken"
}
$Uri = "https://graph.microsoft.com/v1.0/domains"
$Result = Invoke-RestMethod -Headers $Headers -Uri $Uri
Ora hai l'elenco dei domini nel $Result variabile, ma cercando di generare il valore del $Result La variabile risulterà in questo:
PS51> $Result
@odata.context value
-------------- -----
<https://graph.microsoft.com/v1.0/$metadata#domains> {@{authenticationType=Managed; availabilityStatus=; id=contoso.com; isAdminManaged=True; isD..
Il risultato della query è di solito in valore proprietà del risultato. Puoi ottenere il risultato completo semplicemente generando quella proprietà:
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
Ora che hai imparato le basi per ottenere informazioni con GraphAPI, è ora di imparare a usare i filtri.
Usa i filtri
È fantastico poter recuperare tutti i dati disponibili. E anche quando può funzionare, è terribilmente inefficace. Una buona pratica è richiedere solo i dati di cui hai bisogno. Per raggiungere questo obiettivo in GraphAPI, possiamo usare i filtri.
Un buon candidato per testare i filtri è la ricerca utenti. Hanno molti nomi di attributi comuni ad Active Directory locale e, generalmente, ne ha almeno alcuni.
L'URI per ottenere tutti gli utenti è *https://graph.microsoft.com/v1.0/users*, ma vogliamo filtrare questa richiesta. Puoi farlo aggiungendo il $ filtro =
Un filtro (in genere) consiste in un operatore di proprietà e un valore come questo:
property operator 'value'
Se ora vuoi cercare tutti gli utenti con nome di battesimo “John”, dovrebbe essere usato il seguente URI:
https://graph.microsoft.com/v1.0/users?$filter=givenName eq 'John'
Quindi, se vuoi usare PowerShell per fare questa richiesta, il codice dovrebbe assomigliare a questo:
$Uri = "https://graph.microsoft.com/v1.0/users?`$filter=givenName eq 'John'"
$Result = Invoke-RestMethod -Headers $Headers -Uri $Uri
Notare il backtick prima $filter—Quello per sfuggire al simbolo del dollaro - altrimenti, PowerShell l'avrebbe interpretata come una variabile.
Dai un'occhiata alla proprietà value e vedrai tutti gli utenti con un nome di “John” in 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"’ non è l'unico operatore, non ha (Nato), coincidere, contiene, meno / più grande di (lt / gt), e altro ancora. Anche se esula dallo scopo di questo post, maggiori informazioni sugli operatori sono disponibili nel documentazione. Inoltre, nella proprietà è disponibile una documentazione più ampia sulle diverse proprietà del filtro. documentazione su ogni tipo di oggetto.
Crea un utente
Ora che hai le basi, eseguiamo un'operazione di scrittura e creiamo un utente. Per quello, devi sapere come costruire i dati e dove PUBBLICARLI. Puoi vedere un esempio di come farlo andando alla documentazione dell'API Microsoft Graph e guardando “Crea utente”:
Puoi vedere che devi inviare i dati come richiesta POST e che il tipo di contenuto deve essere of app / json. Puoi anche vedere una rappresentazione JSON dei dati; l'obiettivo qui è creare un oggetto PowerShell che crei quel JSON quando ConvertTo-Json è usato in esso.
Proviamo:
$Body = [PSCustomObject]@{
accountEnabled = $True
displayName = "Jane Doe"
mailNickname = "janedoe"
userPrincipalName = "[email protected]"
passwordProfile = @{
forceChangePasswordNextSignIn = $True
password = "Hunter221!"
}
}
Di fretta $Body | ConvertTo-Json risulterà in un JSON simile a quello mostrato nella documentazione. Ciò che resta ora è convertirlo in JSON e POST in GraphAPI URI con il tipo di contenuto corretto:
$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
Se ora vai alla nostra console di Azure Active Directory e dai un'occhiata, troverà l'utente appena creato:
Hai già creato il tuo primo utente utilizzando GraphAPI!
conclusione
Microsoft GraphAPI è uno strumento potente e ti consentirà di automatizzare ulteriormente il tuo ambiente. E non solo quando si tratta di Azure Active Directory, ma oltre alla maggior parte dei servizi SaaS offerti da Microsoft.
Allo stesso tempo, considerando il movimento “senza server” che usa Funzioni di Azure o AWS Lambda in un evento, è possibile creare funzioni minimaliste e guidate dagli eventi per automatizzare il più possibile nel proprio ambiente. Tutto senza dover includere grandi librerie nelle tue funzioni.
