Criar aplicativos .NET com o Microsoft Graph
Este tutorial ensina como criar um aplicativo de console do .NET que usa a API do Microsoft Graph.
Dica
Se você preferir apenas baixar o tutorial concluído, poderá baixar ou clonar o repositório GitHub.
Pré-requisitos
Antes de iniciar este tutorial, você deve ter o SDK do .NET instalado em seu computador de desenvolvimento.
Você também deve ter uma conta pessoal da Microsoft com uma caixa de correio Outlook.com ou uma conta corporativa ou de estudante da Microsoft. Se você não tiver uma conta da Microsoft, há algumas opções para obter uma conta gratuita:
- Você pode se inscrever para uma nova conta pessoal da Microsoft.
- Você pode se inscrever no Programa para Desenvolvedores do Microsoft 365 para obter uma assinatura gratuita do Microsoft 365.
Observação
Este tutorial foi escrito com o SDK do .NET versão 6.0.102. As etapas neste guia podem funcionar com outras versões, mas isso não foi testado.
Registrar o aplicativo no portal
Neste exercício, você registrará um novo aplicativo no Azure Active Directory para habilitar a autenticação do usuário. Você pode registrar um aplicativo usando o Azure Active Directory de administração ou usando o SDK do Microsoft Graph PowerShell.
Registrar aplicativo para autenticação de usuário
Nesta seção, você registrará um aplicativo que dá suporte à autenticação de usuário usando o fluxo de código do dispositivo.
Abra um navegador, navegue até o centro de administração do Azure Active Directory e faça logon usando uma conta pessoal (também conhecida como conta da Microsoft) ou Conta Corporativa ou de Estudante.
Selecione Azure Active Directory na navegação esquerda e selecione Registros de aplicativos em Gerenciar.
Selecione Novo registro. Insira um nome para seu aplicativo, por exemplo,
.NET Graph Tutorial.Defina os tipos de conta com suporte conforme desejado. As opções são:
Opção Who pode entrar? Contas apenas neste diretório organizacional Somente usuários em sua Microsoft 365 organização Contas em qualquer diretório organizacional Usuários em qualquer Microsoft 365 (contas corporativas ou de estudante) Contas em qualquer diretório organizacional... e contas pessoais da Microsoft Usuários em qualquer organização Microsoft 365 (contas corporativas ou de estudante) e contas pessoais da Microsoft Deixe o URI de Redirecionamento vazio.
Selecione Registrar. Na página Visão geral do aplicativo, copie o valor da ID do aplicativo (cliente) e salve-o. Você precisará dele na próxima etapa. Se você escolheu Contas neste diretório organizacional apenas para tipos de conta com suporte, copie também a ID do Diretório (locatário) e salve-a.
Selecione Autenticação em Gerenciar. Localize a seção Configurações avançadas e altere a alternância Permitir fluxos do cliente público para Sim e, em seguida, escolha Salvar.
Observação
Observe que você não configurou nenhuma permissão do Microsoft Graph no registro do aplicativo. Isso ocorre porque o exemplo usará o consentimento dinâmico para solicitar permissões específicas para autenticação do usuário.
Criar um aplicativo de console do .NET
Comece criando um novo projeto de console do .NET usando a CLI do .NET.
Abra sua CLI (interface de linha de comando) em um diretório em que você deseja criar o projeto. Execute o seguinte comando:
dotnet new console -o GraphTutorialDepois que o projeto for criado, verifique se ele funciona alterando o diretório atual para o diretório GraphTutorial e executando o comando a seguir em sua CLI.
dotnet runSe funcionar, o aplicativo deverá gerar saída
Hello, World!.
Instalar dependências
Antes de continuar, adicione algumas dependências adicionais que você usará posteriormente.
- Pacotes de configuração do .NET para ler a configuração de aplicativos de appsettings.json.
- Biblioteca de clientes de Identidade do Azure para .NET para autenticar o usuário e adquirir tokens de acesso.
- Microsoft Graph biblioteca de clientes .NET para fazer chamadas para o Microsoft Graph.
Execute os comandos a seguir na CLI para instalar as dependências.
dotnet add package Microsoft.Extensions.Configuration.Binder
dotnet add package Microsoft.Extensions.Configuration.Json
dotnet add package Azure.Identity
dotnet add package Microsoft.Graph
Carregar configurações do aplicativo
Nesta seção, você adicionará os detalhes do registro do aplicativo ao projeto.
Crie um arquivo no diretório GraphTutorial chamado appsettings.json e adicione o código a seguir.
Atualize os valores de acordo com a tabela a seguir.
Configuração Valor clientIdA ID do cliente do registro do aplicativo authTenantSe você escolheu a opção para permitir que apenas os usuários em sua organização se conectem, altere esse valor para sua ID de locatário. Caso contrário, deixe como common.Dica
Opcionalmente, você pode definir esses valores em um arquivo separado chamado appsettings. Development.json ou no Gerenciador de Segredos do .NET.
Atualize GraphTutorial.csproj para copiar appsettings.json para o diretório de saída. Adicione o código a seguir entre as
<Project>linhas</Project>.<ItemGroup> <None Include="appsettings*.json"> <CopyToOutputDirectory>Always</CopyToOutputDirectory> </None> </ItemGroup>Crie um arquivo no diretório GraphTutorial chamado Configurações.cs e adicione o código a seguir.
Design do aplicativo
Nesta seção, você criará um menu simples baseado em console.
Abra ./Program.cs e substitua todo o conteúdo pelo código a seguir.
Adicione os métodos de espaço reservado a seguir ao final do arquivo. Você os implementará em etapas posteriores.
void InitializeGraph() { // TODO } async Task GreetUserAsync() { // TODO } async Task DisplayAccessTokenAsync() { // TODO } async Task ListInboxAsync() { // TODO } async Task SendMailAsync() { // TODO } async Task ListUsersAsync() { // TODO } async Task MakeGraphCallAsync() { // TODO }
Isso implementa um menu básico e lê a escolha do usuário na linha de comando.
Adicionar autenticação de usuário
Nesta seção, você estenderá o aplicativo do exercício anterior para dar suporte à autenticação com Azure AD. Isso é necessário para obter o token de acesso OAuth necessário para chamar o Microsoft Graph. Nesta etapa, você integrará a biblioteca de clientes de Identidade do Azure para .NET ao aplicativo e configurará a autenticação para a biblioteca de clientes do Microsoft Graph .NET.
A biblioteca de identidade do Azure fornece várias TokenCredential classes que implementam fluxos de token OAuth2. A biblioteca de Graph microsoft usa essas classes para autenticar chamadas para o Microsoft Graph. Neste exemplo, usaremos as classes a TokenCredential seguir.
DeviceCodeCredentialimplementa o fluxo de código do dispositivo para autenticação do usuário.ClientSecretCredentialimplementa o fluxo de credenciais do cliente para autenticação somente de aplicativo. Você usará essa classe nas seções opcionais somente de aplicativo.
Configurar Graph cliente para autenticação de usuário
Nesta seção, você usará a classe para DeviceCodeCredential solicitar um token de acesso usando o fluxo de código do dispositivo.
Crie um novo arquivo no diretório GraphTutorial chamado GraphHelper.cs e adicione o código a seguir a esse arquivo.
using Azure.Core; using Azure.Identity; using Microsoft.Graph; class GraphHelper { }Adicione o seguinte código à classe
GraphHelper.Substitua a função
InitializeGraphvazia em Program.cs pelo seguinte.
Esse código declara duas propriedades privadas, um DeviceCodeCredential objeto e um GraphServiceClient objeto. A InitializeGraphForUserAuth função cria uma nova instância de DeviceCodeCredential, em seguida, usa essa instância para criar uma nova instância de GraphServiceClient. Sempre que uma chamada à API for feita ao Microsoft Graph_userClient, ela usará a credencial fornecida para obter um token de acesso.
Testar o DeviceCodeCredential
Em seguida, adicione código para obter um token de acesso de DeviceCodeCredential.
Adicione a função a seguir à classe
GraphHelper.Substitua a função
DisplayAccessTokenAsyncvazia em Program.cs pelo seguinte.Compile e execute o aplicativo. Insira
1quando for solicitada uma opção. O aplicativo exibe uma URL e um código do dispositivo..NET Graph Tutorial Please choose one of the following options: 0. Exit 1. Display access token 2. List my inbox 3. Send mail 4. List users (requires app-only) 1 To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code RB2RUD56D to authenticate.Abra um navegador e navegue até a URL exibida. Insira o código fornecido e entre.
Importante
Lembre-se de todas as contas Microsoft 365 existentes que estão conectadas ao seu navegador ao navegar até
https://microsoft.com/devicelogin. Use recursos do navegador, como perfis, modo de convidado ou modo privado, para garantir que você se autentique como a conta que pretende usar para teste.Depois de concluído, retorne ao aplicativo para ver o token de acesso.
Dica
Somente para fins de validação e depuração , você pode decodificar tokens de acesso do usuário (somente para contas corporativas ou de estudante) usando o analisador de token online da Microsoft em https://jwt.ms. Isso pode ser útil se você encontrar erros de token ao chamar o Microsoft Graph. Por exemplo, verificar se a declaração
scpno token contém os escopos de permissão Graph Microsoft esperados.
Obter usuário
Nesta seção, você incorporará o microsoft Graph no aplicativo. Para este aplicativo, você usará a Biblioteca de Clientes do Microsoft Graph .NET para fazer chamadas para o Microsoft Graph.
Abra ./GraphHelper.cs e adicione a seguinte função à classe GraphHelper .
Substitua a função
GreetUserAsyncvazia em Program.cs pelo seguinte.
Se você executar o aplicativo agora, depois de fazer logon, o aplicativo receberá você pelo nome.
Hello, Megan Bowen!
Email: MeganB@contoso.com
Código explicado
Considere o código na GetUserAsync função. São apenas algumas linhas, mas há alguns detalhes importantes a serem notado.
Acessando 'eu'
A função usa o construtor _userClient.Me de solicitações, que cria uma solicitação para a API Obter usuário . Essa API pode ser acessada de duas maneiras:
GET /me
GET /users/{user-id}
Nesse caso, o código chamará o ponto de extremidade GET /me da API. Esse é um método de atalho para obter o usuário autenticado sem saber sua ID de usuário.
Observação
Como o GET /me ponto de extremidade da API obtém o usuário autenticado, ele só está disponível para aplicativos que usam autenticação de usuário. Os aplicativos de autenticação somente de aplicativo não podem acessar esse ponto de extremidade.
Solicitando propriedades específicas
A função usa o Select método na solicitação para especificar o conjunto de propriedades de que precisa. Isso adiciona o $select de consulta à chamada à API.
Tipo de retorno fortemente tipado
A função retorna um Microsoft.Graph.User objeto desserializado da resposta JSON da API. Como o código usa Select, somente as propriedades solicitadas terão valores no objeto User retornado. Todas as outras propriedades terão valores padrão.
Caixa de entrada de lista
Nesta seção, você adicionará a capacidade de listar mensagens na caixa de entrada de email do usuário.
Abra ./GraphHelper.cs e adicione a seguinte função à classe GraphHelper .
Substitua a função
ListInboxAsyncvazia em Program.cs pelo seguinte.Execute o aplicativo, entre e escolha a opção 2 para listar sua caixa de entrada.
Please choose one of the following options: 0. Exit 1. Display access token 2. List my inbox 3. Send mail 4. List users (requires app-only) 5. Make a Graph call 2 Message: Updates from Ask HR and other communities From: Contoso Demo on Yammer Status: Read Received: 12/30/2021 4:54:54 AM -05:00 Message: Employee Initiative Thoughts From: Patti Fernandez Status: Read Received: 12/28/2021 5:01:10 PM -05:00 Message: Voice Mail (11 seconds) From: Alex Wilber Status: Unread Received: 12/28/2021 5:00:46 PM -05:00 Message: Our Spring Blog Update From: Alex Wilber Status: Unread Received: 12/28/2021 4:49:46 PM -05:00 Message: Atlanta Flight Reservation From: Alex Wilber Status: Unread Received: 12/28/2021 4:35:42 PM -05:00 Message: Atlanta Trip Itinerary - down time From: Alex Wilber Status: Unread Received: 12/28/2021 4:22:04 PM -05:00 ... More messages available? True
Código explicado
Considere o código na GetInboxAsync função.
Acessando pastas de email conhecidas
A função usa o construtor _userClient.Me.MailFolders["Inbox"].Messages de solicitações, que cria uma solicitação para a API listar mensagens . Como inclui o construtor de MailFolders["Inbox"] solicitações, a API retornará apenas mensagens na pasta de email solicitada. Nesse caso, como a caixa de entrada é uma pasta padrão e conhecida dentro da caixa de correio de um usuário, ela é acessível por meio de seu nome conhecido. As pastas não padrão são acessadas da mesma maneira, substituindo o nome conhecido pela propriedade de ID da pasta de email. Para obter detalhes sobre os nomes de pasta conhecidos disponíveis, consulte o tipo de recurso mailFolder.
Acessando uma coleção
Ao contrário GetUserAsync da função da seção anterior, que retorna um único objeto, esse método retorna uma coleção de mensagens. A maioria das APIs no Microsoft Graph que retornam uma coleção não retorna todos os resultados disponíveis em uma única resposta. Em vez disso, eles usam a paginação para retornar uma parte dos resultados, fornecendo um método para os clientes solicitarem a próxima "página".
Tamanhos de página padrão
As APIs que usam paginação implementam um tamanho de página padrão. Para mensagens, o valor padrão é 10. Os clientes podem solicitar mais (ou menos) usando o parâmetro $top consulta. Em GetInboxAsync, isso é feito com o .Top(25) método.
Observação
O valor passado é .Top() um limite superior, não um número explícito. A API retorna um número de mensagens até o valor especificado.
Obtendo páginas subsequentes
Se houver mais resultados disponíveis no servidor, @odata.nextLink as respostas da coleção incluirão uma propriedade com uma URL de API para acessar a próxima página. A biblioteca de clientes do .NET expõe isso como a propriedade NextPageRequest em objetos de página de coleção. Se essa propriedade não for nula, haverá mais resultados disponíveis.
A NextPageRequest propriedade expõe um método GetAsync que retorna a próxima página.
Classificando coleções
A função usa o OrderBy método na solicitação para solicitar resultados classificados pelo momento em que a mensagem é recebida (ReceivedDateTime propriedade). Ele inclui a palavra-chave DESC para que as mensagens recebidas mais recentemente sejam listadas primeiro. Isso adiciona o $orderby de consulta à chamada à API.
Enviar email
Nesta seção, você adicionará a capacidade de enviar uma mensagem de email como o usuário autenticado.
Abra ./GraphHelper.cs e adicione a seguinte função à classe GraphHelper .
Substitua a função
SendMailAsyncvazia em Program.cs pelo seguinte.Execute o aplicativo, entre e escolha a opção 3 para enviar um email para si mesmo.
Please choose one of the following options: 0. Exit 1. Display access token 2. List my inbox 3. Send mail 4. List users (requires app-only) 5. Make a Graph call 3 Mail sent.Observação
Se você estiver testando com um locatário de desenvolvedor do Microsoft 365 Developer Program, o email enviado poderá não ser entregue e você poderá receber um relatório de não entrega. Se isso acontecer com você, entre em contato com o suporte por meio do Centro de administração do Microsoft 365.
Código explicado
Considere o código na SendMailAsync função.
Enviar email
A função usa o construtor _userClient.Me.SendMail de solicitações, que cria uma solicitação para a API enviar email . O construtor de solicitações usa um Message objeto que representa a mensagem a ser enviada.
Criando objetos
Ao contrário das chamadas anteriores ao Microsoft Graph que somente leem dados, essa chamada cria dados. Para fazer isso com a biblioteca de clientes, crie uma instância da classe que representa os dados (nesse caso, Microsoft.Graph.Message) new usando a palavra-chave, defina as propriedades desejadas e, em seguida, envie-a na chamada à API. Como a chamada está enviando dados, o PostAsync método é usado em vez de GetAsync.
Opcional: configurar a autenticação somente de aplicativo
Nesta seção, você atualizará o registro do aplicativo da seção anterior para dar suporte à autenticação somente de aplicativo. A autenticação somente de aplicativo é uma boa opção para serviços em segundo plano e também há algumas APIs que dão suporte apenas à autenticação somente de aplicativo. Você só precisará concluir esta seção se pretende usar as partes somente de aplicativo deste tutorial. Caso contrário, você pode pular com segurança para a próxima etapa.
Importante
As etapas nesta seção exigem uma conta corporativa/de estudante com a Administrador global função.
Abra o registro do aplicativo na seção anterior no Azure AD de administração.
Selecione Permissões de API em Gerenciar.
Remova a permissão User.Read padrão em Permissões configuradas selecionando as reticências (...) em sua linha e selecionando Remover permissão.
Selecione Adicionar uma permissão e, em seguida, Microsoft Graph.
Selecione Permissões de aplicativo.
Selecione User.Read.All e, em seguida, selecione Adicionar permissões.
Selecione Conceder consentimento do administrador para... e, em seguida, selecione Sim para fornecer consentimento do administrador para a permissão selecionada.
Selecione Certificados e segredos em Gerenciar e, em seguida, selecione Novo segredo do cliente.
Insira uma descrição, escolha uma duração e selecione Adicionar.
Copie o segredo da coluna Valor , você precisará dele nas próximas etapas.
Importante
Este segredo do cliente nunca é mostrado novamente, portanto, certifique-se de copiá-lo agora.
Observação
Observe que, ao contrário das etapas ao se registrar para autenticação do usuário, nesta seção você configurou as permissões do Microsoft Graph no registro do aplicativo. Isso ocorre porque a autenticação somente de aplicativo usa o fluxo de credenciais do cliente, o que exige que as permissões sejam configuradas no registro do aplicativo. Consulte o escopo .default para obter detalhes.
Opcional: adicionar autenticação somente de aplicativo
Nesta seção, você adicionará a autenticação somente de aplicativo ao aplicativo. Esta seção é opcional e requer a conclusão de Opcional: configurar a autenticação somente de aplicativo. Essas etapas só podem ser concluídas com uma conta corporativa ou de estudante.
Configurar Graph cliente para autenticação somente de aplicativo
Nesta seção, você usará a classe para ClientSecretCredential solicitar um token de acesso usando o fluxo de credenciais do cliente.
Atualize o valor de
tenantIdem appsettings.json (ou appsettings. Development.json) com a ID de locatário da sua organização.Adicione o segredo do cliente ao Gerenciador de Segredos do .NET. Na interface de linha de comando, altere o diretório para o local de GraphTutorial.csproj e execute os comandos a seguir, <> substituindo o segredo do cliente pelo segredo do cliente.
dotnet user-secrets init dotnet user-secrets set settings:clientSecret <client-secret>Observação
O Gerenciador de Segredos do .NET só está disponível durante o desenvolvimento. Os aplicativos de produção devem armazenar segredos do cliente em um repositório seguro, como o Azure Key Vault.
Abra ./GraphHelper.cs e adicione o código a seguir à classe GraphHelper .
Opcional: listar usuários
Nesta seção, você adicionará a capacidade de listar todos os usuários em seu Azure Active Directory usando a autenticação somente de aplicativo. Esta seção é opcional e requer a conclusão de Opcional: configurar a autenticação somente de aplicativo e Opcional: adicionar autenticação somente de aplicativo. Essas etapas só podem ser concluídas com uma conta corporativa ou de estudante.
Abra ./GraphHelper.cs e adicione a seguinte função à classe GraphHelper .
Substitua a função
ListUsersAsyncvazia em Program.cs pelo seguinte.Execute o aplicativo, entre e escolha a opção 4 para listar usuários.
Please choose one of the following options: 0. Exit 1. Display access token 2. List my inbox 3. Send mail 4. List users (requires app-only) 5. Make a Graph call 4 User: Adele Vance ID: 05fb57bf-2653-4396-846d-2f210a91d9cf Email: AdeleV@contoso.com User: Alex Wilber ID: a36fe267-a437-4d24-b39e-7344774d606c Email: AlexW@contoso.com User: Allan Deyoung ID: 54cebbaa-2c56-47ec-b878-c8ff309746b0 Email: AllanD@contoso.com User: Bianca Pisani ID: 9a7dcbd0-72f0-48a9-a9fa-03cd46641d49 Email: NO EMAIL User: Brian Johnson (TAILSPIN) ID: a8989e40-be57-4c2e-bf0b-7cdc471e9cc4 Email: BrianJ@contoso.com ... More users available? True
Código explicado
Considere o código na GetUsersAsync função. É muito semelhante ao código em GetInboxAsync:
- Ele obtém uma coleção de usuários
- Ele usa para
Selectsolicitar propriedades específicas - Ele usa
Toppara limitar o número de usuários retornados - Ele usa
OrderBypara classificar a resposta
A principal diferença é que esse código usa o _appClient, não o _userClient. Ambos os clientes usam a mesma sintaxe e construtores de solicitação, mas foram configurados com credenciais diferentes.
Opcional: adicionar seu próprio código
Nesta seção, você adicionará seus próprios recursos Graph Microsoft ao aplicativo. Pode ser um snippet de código da documentação do Microsoft Graph ou Graph Explorer ou código que você criou. Esta seção é opcional.
Atualizar o aplicativo
Abra ./GraphHelper.cs e adicione a seguinte função à classe GraphHelper .
Substitua a função
MakeGraphCallAsyncvazia em Program.cs pelo seguinte.
Escolher uma API
Encontre uma API no Microsoft Graph que você gostaria de experimentar. Por exemplo, a API criar evento . Você pode usar um dos exemplos na documentação da API ou personalizar uma solicitação de API no Graph Explorer e usar o snippet gerado.
Configurar as permissões
Verifique a seção Permissões da documentação de referência da API escolhida para ver quais métodos de autenticação têm suporte. Algumas APIs não dão suporte somente a aplicativos ou contas pessoais da Microsoft, por exemplo.
- Para chamar uma API com autenticação de usuário (se a API der suporte à autenticação de usuário (delegada), adicione o escopo de permissão necessário em appsettings.json.
- Para chamar uma API com autenticação somente de aplicativo (se a API der suporte a ela), adicione o escopo de permissão necessário no Azure AD de administração.
Adicionar seu código
Copie seu código para a MakeGraphCallAsync função em GraphHelper.cs. Se você estiver copiando um snippet de documentação ou Graph Explorer, GraphServiceClient renomeie-o para o cliente apropriado: _userClient ou _appClient.
Parabéns!
Você concluiu o tutorial do .NET Microsoft Graph. Agora que você tem um aplicativo funcional que chama o Microsoft Graph, você pode experimentar e adicionar novos recursos. Visite a Visão geral do Microsoft Graph para ver todos os dados que você pode acessar com o Microsoft Graph.
Exemplos do .NET
Tem algum problema com essa seção? Se tiver, envie seus comentários para que possamos melhorar esta seção.