Início Rápido: Chamar a API do Microsoft Graph de um aplicativo da UWP (Plataforma Universal do Windows)Quickstart: Call the Microsoft Graph API from a Universal Windows Platform (UWP) application

Este início rápido contém um exemplo de código que demonstra como um aplicativo UWP (Plataforma Universal do Windows) pode conectar usuários com contas pessoais, corporativa ou de estudante, obter um token de acesso e chamar a API do Microsoft Graph.This quickstart contains a code sample that demonstrates how a Universal Windows Platform (UWP) application can sign in users with personal accounts or work and school accounts, get an access token, and call the Microsoft Graph API.

Mostra como o aplicativo de exemplo gerado por este início rápido funciona

Registrar e baixar o aplicativo de início rápidoRegister and download your quickstart app

Você tem duas opções para iniciar o aplicativo de início rápido:You have two options to start your quickstart application:

Opção 1: Registrar e configurar o aplicativo automaticamente e, em seguida, baixar seu exemplo de códigoOption 1: Register and auto configure your app and then download your code sample

  1. Acesse o novo painel do portal do Azure – Registros de aplicativo.Go to the new Azure portal - App registrations pane.
  2. Insira um nome para o aplicativo e clique em Registrar.Enter a name for your application and click Register.
  3. Siga as instruções para baixar e configurar automaticamente o novo aplicativo com apenas um clique.Follow the instructions to download and automatically configure your new application for you in one click.

Opção 2: Registrar e configurar manualmente o aplicativo e o exemplo de códigoOption 2: Register and manually configure your application and code sample

Etapa 1: Registre seu aplicativoStep 1: Register your application

Para registrar seu aplicativo e adicionar as informações de registro do aplicativo à solução, siga estas etapas:To register your application and add the app's registration information to your solution, follow these steps:

  1. Entre no portal do Azure usando uma conta corporativa ou de estudante ou uma conta pessoal da Microsoft.Sign in to the Azure portal using either a work or school account, or a personal Microsoft account.
  2. Se sua conta fornecer acesso a mais de um locatário, selecione sua conta no canto superior direito e defina sua sessão do portal para o locatário desejado do Azure AD.If your account gives you access to more than one tenant, select your account in the top right corner, and set your portal session to the desired Azure AD tenant.
  3. Navegue até a página Registros de aplicativo da plataforma de identidade da Microsoft para desenvolvedores.Navigate to the Microsoft identity platform for developers App registrations page.
  4. Selecione Novo registro.Select New registration.
  5. Quando a página Registrar um aplicativo for exibida, insira as informações de registro do aplicativo:When the Register an application page appears, enter your application's registration information:
    • Na seção Nome, insira um nome de aplicativo relevante que será exibido aos usuários do aplicativo, por exemplo, UWP-App-calling-MsGraph.In the Name section, enter a meaningful application name that will be displayed to users of the app, for example UWP-App-calling-MsGraph.
    • Na seção Tipos de conta com suporte, selecione Contas em qualquer diretório organizacional e contas pessoais da Microsoft (por exemplo, Skype, Xbox, Outlook.com) .In the Supported account types section, select Accounts in any organizational directory and personal Microsoft accounts (for example, Skype, Xbox, Outlook.com).
    • Selecione Registrar para criar o aplicativo.Select Register to create the application.
  6. Na lista de páginas para o aplicativo, selecione Autenticação.In the list of pages for the app, select Authentication.
  7. Expanda a seção Desktop + dispositivos.Expand the Desktop + devices section. (Se Desktop + dispositivos não está visível, primeiro clique na faixa superior para exibir a experiência de Autenticação em versão prévia)(If Desktop + devices is not visible, first click the top banner to view the preview Authentication experience)
  8. Na seção URI de redirecionamento, selecione Adicionar URI.Under the Redirect URI section, select Add URI. Digite urn:ietf:wg:oauth:2.0:oob.Type urn:ietf:wg:oauth:2.0:oob.
  9. Clique em Salvar.Select Save.

Etapa 1: Configurar seu aplicativoStep 1: Configure your application

Para que o exemplo de código deste Início Rápido funcione, você precisa adicionar um URI de redirecionamento como urn:ietf:wg:oauth:2.0:oob.For the code sample for this quickstart to work, you need to add a redirect URI as urn:ietf:wg:oauth:2.0:oob.

Já configurado Seu aplicativo já está configurado com esses atributos.Already configured Your application is configured with these attributes.

Etapa 2: Baixar seu projeto do Visual StudioStep 2: Download your Visual Studio project

Etapa 3: Configurar o projeto do Visual StudioStep 3: Configure your Visual Studio project

  1. Extraia o arquivo zip para uma pasta local mais próxima da raiz do disco, por exemplo, C:\Azure-Samples.Extract the zip file to a local folder close to the root of the disk, for example, C:\Azure-Samples.

  2. Abra o projeto no Visual Studio.Open the project in Visual Studio. Pode ser solicitado que você instale um SDK UWP.You might be prompted to install a UWP SDK. Nesse caso, aceite.In that case, accept.

  3. Edite a MainPage.Xaml.cs e substitua os valores do campo ClientId:Edit MainPage.Xaml.cs and replace the values of the ClientId field:

    private const string ClientId = "Enter_the_Application_Id_here";
    

Observação

Este guia de início rápido oferece suporte a Enter_the_Supported_Account_Info_Here.This quickstart supports Enter_the_Supported_Account_Info_Here.

Em que:Where:

  • Enter_the_Application_Id_here: é a ID do aplicativo que você registrou.Enter_the_Application_Id_here - is the Application Id for the application you registered.

Dica

Para localizar o valor da ID do aplicativo, acesse a seção Visão geral no portalTo find the value of Application ID, go to the Overview section in the portal

Etapa 4: Execute seu aplicativo.Step 4: Run your application

Se você quiser testar o guia de início rápido no seu computador Windows:If you want to try the quickstart on your Windows machine:

  1. Na barra de ferramentas do Visual Studio, escolha a plataforma certa (provavelmente x64 ou x86, não ARM).In the Visual Studio toolbar, choose the right platform (probably x64 or x86, not ARM).

    Observe que o dispositivo de destino é alterado de Dispositivo para Computador LocalObserve that the target device changes from Device to Local Machine

  2. Selecione Depurar | Iniciar Sem DepuraçãoSelect Debug | Start Without Debugging

Mais informaçõesMore information

Esta seção fornece mais informações sobre o início rápido.This section provides more information about the quickstart.

MSAL.NETMSAL.NET

MSAL (Microsoft.Identity.Client) é a biblioteca usada para conectar usuários e solicitar tokens de segurança.MSAL (Microsoft.Identity.Client) is the library used to sign in users and request security tokens. Os tokens de segurança são usados para acessar uma API protegida pela plataforma de identidade da Microsoft para desenvolvedores.The security tokens are used to access an API protected by Microsoft Identity platform for developers. Você pode instalar a MSAL executando o comando abaixo no Console do Gerenciador de Pacotes do Visual Studio:You can install MSAL by running the following command in Visual Studio's Package Manager Console:

Install-Package Microsoft.Identity.Client -IncludePrerelease

Inicialização da MSALMSAL initialization

Você pode adicionar a referência da MSAL adicionando o seguinte código:You can add the reference for MSAL by adding the following code:

using Microsoft.Identity.Client;

Em seguida, a MSAL é inicializada usando o seguinte código:Then, MSAL is initialized using the following code:

public static IPublicClientApplication PublicClientApp;
PublicClientApp = new PublicClientApplicationBuilder.Create(ClientId)
                                                    .Build();
Em que:Where:
ClientId É a ID do aplicativo (cliente) relativa ao aplicativo registrado no portal do Azure.Is the Application (client) ID for the application registered in the Azure portal. Você pode encontrar esse valor na página Visão Geral do aplicativo no portal do Azure.You can find this value in the app's Overview page in the Azure portal.

Solicitando tokensRequesting tokens

A MSAL tem dois métodos para adquirir tokens em um aplicativo UWP: AcquireTokenInteractive e AcquireTokenSilent.MSAL has two methods for acquiring tokens in a UWP app: AcquireTokenInteractive and AcquireTokenSilent.

Obter um token de usuário interativamenteGet a user token interactively

Algumas situações exigem forçar os usuários a interagir com o ponto de extremidade da plataforma de identidade da Microsoft por meio de uma janela pop-up para validar suas credenciais ou para dar consentimento.Some situations require forcing users to interact with the Microsoft identity platform endpoint through a popup window to either validate their credentials or to give consent. Alguns exemplos incluem:Some examples include:

  • A primeira vez que os usuários entram no aplicativoThe first-time users sign in to the application
  • Quando os usuários precisam reinserir suas credenciais porque a senha expirouWhen users may need to reenter their credentials because the password has expired
  • Quando seu aplicativo está solicitando acesso a um recurso com o qual o usuário precisa consentirWhen your application is requesting access to a resource, that the user needs to consent to
  • Quando a autenticação de dois fatores é necessáriaWhen two factor authentication is required
authResult = await App.PublicClientApp.AcquireTokenInteractive(scopes)
                      .ExecuteAsync();
Em que:Where:
scopes Contém os escopos que estão sendo solicitados, por exemplo, { "user.read" } para o Microsoft Graph ou { "api://<Application ID>/access_as_user" } para as APIs Web personalizadas.Contains the scopes being requested, such as { "user.read" } for Microsoft Graph or { "api://<Application ID>/access_as_user" } for custom Web APIs.

Obter um token de usuário no modo silenciosoGet a user token silently

Use o método AcquireTokenSilent para obter tokens para acessar recursos protegidos após o método inicial AcquireTokenInteractive.Use the AcquireTokenSilent method to obtain tokens to access protected resources after the initial AcquireTokenInteractive method. Não convém exigir que o usuário valide suas credenciais sempre que precisar acessar um recurso.You don’t want to require the user to validate their credentials every time they need to access a resource. Na maioria das vezes, você quer aquisições e renovação de tokens sem nenhuma interação do usuárioMost of the time you want token acquisitions and renewal without any user interaction

var accounts = await App.PublicClientApp.GetAccountsAsync();
var firstAccount = accounts.FirstOrDefault();
authResult = await App.PublicClientApp.AcquireTokenSilent(scopes, firstAccount)
                                      .ExecuteAsync();
Em que:Where:
scopes Contém os escopos que estão sendo solicitados, por exemplo, { "user.read" } para o Microsoft Graph ou { "api://<Application ID>/access_as_user" } para as APIs Web personalizadasContains the scopes being requested, such as { "user.read" } for Microsoft Graph or { "api://<Application ID>/access_as_user" } for custom Web APIs
firstAccount Especifica a primeira conta de usuário no cache (a MSAL é compatível com vários usuários em um único aplicativo)Specifies the first user account in the cache (MSAL supports multiple users in a single app)

Ajuda e suporteHelp and support

Se você precisar de Ajuda, quiser relatar um problema ou aprender mais sobre as opções de suporte, consulte o seguinte artigo:If you need help, want to report an issue, or want to learn more about your support options, see the following article:

Próximas etapasNext steps

Experimente o tutorial de área de trabalho do Windows para ver um guia passo a passo completo sobre a criação de aplicativos e novos recursos, incluindo uma explicação completa deste início rápido.Try out the Windows desktop tutorial for a complete step-by-step guide on building applications and new features, including a full explanation of this quickstart.

Ajude-nos a melhorar a plataforma de identidade da Microsoft.Help us improve the Microsoft identity platform. Deixe sua opinião respondendo a uma breve pesquisa de duas perguntas.Tell us what you think by completing a short two-question survey.