Skriva klientappens autentiseringskod

2025-04-22

När du har konfigurerat en Azure Digital Twins-instans och autentisering kan du skapa ett klientprogram för att interagera med instansen. Den här artikeln beskriver hur du skriver kod i klientappen för att autentisera den mot Azure Digital Twins-instansen.

Azure Digital Twins autentiserar med hjälp av Microsoft Entra-säkerhetstoken baserat på OAUTH 2.0. Om du vill autentisera din SDK hämtar du en ägartoken med rätt behörigheter till Azure Digital Twins och skickar den tillsammans med dina API-anrop.

Den här artikeln beskriver hur du hämtar autentiseringsuppgifter med hjälp av Azure.Identity klientbiblioteket. Även om den här artikeln visar kodexempel i C#, till exempel vad du skulle skriva för .NET (C#) SDK, kan du använda en version av Azure.Identity oavsett vilken SDK du använder. Mer information om de SDK:er som är tillgängliga för Azure Digital Twins finns i Azure Digital Twins API:er och SDK:er.

Förutsättningar

Slutför först installationsstegen i Konfigurera en instans och autentisering. Den här konfigurationen säkerställer att du har en Azure Digital Twins-instans och att användaren har åtkomstbehörighet. Efter den konfigurationen är du redo att skriva kod för klientappen.

För att fortsätta behöver du ett klientappsprojekt där du skriver koden. Om du inte redan har konfigurerat ett klientappsprojekt skapar du ett grundläggande projekt på det språk du vill använda med den här självstudien.

Autentisera med hjälp av Azure.Identity-biblioteket

Azure.Identity är ett klientbibliotek som innehåller flera metoder för att hämta autentiseringsuppgifter som du kan använda för att hämta en ägartoken och autentisera med din SDK. Även om den här artikeln innehåller exempel i C#, kan du visa Azure.Identity för flera språk, inklusive...

Tre vanliga metoder för att hämta autentiseringsuppgifter i Azure.Identity är:

DefaultAzureCredential tillhandahåller ett standardautentiseringsflöde TokenCredential för program som distribueras till Azure. Den här metoden är det rekommenderade valet för lokal utveckling. Den kan också prova de andra två metoderna som rekommenderas i den här artikeln; den omsluter ManagedIdentityCredential och kan komma åt InteractiveBrowserCredential med en konfigurationsvariabel.
ManagedIdentityCredential fungerar bra i fall där du behöver hanterade identiteter (MSI). Den här metoden är en bra kandidat för att arbeta med Azure Functions och distribuera till Azure-tjänster.
InteractiveBrowserCredential är avsett för interaktiva program. Det här är en metod för att skapa en autentiserad SDK-klient.

Resten av den här artikeln visar hur du använder dessa metoder med .NET (C#) SDK.

Lägga till Azure.Identity i ditt .NET-projekt

Utför följande steg för att konfigurera .NET-projektet att autentisera med Azure.Identity:

Inkludera SDK-paketet Azure.DigitalTwins.Core och Azure.Identity paketet i projektet. Beroende på vilka verktyg du väljer kan du inkludera paketen med hjälp av Visual Studio-pakethanteraren eller dotnet kommandoradsverktyget.

Lägg till följande användningsinstruktioner i projektkoden:

using Azure.DigitalTwins.Core;
using Azure.Identity;
using System;

Lägg sedan till kod för att hämta autentiseringsuppgifter med någon av metoderna i Azure.Identity. Följande avsnitt innehåller mer information om hur du använder varje metod.

Standardmetod förAzureCredential

DefaultAzureCredential tillhandahåller ett standardautentiseringsflöde TokenCredential för program som distribueras till Azure. Den här metoden är det rekommenderade valet för lokal utveckling.

Om du vill använda standardautentiseringsuppgifterna för Azure behöver du Azure Digital Twins-instansens URL (instruktioner för att hitta).

Här är ett kodexempel för att lägga till ett DefaultAzureCredential i projektet:

public class DefaultAzureCredentialSample
{
    // The URL of your instance, starting with the protocol (https://)
    private const string adtInstanceUrl = "https://<your-Azure-Digital-Twins-instance-URL>";

    internal void RunSample()
    {
        //...

        DigitalTwinsClient client;
        try
        {
            var credential = new DefaultAzureCredential();
            client = new DigitalTwinsClient(new Uri(adtInstanceUrl), credential);
        }
        catch (Exception e)
        {
            Console.WriteLine($"Authentication or client creation error: {e.Message}");
            Environment.Exit(0);
        }
    }
}

Anteckning

Det finns för närvarande ett känt problem som påverkar omslutningsklassen DefaultAzureCredential som kan leda till ett fel vid autentisering. Om du stöter på det här problemet kan du prova att instansiera DefaultAzureCredential med följande valfria parameter för att lösa det: new DefaultAzureCredential(new DefaultAzureCredentialOptions { ExcludeSharedTokenCacheCredential = true });

Mer information om det här problemet finns i Kända problem med Azure Digital Twins.

Konfigurera lokala Azure-autentiseringsuppgifter

Med DefaultAzureCredentialsöker exemplet efter autentiseringsuppgifter i din lokala miljö, till exempel en Azure-inloggning i en lokal Azure CLI- eller i Visual Studio eller Visual Studio Code. Därför bör du logga in på Azure lokalt via någon av dessa mekanismer för att konfigurera autentiseringsuppgifter för exemplet.

Om du använder Visual Studio eller Visual Studio Code för att köra kodexempel kontrollerar du att du är inloggad i redigeringsprogrammet med samma Azure-autentiseringsuppgifter som du vill använda för att komma åt din Azure Digital Twins-instans. Om du använder ett lokalt CLI-fönster kör az login du kommandot för att logga in på ditt Azure-konto. När du har loggat in bör du autentiseras automatiskt när du kör kodexemplet.

ManagedIdentityCredential metod

Metoden ManagedIdentityCredential fungerar bra i fall där du behöver hanterade identiteter (MSI) – till exempel när du autentiserar med Azure Functions.

Du kan använda ManagedIdentityCredential i samma projekt som DefaultAzureCredential eller InteractiveBrowserCredential för att autentisera en annan del av projektet.

Om du vill använda standardautentiseringsuppgifterna för Azure behöver du Azure Digital Twins-instansens URL (instruktioner för att hitta). Du kan också behöva en appregistrering och registreringens program-ID (klient).

I en Azure-funktion kan du använda autentiseringsuppgifterna för den hanterade identiteten så här:

public class ManagedIdentityCredentialSample
{
    // The URL of your instance, starting with the protocol (https://)
    private const string adtInstanceUrl = "https://<your-Azure-Digital-Twins-instance-URL>";

    internal void RunSample()
    {
        DigitalTwinsClient client;
        try
        {
            // To use the function app's system-assigned identity:
            ManagedIdentityCredential cred = new ManagedIdentityCredential();
            // To use a user-assigned identity for the function app:
            //ManagedIdentityCredential cred = new ManagedIdentityCredential("<uai-client-ID>");

            client = new DigitalTwinsClient(new Uri(adtInstanceUrl), cred);
        }
        catch (Exception e)
        {
            Console.WriteLine($"Authentication or client creation error: {e.Message}");
            Environment.Exit(0);
        }
    }
}

När du skapar autentiseringsuppgifterna utan parametrar, som du ser i föregående exempel, returneras autentiseringsuppgifterna för funktionsappens systemtilldelade identitet, om den har en. Om du vill ange en användartilldelad identitet i stället skickar du den användartilldelade identitetens klient-ID till parametern id för konstruktorn.

"InteractiveBrowserCredential"-metod

Metoden InteractiveBrowserCredential är avsedd för interaktiva program och öppnar en webbläsare för autentisering. Använd den här metoden i stället för DefaultAzureCredential när du behöver interaktiv autentisering.

Om du vill använda autentiseringsuppgifterna för interaktiva webbläsare behöver du en appregistrering som har behörighet till Azure Digital Twins-API:erna. Anvisningar om hur du konfigurerar den här appregistreringen finns i Skapa en appregistrering med Azure Digital Twins-åtkomst. När appregistreringen har konfigurerats behöver du följande värden:

Här är ett exempel på koden för att skapa en autentiserad SDK-klient med .InteractiveBrowserCredential

public class InteractiveBrowserCredentialSample
{
    // Your client / app registration ID
    private const string clientId = "<your-client-ID>";
    // Your tenant / directory ID
    private const string tenantId = "<your-tenant-ID>";
    // The URL of your instance, starting with the protocol (https://)
    private const string adtInstanceUrl = "https://<your-Azure-Digital-Twins-instance-URL>";

    internal void RunSample()
    {
        //...

        DigitalTwinsClient client;
        try
        {
            var credential = new InteractiveBrowserCredential(tenantId, clientId);
            client = new DigitalTwinsClient(new Uri(adtInstanceUrl), credential);
        }
        catch (Exception e)
        {
            Console.WriteLine($"Authentication or client creation error: {e.Message}");
            Environment.Exit(0);
        }
    }
}

Anteckning

Även om exemplet ovan placerar klient-ID, klient-ID och instans-URL direkt i koden, är det en bra idé att hämta dessa värden från en konfigurationsfil eller miljövariabel i stället.

Autentisera Azure Functions

Det här avsnittet innehåller viktiga konfigurationsalternativ för autentisering med Azure Functions. Först läser du om rekommenderade variabler på klassnivå och autentiseringskod som gör att funktionen kan komma åt Azure Digital Twins. Sedan kan du läsa om några sista konfigurationssteg som ska slutföras för din funktion när dess kod har publicerats till Azure.

Skriva programkod

När du skriver Azure-funktionen bör du överväga att lägga till dessa variabler och kod i din funktion:

Kod för att läsa Azure Digital Twins-tjänstens URL som en miljövariabel eller konfigurationsinställning. Det är en bra idé att läsa tjänst-URL:en från en programinställning/miljövariabel i stället för att hårdkoda den i funktionen. I en Azure-funktion kan koden för att läsa miljövariabeln se ut så här:
```
private static readonly string adtInstanceUrl = Environment.GetEnvironmentVariable("ADT_SERVICE_URL");
```
När du har publicerat funktionen senare skapar och anger du värdet för miljövariabeln för den här koden som ska läsas. Anvisningar om hur du gör det finns i Konfigurera programinställningar.
En statisk variabel som ska innehålla en HttpClient-instans. HttpClient är relativt dyrt att skapa, så du vill förmodligen skapa det en gång med autentiseringskoden för att undvika att skapa den för varje funktionsanrop.
```
private static readonly HttpClient singletonHttpClientInstance = new HttpClient();
```
Autentiseringsuppgifter för hanterad identitet. Skapa en autentiseringsuppgift för hanterad identitet som din funktion använder för att få åtkomst till Azure Digital Twins.
```
// To use the function app's system-assigned identity:
var cred = new ManagedIdentityCredential();
// To use a user-assigned identity for the function app:
//var cred = new ManagedIdentityCredential("<uai-client-ID>");
```
När du skapar autentiseringsuppgifterna utan parametrar, som du ser i föregående exempel, returneras autentiseringsuppgifterna för funktionsappens systemtilldelade identitet, om den har en. Om du vill ange en användartilldelad identitet i stället skickar du den användartilldelade identitetens klient-ID till parametern id för konstruktorn.

När du har publicerat funktionen senare kontrollerar du att funktionens identitet har behörighet att komma åt Azure Digital Twins-API:erna. Anvisningar om hur du gör det finns i Tilldela en åtkomstroll.

En lokal variabel DigitalTwinsClient. Lägg till variabeln i funktionen för att lagra din Azure Digital Twins-klientinstans. Gör inte den här variabeln statisk i klassen.

var client = new DigitalTwinsClient(
    new Uri(adtInstanceUrl),
    cred,
    new DigitalTwinsClientOptions
    {
        Transport = new HttpClientTransport(singletonHttpClientInstance)
    });

En null-kontroll för adtInstanceUrl. Om du vill fånga eventuella undantag lägger du till null-kontrollen och omsluter sedan funktionslogiken i ett try/catch-block.

När du har lagt till dessa variabler i en funktion kan funktionskoden se ut som i följande exempel.

// Default URL for triggering event grid function in the local environment.
// http://localhost:7071/runtime/webhooks/EventGrid?functionName={functionname}
//<Function_dependencies>
using Azure.Core.Pipeline;
using Azure.DigitalTwins.Core;
using Azure.Identity;
using Azure.Messaging.EventGrid;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.EventGrid;
using Microsoft.Extensions.Logging;
using System;
using System.Net.Http;
//</Function_dependencies>

namespace DigitalTwins_Samples
{
    public class DigitalTwinsIngestFunctionSample
    {
        // Your Digital Twin URL is stored in an application setting in Azure Functions
        // <ADT_service_URL>
        private static readonly string adtInstanceUrl = Environment.GetEnvironmentVariable("ADT_SERVICE_URL");
        // </ADT_service_URL>
        // <HTTP_client>
        private static readonly HttpClient singletonHttpClientInstance = new HttpClient();
        // </HTTP_client>

        [FunctionName("TwinsFunction")]
        public void Run([EventGridTrigger] EventGridEvent eventGridEvent, ILogger log)
        {
            log.LogInformation(eventGridEvent.Data.ToString());
            if (adtInstanceUrl == null) log.LogError("Application setting \"ADT_SERVICE_URL\" not set");
            try
            {
                // Authenticate with Digital Twins
                // <ManagedIdentityCredential>
                // To use the function app's system-assigned identity:
                var cred = new ManagedIdentityCredential();
                // To use a user-assigned identity for the function app:
                //var cred = new ManagedIdentityCredential("<uai-client-ID>");
                // </ManagedIdentityCredential>
                // <DigitalTwinsClient>
                var client = new DigitalTwinsClient(
                    new Uri(adtInstanceUrl),
                    cred,
                    new DigitalTwinsClientOptions
                    {
                        Transport = new HttpClientTransport(singletonHttpClientInstance)
                    });
                // </DigitalTwinsClient>
                log.LogInformation($"ADT service client connection created.");

                // Add your business logic here.
            }
            catch (Exception e)
            {
                log.LogError(e.Message);
            }
        }
    }
}

När du är klar med funktionskoden, inklusive att lägga till autentisering och funktionens logik, publicerar du appen i Azure.

Konfigurera publicerad app

Slutför slutligen följande konfigurationssteg för en publicerad Azure-funktion för att se till att den kan komma åt din Azure Digital Twins-instans.

Kör följande kommandon i Azure Cloud Shell eller ett lokalt Azure CLI.

Anteckning

En Azure-användare som har behörighet att hantera användaråtkomst till Azure-resurser, inklusive beviljande och delegering av behörigheter, måste slutföra det här avsnittet. Vanliga roller som uppfyller detta krav är ägare, kontoadministratör eller kombinationen av administratör och deltagare för användaråtkomst. Mer information om behörighetskrav för Azure Digital Twins-roller finns i Konfigurera en instans och autentisering.

Tilldela en åtkomstroll

Azure-funktionen kräver att en ägartoken skickas till den. För att se till att ägartoken skickas beviljar du funktionsappen rollen Azure Digital Twins-dataägare för din Azure Digital Twins-instans, vilket ger funktionsappen behörighet att utföra dataplansaktiviteter på instansen.

Använd följande kommando för att skapa en systemhanterad identitet för din funktion (om funktionen redan har en skrivs dess information ut med det här kommandot). Observera fältet principalId i utdata. Du använder det här ID:t för att referera till funktionen så att du kan ge den behörighet i nästa steg.
```
az functionapp identity assign --resource-group <your-resource-group> --name <your-function-app-name>	
```

principalId Använd värdet i följande kommando för att ge funktionen rollen Azure Digital Twins-dataägare för din Azure Digital Twins-instans.

az dt role-assignment create --dt-name <your-Azure-Digital-Twins-instance> --assignee "<principal-ID>" --role "Azure Digital Twins Data Owner"

Konfigurera programinställningar

Gör sedan URL:en för din Azure Digital Twins-instans tillgänglig för din funktion genom att ange en miljövariabel för den.

Tips

Azure Digital Twins-instansens URL skapas genom att https:// läggs till i början av instansens värdnamn. Om du vill se värdnamnet, tillsammans med alla egenskaper för din instans, kör du az dt show --dt-name <your-Azure-Digital-Twins-instance>.

Följande kommando anger en miljövariabel för din instans URL som funktionen använder när den behöver komma åt instansen.

az functionapp config appsettings set --resource-group <your-resource-group> --name <your-function-app-name> --settings "ADT_SERVICE_URL=https://<your-Azure-Digital-Twins-instance-host-name>"

Autentisera mellan tenanter

Azure Digital Twins är en tjänst som bara stöder en Microsoft Entra-klientorganisation: huvudklientorganisationen från prenumerationen där Azure Digital Twins-instansen finns.

Därför kräver begäranden till Azure Digital Twins-API:erna en användare eller tjänstens huvudnamn som ingår i samma klientorganisation där Azure Digital Twins-instansen finns. För att förhindra skadlig genomsökning av Azure Digital Twins-slutpunkter returnerar begäranden med åtkomsttoken utanför den ursprungliga klientorganisationen felmeddelandet "404 Sub-Domain hittades inte". Det här felet returneras även om användaren eller tjänstens principenhet har tilldelats någon av rollerna Azure Digital Twins Data Owner eller Azure Digital Twins Data Reader via Microsoft Entra B2B-samarbete.

Om du behöver komma åt din Azure Digital Twins-instans med hjälp av ett huvudnamn för tjänsten eller ett användarkonto som tillhör en annan klientorganisation än instansen kan du låta varje federerad identitet från en annan klient begära en token från Azure Digital Twins-instansens "hem"-klientorganisation.

Ett sätt att göra detta är med följande CLI-kommando, där <home-tenant-ID> är ID:t för Microsoft Entra-klientorganisationen som innehåller Azure Digital Twins-instansen:

az account get-access-token --tenant <home-tenant-ID> --resource https://digitaltwins.azure.net

Efter den här begäran får identiteten en token utfärdad för Microsoft Entra-resursen https://digitaltwins.azure.net , som har ett matchande klient-ID-anspråk till Azure Digital Twins-instansen. Om du använder den här token i API-begäranden eller med din Azure.Identity kod bör den federerade identiteten kunna komma åt Azure Digital Twins-resursen.

Du kan också ange hemklientorganisationen i autentiseringsalternativen i din kod.

I följande exempel visas hur du anger ett exempelvärde för klientorganisations-ID i alternativen InteractiveBrowserTenantId och DefaultAzureCredential.

public class DefaultAzureCredentialOptionsSample
{
    // The URL of your instance, starting with the protocol (https://)
    private const string adtInstanceUrl = "https://<your-Azure-Digital-Twins-instance-URL>";

    private static DefaultAzureCredentialOptions credentialOptions = new DefaultAzureCredentialOptions()
    {
        ExcludeSharedTokenCacheCredential = true,
        ExcludeVisualStudioCodeCredential = true,
        TenantId = "<your-Azure-Active-Directory-tenant-ID>"
    };

    private static DefaultAzureCredential credential = new DefaultAzureCredential(credentialOptions);

    DigitalTwinsClient client = new DigitalTwinsClient(new Uri(adtInstanceUrl), credential);
}

Det finns liknande alternativ för att ange en hyresgäst för autentisering med Visual Studio och Visual Studio Code. Mer information om tillgängliga alternativ finns i dokumentationen DefaultAzureCredentialOptions.

Andra autentiseringsmetoder

Om de markerade autentiseringsscenarierna som beskrivs i den här artikeln inte täcker appens behov kan du utforska andra typer av autentisering som erbjuds på Microsofts identitetsplattform. Dokumentationen för den här plattformen omfattar fler autentiseringsscenarier, ordnade efter programtyp.

Nästa steg

Mer information om hur säkerhet fungerar i Azure Digital Twins finns i:

Säkerhet för Azure Digital Twins-lösningar

Eller nu när autentiseringen har konfigurerats går du vidare till att skapa och hantera modeller i din instans:

Hantera DTDL-modeller

Dela via

Skriva klientappens autentiseringskod

Förutsättningar

Autentisera med hjälp av Azure.Identity-biblioteket

Lägga till Azure.Identity i ditt .NET-projekt

Standardmetod förAzureCredential

Konfigurera lokala Azure-autentiseringsuppgifter

ManagedIdentityCredential metod

"InteractiveBrowserCredential"-metod

Autentisera Azure Functions

Skriva programkod

Konfigurera publicerad app

Tilldela en åtkomstroll

Konfigurera programinställningar

Autentisera mellan tenanter

Andra autentiseringsmetoder

Nästa steg

Feedback

Ytterligare resurser