Créer des scripts PowerShell avec Microsoft Graph

Article
Developer (Débutant)
21 minutes avant achèvement

Ce tutoriel vous apprend à créer un script PowerShell qui utilise microsoft API Graph pour accéder aux données pour le compte d’un utilisateur.

Remarque

Pour savoir comment utiliser Microsoft Graph pour accéder aux données à l’aide de l’authentification d’application uniquement, consultez ce tutoriel sur l’authentification d’application uniquement.

Dans ce didacticiel, vous allez :

Conseil

Au lieu de suivre ce tutoriel, vous pouvez télécharger le code terminé via l’outil de démarrage rapide , qui automatise l’inscription et la configuration des applications. Le code téléchargé fonctionne sans aucune modification requise.

Vous pouvez également télécharger ou cloner le dépôt GitHub et suivre les instructions du fichier LISEZ-MOI pour inscrire une application et configurer le projet.

Prerequisites

Avant de commencer ce didacticiel, PowerShell doit être installé sur votre ordinateur de développement. PowerShell 5.1 est la configuration minimale requise, mais PowerShell 7 est recommandé.

Vous devez également disposer d’un compte professionnel ou scolaire Microsoft avec une boîte aux lettres Exchange Online. Si vous n’avez pas de locataire Microsoft 365, vous pouvez être éligible pour un client via le Programme pour les développeurs Microsoft 365 ; Pour plus d’informations, consultez la FAQ. Vous pouvez également vous inscrire à un essai gratuit de 1 mois ou acheter un plan Microsoft 365.

Remarque

Ce tutoriel a été écrit avec PowerShell 7.2.2 et le Kit de développement logiciel (SDK) Microsoft Graph PowerShell version 1.9.5. Les étapes décrites dans ce guide peuvent fonctionner avec d’autres versions, mais elles n’ont pas été testées.

Inscrire l’application sur le portail

20 minutes restantes

Dans cet exercice, vous allez inscrire une nouvelle application dans Azure Active Directory pour activer l’authentification utilisateur. Vous pouvez inscrire une application à l’aide du Centre d’administration Azure Active Directory ou du Kit de développement logiciel (SDK) Microsoft Graph PowerShell.

Inscrire l’application pour l’authentification utilisateur

Dans cette section, vous allez inscrire une application qui prend en charge l’authentification utilisateur à l’aide du flux de code d’appareil.

Remarque

L’inscription d’une application pour l’authentification utilisateur pour le Kit de développement logiciel (SDK) Microsoft Graph PowerShell est facultative. Le SDK a sa propre inscription d’application et l’ID client correspondant. Toutefois, l’utilisation de votre propre ID d’application permet de mieux contrôler les étendues d’autorisation pour un script PowerShell particulier.

Centre d’administration Azure AD
PowerShell

Ouvrez un navigateur et accédez au Centre d’administration Azure Active Directory et connectez-vous à l’aide d’un compte professionnel ou scolaire.
Sélectionnez Azure Active Directory dans le volet de navigation gauche, puis sélectionnez Inscriptions d’applications sous Gérer.
Sélectionnez Nouvelle inscription. Entrez un nom pour votre application, par exemple . Graph User Auth Tutorial

Définissez types de comptes pris en charge comme vous le souhaitez. Les options disponibles sont les suivantes :

Option	Qui peut se connecter ?
Comptes dans cet annuaire organisationnel uniquement	Seuls les utilisateurs de votre organization Microsoft 365
Comptes dans un annuaire organisationnel	Utilisateurs de n’importe quel organization Microsoft 365 (comptes professionnels ou scolaires)
Comptes dans n’importe quel annuaire organisationnel ... et comptes Microsoft personnels	Utilisateurs d’un compte Microsoft 365 organization (comptes professionnels ou scolaires) et de comptes Microsoft personnels

Laissez Redirect URI vide.
Sélectionner Inscription. Dans la page Vue d’ensemble de l’application, copiez la valeur de l’ID d’application (client) et enregistrez-la. Vous en aurez besoin à l’étape suivante. Si vous avez choisi Comptes dans cet annuaire organisationnel uniquement pour Types de comptes pris en charge, copiez également l’ID d’annuaire (locataire) et enregistrez-le.
Sous Gérer, sélectionnez Authentification. Recherchez la section Paramètres avancés et modifiez le bouton bascule Autoriser les flux clients publics sur Oui, puis choisissez Enregistrer.

Pour utiliser PowerShell, vous avez besoin du Kit de développement logiciel (SDK) Microsoft Graph PowerShell. Si vous ne l’avez pas, consultez Installer le Kit de développement logiciel (SDK) Microsoft Graph PowerShell pour obtenir des instructions d’installation.

Importante

Le script PowerShell nécessite un compte professionnel/scolaire avec l’administrateur d’application, l’administrateur d’application cloud ou Administrateur général rôle. Si votre compte a le rôle Développeur d’applications, vous pouvez vous inscrire dans le Centre d’administration Azure AD.

Créez un fichier nommé RegisterAppForUserAuth.ps1 et ajoutez le code suivant.

param(
  [Parameter(Mandatory=$true,
  HelpMessage="The friendly name of the app registration")]
  [String]
  $AppName,

  [Parameter(Mandatory=$false,
  HelpMessage="The sign in audience for the app")]
  [ValidateSet("AzureADMyOrg", "AzureADMultipleOrgs", `
  "AzureADandPersonalMicrosoftAccount", "PersonalMicrosoftAccount")]
  [String]
  $SignInAudience = "AzureADandPersonalMicrosoftAccount",

  [Parameter(Mandatory=$false)]
  [Switch]
  $StayConnected = $false
)

# Tenant to use in authentication.
# See https://learn.microsoft.com/azure/active-directory/develop/v2-oauth2-device-code#device-authorization-request
$authTenant = switch ($SignInAudience)
{
  "AzureADMyOrg" { "tenantId" }
  "AzureADMultipleOrgs" { "organizations" }
  "AzureADandPersonalMicrosoftAccount" { "common" }
  "PersonalMicrosoftAccount" { "consumers" }
  default { "invalid" }
}

if ($authTenant -eq "invalid")
{
  Write-Host -ForegroundColor Red "Invalid sign in audience:" $SignInAudience
  Exit
}

# Requires an admin
Connect-MgGraph -Scopes "Application.ReadWrite.All User.Read" -UseDeviceAuthentication -ErrorAction Stop

# Get context for access to tenant ID
$context = Get-MgContext -ErrorAction Stop

if ($authTenant -eq "tenantId")
{
  $authTenant = $context.TenantId
}

# Create app registration
$appRegistration = New-MgApplication -DisplayName $AppName -SignInAudience $SignInAudience `
 -IsFallbackPublicClient -ErrorAction Stop
Write-Host -ForegroundColor Cyan "App registration created with app ID" $appRegistration.AppId

# Create corresponding service principal
if ($SignInAudience -ne "PersonalMicrosoftAccount")
{
  New-MgServicePrincipal -AppId $appRegistration.AppId -ErrorAction SilentlyContinue `
   -ErrorVariable SPError | Out-Null
  if ($SPError)
  {
    Write-Host -ForegroundColor Red "A service principal for the app could not be created."
    Write-Host -ForegroundColor Red $SPError
    Exit
  }

  Write-Host -ForegroundColor Cyan "Service principal created"
}

Write-Host
Write-Host -ForegroundColor Green "SUCCESS"
Write-Host -ForegroundColor Cyan -NoNewline "Client ID: "
Write-Host -ForegroundColor Yellow $appRegistration.AppId
Write-Host -ForegroundColor Cyan -NoNewline "Auth tenant: "
Write-Host -ForegroundColor Yellow $authTenant

if ($StayConnected -eq $false)
{
  Disconnect-MgGraph | Out-Null
  Write-Host "Disconnected from Microsoft Graph"
}
else
{
  Write-Host
  Write-Host -ForegroundColor Yellow `
   "The connection to Microsoft Graph is still active. To disconnect, use Disconnect-MgGraph"
}

Enregistrez le fichier.
Ouvrez PowerShell et remplacez le répertoire actif par l’emplacement de RegisterAppForUserAuth.ps1.

Exécutez la commande suivante, en <remplaçant audience-value> par la valeur souhaitée (voir le tableau ci-dessous).

.\RegisterAppForUserAuth.ps1 -AppName "Graph User Auth Tutorial" -SignInAudience <audience-value>

Valeur SignInAudience	Qui peut se connecter ?
`AzureADMyOrg`	Seuls les utilisateurs de votre organization Microsoft 365
`AzureADMultipleOrgs`	Utilisateurs de n’importe quel organization Microsoft 365 (comptes professionnels ou scolaires)
`AzureADandPersonalMicrosoftAccount`	Utilisateurs d’un compte Microsoft 365 organization (comptes professionnels ou scolaires) et de comptes Microsoft personnels
`PersonalMicrosoftAccount`	Seuls les comptes Microsoft personnels

Suivez l’invite pour ouvrir https://microsoft.com/devicelogin dans un navigateur, entrez le code fourni et terminez le processus d’authentification.
Copiez les valeurs d’ID client et de locataire d’authentification à partir de la sortie du script. Vous aurez besoin de ces valeurs à l’étape suivante.
```
SUCCESS
Client ID: 2fb1652f-a9a0-4db9-b220-b224b8d9d38b
Auth tenant: common
```

Remarque

Notez que vous n’avez configuré aucune autorisation Microsoft Graph sur l’inscription de l’application. Cela est dû au fait que l’exemple utilise le consentement dynamique pour demander des autorisations spécifiques pour l’authentification utilisateur.

Ajouter l’authentification utilisateur

17 minutes restantes

Dans cette section, vous allez authentifier une session PowerShell en tant qu’utilisateur pour Microsoft Graph. Cela est nécessaire pour obtenir le jeton d’accès OAuth nécessaire pour appeler Microsoft Graph.

Le Kit de développement logiciel (SDK) Microsoft Graph PowerShell fournit deux méthodes d’authentification pour l’authentification utilisateur : l’authentification interactive du navigateur et l’authentification par code d’appareil. L’authentification interactive du navigateur utilise le navigateur par défaut d’un appareil pour permettre à l’utilisateur de se connecter. L’authentification par code d’appareil autorise l’authentification dans les environnements qui n’ont pas de navigateur par défaut. Dans cet exercice, vous allez utiliser l’authentification par code d’appareil.

Importante

Si vous n’avez pas encore installé le Kit de développement logiciel (SDK) Microsoft Graph PowerShell, installez-le maintenant avant de continuer.

Authentifier l’utilisateur

Ouvrez PowerShell et utilisez la commande suivante pour définir la $clientID variable de session, en <remplaçant your-client-id> par l’ID client de votre inscription d’application.
```
$clientId = <your-client-id>
```
Définissez la variable de $tenantId session. Si vous avez choisi d’autoriser uniquement les utilisateurs de votre organization à se connecter lors de l’inscription de votre application, remplacez <tenant-id> par l’ID de locataire de votre organization. Sinon, remplacez par common.
```
$tenantId = <tenant-id>
```

Définissez la variable de $graphScopes session.

$graphScopes = "user.read mail.read mail.send"

Utilisez la commande suivante pour authentifier l’utilisateur à l’intérieur de la session PowerShell actuelle.
```
# Authenticate the user
Connect-MgGraph -ClientId $clientId -TenantId $tenantId -Scopes $graphScopes -UseDeviceAuthentication
```
Conseil

Si vous préférez utiliser l’authentification interactive du navigateur, omettez le -UseDeviceAuthentication paramètre .
Ouvrez un navigateur et accédez à l’URL affichée. Entrez le code fourni et connectez-vous.

Importante

Gardez à l’esprit tous les comptes Microsoft 365 existants qui sont connectés à votre navigateur lorsque vous accédez à https://microsoft.com/devicelogin. Utilisez les fonctionnalités du navigateur telles que les profils, le mode invité ou le mode privé pour vous assurer que vous vous authentifiez en tant que compte que vous envisagez d’utiliser pour les tests.

Une fois terminé, revenez à la fenêtre PowerShell. Exécutez la commande suivante pour vérifier le contexte authentifié.

# Get the Graph context
Get-MgContext

ClientId              : 2fb1652f-a9a0-4db9-b220-b224b8d9d38b
TenantId              : 601faea3-be45-4960-898f-92b379b17cd9
CertificateThumbprint :
Scopes                : {Mail.Read, Mail.Send, openid, profile…}
AuthType              : Delegated
AuthProviderType      : DeviceCodeProvider
CertificateName       :
Account               : MeganB@contoso.com
AppName               : PowerShell Graph Tutorial
ContextScope          : CurrentUser
Certificate           :
PSHostVersion         : 2022.4.1
ClientTimeout         : 00:05:00

Obtenir un utilisateur

12 minutes restantes

Dans cette section, vous allez obtenir l’utilisateur authentifié.

Dans votre session PowerShell authentifiée, exécutez la commande suivante pour obtenir le contexte actuel. Le contexte fournit des informations permettant d’identifier l’utilisateur authentifié.
```
$context = Get-MgContext
```
Exécutez la commande suivante pour obtenir l’utilisateur à partir de Microsoft Graph.
```
# Get the authenticated user by UPN
$user = Get-MgUser -UserId $context.Account -Select 'displayName, id, mail, userPrincipalName'
```
Conseil

Vous pouvez ajouter le -Debug commutateur à la commande précédente pour afficher la demande et la réponse de l’API.

Exécutez les commandes suivantes pour générer des informations utilisateur.

Write-Host "Hello," $user.DisplayName
# For Work/school accounts, email is in Mail property
# Personal accounts, email is in UserPrincipalName
Write-Host "Email:", ($user.Mail ?? $user.UserPrincipalName)

Hello, Megan Bowen!
Email: MeganB@contoso.com

Explication du code

Considérez la commande utilisée pour obtenir l’utilisateur authentifié. Il s’agit d’une commande apparemment simple, mais il y a quelques détails clés à noter.

Accès à « moi »

La Get-MgUser commande génère une requête à l’API Obtenir l’utilisateur . Cette API est accessible de deux façons :

GET /me
GET /users/{user-id}

Le Kit de développement logiciel (SDK) Microsoft Graph PowerShell ne prend pas en charge le point de terminaison d’API GET /me . Pour utiliser le point de GEt /users/{user-id} terminaison, nous devons fournir une valeur pour le {user-id} paramètre . Dans l’exemple ci-dessus, la $context.Account valeur est utilisée. Cette valeur contient le nom d’utilisateur principal (UPN) de l’utilisateur authentifié.

Demande de propriétés spécifiques

La fonction utilise le -Select paramètre sur la commande pour spécifier le jeu de propriétés dont elle a besoin. Cela ajoute le paramètre de requête $select à l’appel d’API.

Type de retour fortement typé

La fonction retourne un MicrosoftGraphUser objet désérialisé à partir de la réponse JSON de l’API. Étant donné que la commande utilise -Select, seules les propriétés demandées auront des valeurs dans l’objet retourné. Toutes les autres propriétés ont des valeurs par défaut.

Boîte de réception de liste

10 minutes restantes

Dans cette section, vous allez répertorier les messages dans la boîte de réception de messagerie de l’utilisateur.

Dans votre session PowerShell authentifiée, vérifiez que la $user variable est définie.
```
PS > $user.DisplayName
Megan Bowen
```

Exécutez la commande suivante pour répertorier la boîte de réception de l’utilisateur.

Get-MgUserMailFolderMessage -UserId $user.Id -MailFolderId Inbox -Select `
  "from,isRead,receivedDateTime,subject" -OrderBy "receivedDateTime DESC" `
  -Top 25 | Format-Table Subject,@{n='From';e={$_.From.EmailAddress.Name}}, `
  IsRead,ReceivedDateTime

Passez en revue la sortie.

Subject                                    From                    IsRead ReceivedDateTime
-------                                    ----                    ------ ----------------
Updates from Ask HR and other communities  Contoso Demo on Yammer  False  4/19/2022 10:19:02 PM
Employee Initiative Thoughts               Patti Fernandez         False  4/19/2022 3:15:56 PM
Voice Mail (11 seconds)                    Alex Wilber             False  4/18/2022 2:24:16 PM
Our Spring Blog Update                     Alex Wilber             True   4/18/2022 1:52:03 PM
Atlanta Flight Reservation                 Alex Wilber             False  4/13/2022 2:30:27 AM
Atlanta Trip Itinerary - down time         Alex Wilber             False  4/12/2022 4:46:01 PM

Explication du code

Considérez la commande utilisée pour répertorier la boîte de réception de l’utilisateur

Accès aux dossiers de courrier connus

La Get-MgUserMailFolderMessage commande génère une requête à l’API Répertorier les messages , en utilisant spécifiquement le point de GET /users/{user-id}/mailFolders/{folder-id}/messages terminaison. À l’aide de ce point de terminaison, l’API retourne uniquement les messages dans le dossier de messagerie demandé. Dans ce cas, étant donné que la boîte de réception est un dossier par défaut connu dans la boîte aux lettres d’un utilisateur, elle est accessible via son nom connu : -MailFolderId Inbox. Les dossiers autres que les dossiers par défaut sont accessibles de la même façon, en remplaçant le nom connu par la propriété ID du dossier de messagerie. Pour plus d’informations sur les noms de dossiers connus disponibles, consultez Type de ressource mailFolder.

Accès à une collection

Contrairement à la Get-MgUser commande de la section précédente, qui retourne un seul objet, cette méthode retourne une collection de messages. La plupart des API de Microsoft Graph qui retournent une collection ne retournent pas tous les résultats disponibles dans une seule réponse. Au lieu de cela, ils utilisent la pagination pour retourner une partie des résultats tout en fournissant une méthode permettant aux clients de demander la « page » suivante.

Tailles de page par défaut

Les API qui utilisent la pagination implémentent une taille de page par défaut. Pour les messages, la valeur par défaut est 10. Les clients peuvent demander plus (ou moins) à l’aide du paramètre de requête $top . Dans le Kit de développement logiciel (SDK) Microsoft Graph PowerShell, cela s’effectue avec le -Top 25 paramètre .

Remarque

La valeur transmise via -Top est une limite supérieure, et non un nombre explicite. L’API retourne un certain nombre de messages jusqu’à la valeur spécifiée.

Tri des collections

La fonction utilise le -OrderBy paramètre sur la demande pour demander des résultats triés au moment de la réception du message (receivedDateTime propriété ). Il inclut les DESC mot clé afin que les messages reçus plus récemment soient répertoriés en premier. Cela ajoute le paramètre de requête $orderby à l’appel d’API.

Envoyer un message

8 minutes restantes

Dans cette section, vous allez envoyer un e-mail en tant qu’utilisateur authentifié.

Dans votre session PowerShell authentifiée, vérifiez que la $user variable est définie.
```
PS > $user.DisplayName
Megan Bowen
```

Utilisez la commande suivante pour définir un objet représentant le corps de la demande pour l’API Envoyer un courrier .

$sendMailParams = @{
    Message = @{
        Subject = "Testing Microsoft Graph"
        Body = @{
            ContentType = "text"
            Content = "Hello world!"
        }
        ToRecipients = @(
            @{
                EmailAddress = @{
                    Address = ($user.Mail ?? $user.UserPrincipalName)
                }
            }
        )
    }
}

Utilisez la commande suivante pour envoyer le message.
```
Send-MgUserMail -UserId $user.Id -BodyParameter $sendMailParams
```
Remarque

Si vous effectuez des tests auprès d’un locataire développeur à partir du Programme pour développeurs Microsoft 365, l’e-mail que vous envoyez risque de ne pas être remis et vous pouvez recevoir un rapport de non-remise. Si cela vous arrive, contactez le support via le Centre d'administration Microsoft 365.
Pour vérifier que le message a été reçu, répétez la Get-MgUserMailFolderMessage commande de l’étape précédente.

Explication du code

Considérez les commandes utilisées pour envoyer un message.

Envoi de messages

La Send-MgUserMail commande génère une requête à l’API Envoyer un courrier .

Création d’objets

Contrairement aux appels précédents à Microsoft Graph qui ne lisent que les données, cet appel crée des données. Pour ce faire, vous créez un objet représentant le corps de la demande, définissez les propriétés souhaitées, puis transmettez-le dans le BodyParameter paramètre .

Facultatif : ajouter votre propre code

5 minutes restantes

Dans cette section, vous allez utiliser vos propres commandes du Kit de développement logiciel (SDK) Microsoft Graph PowerShell. Il peut s’agir d’un extrait de code de la documentation Microsoft Graph, d’un Explorer Graph ou d’un code que vous avez créé. Cette section est facultative.

Choisir une API

Recherchez une API dans Microsoft Graph que vous souhaitez essayer. Par exemple, l’API Créer un événement . Vous pouvez utiliser l’un des exemples de la documentation de l’API, personnaliser une demande d’API dans Graph Explorer et utiliser l’extrait de code généré, ou utiliser la Find-MgGraphCommand commande pour rechercher la commande correspondante.

Par exemple, l’un des points de terminaison d’API pour créer un événement est POST /users/{id | userPrincipalName}/events. Vous pouvez l’utiliser pour rechercher la commande PowerShell correspondante.

PS > Find-MgGraphCommand -Uri "/users/{id | userPrincipalName}/events" -Method "POST"

   APIVersion: v1.0

Command         Module   Method URI                     OutputType           Permissions           Variants
-------         ------   ------ ---                     ----------           -----------           --------
New-MgUserEvent Calendar POST   /users/{user-id}/events IMicrosoftGraphEvent {Calendars.ReadWrite} {Create1, CreateExp…

   APIVersion: beta

Command         Module   Method URI                     OutputType            Permissions           Variants
-------         ------   ------ ---                     ----------            -----------           --------
New-MgUserEvent Calendar POST   /users/{user-id}/events IMicrosoftGraphEvent1 {Calendars.ReadWrite} {Create, CreateExp…

La sortie indique que la New-MgUserEvent commande est la commande correspondante.

Configuration des autorisations

Consultez la section Autorisations de la documentation de référence de l’API choisie pour voir quelles méthodes d’authentification sont prises en charge. Certaines API ne prennent pas en charge l’authentification utilisateur (déléguée) ou les comptes Microsoft personnels, par exemple.

Déconnectez la session active (Disconnect-MgGraph) et reconnectez-vous avec l’autorisation requise dans le -Scopes paramètre .

Conseil

L’utilisation du -ForceRefresh paramètre avec la Connect-MgGraph commande garantit que les autorisations nouvellement configurées sont appliquées.

Exécuter la commande

Maintenant que vous êtes connecté avec les autorisations requises, exécutez la commande que vous avez choisie.

Créer des scripts PowerShell avec Microsoft Graph

Prerequisites

Inscrire l’application sur le portail

Inscrire l’application pour l’authentification utilisateur

Ajouter l’authentification utilisateur

Authentifier l’utilisateur

Obtenir un utilisateur

Explication du code

Accès à « moi »

Demande de propriétés spécifiques

Type de retour fortement typé

Boîte de réception de liste

Explication du code

Accès aux dossiers de courrier connus

Accès à une collection

Tailles de page par défaut

Tri des collections

Envoyer un message

Explication du code

Envoi de messages

Création d’objets

Facultatif : ajouter votre propre code

Choisir une API

Configuration des autorisations

Exécuter la commande

Félicitations !