Fazer chamadas de API usando os SDKs do Microsoft GraphMake API calls using the Microsoft Graph SDKs

As bibliotecas de serviço SDK do Microsoft Graph fornecem uma classe de cliente que você pode usar como o ponto de partida para a criação de todas as solicitações de API.The Microsoft Graph SDK service libraries provide a client class that you can use as the starting point for creating all API requests. Há 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") ).There are two styles of client class: one uses a fluent interface to create the request (for example, client.Users["user-id"].Manager) and the other accepts a path string (for example, api("/users/user-id/manager")). Quando você tem um objeto Request, é possível especificar uma variedade de opções, como filtragem e classificação, e, por fim, você seleciona o tipo de operação que deseja executar.When you have a request object, you can specify a variety of options such as filtering and sorting, and finally, you select the type of operation you want to perform.

Há também o SDK do Microsoft Graph PowerShell, que não tem nenhuma classe de cliente.There is also the Microsoft Graph PowerShell SDK, which has no client class at all. Em vez disso, todas as solicitações são representadas como comandos do PowerShell.Instead, all requests are represented as PowerShell commands. Por exemplo, para obter o gerente de um usuário, o comando é Get-MgUserManager .For example, to get a user's manager, the command is Get-MgUserManager. Para obter mais informações sobre como localizar comandos para chamadas de API, consulte navegação no Microsoft Graph PowerShell SDK.For more information on finding commands for API calls, see Navigating the Microsoft Graph PowerShell SDK.

Ler informações do Microsoft GraphRead information from Microsoft Graph

Para ler informações do Microsoft Graph, você precisa primeiro criar um objeto Request e, em seguida, executar o GET método na solicitação.To read information from Microsoft Graph, you first need to create a request object and then run the GET method on the request.

// GET https://graph.microsoft.com/v1.0/me

var user = await graphClient.Me
    .Request()
    .GetAsync();

Use $select para controlar as propriedades retornadasUse $select to control the properties returned

Ao recuperar uma entidade, nem todas as propriedades são recuperadas automaticamente; às vezes, eles precisam ser explicitamente selecionados.When retrieving an entity, not all properties are automatically retrieved; sometimes they need to be explicitly selected. Além disso, em alguns cenários, não é necessário retornar o conjunto de propriedades padrão.Also, in some scenarios it isn't necessary to return the default set of properties. Selecionar apenas as propriedades necessárias pode melhorar o desempenho da solicitação.Selecting just the required properties can improve the performance of the request. Você pode personalizar a solicitação para incluir o $select parâmetro de consulta com uma lista de propriedades.You can customize the request to include the $select query parameter with a list of properties.

// GET https://graph.microsoft.com/v1.0/me?$select=displayName,jobTitle

var user = await graphClient.Me
    .Request()
    .Select(u => new {
        u.DisplayName,
        u.JobTitle
    })
    .GetAsync();

Recuperar uma lista de entidadesRetrieve a list of entities

A recuperação de uma lista de entidades é semelhante à recuperação de uma única entidade, exceto por várias outras opções de configuração da solicitação.Retrieving a list of entities is similar to retrieving a single entity except there a number of other options for configuring the request. O $filter parâmetro de consulta pode ser usado para reduzir o conjunto de resultados apenas às linhas que correspondem à condição fornecida.The $filter query parameter can be used to reduce the result set to only those rows that match the provided condition. O $orderBy parâmetro de consulta solicitará que o servidor forneça a lista de entidades classificadas pelas propriedades especificadas.The $orderBy query parameter will request that the server provide the list of entities sorted by the specified properties.

// GET https://graph.microsoft.com/v1.0/me/messages?$select=subject,sender&$filter=<some condition>&orderBy=receivedDateTime

var messages = await graphClient.Me.Messages
    .Request()
    .Select(m => new {
        m.Subject,
        m.Sender
    })
    .Filter("<filter condition>")
    .OrderBy("receivedDateTime")
    .GetAsync();

O objeto retornado ao recuperar uma lista de entidades provavelmente será uma coleção paginável.The object returned when retrieving a list of entities is likely to be a paged collection. Para obter detalhes sobre como obter a lista completa de entidades, consulte paginação por meio de uma coleção.For details about how to get the complete list of entities, see paging through a collection.

Acessar um item de uma coleçãoAccess an item of a collection

Para SDKs que oferecem suporte a um estilo fluente, as coleções de entidades podem ser acessadas usando um índice de matriz.For SDKs that support a fluent style, collections of entities can be accessed using an array index. Para SDKs baseados em modelo, é suficiente incorporar o identificador de item no segmento de caminho após a coleção.For template-based SDKs, it is sufficient to embed the item identifier in the path segment following the collection. Para o PowerShell, os identificadores são passados como parâmetros.For PowerShell, identifiers are passed as parameters.

// GET https://graph.microsoft.com/v1.0/me/messages/{message-id}

string messageId = "AQMkAGUy..";
var message = await graphClient.Me.Messages[messageId]
    .Request()
    .GetAsync();

Você pode usar o $expand filtro para solicitar uma entidade relacionada, ou uma coleção de entidades, ao mesmo que você solicite a entidade principal.You can use the $expand filter to request a related entity, or collection of entities, at the same that you request the main entity.

// GET https://graph.microsoft.com/v1.0/me/messages/{message-id}?$expand=attachments

string messageId = "AQMkAGUy...";
var message = await graphClient.Me.Messages[messageId]
    .Request()
    .Expand("attachments")
    .GetAsync();

Excluir uma entidadeDelete an entity

As solicitações Delete são criadas da mesma maneira que as solicitações para recuperar uma entidade, mas usam uma DELETE solicitação em vez de um GET .Delete requests are constructed in the same way as requests to retrieve an entity, but use a DELETE request instead of a GET.

// DELETE https://graph.microsoft.com/v1.0/me/messages/{message-id}

string messageId = "AQMkAGUy...";
var message = await graphClient.Me.Messages[messageId]
    .Request()
    .DeleteAsync();

Fazer uma solicitação POST para criar uma nova entidadeMake a POST request to create a new entity

Para SDKs que oferecem suporte a um estilo fluente, novos itens podem ser adicionados às coleções com um Add método.For SDKs that support a fluent style, new items can be added to collections with an Add method. Para SDKs baseados em modelo, o objeto Request expõe um post método.For template-based SDKs, the request object exposes a post method. Para o PowerShell, um New-* comando disponível que aceita parâmetros que mapeiam a entidade a ser adicionada.For PowerShell, a New-* command is available that accepts parameters that map to the entity to add. A entidade criada é normalmente retornada da chamada.The created entity is usually returned from the call.

// POST https://graph.microsoft.com/v1.0/me/calendars

var calendar = new Calendar
{
    Name = "Volunteer"
};

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

Atualizando uma entidade existente com PATCHUpdating an existing entity with PATCH

A maioria das atualizações no Microsoft Graph é realizada usando um PATCH método e, portanto, só é necessário incluir as propriedades que você deseja alterar no objeto aprovado.Most updates in Microsoft Graph are performed using a PATCH method and therefore it is only necessary to include the properties that you want to change in the object you pass.

// PATCH https://graph.microsoft.com/v1.0/teams/{team-id}

var team = new Team
{
    FunSettings = new TeamFunSettings
    {
        AllowGiphy = true,
        GiphyContentRating = GiphyRatingType.Strict
    }
};

var teamId = "71766077-aacc-470a-be5e-ba47db3b2e88";

await graphClient.Teams[teamId]
    .Request()
    .UpdateAsync(team);

Usar cabeçalhos HTTP para controlar o comportamento da solicitaçãoUse HTTP headers to control request behavior

Você pode usar uma Header() função para anexar cabeçalhos personalizados a uma solicitação.You can use a Header() function to attach custom headers to a request. Para o PowerShell, a adição de cabeçalhos só é possível com o Invoke-GraphRequest método.For PowerShell, adding headers is only possible with the Invoke-GraphRequest method. Vários cenários do Microsoft Graph usam cabeçalhos personalizados para ajustar o comportamento da solicitação.A number of Microsoft Graph scenarios use custom headers to adjust the behavior of the request.

//  GET https://graph.microsoft.com/v1.0/users/{user-id}/events

var events = await graphClient.Me.Events
    .Request()
    .Header("Prefer",@"outlook.timezone=""Pacific Standard Time""")
    .Select( e => new {
        e.Subject,
        e.Body,
        e.BodyPreview
    })
    .GetAsync();

Fornecer parâmetros de consulta personalizadosProvide custom query parameters

Para SDKs que oferecem suporte a um estilo fluente, você pode fornecer valores de parâmetro de consulta personalizados usando uma lista de QueryOptions objetos.For SDKs that support a fluent style, you can provide custom query parameter values by using a list of QueryOptions objects. Para SDKs baseados em modelo, os parâmetros são codificados por URL e adicionados à URI de solicitação.For template-based SDKs, the parameters are URL-encoded and added to the request URI. Para o PowerShell, os parâmetros de consulta definidos para uma determinada API são expostos como parâmetros para o comando correspondente.For PowerShell, defined query parameters for a given API are exposed as parameters to the corresponding command.

//GET https://graph.microsoft.com/v1.0/me/calendarView

var queryOptions = new List<QueryOption>()
{
    new QueryOption("startdate", "2020-12-01T00:00:00Z"),
    new QueryOption("enddate", "2020-12-30T00:00:00Z")
};

var calendar = await graphClient.Me.CalendarView()
    .Request(queryOptions)
    .GetAsync();