Microsoft GraphAPI è un potente strumento per avere. Non solo lo si può utilizzare per creare utensili per automatizzare i nostri carichi di lavoro si può anche accedere a nuove funzioni in precedenza.
In questo articolo, impareremo ad esplorare e utilizzare Microsoft GraphAPI per Azure AD.
Prerequisiti
È necessario soddisfare alcuni prerequisiti prima di poter iniziare. Prima di iniziare con la procedura descritta in questo articolo, assicurarsi che si incontrano o sono i seguenti:
- Un’App di Registrazione in AzureAD con il seguente GraphAPI autorizzazioni:
- Directory.Leggere.Tutti
- Directory.ReadWrite.Tutti
- Id applicazione (client-id) e client-segreto per sopra le App di Registrazione
- Il tuo nome proprietario
- Un computer che esegue PowerShell versione 5.1 o superiore
Con quella di mezzo—impariamo a esplorare il GraphAPI.
Leggere la Documentazione
Microsoft GraphAPI è ben documentato, e il posto migliore per iniziare quando scoprire come utilizzare una nuova funzione per avviare la documentazione di riferimento di Microsoft Graph API.
Questa specifica come utilizzare una funzione specifica e le autorizzazioni necessarie per utilizzare esso. Attualmente ci sono due versioni del GraphAPI: v1.0 e la beta di API. Possono sembrare identici a prima, ma la beta API contiene un sacco di nuove funzioni che non sono ancora stato rilasciato. Anche essere consapevoli del fatto che funzioni in beta API sono soggette a modifica in qualsiasi momento.
Autorizzazioni
Le autorizzazioni sono una parte importante di esplorare e utilizzando l’API grafica autorizzazioni—per fortuna tutte le autorizzazioni necessarie per eseguire una certa azione sono specificati nella documentazione di riferimento della funzione.
La seguente schermata mostra l’autorizzazione necessaria per utilizzare il getDirectoryObject funzione. E perché si potrà accedere ad esso come un’applicazione, è necessario Directory.ReadAll autorizzazione.
Ora che avete le basi, si può iniziare con la richiesta di un token di accesso temporanea segreto che verrà utilizzato per accedere a Microsoft Graph API.
La richiesta di un Token di Accesso
Il token di accesso è un segreto che si può richiedere tramite il nostro client-id client e segreto. È questo token che è necessario nelle richieste verso il GraphAPI.
Per richiedere un token di accesso, è necessario autorizzare contro l’inquilino del oauth2 endpoint inviando il vostro Id Applicazione e l’Applicazione Segreto.
Modificare lo script seguente, sostituendo AppId, AppSecret, e Inquilino nome, e correre in PowerShell per richiedere un token di accesso:
Add-Tipo -AssemblyName Sistema.Web
$Idapp = ‘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 = $Corpo
Uri = $Url
}
# Richiesta del token!
$Richiesta = Invoke-RestMethod @PostSplat
Ora, se si dà un’occhiata a $variabile di Richiesta, si può vedere che contiene il nostro token di accesso, nonché il tipo e la data di scadenza.
PS51> $Richiesta
token_type expires_in ext_expires_in access_token
———- ———- ————– ————
Portatore 3599 3599 eyJ……………
Il expires_in è in secondi, il che significa che è necessario richiedere un nuovo token all’interno di un’ora o smettere di lavorare.
Cerchiamo di salvare il token di accesso in una variabile per un uso futuro, e poi iniziare a fare le richieste verso il GraphApi:
PS51> $AccessToken = $Request.access_token
Il Primo GraphAPI Richiesta
È il momento per il tuo primo grafico richiesta! La più semplice richieste sono le richieste che utilizza HTTP GET. OTTENERE i comandi sono disponibili solo per il recupero di informazioni, quindi non è necessario preoccuparsi di rovinare nulla.
Si partirà con una semplice richiesta di quotazione i domini legati al nostro inquilino. E ricordate di leggere la documentazione. Tutte le informazioni su come utilizzare il GraphAPI funzioni è la documentazione.
Potreste aver notato nella documentazione per la Lista dei Domini di comando che si può chiamare utilizzando HTTP GET—il metodo di default quando si utilizza Invoke-RestMethod:
Con queste informazioni, è possibile iniziare a costruire la richiesta. Per questo, abbiamo bisogno di creare un’Intestazione di Autorizzazione che contiene “Portatore <token>” e l’uso che per effettuare una richiesta GET verso l’URL nella foto sopra:
$Intestazioni = @{
Autorizzazione = “Portatore $AccessToken”
}
$Uri = “https://graph.microsoft.com/v1.0/domains”
$Risultato = Invoke-RestMethod -Header $Intestazioni -Uri $Uri
Ora avete l’elenco dei domini nella variabile $Result, ma cercando di output il valore della variabile $Result risultato sarà questo:
PS51> $Risultato
@odata.valore di contesto
————– —–
<https://graph.microsoft.com/v1.0/$metadati#domini> {@{authenticationType=Gestite; availabilityStatus=; id=contoso.com; isAdminManaged=True; isD..
Il risultato della query è, di solito, il valore della proprietà del risultato. Si può ottenere il risultato da solo l’output di tale proprietà, invece:
PS51> $Risultato.valore
authenticationType : Gestito
availabilityStatus :
id : contoso.com
isAdminManaged : True
isDefault : True
isInitial : False
isRoot : True
isVerified : True
supportedServices : {e-Mail, Intune}
stato :
passwordValidityPeriodInDays : 2147483647
passwordNotificationWindowInDays : 14
authenticationType : Gestito
availabilityStatus :
id : contoso.onmicrosoft.com
isAdminManaged : True
isDefault : False
isInitial : True
isRoot : True
isVerified : True
supportedServices : {e-Mail, OfficeCommunicationsOnline}
stato :
passwordValidityPeriodInDays : 2147483647
passwordNotificationWindowInDays : 14
Ora che hai imparato le basi di ottenere informazioni con il GraphAPI, è il momento di imparare come utilizzare i filtri.
Utilizza I Filtri
È bello essere in grado di recuperare tutti i dati che sono disponibili. E mentre non può funzionare, è terribilmente inefficace. Una buona pratica è quello di richiedere solo i dati di cui avete bisogno. Per raggiungere questo obiettivo nel GraphAPI, siamo in grado di utilizzare i filtri.
Un buon candidato per provare i filtri dal recupero degli utenti. Hanno un sacco di comuni nomi di attributo per on-prem Active Directory e di solito hanno almeno un paio di loro.
L’URI per il recupero di tutti gli utenti è *https://graph.microsoft.com/v1.0/users* ma vogliamo filtrare questa richiesta. Si può fare aggiungendo che il $filter=<filtro> parametro per l’URI.
Un filtro (di solito) si compone di proprietà dell’operatore e un valore come questo:
proprietà operatore ‘valore’
Se si desidera recuperare tutti gli utenti con le givenName “John,” il seguente URI deve essere utilizzato:
https://graph.microsoft.com/v1.0/users?$filtro=givenName eq ‘Giovanni’
Quindi, se si desidera utilizzare PowerShell per fare questa richiesta, il codice dovrebbe essere simile a questo:
$Uri = “https://graph.microsoft.com/v1.0/users?`$filtro=givenName eq ‘Giovanni'”
$Risultato = Invoke-RestMethod -Header $Intestazioni -Uri $Uri
Notare il backtick prima $filter—che per sfuggire il segno di dollaro—altro PowerShell sarebbe stato interpretato come una variabile.
Date un’occhiata al valore della proprietà, e vedrete tutti gli utenti con un givenName di “John” in Azure Active Directory:
PS51> $Risultato.valore
businessPhones : {5554012}
displayName : John Doe
givenName : Giovanni
jobTitle :
mail : jdoe@contoso.com
il cellulare :
officeLocation :
preferredLanguage : it
cognome : Rossi
userPrincipalName : jdoe@contoso.com
id : 7fd22087-ec0a-47a1-91fb-0a7d8e6f0c
‘EQ’ non è l’unico operatore che, non (ne), partita, contiene, minore/maggiore (lt/gt), e molto altro ancora. Mentre al di fuori dell’ambito di questo articolo, ulteriori informazioni sugli operatori è disponibile nella documentazione. Anche più ampia documentazione sulle diverse proprietà del filtro è disponibile nella documentazione di proprietà su ogni tipo di oggetto.
Creazione di un Utente
Ora che hai imparato le basi, facciamo eseguire un’operazione di scrittura e la creazione di un utente. Per questo, avete bisogno di sapere come costruire i dati e dove POSTARE. Si può vedere un esempio su come eseguire e che andando a Microsoft Graph API di documentazione e di ricerca in “Crea Utente”:
Si può vedere che avete bisogno di inviare i dati come una richiesta POST, e che il contenuto dovrebbe essere del tipo application/json. È anche possibile vedere una rappresentazione JSON dei dati, l’obiettivo qui è quello di creare un PowerShell oggetto che crea JSON quando ConvertTo-Json viene utilizzato su di esso.
Diamo un’occhiata:
$Body = [PSCustomObject]@{
accountEnabled = $True
displayName = “Jane Doe”
mailNickname = “mariorossi”
userPrincipalName = “jane.doe@automativity.com”
passwordProfile = @{
forceChangePasswordNextSignIn = $True
password = “Hunter221!”
}
}
In esecuzione $Corpo | ConvertTo-Json si tradurrà in un simile JSON a quanto indicato nella documentazione. Ciò che rimane ora è per la conversione di JSON e POST-it per il GraphAPI URI con il giusto tipo di contenuto:
$Body = [PSCustomObject]@{
accountEnabled = $True
displayName = “Jane Doe”
mailNickname = “mariorossi”
userPrincipalName = “jane.doe@contoso.com”
passwordProfile = @{
forceChangePasswordNextSignIn = $True
password = “Hunter221!”
}
}
$BodyJson = $Corpo | ConvertTo-Json
$Uri = “https://graph.microsoft.com/v1.0/users”
Invoke-RestMethod -Uri $Uri -Header $Intestazioni -Metodo di POST -content-type application/json -Corpo $BodyJson
Se ora vai al nostro Azure Active Directory Console e dare un’occhiata, troverete l’utente appena creato:
Ora avete creato il vostro primo utente che utilizza GraphAPI!
Conclusione
Microsoft GraphAPI è un potente strumento che ci permetterà di automatizzare il vostro ambiente ancora di più. E non solo quando si tratta di Azure Active Directory—ma anche per la maggior parte di SaaS servizi che Microsoft mette a disposizione.
Anche considerando la “serverless” movimento utilizzando Azure Funzioni o AWS Lambda in un evento, è possibile creare minimalista e event-driven funzioni per automatizzare quanto più possibile nel proprio ambiente. Il tutto senza la necessità di includere grandi librerie di funzioni.