Psaní ověřovacího kódu klientské aplikace

Po nastavení instance a ověřování Azure Digital Twins můžete vytvořit klientskou aplikaci, kterou použijete k interakci s instancí. Jakmile nastavíte počáteční klientský projekt, budete muset v této klientské aplikaci napsat kód, který ho ověří v instanci Azure Digital Twins.

Azure Digital Twins se ověřuje pomocí tokenů zabezpečení Microsoft Entra na základě OAUTH 2.0. K ověření sady SDK budete muset získat nosný token se správnými oprávněními ke službě Azure Digital Twins a předat ho spolu s voláními rozhraní API.

Tento článek popisuje, jak získat přihlašovací údaje pomocí Azure.Identity klientské knihovny. I když tento článek ukazuje příklady kódu v jazyce C#, například to, co byste napsali pro sadu .NET (C#) SDK, můžete použít verzi Azure.Identity bez ohledu na to, jakou sadu SDK používáte (další informace o sadách SDK dostupných pro Azure Digital Twins, viz rozhraní API a sady SDK služby Azure Digital Twins.

Předpoklady

Nejprve proveďte kroky nastavení v části Nastavení instance a ověřování. Toto nastavení zajistí, že máte instanci služby Azure Digital Twins a váš uživatel má přístupová oprávnění. Po nastavení jste připraveni napsat kód klientské aplikace.

Abyste mohli pokračovat, budete potřebovat projekt klientské aplikace, ve kterém napíšete svůj kód. Pokud ještě nemáte nastavený projekt klientské aplikace, vytvořte si v tomto kurzu základní projekt ve zvoleném jazyce.

Ověřování pomocí knihovny Azure.Identity

Azure.Identity je klientská knihovna, která poskytuje několik metod získávání přihlašovacích údajů, které můžete použít k získání nosné tokeny a ověření pomocí sady SDK. I když tento článek obsahuje příklady v jazyce C#, můžete zobrazit Azure.Identity několik jazyků, včetně...

• .NET (C#)
• Java
• JavaScript
• Python

Existují tři běžné metody Azure.Identity získávání přihlašovacích údajů:

• DefaultAzureCredential poskytuje výchozí TokenCredential tok ověřování pro aplikace, které se nasadí do Azure, a je doporučenou volbou pro místní vývoj. Můžete také povolit vyzkoušení dalších dvou metod doporučených v tomto článku; zabalí ManagedIdentityCredential a může přistupovat s InteractiveBrowserCredential konfigurační proměnnou.
• ManagedIdentityCredential funguje dobře v případech, kdy potřebujete spravované identity (MSI) a je vhodným kandidátem pro práci se službou Azure Functions a nasazením do služeb Azure.
• InteractiveBrowserCredential je určený pro interaktivní aplikace a dá se použít k vytvoření ověřeného klienta sady SDK.

Zbývající část tohoto článku ukazuje, jak tyto metody používat se sadou .NET (C#) SDK.

Přidání Azure.Identity do projektu .NET

Pokud chcete nastavit projekt .NET pro ověření Azure.Identity, proveďte následující kroky:

1. Zahrňte balíček Azure.DigitalTwins.Core sady SDK a Azure.Identity balíček do projektu. V závislosti na zvolených nástrojích můžete balíčky zahrnout pomocí správce balíčků sady Visual Studio nebo nástroje příkazového dotnet řádku.

2. Do kódu projektu přidejte následující příkazy using:

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

Dále přidejte kód pro získání přihlašovacích údajů pomocí jedné z metod v Azure.Identity. V následujících částech najdete podrobnější informace o použití jednotlivých částí.

DefaultAzureCredential – metoda

DefaultAzureCredential poskytuje výchozí TokenCredential tok ověřování pro aplikace, které se nasadí do Azure, a je doporučenou volbou pro místní vývoj.

Pokud chcete použít výchozí přihlašovací údaje Azure, budete potřebovat adresu URL instance Služby Azure Digital Twins (pokyny k vyhledání).

Tady je ukázka kódu pro přidání DefaultAzureCredential do projektu:

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

Nastavení místních přihlašovacích údajů Azure

Pomocí DefaultAzureCredentialtéto ukázky vyhledáte přihlašovací údaje ve vašem místním prostředí, jako je přihlášení k Azure v místním Azure CLI nebo v sadě Visual Studio nebo Visual Studio Code. Z tohoto důvodu byste se měli k Azure přihlásit místně prostřednictvím jednoho z těchto mechanismů, abyste pro ukázku nastavili přihlašovací údaje.

Pokud ke spouštění ukázek kódu používáte Visual Studio nebo Visual Studio Code, ujistěte se, že jste k ho editoru přihlášeni pomocí stejných přihlašovacích údajů Azure, které chcete použít pro přístup k vaší instanci Azure Digital Twins. Pokud používáte místní okno rozhraní příkazového řádku, spusťte az login příkaz pro přihlášení ke svému účtu Azure. Potom byste při spuštění ukázky kódu měli být automaticky ověřeni.

Metoda ManagedIdentityCredential

Metoda ManagedIdentityCredential funguje dobře v případech, kdy potřebujete spravované identity (MSI) – například při ověřování pomocí Azure Functions.

To znamená, že můžete použít ManagedIdentityCredential stejný projekt jako DefaultAzureCredential nebo InteractiveBrowserCredential, k ověření jiné části projektu.

Pokud chcete použít výchozí přihlašovací údaje Azure, budete potřebovat adresu URL instance Služby Azure Digital Twins (pokyny k vyhledání). Můžete také potřebovat registraci aplikace a ID aplikace (klienta).

Ve funkci Azure můžete použít přihlašovací údaje spravované identity, jako je tato:

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

Při vytváření přihlašovacích údajů ponechte parametr prázdný, jak je znázorněno výše, vrátí přihlašovací údaje pro identitu přiřazenou systémem aplikace funkcí, pokud ho má. Pokud chcete místo toho zadat identitu přiřazenou uživatelem, předejte do parametru ID klienta přiřazené uživatelem.

InteractiveBrowserCredential – metoda

Metoda InteractiveBrowserCredential je určená pro interaktivní aplikace a vyvolá webový prohlížeč pro ověřování. Tuto metodu můžete použít místo DefaultAzureCredential v případech, kdy potřebujete interaktivní ověřování.

Pokud chcete používat přihlašovací údaje interaktivního prohlížeče, budete potřebovat registraci aplikace, která má oprávnění k rozhraním API služby Azure Digital Twins. Postup nastavení registrace aplikace najdete v tématu Vytvoření registrace aplikace s přístupem ke službě Azure Digital Twins. Po nastavení registrace aplikace budete potřebovat...

• ID aplikace registrace (klienta)
• ID adresáře (tenanta) registrace aplikace
• adresa URL instance Azure Digital Twins

Tady je příklad kódu pro vytvoření ověřeného klienta sady SDK pomocí 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);
        }
    }
}

Ověřování Azure Functions

Tato část obsahuje některé důležité volby konfigurace v kontextu ověřování ve službě Azure Functions. Nejprve si přečtete o doporučených proměnných na úrovni třídy a ověřovacím kódu, který funkci umožní přístup ke službě Azure Digital Twins. Pak si přečtete několik konečných kroků konfigurace, které se pro vaši funkci dokončí po publikování kódu do Azure.

Psaní kódu aplikace

Při psaní funkce Azure zvažte přidání těchto proměnných a kódu do funkce:

• Kód pro čtení adresy URL služby Azure Digital Twins jako proměnné prostředí nebo nastavení konfigurace Je vhodné si přečíst adresu URL služby z nastavení aplikace nebo proměnné prostředí, a ne pevně ji zakódovat ve funkci. Ve funkci Azure může tento kód pro čtení proměnné prostředí vypadat takto:

  private static readonly string adtInstanceUrl = Environment.GetEnvironmentVariable("ADT_SERVICE_URL");
  

  Později po publikování funkce vytvoříte a nastavíte hodnotu proměnné prostředí pro čtení tohoto kódu. Pokyny k tomu, jak to udělat, přeskočte k části Konfigurace nastavení aplikace.

• Statická proměnná pro uložení instance HttpClient. Vytvoření HttpClient je poměrně nákladné, takže ho pravděpodobně budete chtít vytvořit jednou pomocí ověřovacího kódu, abyste se vyhnuli jeho vytvoření pro každé vyvolání funkce.

  private static readonly HttpClient singletonHttpClientInstance = new HttpClient();
  

• Přihlašovací údaje spravované identity. Vytvořte přihlašovací údaje spravované identity, které bude vaše funkce používat pro přístup ke službě 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>");
  

  Když parametr necháte prázdný, jak je uvedeno výše, vrátí přihlašovací údaje pro identitu přiřazenou systémem aplikace funkcí, pokud ji má. Pokud chcete místo toho zadat identitu přiřazenou uživatelem, předejte do parametru ID klienta přiřazené uživatelem.

  Později po publikování funkce zajistíte, že identita funkce má oprávnění pro přístup k rozhraním API služby Azure Digital Twins. Pokyny k tomu, jak to udělat, přeskočte dopředu a přiřaďte přístupovou roli.

• Místní proměnná DigitalTwinsClient. Přidejte proměnnou uvnitř funkce pro uložení instance klienta Azure Digital Twins. Tuto proměnnou nestavte ve své třídě jako statickou.

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

• A null check for adtInstanceUrl. Přidejte kontrolu null a pak zabalte logiku funkce do bloku try/catch, aby se zachytily všechny výjimky.

Po přidání těchto proměnných do funkce může kód funkce vypadat jako v následujícím příkladu.

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

Po dokončení kódu funkce, včetně přidání ověřování a logiky funkce, publikujte aplikaci do Azure.

Konfigurace publikované aplikace

Nakonec proveďte následující kroky konfigurace publikované funkce Azure, abyste měli jistotu, že má přístup k vaší instanci Azure Digital Twins.

V Azure Cloud Shellu nebo místním Azure CLI spusťte následující příkazy.

Přiřazení přístupové role

Funkce Azure vyžaduje předání nosného tokenu. Aby se zajistilo předání nosného tokenu, udělte aplikaci funkcí roli Vlastník dat Azure Digital Twins pro vaši instanci služby Azure Digital Twins, která aplikaci funkcí udělí oprávnění k provádění aktivit roviny dat v instanci.

1. Pomocí následujícího příkazu vytvořte identitu spravovanou systémem pro vaši funkci (pokud ji už funkce obsahuje, vytiskne tento příkaz jeho podrobnosti). Poznamenejte si principalId pole ve výstupu. Toto ID použijete k odkazování na funkci, abyste jí mohli udělit oprávnění v dalším kroku.

   az functionapp identity assign --resource-group <your-resource-group> --name <your-function-app-name>	
   

2. principalId Pomocí hodnoty v následujícím příkazu dejte funkci roli Vlastník dat Azure Digital Twins pro vaši instanci Azure Digital Twins.

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

Konfigurace nastavení aplikace

Dále nastavte adresu URL vaší instance Azure Digital Twins, která bude přístupná vaší funkci nastavením proměnné prostředí.

Následující příkaz nastaví proměnnou prostředí pro adresu URL vaší instance, kterou bude vaše funkce používat při každém přístupu k instanci.

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>"

Ověřování mezi tenanty

Azure Digital Twins je služba, která podporuje pouze jednoho tenanta Microsoft Entra: hlavního tenanta z předplatného, ve kterém se nachází instance Azure Digital Twins.

V důsledku toho požadavky na rozhraní API služby Azure Digital Twins vyžadují uživatele nebo instanční objekt, který je součástí stejného tenanta, ve kterém se nachází instance služby Azure Digital Twins. Aby se zabránilo škodlivé kontrole koncových bodů služby Azure Digital Twins, budou žádosti s přístupovými tokeny mimo původního tenanta vráceny chybovou zprávou "404 Sub-Domain not found" (Nenalezena poddoména 404). Tato chyba se vrátí i v případě, že uživateli nebo instančnímu objektu byla udělena role vlastníka dat Azure Digital Twins nebo role Čtenář dat Azure Digital Twins prostřednictvím spolupráce Microsoft Entra B2B.

Pokud potřebujete získat přístup k instanci Služby Azure Digital Twins pomocí instančního objektu nebo uživatelského účtu, který patří jinému tenantovi od instance, můžete mít každou federovanou identitu z jiného tenanta požádat o token z "domovského" tenanta instance Azure Digital Twins.

Jedním ze způsobů, jak to udělat, je následující příkaz rozhraní příkazového řádku, kde <home-tenant-ID> je ID tenanta Microsoft Entra, který obsahuje instanci Azure Digital Twins:

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

Po vyžádání této identity obdrží token vystavený pro https://digitaltwins.azure.net prostředek Microsoft Entra, který má odpovídající deklaraci ID tenanta pro instanci Azure Digital Twins. Použití tohoto tokenu v požadavcích rozhraní API nebo s vaším Azure.Identity kódem by mělo umožnit federované identitě přístup k prostředku Azure Digital Twins.

Můžete také zadat domovského tenanta v možnostech přihlašovacích údajů v kódu.

Následující příklad ukazuje, jak nastavit ukázkovou hodnotu ID tenanta pro InteractiveBrowserTenantId v možnostech 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);
}

Existují podobné možnosti, jak nastavit tenanta pro ověřování pomocí sady Visual Studio a editoru Visual Studio Code. Další informace o dostupných možnostech najdete v dokumentaci DefaultAzureCredentialOptions.

Jiné metody přihlašovacích údajů

Pokud výše uvedené zvýrazněné scénáře ověřování nepokrývají potřeby vaší aplikace, můžete prozkoumat další typy ověřování nabízené na platformě Microsoft Identity Platform. Dokumentace pro tuto platformu popisuje více scénářů ověřování uspořádaných podle typu aplikace.

Další kroky

Přečtěte si další informace o tom, jak funguje zabezpečení ve službě Azure Digital Twins:

• Zabezpečení pro řešení Azure Digital Twins

Nebo teď, když je ověřování nastavené, přejděte k vytváření a správě modelů ve vaší instanci:

• Správa modelů DTDL