Condividi tramite

Esempio Quick Start per un'API Web semplice (C#)

  • Articolo

 

Si applica a: Dynamics 365 (online), Dynamics 365 (on-premises)

In questo esempio viene illustrato come eseguire l'autenticazione tramite Server Microsoft Dynamics 365 e quindi chiamare un'operazione dell'API Web di base,WhoAmI Function. A differenza di altri esempi API Web, questo esempio non dipende da altri librerie helper non standard o da file di origine aggiuntivi. Tutto il codice sorgente si trova in un singolo file, Program.cs, per rendere il processo di flusso logico e autenticazione più semplice da comprendere. In questo esempio il lavoro verrà svolto online, in locale e tramite distribuzione con connessione Internet.

Requisiti

Per l'esempio sono previsti i requisiti generali seguenti:

Importante

Da progettazione, inizialmente la soluzione non verrà creatala correttamente. Il codice sorgente deve essere modificato nelle righe indicate tramite i commenti //TODO fornendo informazioni relative all'account utente e/o di registrazione dell'applicazione.

Dimostra

Questo semplice esempio illustra due concetti di base necessari per lo sviluppo tramite l'API Web: l'autenticazione in Server Microsoft Dynamics 365 e la creazione di chiamate dell'API Web di base tramite il protocollo HTTP.

L'autenticazione è necessaria prima che un'applicazione client possa accedere a qualsiasi risorsa di Dynamics 365. Il processo può non essere banale per due motivi: i meccanismi di autenticazione necessari sono diversi per tipi diversi di distribuzione e i meccanismi di autenticazione basati su Web includono in genere più passaggi di programmazione. L'autenticazione integrata di Windows, necessaria per le distribuzioni locali, è relativamente lineare e richiede solo nome utente e password. Successivamente, il programma funge da agente dell'utente autenticato.

Invece, le distribuzioni online e IFD richiedono prima la registrazione dell'applicazione client e quindi l'utilizzo di un processo di autenticazione OAuth con più passaggi. Il processo di registrazione per Dynamics 365 (online) è descritto nell'articolo Procedura dettagliata: registrare un'app Dynamics 365 con Azure Active Directory. Il processo di registrazione per Dynamics 365 (locale) con Distribuzione con connessione Internet è descritto nell'articolo Procedura dettagliata: registrare un'app Dynamics 365 con Active Directory. Ogni richiesta successiva dell'API Web deve essere autenticata con OAuth. Fortunatamente, il larga misura la complessità dell'autenticazione OAuth può essere resa più semplice tramite l'utilizzo le librerie di autenticazione di Microsoft Azure Active Directory (ADAL) per i client .NET, che vengono aggiunte all'esempio come pacchetto NuGet Microsoft.IdentityModel.Clients.ActiveDirectory. L'autorizzazione OAuth viene ulteriormente incapsulata in questo esempio con l'inclusione della classe OAuthMessageHandler, che aggiunge l'intestazione di autorizzazione richiesta di OAuth alle richieste di messaggio. Negli esempi futuri, la funzionalità di autenticazione di supporto viene separata nella libreria helper API Web. Per ulteriori informazioni, vedere Autenticare gli utenti in Microsoft Dynamics 365.

L'API Web di Dynamics 365 è un'API REST basata sulla specifica OData, pertanto supporta le richieste HTTP standardizzate con le entità, nonché con funzionalità e azioni di chiamata. Questo esempio illustra la richiamata della funzione WhoAmI Function con una richiesta di GET, quindi l'utilizzo delle informazioni fornite da questa funzione nella risposta HTTP risultante. Molte librerie standard verranno sfruttate da questo esempio per supportare la richiamata:

Eseguire l'esempio

Innanzitutto passare a Esempio Quick Start per un'API Web semplice (C#), scaricare il file di archiviazione di esempio Simple Web API quick-start sample (CS.zip) ed estrarre il relativo contenuto in una cartella locale. La cartella deve contenere i file seguenti:

File

Scopo/Descrizione

Program.cs

Contiene il codice sorgente per questo esempio.

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

La soluzione Microsoft Visual Studio 2015, il progetto, la configurazione pacchetto NuGet e i file di informazioni dell'assembly e i file di configurazione dell'applicazione per questo esempio.

Quindi, usa la procedura seguente per eseguire l'esempio.

  1. Individuare e fare doppio clic sul file della soluzione, SimpleWebApi.sln, per caricare la soluzione in Visual Studio.

  2. In Solution Explorer fare doppio clic sul file Program.cs per aprirlo nell'editor.

  3. Individuare i commenti //TODO nel metodo Main, aggiungere i valori stringa di connessione e rimuovere i commenti dalle righe di codice associate.

  4. Creare la soluzione SimpleWebApi. In tal modo vengono scaricati e installati automaticamente tutti i pacchetti NuGet necessari che mancano o devono essere aggiornati.

  5. Eseguire il progetto SimpleWebApi da Visual Studio. Tutte le soluzioni di esempio sono configurate per l'esecuzione in modalità di debug per impostazione predefinita.

  6. Il comportamento dipende dal tipo di distribuzione.

    • Per le distribuzioni online e IFD, l'applicazione console aprirà una nuova finestra per immettere credenziali e password dell'utente.

    • Per le distribuzioni locali, l'applicazione console richiederà una password per l'account Dynamics 365 fornito.

    Immettere le informazioni e premere Enter.

Elenco di codice

L'origine più aggiornata per il file è disponibile nel pacchetto del download di esempio.

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

Vedere anche

Web API Reference
Esempi di API Web
Utilizzare la libreria helper API Web di Microsoft Dynamics 365 (C#)
Autenticare gli utenti in Microsoft Dynamics 365

Microsoft Dynamics 365

© 2017 Microsoft. Tutti i diritti sono riservati. Copyright