Faça chamadas à API usando os SDKs do Microsoft Graph

As bibliotecas de serviço do SDK do Microsoft Graph fornecem uma classe de cliente a ser usada como ponto de partida para criar todas as solicitações de API. Existem dois estilos de classe de cliente: um usa uma interface fluente para criar a solicitação (por exemplo, client.Users["user-id"].Manager) e o outro aceita uma cadeia de caracteres de caminho (por exemplo, api("/users/user-id/manager")). Quando você tem um objeto de solicitação, pode especificar várias opções, como filtragem e classificação, e, por fim, selecionar o tipo de operação que deseja executar.

Há também o SDK do Microsoft Graph PowerShell, que não tem nenhuma classe de cliente. Em vez disso, todas as solicitações são representadas como comandos do PowerShell. Por exemplo, para obter o gerente de um usuário, o comando é Get-MgUserManager. Para obter mais informações sobre como localizar comandos para chamadas de API, consulte Navegando no SDK do Microsoft Graph PowerShell.

Ler informações do Microsoft Graph

Para ler informações do Microsoft Graph, primeiro você precisa criar um objeto de solicitação e, em seguida, executar o GET método na solicitação.

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

Use $select para controlar as propriedades retornadas

Ao recuperar uma entidade, nem todas as propriedades são recuperadas automaticamente; Às vezes, eles precisam ser selecionados explicitamente. Além disso, retornar o conjunto padrão de propriedades não é necessário em alguns cenários. Selecionar apenas as propriedades necessárias pode melhorar o desempenho da solicitação. Você pode personalizar a solicitação 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"];
    });

Recuperar uma lista de entidades

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

Observação

Algumas solicitações de recursos do Microsoft Entra exigem o uso de recursos avançados de consulta. Se você receber uma resposta indicando uma solicitação incorreta, uma consulta sem suporte ou uma resposta que inclua resultados inesperados, incluindo o parâmetro de consulta e ConsistencyLevel o $count cabeçalho, poderá permitir que a solicitação seja bem-sucedida. Para obter detalhes e exemplos, consulte Recursos avançados 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 retornado ao recuperar uma lista de entidades provavelmente será uma coleção paginada. Para obter detalhes sobre como obter a lista completa de entidades, consulte Paginação por meio de uma coleção.

Acessar um item de uma coleção

Para SDKs que dão suporte a um estilo fluente, coleções de entidades podem ser acessadas usando um índice de matriz. Para SDKs baseados em modelo, é suficiente inserir o identificador de item no segmento de caminho após a coleção. Para o PowerShell, os identificadores são passados 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();

Você pode usar o $expand filtro para solicitar uma entidade relacionada ou um conjunto de entidades ao mesmo tempo em que solicita 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"]);

Excluir uma entidade

As solicitações de exclusão são construídas da mesma forma que as solicitações para recuperar uma entidade, mas usam uma DELETE solicitação 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();

Criando uma nova entidade com POST

Para SDKs de estilo fluente e baseados em modelo, novos itens podem ser adicionados a coleções com um POST método. Para o PowerShell, um New-* comando aceita parâmetros que mapeiam para a entidade a ser adicionada. A entidade criada é retornada 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);

Atualizando uma entidade existente com PATCH

A maioria das atualizações no Microsoft Graph é executada usando um PATCH método; portanto, só é necessário incluir as propriedades que você deseja alterar no objeto que você passa.

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

Usar cabeçalhos HTTP para controlar o comportamento da solicitação

Você pode anexar cabeçalhos personalizados a uma solicitação usando a Headers coleção. Para o PowerShell, adicionar cabeçalhos só é possível com o Invoke-GraphRequest método. Alguns cenários do Microsoft Graph usam cabeçalhos personalizados para ajustar o comportamento da solicitação.

// 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 SDKs que dão suporte ao estilo fluente, você pode fornecer valores de parâmetro de consulta personalizados usando o QueryParameters objeto. Para SDKs baseados em modelo, os parâmetros são codificados como URL-codificados e adicionados ao URI da solicitação. Para PowerShell e Go, os parâmetros de consulta definidos para uma determinada API são expostos como parâmetros para o 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";
    });
  • Last updated on