Ügyfélalkalmazás-hitelesítési kód írása

Miután beállított egy Azure Digital Twins-példányt és -hitelesítést, létrehozhat egy ügyfélalkalmazást, amelyet használni fog a példány használatához. Miután beállított egy kezdő ügyfélprojektet, kódot kell írnia az ügyfélalkalmazásban, hogy hitelesítse azt az Azure Digital Twins-példányon.

Az Azure Digital Twins az OAUTH 2.0-n alapuló Microsoft Entra biztonsági jogkivonatokkal hitelesít. Az SDK hitelesítéséhez le kell szereznie egy tulajdonosi jogkivonatot a megfelelő engedélyekkel az Azure Digital Twinshez, és továbbítania kell azt az API-hívásokkal együtt.

Ez a cikk bemutatja, hogyan szerezhet be hitelesítő adatokat az Azure.Identity ügyfélkódtár használatával. Bár ez a cikk c#-kódpéldákat mutat be, például azt, hogy mit ír a .NET (C#) SDK-hoz, a használt SDK-któl függetlenül használhat egy verziót Azure.Identity (az Azure Digital Twinshez elérhető SDK-król további információt az Azure Digital Twins API-k és az SDK-k című témakörben talál.

Előfeltételek

Először végezze el a példány és a hitelesítés beállításának lépéseit. Ez a beállítás biztosítja, hogy rendelkezik Egy Azure Digital Twins-példánysal, és a felhasználó hozzáférési engedélyekkel rendelkezzen. A beállítás után készen áll az ügyfélalkalmazás kódjának írására.

A folytatáshoz szüksége van egy ügyfélalkalmazás-projektre, amelyben megírja a kódot. Ha még nincs beállítva ügyfélalkalmazás-projekt, hozzon létre egy alapszintű projektet az ön által választott nyelven, amelyet ezzel az oktatóanyaggal használhat.

Hitelesítés az Azure.Identity-kódtár használatával

Azure.Identity Egy ügyfélkódtár, amely számos hitelesítőadat-lekérési módszert biztosít, amelyekkel lekérheti a tulajdonosi jogkivonatot, és hitelesítheti az SDK-val. Bár ez a cikk példákat tartalmaz a C#-ban, számos nyelvet tekinthet meg Azure.Identity , többek között...

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

Három gyakori hitelesítőadat-lekérési módszer a Azure.Identity következő:

• A DefaultAzureCredential alapértelmezett TokenCredential hitelesítési folyamatot biztosít az Azure-ban üzembe helyezett alkalmazásokhoz. Ez a módszer ajánlott a helyi fejlesztéshez. A cikkben javasolt másik két módszer kipróbálása is engedélyezhető; ez körbefut, ManagedIdentityCredential és egy konfigurációs változóval is elérhető InteractiveBrowserCredential .
• A ManagedIdentityCredential jól működik olyan esetekben, amikor felügyelt identitásra (MSI) van szüksége. Ez a módszer jó választás az Azure Functions használatához és az Azure-szolgáltatásokban való üzembe helyezéshez.
• Az InteractiveBrowserCredential interaktív alkalmazásokhoz készült. Ez a módszer hitelesített SDK-ügyfél létrehozásához használható.

A cikk további része bemutatja, hogyan használhatja ezeket a metódusokat a .NET (C#) SDK-val.

Azure.Identity hozzáadása a .NET-projekthez

A .NET-projekt hitelesítésének Azure.Identitybeállításához hajtsa végre a következő lépéseket:

1. Vegye fel az SDK-csomagot Azure.DigitalTwins.Core és a Azure.Identity csomagot a projektbe. A választott eszközöktől függően a csomagokat a Visual Studio csomagkezelőjével vagy a dotnet parancssori eszközzel is felveheti.

2. Adja hozzá a következő utasításokat a projektkódhoz:

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

Ezután adjon hozzá kódot a hitelesítő adatok beszerzéséhez a következő Azure.Identitymetódusok egyikével: . Az alábbi szakaszok részletesebben ismertetik az egyes műveletek használatát.

DefaultAzureCredential metódus

A DefaultAzureCredential alapértelmezett TokenCredential hitelesítési folyamatot biztosít az Azure-ban üzembe helyezett alkalmazásokhoz. Ez a módszer ajánlott a helyi fejlesztéshez.

Az alapértelmezett Azure-hitelesítő adatok használatához szüksége van az Azure Digital Twins-példány URL-címére (a kereséshez szükséges utasításokra).

Íme egy kódminta a projekthez való hozzáadásához DefaultAzureCredential :

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

Helyi Azure-hitelesítő adatok beállítása

Ezzel DefaultAzureCredentiala példával a minta hitelesítő adatokat keres a helyi környezetben, például egy Azure-bejelentkezést egy helyi Azure CLI-ben vagy a Visual Studióban vagy a Visual Studio Code-ban. Ezért helyileg kell bejelentkeznie az Azure-ba ezen mechanizmusok egyikével a minta hitelesítő adatainak beállításához.

Ha a Visual Studio vagy a Visual Studio Code használatával futtat kódmintákat, győződjön meg arról , hogy ugyanazokkal az Azure-hitelesítő adatokkal jelentkezett be a szerkesztőbe , amelyeket az Azure Digital Twins-példány eléréséhez használni szeretne. Ha helyi CLI-ablakot használ, futtassa a parancsot az az login Azure-fiókba való bejelentkezéshez. Ezt követően a kódminta futtatásakor automatikusan hitelesíteni kell.

ManagedIdentityCredential metódus

A ManagedIdentityCredential metódus jól működik azokban az esetekben, amikor felügyelt identitásokra (MSI) van szüksége – például az Azure Functions-hitelesítéskor.

Ez azt jelenti, hogy ugyanabban a projektben használhatja ManagedIdentityCredential , mint DefaultAzureCredential vagy InteractiveBrowserCredentiala projekt egy másik részének hitelesítéséhez.

Az alapértelmezett Azure-hitelesítő adatok használatához szüksége van az Azure Digital Twins-példány URL-címére (a kereséshez szükséges utasításokra). Szükség lehet egy alkalmazásregisztrációra és a regisztrációs alkalmazás (ügyfél) azonosítójára is.

Egy Azure-függvényben a következő módon használhatja a felügyelt identitás hitelesítő adatait:

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

Amikor paraméterek nélkül hozza létre a hitelesítő adatokat, ahogy az az előző példában is látható, az visszaadja a függvényalkalmazás rendszer által hozzárendelt identitásának hitelesítő adatait, ha van ilyenje. Ha ehelyett felhasználó által hozzárendelt identitást szeretne megadni, adja meg a felhasználó által hozzárendelt identitás ügyfélazonosítóját a id konstruktor paraméterének.

InteractiveBrowserCredential metódus

Az InteractiveBrowserCredential metódus interaktív alkalmazásokhoz készült, és egy webböngészőt hoz létre a hitelesítéshez. Ezt a módszert használhatja DefaultAzureCredential azokban az esetekben, amikor interaktív hitelesítésre van szükség.

Az interaktív böngésző hitelesítő adatainak használatához olyan alkalmazásregisztrációra van szükség, amely engedélyekkel rendelkezik az Azure Digital Twins API-khoz. Az alkalmazásregisztráció beállításának lépéseit az Alkalmazásregisztráció létrehozása Azure Digital Twins-hozzáféréssel című témakörben találja. Az alkalmazásregisztráció beállítása után a következő értékekre lesz szüksége:

• az alkalmazásregisztrációs alkalmazás (ügyfél) azonosítója
• az alkalmazásregisztráció címtárának (bérlőjének) azonosítója
• az Azure Digital Twins-példány URL-címe

Íme egy példa arra a kódra, amely egy hitelesített SDK-ügyfelet hoz létre a használatával 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);
        }
    }
}

Az Azure Functions hitelesítése

Ez a szakasz néhány fontos konfigurációs lehetőséget tartalmaz az Azure Functions-hitelesítés kontextusában. Először az ajánlott osztályszintű változókról és hitelesítési kódról olvashat, amelyek lehetővé teszik a függvény számára az Azure Digital Twins elérését. Ezután elolvashat néhány végső konfigurációs lépést, amelyet a függvénynek végre kell hajtania a kód Azure-ban való közzététele után.

Alkalmazáskód írása

Az Azure-függvény írásakor vegye fel ezeket a változókat és kódot a függvénybe:

• Kód az Azure Digital Twins szolgáltatás URL-címének környezeti változóként vagy konfigurációs beállításként való olvasásához. Ajánlott beolvasni a szolgáltatás URL-címét egy alkalmazásbeállításból/környezeti változóból, ahelyett, hogy a függvényben kódolva lenne. Egy Azure-függvényben a környezeti változó olvasására használt kód a következőképpen nézhet ki:

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

  Később, a függvény közzététele után létrehozza és be fogja állítani a kódhoz tartozó környezeti változó értékét olvasásra. Ennek módjával kapcsolatos útmutatásért ugorjon tovább az alkalmazásbeállítások konfigurálásához.

• Egy httpClient-példány tárolására használt statikus változó. A HttpClient létrehozása viszonylag költséges, ezért érdemes egyszer létrehozni a hitelesítési kóddal, hogy ne hozza létre minden függvényhíváshoz.

  private static readonly HttpClient singletonHttpClientInstance = new HttpClient();
  

• Felügyelt identitás hitelesítő adatai. Hozzon létre egy felügyelt identitás hitelesítő adatait, amelyet a függvény az Azure Digital Twins eléréséhez használ.

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

  Amikor paraméterek nélkül hozza létre a hitelesítő adatokat, ahogy az az előző példában is látható, az visszaadja a függvényalkalmazás rendszer által hozzárendelt identitásának hitelesítő adatait, ha van ilyenje. Ha ehelyett felhasználó által hozzárendelt identitást szeretne megadni, adja meg a felhasználó által hozzárendelt identitás ügyfélazonosítóját a id konstruktor paraméterének.

  Később, a függvény közzététele után győződjön meg arról, hogy a függvény identitása rendelkezik engedéllyel az Azure Digital Twins API-k eléréséhez. Ennek módjával kapcsolatos útmutatásért ugorjon előre a hozzáférési szerepkör hozzárendeléséhez.

• A DigitalTwinsClient helyi változója. Adja hozzá a változót a függvényhez az Azure Digital Twins-ügyfélpéldány tárolásához. Ne tegye ezt a változót statikussá az osztályon belül.

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

• Null értékű ellenőrzés az adtInstanceUrl esetében. A kivételek elhárításához adja hozzá a null ellenőrzést, majd csomagolja be a függvénylogikát egy próba/fogási blokkba.

Miután hozzáadta ezeket a változókat egy függvényhez, a függvénykód az alábbi példához hasonlóan nézhet ki.

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

Ha végzett a függvénykóddal, beleértve a hitelesítést és a függvény logikáját, tegye közzé az alkalmazást az Azure-ban

Közzétett alkalmazás konfigurálása

Végül végezze el a következő konfigurációs lépéseket egy közzétett Azure-függvényhez, hogy biztosan hozzáférhessen az Azure Digital Twins-példányhoz.

Futtassa az alábbi parancsokat az Azure Cloud Shellben vagy egy helyi Azure CLI-ben.

Hozzáférési szerepkör hozzárendelése

Az Azure-függvényhez egy tulajdonosi jogkivonatot kell átadni. A tulajdonosi jogkivonat átadásához adja meg a függvényalkalmazásnak az Azure Digital Twins-példány Azure Digital Twins-adattulajdonosi szerepkörét, amely engedélyt ad a függvényalkalmazásnak az adatsík-tevékenységek végrehajtására a példányon.

1. A következő paranccsal hozzon létre egy rendszer által felügyelt identitást a függvényhez (ha a függvény már rendelkezik ilyenrel, ez a parancs kinyomtatja annak részleteit). Jegyezze fel a principalId kimenet mezőjét. Ezzel az azonosítóval hivatkozhat a függvényre, így a következő lépésben engedélyeket adhat neki.

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

2. principalId Az alábbi paranccsal adja meg a függvény Azure Digital Twins-adattulajdonosi szerepkörét az Azure Digital Twins-példányhoz.

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

Alkalmazásbeállítások konfigurálása

Ezután tegye elérhetővé az Azure Digital Twins-példány URL-címét a függvény számára egy környezeti változó beállításával.

Az alábbi parancs beállít egy környezeti változót a példány URL-címéhez, amelyet a függvény minden alkalommal használni fog, amikor hozzá kell férnie a példányhoz.

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

Hitelesítés bérlőkön keresztül

Az Azure Digital Twins egy szolgáltatás, amely csak egy Microsoft Entra-bérlőt támogat: a fő bérlőt abból az előfizetésből, amelyben az Azure Digital Twins-példány található.

Ennek eredményeképpen az Azure Digital Twins API-khoz irányuló kérésekhez olyan felhasználóra vagy szolgáltatásnévre van szükség, amely ugyanahhoz a bérlőhöz tartozik, ahol az Azure Digital Twins-példány található. Az Azure Digital Twins-végpontok rosszindulatú vizsgálatának megakadályozása érdekében a rendszer "404 altartomány nem található" hibaüzenetet ad vissza az eredeti bérlőn kívüli hozzáférési jogkivonatokkal. Ez a hiba akkor is megjelenik, ha a felhasználó vagy szolgáltatásnév Azure Digital Twins-adattulajdonosi vagy Azure Digital Twins-adatolvasói szerepkört kapott a Microsoft Entra B2B együttműködésével.

Ha az Azure Digital Twins-példányt egy olyan szolgáltatásnévvel vagy felhasználói fiókkal kell elérnie, amely a példánytól eltérő bérlőhöz tartozik, minden egyes összevont identitás egy másik bérlőtől kérhet jogkivonatot az Azure Digital Twins-példány "otthoni" bérlőjétől.

Ennek egyik módja a következő CLI-parancs, ahol <home-tenant-ID> az Azure Digital Twins-példányt tartalmazó Microsoft Entra-bérlő azonosítója található:

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

Ezt követően az identitás megkapja a https://digitaltwins.azure.net Microsoft Entra-erőforráshoz kiadott jogkivonatot, amely egyező bérlőazonosító-jogcímet biztosít az Azure Digital Twins-példányhoz. Ha ezt a jogkivonatot API-kérésekben vagy a Azure.Identity kóddal használja, engedélyeznie kell az összevont identitás számára az Azure Digital Twins-erőforrás elérését.

Az otthoni bérlőt a kód hitelesítő adatai között is megadhatja.

Az alábbi példa bemutatja, hogyan állíthat be egy bérlőazonosító-mintaértéket InteractiveBrowserTenantId a DefaultAzureCredential beállítások között:

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

A Visual Studióval és a Visual Studio Code-tal való hitelesítéshez hasonló lehetőségek állnak rendelkezésre a bérlők beállításához. Az elérhető lehetőségekről további információt a DefaultAzureCredentialOptions dokumentációjában talál.

Egyéb hitelesítő módszerek

Ha a cikkben ismertetett kiemelt hitelesítési forgatókönyvek nem fedik le az alkalmazás igényeit, a Microsoft Identitásplatform kínált egyéb típusú hitelesítéseket is megismerheti. A platform dokumentációja több hitelesítési forgatókönyvet is tartalmaz, alkalmazástípus szerint rendezve.

Következő lépések

További információ a biztonság működéséről az Azure Digital Twinsben:

• Az Azure Digital Twins-megoldások biztonsága

Vagy most, hogy a hitelesítés be van állítva, lépjen tovább a modellek létrehozására és kezelésére a példányban:

• DTDL-modellek kezelése