Effectuer des appels d’API à l’aide des Kits de développement logiciel (SDK) Microsoft Graph

  • Article

Les bibliothèques de service du Kit de développement logiciel (SDK) Microsoft Graph fournissent une classe cliente à utiliser comme point de départ pour créer toutes les demandes d’API. Il existe deux styles de classe client : l’un utilise une interface Fluent pour créer la requête (par exemple, client.Users["user-id"].Manager) et l’autre accepte une chaîne de chemin d’accès (par exemple, api("/users/user-id/manager")). Lorsque vous avez un objet de requête, vous pouvez spécifier différentes options, telles que le filtrage et le tri, et enfin, vous sélectionnez le type d’opération que vous souhaitez effectuer.

Il existe également le Kit de développement logiciel (SDK) Microsoft Graph PowerShell, qui n’a pas de classe cliente. Au lieu de cela, toutes les requêtes sont représentées sous forme de commandes PowerShell. Par exemple, pour obtenir le responsable d’un utilisateur, la commande est Get-MgUserManager. Pour plus d’informations sur la recherche de commandes pour les appels d’API, consultez Navigation dans le Kit de développement logiciel (SDK) Microsoft Graph PowerShell.

Lire les informations de Microsoft Graph

Pour lire des informations à partir de Microsoft Graph, vous devez d’abord créer un objet de requête, puis exécuter la GET méthode sur la requête.

// GET https://graph.microsoft.com/v1.0/me
var user = await graphClient.Me
    .GetAsync();

Utiliser $select pour contrôler les propriétés retournées

Lors de la récupération d’une entité, toutes les propriétés ne sont pas récupérées automatiquement ; parfois, ils doivent être explicitement sélectionnés. En outre, le renvoi du jeu de propriétés par défaut n’est pas nécessaire dans certains scénarios. Sélectionner uniquement les propriétés requises peut améliorer les performances de la requête. Vous pouvez personnaliser la demande pour inclure le $select paramètre de requête avec une liste de propriétés.

// GET https://graph.microsoft.com/v1.0/me?$select=displayName,jobTitle
var user = await graphClient.Me
    .GetAsync(requestConfiguration =>
    {
        requestConfiguration.QueryParameters.Select =
            ["displayName", "jobTitle"];
    });

Récupérer une liste d’entités

La récupération d’une liste d’entités est similaire à la récupération d’une seule entité, sauf qu’il existe d’autres options pour configurer la requête. Le $filter paramètre de requête peut réduire le jeu de résultats uniquement aux lignes qui correspondent à la condition fournie. Le $orderby paramètre de requête demande au serveur de fournir la liste des entités triées par les propriétés spécifiées.

Remarque

Certaines demandes de ressources Microsoft Entra nécessitent l’utilisation de fonctionnalités de requête avancées. Si vous obtenez une réponse indiquant une requête incorrecte, une requête non prise en charge ou une réponse qui inclut des résultats inattendus, y compris le paramètre de requête et ConsistencyLevel l’en-tête $count peut permettre à la requête de réussir. Pour plus d’informations et d’exemples, consultez Fonctionnalités de requête avancées sur les objets d’annuaire.

// GET https://graph.microsoft.com/v1.0/me/messages?
// $select=subject,sender&$filter=subject eq 'Hello world'
var messages = await graphClient.Me.Messages
    .GetAsync(requestConfig =>
    {
        requestConfig.QueryParameters.Select =
            ["subject", "sender"];
        requestConfig.QueryParameters.Filter =
            "subject eq 'Hello world'";
    });

L’objet retourné lors de la récupération d’une liste d’entités est probablement une collection paginée. Pour plus d’informations sur la façon d’obtenir la liste complète des entités, consultez Pagination dans une collection.

Accéder à un élément d’une collection

Pour les sdk qui prennent en charge un style Fluent, les collections d’entités sont accessibles à l’aide d’un index de tableau. Pour les sdk basés sur des modèles, il suffit d’incorporer l’identificateur d’élément dans le segment de chemin d’accès suivant la collection. Pour PowerShell, les identificateurs sont passés en tant que paramètres.

// GET https://graph.microsoft.com/v1.0/me/messages/{message-id}
// messageId is a string containing the id property of the message
var message = await graphClient.Me.Messages[messageId]
    .GetAsync();

Vous pouvez utiliser le $expand filtre pour demander une entité ou une collection d’entités associées en même temps que vous demandez l’entité main.

// GET https://graph.microsoft.com/v1.0/me/messages/{message-id}?$expand=attachments
// messageId is a string containing the id property of the message
var message = await graphClient.Me.Messages[messageId]
    .GetAsync(requestConfig =>
        requestConfig.QueryParameters.Expand =
            ["attachments"]);

Supprimer une entité

Les demandes de suppression sont construites de la même façon que les demandes de récupération d’une entité, mais utilisez une DELETE requête au lieu d’un GET.

// DELETE https://graph.microsoft.com/v1.0/me/messages/{message-id}
// messageId is a string containing the id property of the message
await graphClient.Me.Messages[messageId]
    .DeleteAsync();

Effectuer une requête POST pour créer une entité

Pour les Kits de développement logiciel (SDK) qui prennent en charge un style fluent, de nouveaux éléments peuvent être ajoutés aux collections avec une Add méthode . Pour les sdk basés sur un modèle, l’objet de requête expose une post méthode. Pour PowerShell, une New-* commande accepte les paramètres qui sont mappés à l’entité à ajouter. L’entité créée est retournée à partir de l’appel.

// POST https://graph.microsoft.com/v1.0/me/calendars
var calendar = new Calendar
{
    Name = "Volunteer",
};

var newCalendar = await graphClient.Me.Calendars
    .PostAsync(calendar);

Mise à jour d’une entité existante avec PATCH

La plupart des mises à jour dans Microsoft Graph sont effectuées à l’aide d’une PATCH méthode . Par conséquent, il est uniquement nécessaire d’inclure les propriétés que vous souhaitez modifier dans l’objet que vous passez.

// PATCH https://graph.microsoft.com/v1.0/teams/{team-id}
var team = new Team
{
    FunSettings = new TeamFunSettings
    {
        AllowGiphy = true,
        GiphyContentRating = GiphyRatingType.Strict,
    },
};

// teamId is a string containing the id property of the team
await graphClient.Teams[teamId]
    .PatchAsync(team);

Utiliser des en-têtes HTTP pour contrôler le comportement des requêtes

Vous pouvez attacher des en-têtes personnalisés à une requête à l’aide d’une Header() fonction . Pour PowerShell, l’ajout d’en-têtes n’est possible qu’avec la Invoke-GraphRequest méthode . Certains scénarios Microsoft Graph utilisent des en-têtes personnalisés pour ajuster le comportement de la requête.

// GET https://graph.microsoft.com/v1.0/me/events
var events = await graphClient.Me.Events
    .GetAsync(requestConfig =>
    {
        requestConfig.Headers.Add(
            "Prefer", @"outlook.timezone=""Pacific Standard Time""");
    });

Fournir des paramètres de requête personnalisés

Pour les sdk qui prennent en charge un style Fluent, vous pouvez fournir des valeurs de paramètres de requête personnalisées à l’aide d’une liste d’objets QueryOptions . Pour les sdk basés sur des modèles, les paramètres sont encodés dans une URL et ajoutés à l’URI de la requête. Pour PowerShell et Go, les paramètres de requête définis pour une API donnée sont exposés en tant que paramètres à la commande correspondante.

// GET https://graph.microsoft.com/v1.0/me/calendarView?
// startDateTime=2023-06-14T00:00:00Z&endDateTime=2023-06-15T00:00:00Z
var events = await graphClient.Me.CalendarView
    .GetAsync(requestConfiguration =>
    {
        requestConfiguration.QueryParameters.StartDateTime =
            "2023-06-14T00:00:00Z";
        requestConfiguration.QueryParameters.EndDateTime =
            "2023-06-15T00:00:00Z";
    });