Partilhar via


Efetuar chamadas à API com os SDKs do Microsoft Graph

As bibliotecas de serviço do SDK do Microsoft Graph fornecem uma classe de cliente para utilizar como ponto de partida para criar todos os pedidos de API. Existem dois estilos de classe de cliente: um utiliza uma interface fluente para criar o pedido (por exemplo, client.Users["user-id"].Manager) e o outro aceita uma cadeia de caminho (por exemplo, api("/users/user-id/manager")). Quando tem um objeto de pedido, pode especificar várias opções, como filtragem e ordenação e, por fim, seleciona o tipo de operação que pretende executar.

Também existe o SDK do PowerShell do Microsoft Graph, que não tem classe de cliente. Em vez disso, todos os pedidos são representados como comandos do PowerShell. Por exemplo, para obter o gestor de um utilizador, o comando é Get-MgUserManager. Para obter mais informações sobre como localizar comandos para chamadas à API, veja Navegar no SDK do PowerShell do Microsoft Graph.

Ler informações do Microsoft Graph

Para ler informações do Microsoft Graph, primeiro tem de criar um objeto de pedido e, em seguida, executar o GET método no pedido.

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

Utilizar $select para controlar as propriedades devolvidas

Ao obter uma entidade, nem todas as propriedades são obtidas automaticamente; por vezes, têm de ser explicitamente selecionados. Além disso, não é necessário devolver o conjunto predefinido de propriedades em alguns cenários. Selecionar apenas as propriedades necessárias pode melhorar o desempenho do pedido. Pode personalizar o pedido para incluir o $select parâmetro de consulta com uma lista de propriedades.

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

Obter uma lista de entidades

Obter uma lista de entidades é semelhante à obtenção de uma única entidade, exceto que existem outras opções para configurar o pedido. O $filter parâmetro de consulta pode reduzir o conjunto de resultados apenas para as linhas que correspondem à condição fornecida. O $orderby parâmetro de consulta pede que o servidor forneça a lista de entidades ordenadas pelas propriedades especificadas.

Observação

Alguns pedidos de recursos Microsoft Entra requerem a utilização de capacidades de consulta avançadas. Se receber uma resposta a indicar um pedido incorreto, uma consulta não suportada ou uma resposta que inclua resultados inesperados, incluindo o parâmetro de consulta e ConsistencyLevel o $count cabeçalho, poderá permitir que o pedido seja bem-sucedido. Para obter detalhes e exemplos, veja Capacidades avançadas de consulta em objetos de diretório.

// 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'";
    });

O objeto devolvido ao obter uma lista de entidades será provavelmente uma coleção paginada. Para obter detalhes sobre como obter a lista completa de entidades, veja paginação através de uma coleção.

Aceder a um item de uma coleção

Para os SDKs que suportam um estilo fluente, as coleções de entidades podem ser acedidas através de um índice de matriz. Para os SDKs baseados em modelos, é suficiente incorporar o identificador de item no segmento de caminho a seguir à coleção. Para o PowerShell, os identificadores são transmitidos como parâmetros.

// 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();

Pode utilizar o $expand filtro para pedir uma entidade relacionada ou uma coleção de entidades ao mesmo tempo que pede a entidade principal.

// 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"]);

Eliminar uma entidade

Os pedidos de eliminação são criados da mesma forma que os pedidos para obter uma entidade, mas utilize um DELETE pedido em vez de um 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();

Criar uma nova entidade com POST

Para estilo fluente e SDKs baseados em modelos, podem ser adicionados novos itens a coleções com um POST método. Para o PowerShell, um New-* comando aceita parâmetros que mapeiam para a entidade a adicionar. A entidade criada é devolvida a partir da chamada.

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

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

Atualizar uma entidade existente com PATCH

A maioria das atualizações no Microsoft Graph são efetuadas através de um PATCH método. Por conseguinte, só é necessário incluir as propriedades que pretende alterar no objeto que transmite.

// 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);

Utilizar cabeçalhos HTTP para controlar o comportamento dos pedidos

Pode anexar cabeçalhos personalizados a um pedido através da Headers coleção. Para o PowerShell, a adição de cabeçalhos só é possível com o Invoke-GraphRequest método . Alguns cenários do Microsoft Graph utilizam cabeçalhos personalizados para ajustar o comportamento do pedido.

// 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""");
    });

Fornecer parâmetros de consulta personalizados

Para os SDKs que suportam o estilo fluente, pode fornecer valores de parâmetros de consulta personalizados com o QueryParameters objeto . Para os SDKs baseados em modelos, os parâmetros são codificados com URL e adicionados ao URI do pedido. Para o PowerShell e Go, os parâmetros de consulta definidos para uma determinada API são expostos como parâmetros ao comando correspondente.

// 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";
    });