İstemci uygulaması kimlik doğrulama kodu yazma

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

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

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:

1. 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.

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

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

• uygulama kaydının Uygulama (istemci) kimliği
• uygulama kaydının Dizin (kiracı) kimliği
• Azure Digital Twins örneğinin URL'si

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

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.

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.

1. İş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>	
   

2. İşleve principalId Azure 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.

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