İ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
Önkoş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; sarmalarManagedIdentityCredential
ve bir yapılandırma değişkeni ile erişebilirInteractiveBrowserCredential
. - 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.Identity
kimlik doğrulaması yapmak üzere ayarlamak için aşağıdaki adımları tamamlayın:
SDK paketini ve
Azure.Identity
paketiAzure.DigitalTwins.Core
projenize ekleyin. Seçtiğiniz araçlara bağlı olarak, Visual Studio paket yöneticisini veyadotnet
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.Identity
yö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);
}
}
}
Not
Ş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 InteractiveBrowserCredential
ile 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);
}
}
}
Not
İ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.
Not
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öneticisi 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
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.
İpucu
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:
Veya artık kimlik doğrulaması ayarlandıktan sonra örneğinizde model oluşturmaya ve yönetmeye geçin: