Share via

Einfaches Web API Schnellstartbeispiel C#)

  • Artikel

 

Gilt für: Dynamics 365 (online), Dynamics 365 (on-premises)

Dieses Beispiel veranschaulicht, wie Sie mit Microsoft Dynamics 365 Server authentifizieren und dann einen grundlegenden Web API-Vorgang erzeugen, denWhoAmI Function. Anders als andere Web API-Beispiele hängt dieses Beispiel nicht von anderen nicht dem Standard entsprechenden Hilfebibliotheken oder weiteren Quelldateien ab. Sämtliche Quellcodes befinden sich in einer einzigen Datei, Program.cs, mit denen der Logikfluss und der Authentifizierungsprozess einfacher verstanden werden kann. Das Beispiel funktioniert mit online, lokaler und der Bereitstellung mit Internetzugriff (IFDs).

Anforderungen

Dieses Beispiel hat die folgenden Anforderungen:

Wichtig

Mit Absicht wird die Lösung zu Beginn nicht erfolgreich erstellt. Der Quellcode muss in den mit //TODO Kommentaren versehenen Zeilen bearbeitet werden, um Benutzerkonten und/oder Anwendungsregistrierungsinformationen bereitzustellen.

Demonstriert

Dieses Beispiel veranschaulicht zwei einfache Konzepte, die für die Verwendung von Web API erforderlich sind: Authentifizierung mit Microsoft Dynamics 365 Server und das erstellen der grundlegenden Web API Aufrufen mithilfe von HTTP Protokollen.

Authentifizierung ist erforderlich, damit eine Clientanwendung auf jede Dynamics 365 Ressource zugreifen kann. Dieser Prozess ist aus zwei Gründen nicht ganz trivial: verschiedene Authentifizierungsmechanismen sind für die verschiedenen Bereitstellungsarten erforderlich, und webbasierte Authentifizierungsmechanismen erfordern in der Regel mehrere programmgesteuerte Schritte. Die integrierte Windows-Authentifizierung, die für die lokale Bereitstellungen erforderlich ist, ist verhältnismäßig einfach und erfordert lediglich einen Benutzernamen und ein Kennwort. Danach tritt das Programm kann als ein Agent des authentifizierten Benutzers auf.

Demgegenüber benötigen Online und für IFD-Bereitstellungen die Registrierung der Clientanwendung Voraus und verwenden dann einen Mehrstufen-OAuth-Authentifizierungsprozess. Der Anmeldeprozess für Dynamics 365 (online) wurde im Artikel Exemplarische Vorgehensweise: Registrieren einer Dynamics 365-App bei Azure Active Directory beschrieben. Der Anmeldeprozess für Dynamics 365 (lokal) mit Bereitstellung mit Internetzugriff (IFD) wurde im Artikel Exemplarische Vorgehensweise: Registrieren einer Dynamics 365-App mit Active Directory beschrieben. Jede nachfolgende Web API-Anforderung muss für OAuth authentifiziert werden. Glücklicherweise kann viel von der Komplexität der OAuth-Authentifizierung durch die Verwendung von Active Directory-Authentifizierungs-Bibliotheken (ADAL) für .NET-Clienten vereinfacht werden, das beispielsweise als NuGet-Paket Microsoft.IdentityModel.Clients.ActiveDirectory hinzugefügt wird. OAuth-Autorisierung kann im vorliegenden Beispiel mit der Inklusion der OAuthMessageHandler-Klasse gekapselt werden, die die erforderliche OAuth-Autorisierungskopfzeile der Nachrichtenanforderungen hinzufügt. In zukünftigen Beispielen wird Unterstützung für Authentifizierungsfunktion in dieWeb API Hilfe-Bibliothek getrennt. Weitere Informationen finden Sie unter Authentifizieren von Benutzern in Microsoft Dynamics 365.

Die Dynamics 365 Web API ist eine REST-API, die auf der OData-Spezifikation basiert und standardisierte HTTP-Anforderungen für Entitäten, Ruffunktionen und Aktionen unterstützt. Dieses Beispiel veranschaulicht die WhoAmI Function Funktion mit einer GET-Anforderung und verwendet dann die von dieser Funktion in der daraus resultierenden HTTP-Antwort bereitgestellte Information.. Einige Standardbibliotheken werden über dieses Beispiel genutzt, um diesen Aufruf zu unterstützen.

Beispiel ausführen

Gehen Sie zu Einfache Web API Schnellstartbeispiel C#), und laden Sie die Beispielarchivdatei, Simple Web API quick-start sample (CS.zip) herunter und extrahieren die Inhalte in einem lokalen Ordner. Dieser Ordner sollte die folgenden Datei enthalten:

Datei

Zweck/Beschreibung

Program.cs

Enthält den primären Quellcode für dieses Beispiel.

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

Die Standard-Microsoft Visual Studio 2015-Lösung, das Projekt, die NuGet-Paketkonfiguration Assemblyinformationsdateien und die Anwendungskonfigurationsdateien, für dieses Beispiel.

Führen Sie als Nächstes das folgende Verfahren aus, um dieses Beispiel auszuführen.

  1. Suchen und doppelklicken Sie auf die Lösungsdatei, SimpleWebApi.sln, um die Lösung in Visual Studio zu laden.

  2. In Lösungs-Explorer machen Sie einen Doppelklick auf die Datei Program.cs, um sie im Editor zu öffnen.

  3. Suchen Sie die //TODO Kommentare in der Main-Methode, fügen die erforderlichen Verbindungszeichenfolgenwerte hinzu und entfernen Sie die zugeordneten Zeilen.

  4. Erstellen Sie die SimpleWebApi-Lösung. Dies sollte alle erforderlichen NuGet-Pakete automatisch herunterladen und installieren.

  5. Führen Sie das Projekt SimpleWebApi in Visual Studio aus. Alle Beispiellösungen sind für die Ausführung im Debugmodus konfiguriert.

  6. Die Verhaltensweisen hängen von der Bereitstellungsart ab.

    • Für Online und für IFD-Bereitstellungen öffnet die Konsolenanwendung ein neues Fenster, um Ihre Anmeldeinformationen und das zugehörige Kennwort einzugeben.

    • Für lokale Bereitstellungen fordert die Konsolenanwendung Sie für ein Kennwort für das angegebene Dynamics 365 Konto auf.

    Liefern Sie diese Angabe und drücken Sie dann Enter.

Codelisten

Den aktuellen Quellcode für diese Datei finden Sie im Beispieldownloadpaket.

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

Siehe auch

Web API Reference
Web API Beispiele
Verwenden Sie die Microsoft Dynamics 365 WEB API Hilfe-Bibliothek (C#)
Authentifizieren von Benutzern in Microsoft Dynamics 365

Microsoft Dynamics 365

© 2017 Microsoft. Alle Rechte vorbehalten. Copyright