Exemplo simples de início rápido de API da Web (C#)

  • Artigo

 

Aplicável a: Dynamics 365 (online), Dynamics 365 (on-premises)

Este exemplo mostra como autenticar um Servidor do Microsoft Dynamics 365 e, em seguida, chamar uma operação básica de API da Web, aWhoAmI Function. Diferentemente de outros exemplos de API da Web, isso não dependerá de outras bibliotecas auxiliares não padrão ou de arquivos de origem adicionais. Todo seu código-fonte está em um arquivo único, Program.cs para ajudar a criar fluxo lógico e o processo de autenticação mais fácil de entender. O exemplo funcionará com implantações para a internet (IFDS) e locais, online.

Requisitos

Este exemplo tem os seguintes requisitos:

Importante

Por padrão, inicialmente a solução não será criada com êxito. O código-fonte deve ser editado nas linhas indicadas pelos comentários de //TODO para fornecer informações de conta do usuário e/ou registro do aplicativo.

Demonstrações

Este exemplo simples demonstra dois conceitos básicos necessários para desenvolvimento usando a API da Web: autenticação com um Servidor do Microsoft Dynamics 365 e formação de chamadas básicas de API da Web usando o protocolo HTTP.

A autenticação é necessária antes que um aplicativo cliente possa acessar qualquer recurso do Dynamics 365. Este processo poderá ser não trivial por dois motivos: diferentes mecanismos de autenticação são necessários para diferentes tipos de implementação, e os mecanismos de autenticação com base na Web geralmente envolvem várias etapas programáticas. Autenticação Integrada do Windows, necessária para implantações no local, é relativamente simples e só exige um nome de usuário e uma senha. Em seguida, o programa atual como um agente do usuário autenticado.

Por outro lado, as implantações IFD e online exigem o registro do aplicativo cliente com antecedência e usa um processo de autenticação de OAuth de várias etapas. O processo de registro do Dynamics 365 (online) é descrito no artigo Passo a passo: Registrar o aplicativo Dynamics 365 com Ative Directory do Azure. O processo de registro do Dynamics 365 (local) com o Implantação para a Internet (IFD) é descrito no artigo Passo a passo: Registrar o aplicativo Dynamics 365 com Ative Directory. Cada solicitação da API subsequente deverá ser autenticada com OAuth. Felizmente a maior parte da complexidade de autenticação de OAuth pode ser simplificada com o uso das Bibliotecas de Autenticação do Active Directory (ADAL) para clientes .NET, que é adicionada à amostra como pacote do NuGet Microsoft.IdentityModel.Clients.ActiveDirectory. A autorização de OAuth é mais encapsulada neste exemplo com a inclusão da classe de OAuthMessageHandler, que adiciona o cabeçalho de autorização de OAuth necessário para solicitações de mensagem. Nos exemplos futuros, a funcionalidade de suporte à autenticação será separada na Biblioteca Auxiliar da API Web. Para obter mais informações, consulte Autenticar usuários no Microsoft Dynamics 365.

A API da Web do Dynamics 365 é uma API REST com base na Especificação OData, dessa forma, ela suporta solicitações HTTP padronizadas com entidades e funções e ações de chamada. Este exemplo mostra a chamada da função WhoAmI Functioncom uma solicitação GET, em seguida, usando as informações fornecidas por esta função na resposta HTTP resultante. Várias bibliotecas padrão são aproveitadas por este exemplo para auxiliar nesta invocação:

Executar este exemplo

Primeiro, vá para Exemplo simples de início rápido de API da Web (C#), faça download do download do arquivo de exemplo, Simple Web API quick-start sample (CS.zip) e extrai seus conteúdo para uma pasta local. Esta pasta deve conter os seguintes arquivos:

Arquivo

Finalidade/descrição

Program.cs

Contém o código fonte para este exemplo.

SimpleWebApi.sln
SimpleWebApi.csproj
packages.config
AssemblyInfo.cs
App.config

A solução padrão do Microsoft Visual Studio 2015, projeto, configuração do pacote NuGet, informações de montagem e arquivos de configuração do aplicativo para este exemplo.

Em seguida, use o próximo procedimento para executar este exemplo.

  1. Localize e clique duas vezes no arquivo da solução, SimpleWebApi.sln, para carregar a solução no Visual Studio.

  2. Em Solution Explorer, clique duas vezes no arquivo Program.cs para abri-lo no editor.

  3. Localize os comentários do //TODO dentro do método Main, adicione os valores da cadeia de conexão necessários e remova o comentários das linhas associadas.

  4. Crie a solução SimpleWebApi. Isto deve baixar e instalar automaticamente todos os pacotes NuGet necessários que estejam ausentes ou que precisem ser atualizados.

  5. Execute o projeto SimpleWebApi no Visual Studio. Por padrão, todas as soluções de exemplo são configuradas para execução em modo de depuração.

  6. O comportamento depende do tipo de implantação.

    • Para implantações IFD e on-line, o aplicativo de console abrirá uma nova janela para inserir suas credenciais do usuário e senha.

    • Para implantações no local, o aplicativo de console solicitará uma senha para o Dynamics 365 fornecido.

    Forneça as informações e pressione Enter.

Listagem de códigos

A origem mais atual deste arquivo pode ser encontrada no pacote de download do exemplo.

Program.cs

namespace Microsoft.Crm.Sdk.Samples
{
    /// <summary>
    /// A basic Web API client application for Dynamics 365 (CRM). This sample authenticates 
    /// the user and then calls the WhoAmI Web API function. 
    /// </summary>
    /// <remarks> 
    /// Prerequisites: 
    ///   -  To run this application, you must have a CRM Online or on-premise account. 
    ///   -  For CRM Online or Internet-facing deployments (IFD), the application must be registered  
    ///      with Azure Active Directory as described in this article: 
    ///      https://msdn.microsoft.com/en-us/library/dn531010.aspx
    ///   
    /// The WhoAmI Web API function is documented here: 
    ///    https://msdn.microsoft.com/en-us/library/mt607925.aspx
    /// </remarks>
    static class SimpleWebApi
    {
        //TODO: Uncomment then substitute your correct Dynamics 365 organization service 
        // address for either CRM Online or on-premise (end with a forward-slash).
        //private static string serviceUrl = "https://mydomain.crm.dynamics.com/myorg/";   // CRM Online
        //private static string serviceUrl = "https://<organization name>.<domain name>/";   // CRM IFD
        //private statics string serviceUrl = "http://myserver/myorg/";        // CRM on-premises

        //TODO: For an on-premises deployment, set your organization credentials here. (If
        // online or IFD, you can you can disregard or set to null.)
        private static string userAccount = "<user-account>";  //CRM user account
        private static string domain = "<server-domain>";  //CRM server domain

        //TODO: For CRM Online or IFD deployments, substitute your app registration values  
        // here. (If on-premise, you can disregard or set to null.)
        private static string clientId = "<app-reg-guid>";     //e.g. "e5cf0024-a66a-4f16-85ce-99ba97a24bb2"
        private static string redirectUrl = "<redirect-URL>";  //e.g. "https://localhost/SdkSample"

        static public void Main(string[] args)
        {
            //One message handler for OAuth authentication, and the other for Windows integrated 
            // authentication.  (Assumes that HTTPS protocol only used for CRM Online.)
            HttpMessageHandler messageHandler;
            if (serviceUrl.StartsWith("https://"))
            {
                messageHandler = new OAuthMessageHandler(serviceUrl, clientId, redirectUrl,
                         new HttpClientHandler());
            }
            else
            {
                //Prompt for user account password required for on-premise credentials.  (Better
                // approach is to use the SecureString class here.)
                Console.Write("Please enter the password for account {0}: ", userAccount);
                string password = Console.ReadLine().Trim();
                NetworkCredential credentials = new NetworkCredential(userAccount, password, domain);
                messageHandler = new HttpClientHandler() { Credentials = credentials };
            }
            try
            {
                //Create an HTTP client to send a request message to the CRM Web service.
                using (HttpClient httpClient = new HttpClient(messageHandler))
                {
                    //Specify the Web API address of the service and the period of time each request 
                    // has to execute.
                    httpClient.BaseAddress = new Uri(serviceUrl);
                    httpClient.Timeout = new TimeSpan(0, 2, 0);  //2 minutes

                    //Send the WhoAmI request to the Web API using a GET request. 
                    var response = httpClient.GetAsync("api/data/v8.1/WhoAmI",
                            HttpCompletionOption.ResponseHeadersRead).Result;
                    if (response.IsSuccessStatusCode)
                    {
                        //Get the response content and parse it.
                        JObject body = JObject.Parse(response.Content.ReadAsStringAsync().Result);
                        Guid userId = (Guid)body["UserId"];
                        Console.WriteLine("Your system user ID is: {0}", userId);
                    }
                    else
                    {
                        Console.WriteLine("The request failed with a status of '{0}'",
                               response.ReasonPhrase);
                    }
                }
            }
            catch (Exception ex)
            {
                DisplayException(ex);
                throw;
            }
            finally
            {
                Console.WriteLine("Press <Enter> to exit the program.");
                Console.ReadLine();
            }
        }

        /// <summary> Displays exception information to the console. </summary>
        /// <param name="ex">The exception to output</param>
        private static void DisplayException(Exception ex)
        {
            Console.WriteLine("The application terminated with an error.");
            Console.WriteLine(ex.Message);
            while (ex.InnerException != null)
            {
                Console.WriteLine("\t* {0}", ex.InnerException.Message);
                ex = ex.InnerException;
            }
        }
    }

    /// <summary>
    ///Custom HTTP message handler that uses OAuth authentication thru ADAL.
    /// </summary>
    class OAuthMessageHandler : DelegatingHandler
    {
        private AuthenticationHeaderValue authHeader;

        public OAuthMessageHandler(string serviceUrl, string clientId, string redirectUrl,
                HttpMessageHandler innerHandler)
            : base(innerHandler)
        {
            // Obtain the Azure Active Directory Authentication Library (ADAL) authentication context.
            AuthenticationParameters ap = AuthenticationParameters.CreateFromResourceUrlAsync(
                    new Uri(serviceUrl + "api/data/")).Result;
            AuthenticationContext authContext = new AuthenticationContext(ap.Authority, false);
            //Note that an Azure AD access token has finite lifetime, default expiration is 60 minutes.
            AuthenticationResult authResult = authContext.AcquireToken(serviceUrl, clientId, new Uri(redirectUrl));
            authHeader = new AuthenticationHeaderValue("Bearer", authResult.AccessToken);
        }

        protected override Task<HttpResponseMessage> SendAsync(
                 HttpRequestMessage request, System.Threading.CancellationToken cancellationToken)
        {
            request.Headers.Authorization = authHeader;
            return base.SendAsync(request, cancellationToken);
        }
    }
}

Confira Também

Web API Reference
Exemplos de API Web
Use a Microsoft Dynamics 365 Biblioteca Auxiliar da API Web (C#)
Autenticar usuários no Microsoft Dynamics 365

Microsoft Dynamics 365

© 2017 Microsoft. Todos os direitos reservados. Direitos autorais