İstemci uygulaması kimlik doğrulama kodu yazma

Makale
03/25/2023

Bir Azure Digital Twins örneği ve kimlik doğrulaması ayarladıktan sonra, örnekle etkileşim kurmak için kullanacağınız bir istemci uygulaması oluşturabilirsiniz. Başlangıç istemci projesini ayarladıktan sonra Azure Digital Twins örneğinde kimlik doğrulaması yapmak için bu istemci uygulamasına kod yazmanız gerekir.

Azure Digital Twins, OAUTH 2.0 tabanlı Microsoft Entra Güvenlik Belirteçlerini kullanarak kimlik doğrulaması yapar. SDK'nızın kimliğini doğrulamak için Azure Digital Twins için doğru izinlere sahip bir taşıyıcı belirteci almanız ve API çağrılarınızla birlikte iletmeniz gerekir.

Bu makalede, istemci kitaplığını kullanarak kimlik bilgilerinin nasıl alındığı Azure.Identity açıklanır. Bu makalede C# dilinde kod örnekleri gösterilip .NET (C#) SDK'sı için ne yazacağınız gibi örnekler gösterilebilir ancak kullandığınız SDK'ya bakılmaksızın sürümünü kullanabilirsiniz (Azure Digital Twins için kullanılabilen SDK'lar hakkında daha fazla bilgi için bkz. Azure Digital Twins API'leri ve SDK'ları.Azure.Identity

Ön koşullar

İlk olarak, Örnek ve kimlik doğrulaması ayarlama'daki kurulum adımlarını tamamlayın. Bu kurulum, bir Azure Digital Twins örneğine sahip olduğunuzdan ve kullanıcınızın erişim izinlerine sahip olduğundan emin olur. Bu kurulumdan sonra istemci uygulama kodu yazmaya hazırsınız demektir.

Devam etmek için kodunuzu yazdığınız bir istemci uygulaması projesi gerekir. Henüz ayarlanmış bir istemci uygulama projeniz yoksa, bu öğreticiyle kullanmak istediğiniz dilde temel bir proje oluşturun.

Azure.Identity kitaplığını kullanarak kimlik doğrulaması

Azure.Identity , taşıyıcı belirteci almak ve SDK'nızla kimlik doğrulaması yapmak için kullanabileceğiniz birkaç kimlik bilgisi alma yöntemi sağlayan bir istemci kitaplığıdır. Bu makalede C# dilinde örnekler verilmektedir Azure.Identity ancak...

içindeki Azure.Identity üç yaygın kimlik bilgisi alma yöntemi şunlardır:

DefaultAzureCredential, Azure'a dağıtılacak uygulamalar için varsayılan TokenCredential bir kimlik doğrulama akışı sağlar ve yerel geliştirme için önerilen seçenektir. Bu makalede önerilen diğer iki yöntemi denemek için de etkinleştirilebilir; sarmalar ManagedIdentityCredential ve bir yapılandırma değişkeni ile erişebilir InteractiveBrowserCredential .
ManagedIdentityCredential, yönetilen kimliklere (MSI) ihtiyaç duyduğunuz durumlarda iyi çalışır ve Azure İşlevleri ile çalışmak ve Azure hizmetlerine dağıtmak için iyi bir adaydır.
InteractiveBrowserCredential , etkileşimli uygulamalara yöneliktir ve kimliği doğrulanmış bir SDK istemcisi oluşturmak için kullanılabilir.

Bu makalenin geri kalanında bu yöntemlerin .NET (C#) SDK ile nasıl kullanılacağı gösterilmektedir.

.NET projenize Azure.Identity ekleme

.NET projenizi ile Azure.Identitykimlik doğrulaması yapmak üzere ayarlamak için aşağıdaki adımları tamamlayın:

SDK paketini ve Azure.Identity paketi Azure.DigitalTwins.Core projenize ekleyin. Seçtiğiniz araçlara bağlı olarak, Visual Studio paket yöneticisini veya dotnet komut satırı aracını kullanarak paketleri ekleyebilirsiniz.

Proje kodunuza aşağıdaki using deyimlerini ekleyin:

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

Ardından, içindeki Azure.Identityyöntemlerden birini kullanarak kimlik bilgilerini almak için kod ekleyin. Aşağıdaki bölümlerde her birini kullanma hakkında daha fazla ayrıntı verebilirsiniz.

DefaultAzureCredential yöntemi

DefaultAzureCredential, Azure'a dağıtılacak uygulamalar için varsayılan TokenCredential bir kimlik doğrulama akışı sağlar ve yerel geliştirme için önerilen seçenektir.

Varsayılan Azure kimlik bilgilerini kullanmak için Azure Digital Twins örneğinin URL'sine (bulma yönergeleri) ihtiyacınız vardır.

İşte projenize eklemek için bir DefaultAzureCredential kod örneği:

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

Dekont

Şu anda sarmalayıcı sınıfını DefaultAzureCredential etkileyen ve kimlik doğrulaması sırasında hataya neden olabilecek bilinen bir sorun vardır. Bu sorunla karşılaşırsanız, çözmek için aşağıdaki isteğe bağlı parametreyle örnek DefaultAzureCredential oluşturmayı deneyebilirsiniz: new DefaultAzureCredential(new DefaultAzureCredentialOptions { ExcludeSharedTokenCacheCredential = true });

Bu sorun hakkında daha fazla bilgi için bkz . Azure Digital Twins bilinen sorunlar.

Yerel Azure kimlik bilgilerini ayarlama

ileDefaultAzureCredential, örnek yerel ortamınızda yerel Azure CLI'da veya Visual Studio ya da Visual Studio Code'da Azure oturumu açma gibi kimlik bilgilerini arar. Bu nedenle, örneğin kimlik bilgilerini ayarlamak için bu mekanizmalardan biriyle Azure'da yerel olarak oturum açmanız gerekir.

Kod örneklerini çalıştırmak için Visual Studio veya Visual Studio Code kullanıyorsanız, Azure Digital Twins örneğine erişmek için kullanmak istediğiniz Azure kimlik bilgileriyle bu düzenleyicide oturum açtığınızdan emin olun. Yerel CLI penceresi kullanıyorsanız Azure hesabınızda oturum açmak için komutunu çalıştırın az login . Bundan sonra, kod örneğinizi çalıştırdığınızda otomatik olarak kimliğiniz doğrulanmalıdır.

ManagedIdentityCredential yöntemi

ManagedIdentityCredential yöntemi, yönetilen kimliklere (MSI) ihtiyaç duyduğunuz durumlarda (örneğin, Azure İşlevleri ile kimlik doğrulaması yaparken) iyi çalışır.

Bu, projenin farklı bir bölümünde kimlik doğrulaması yapmak için veya InteractiveBrowserCredentialile DefaultAzureCredential aynı projede kullanabileceğiniz ManagedIdentityCredential anlamına gelir.

Varsayılan Azure kimlik bilgilerini kullanmak için Azure Digital Twins örneğinin URL'sine (bulma yönergeleri) ihtiyacınız vardır. Ayrıca bir uygulama kaydına ve kaydın Uygulama (istemci) kimliğine de ihtiyacınız olabilir.

Azure işlevinde aşağıdaki gibi yönetilen kimlik kimlik bilgilerini kullanabilirsiniz:

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

Kimlik bilgisi oluşturulurken, yukarıda gösterildiği gibi parametresi boş bırakılırsa işlev uygulamasının sistem tarafından atanan kimliği (varsa) için kimlik bilgisi döndürülecektir. Bunun yerine kullanıcı tarafından atanan bir kimlik belirtmek için, kullanıcı tarafından atanan kimliğin istemci kimliğini parametresine geçirin.

InteractiveBrowserCredential yöntemi

InteractiveBrowserCredential yöntemi etkileşimli uygulamalara yöneliktir ve kimlik doğrulaması için bir web tarayıcısı getirir. Etkileşimli kimlik doğrulaması gerektiren durumlar yerine DefaultAzureCredential bu yöntemi kullanabilirsiniz.

Etkileşimli tarayıcı kimlik bilgilerini kullanmak için Azure Digital Twins API'leri için izinlere sahip bir uygulama kaydına sahip olmanız gerekir. Bu uygulama kaydını ayarlama adımları için bkz . Azure Digital Twins erişimiyle uygulama kaydı oluşturma. Uygulama kaydı ayarlandıktan sonra...

Aşağıda kullanarak kimliği doğrulanmış bir SDK istemcisi oluşturmaya yönelik bir kod örneği verilmiştır 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);
        }
    }
}

Dekont

İstemci kimliğini, kiracı kimliğini ve örnek URL'sini yukarıda gösterildiği gibi doğrudan koda yerleştirebilirsiniz ancak kodunuzun bu değerleri bir yapılandırma dosyasından veya ortam değişkeninden alması iyi bir fikirdir.

kimlik doğrulaması Azure İşlevleri

Bu bölüm, Azure İşlevleri kimlik doğrulaması bağlamındaki bazı önemli yapılandırma seçeneklerini içerir. İlk olarak, işlevin Azure Digital Twins'e erişmesine izin verecek önerilen sınıf düzeyinde değişkenler ve kimlik doğrulama kodu hakkında bilgi edineceksiniz. Ardından, kodu Azure'da yayımlandıktan sonra işleviniz için tamamlanması gereken bazı son yapılandırma adımları hakkında bilgi edineceksiniz.

Uygulama kodu yazma

Azure işlevini yazarken işlevinize şu değişkenleri ve kodu eklemeyi göz önünde bulundurun:

Azure Digital Twins hizmet URL'sini ortam değişkeni veya yapılandırma ayarı olarak okumak için kod. Hizmet URL'sini işlevde sabit kodlamak yerine bir uygulama ayarından/ortam değişkeninden okumak iyi bir uygulamadır. Azure işlevinde ortam değişkenini okumak için bu kod aşağıdaki gibi görünebilir:
```
private static readonly string adtInstanceUrl = Environment.GetEnvironmentVariable("ADT_SERVICE_URL");
```
Daha sonra işlevi yayımladıktan sonra, bu kodun okunacağı ortam değişkeninin değerini oluşturacak ve ayarlayacaksınız. Bunu yapma yönergeleri için Uygulama ayarlarını yapılandırma bölümüne atlayın.
HttpClient örneğini tutan statik değişken. HttpClient'ın oluşturulması nispeten pahalı olduğundan, her işlev çağrısında oluşturulmasını önlemek için kimlik doğrulama koduyla bir kez oluşturmak isteyebilirsiniz.
```
private static readonly HttpClient singletonHttpClientInstance = new HttpClient();
```
Yönetilen kimlik kimlik bilgileri. İşlevinizin Azure Digital Twins'e erişmek için kullanacağı bir yönetilen kimlik kimlik bilgisi oluşturun.
```
// 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>");
```
Parametreyi yukarıda gösterildiği gibi boş bırakmak, varsa işlev uygulamasının sistem tarafından atanan kimliğinin kimlik bilgilerini döndürür. Bunun yerine kullanıcı tarafından atanan bir kimlik belirtmek için, kullanıcı tarafından atanan kimliğin istemci kimliğini parametresine geçirin.

Daha sonra işlevi yayımladıktan sonra işlevin kimliğinin Azure Digital Twins API'lerine erişme izni olduğundan emin olacaksınız. Bunu nasıl yapacağınıza ilişkin yönergeler için Erişim rolü atama bölümüne atlayın.

DigitalTwinsClient yerel değişkeni. Azure Digital Twins istemci örneğinizi tutmak için değişkeni işlevinizin içine ekleyin. Bu değişkeni sınıfınızın içinde statik yapmayın.

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

adtInstanceUrl için null denetim. Null denetimi ekleyin ve ardından özel durumları yakalamak için işlev mantığınızı try/catch bloğuna sarmalayın.

Bu değişkenler bir işleve eklendikten sonra işlev kodunuz aşağıdaki örnekteki gibi görünebilir.

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

Kimlik doğrulaması ve işlevin mantığı dahil olmak üzere işlev kodunuzla işiniz bittiğinde uygulamayı Azure'da yayımlayın

Yayımlanan uygulamayı yapılandırma

Son olarak, yayımlanan bir Azure işlevinin Azure Digital Twins örneğine erişebildiğinden emin olmak için aşağıdaki yapılandırma adımlarını tamamlayın.

Azure Cloud Shell'de veya yerel bir Azure CLI'da aşağıdaki komutları çalıştırın.

Dekont

Bu bölüm, izin verme ve temsilci atama dahil olmak üzere Azure kaynaklarına kullanıcı erişimini yönetme izinleri olan bir Azure kullanıcısı tarafından tamamlanmalıdır. Bu gereksinimi karşılayan yaygın roller Sahip, Hesap yöneticisi veya Kullanıcı Erişimi Yönetici istrator ve Katkıda Bulunan birleşimidir. Azure Digital Twins rolleri için izin gereksinimleri hakkında daha fazla bilgi için bkz . Örnek ve kimlik doğrulaması ayarlama.

Erişim rolü atama

Azure işlevine bir taşıyıcı belirtecin geçirilmesi gerekir. Taşıyıcı belirtecinin geçirildiğinden emin olmak için işlev uygulamasına Azure Digital Twins örneğiniz için Azure Digital Twins Veri Sahibi rolünü verin. Bu rol işlev uygulamasına örnekte veri düzlemi etkinlikleri gerçekleştirme izni verir.

İşleviniz için sistem tarafından yönetilen bir kimlik oluşturmak için aşağıdaki komutu kullanın (işlevin zaten bir kimliği varsa, bu komut ayrıntılarını yazdırır). Çıktıdaki principalId alanı not alın. Sonraki adımda işleve izin verebilmek için işleve başvurmak için bu kimliği kullanacaksınız.
```
az functionapp identity assign --resource-group <your-resource-group> --name <your-function-app-name>	
```
İşleve principalIdAzure Digital Twins örneğinizin Azure Digital Twins Veri Sahibi rolünü vermek için aşağıdaki komuttaki değeri kullanın.
```
az dt role-assignment create --dt-name <your-Azure-Digital-Twins-instance> --assignee "<principal-ID>" --role "Azure Digital Twins Data Owner"
```

Uygulama ayarlarını yapılandırma

Ardından, Azure Digital Twins örneğinizin URL'sini işleviniz için bir ortam değişkeni ayarlayarak erişilebilir hale getirin.

Bahşiş

Azure Digital Twins örneğinin URL'si, örneğinizin ana bilgisayar adının başına https:// eklenerek oluşturulur. Ana bilgisayar adını ve örneğinizin tüm özelliklerini görmek için komutunu çalıştırın az dt show --dt-name <your-Azure-Digital-Twins-instance>.

Aşağıdaki komut, örneğinize erişmesi gereken her durumda işlevinizin kullanacağı örneğinizin URL'si için bir ortam değişkeni ayarlar.

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

Kiracılar arasında kimlik doğrulaması

Azure Digital Twins yalnızca bir Microsoft Entra kiracısını destekleyen bir hizmettir: Azure Digital Twins örneğinin bulunduğu abonelikten ana kiracı.

Sonuç olarak, Azure Digital Twins API'lerine yönelik istekler, Azure Digital Twins örneğinin bulunduğu kiracının bir parçası olan bir kullanıcı veya hizmet sorumlusu gerektirir. Azure Digital Twins uç noktalarının kötü amaçlı taranmasını önlemek için, kaynak kiracı dışından erişim belirteçlerine sahip isteklere "404 Alt Etki Alanı bulunamadı" hata iletisi döndürülür. Kullanıcı veya hizmet sorumlusuna Microsoft Entra B2B işbirliği aracılığıyla Azure Digital Twins Veri Sahibi veya Azure Digital Twins Veri Okuyucusu rolü verilmiş olsa bile bu hata döndürülür.

Azure Digital Twins örneğine örnekten farklı bir kiracıya ait bir hizmet sorumlusu veya kullanıcı hesabı kullanarak erişmeniz gerekiyorsa, başka bir kiracıdaki federasyon kimliklerinin her birinin Azure Digital Twins örneğinin "ev" kiracısından bir belirteç istemesini sağlayabilirsiniz.

Bunu gerçekleştirmenin bir yolu aşağıdaki CLI komutudur; burada <home-tenant-ID> Azure Digital Twins örneğini içeren Microsoft Entra kiracısının kimliğidir:

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

Bunu istedikten sonra kimlik, Azure Digital Twins örneğiyle https://digitaltwins.azure.net eşleşen bir kiracı kimliği talebi olan Microsoft Entra kaynağı için verilen bir belirteç alır. Api isteklerinde veya kodunuzla bu belirteci kullanmak Azure.Identity , federasyon kimliğinin Azure Digital Twins kaynağına erişmesine izin vermelidir.

Ayrıca, kodunuzdaki kimlik bilgisi seçeneklerinde ev kiracısını belirtebilirsiniz.

Aşağıdaki örnekte, seçeneklerde için InteractiveBrowserTenantId örnek kiracı kimliği değerinin nasıl ayarlanacağı gösterilmektedir 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);
}

Visual Studio ve Visual Studio Code ile kimlik doğrulaması için kiracı ayarlamaya yönelik benzer seçenekler vardır. Sağlanan seçenekler hakkında daha fazla bilgi için DefaultAzureCredentialOptions belgelerine bakın.

Diğer kimlik bilgisi yöntemleri

Yukarıdaki vurgulanan kimlik doğrulama senaryoları uygulamanızın gereksinimlerini karşılamıyorsa, Microsoft kimlik platformu sunulan diğer kimlik doğrulama türlerini keşfedebilirsiniz. Bu platformun belgeleri, uygulama türüne göre düzenlenmiş daha fazla kimlik doğrulama senaryosunu kapsar.

Sonraki adımlar

Azure Digital Twins'de güvenliğin nasıl çalıştığı hakkında daha fazla bilgi edinin:

Azure Digital Twins çözümleri için güvenlik

Veya artık kimlik doğrulaması ayarlandıktan sonra örneğinizde model oluşturmaya ve yönetmeye geçin:

DTDL modellerini yönetme

İstemci uygulaması kimlik doğrulama kodu yazma

Ön koşullar

Azure.Identity kitaplığını kullanarak kimlik doğrulaması

.NET projenize Azure.Identity ekleme

DefaultAzureCredential yöntemi

Yerel Azure kimlik bilgilerini ayarlama

ManagedIdentityCredential yöntemi

InteractiveBrowserCredential yöntemi

kimlik doğrulaması Azure İşlevleri

Uygulama kodu yazma

Yayımlanan uygulamayı yapılandırma

Erişim rolü atama

Uygulama ayarlarını yapılandırma

Kiracılar arasında kimlik doğrulaması

Diğer kimlik bilgisi yöntemleri

Sonraki adımlar

Ek kaynaklar