Fazer chamadas de API usando os SDKs do Microsoft Graph

  • Artigo

As bibliotecas de serviçoS SDK do Microsoft Graph fornecem uma classe cliente a ser usada como ponto de partida para criar todas as solicitações de API. Há dois estilos de classe 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, selecione o tipo de operação que deseja executar.

Há também o SDK do Microsoft Graph PowerShell, que não tem classe cliente. Em vez disso, todas as solicitações são representadas como comandos do PowerShell. Por exemplo, para obter o gerenciador de um usuário, o comando é Get-MgUserManager. Para obter mais informações sobre como encontrar comandos para chamadas de API, consulte Navegando pelo 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, elas precisam ser explicitamente selecionadas. Além disso, o retorno do 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 à recuperação de 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 correspondem à 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 Microsoft Entra exigem o uso de recursos avançados de consulta. Se você receber uma resposta indicando uma solicitação ruim, uma consulta sem suporte ou uma resposta que inclua resultados inesperados, incluindo o parâmetro de consulta e ConsistencyLevel o $count cabeçalho podem permitir que a solicitação tenha êxito. Para obter detalhes e exemplos, confira Recursos de consulta avançados 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 de páginas. Para obter detalhes sobre como obter a lista completa de entidades, confira 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 ou coleção de entidades relacionadas ao mesmo tempo em que solicita a entidade 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"]);

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

Fazer uma solicitação POST para criar uma nova entidade

Para SDKs que dão suporte a um estilo fluente, novos itens podem ser adicionados a coleções com um Add método. Para SDKs baseados em modelo, o objeto de solicitação expõe 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);

Atualizar 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 uma Header() funçã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 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 a um estilo fluente, você pode fornecer valores de parâmetro de consulta personalizados usando uma lista de QueryOptions objetos. Para SDKs baseados em modelo, os parâmetros são codificados por URL e adicionados ao URI de 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";
    });