Azure Digital Twins API'leri ve SDK'ları

Bu makalede, kullanılabilir Azure Digital Twins API'lerine ve bunlarla etkileşim kurma yöntemlerine genel bir bakış sunulmaktadır. REST API'lerini doğrudan ilişkili Swagger belgeleriyle veya bir SDK kullanarak kullanabilirsiniz.

Azure Digital Twins, örneğinizi ve öğelerini yönetmek için denetim düzlemi API'leri, veri düzlemi API'leri ve SDK'larla donatılmış olarak gelir.

  • Denetim düzlemi API'leri Azure Resource Manager (ARM) API'leridir ve örneğinizi oluşturma ve silme gibi kaynak yönetimi işlemlerini kapsar.
  • Veri düzlemi API'leri Azure Digital Twins API'leridir ve modelleri, ikizleri ve grafı yönetme gibi veri yönetimi işlemleri için kullanılır.
  • SDK'lar, Azure Digital Twins kullanan özel uygulamaların geliştirilmesini kolaylaştırmak için mevcut API'lerden yararlanır.

Kontrol düzlemi genel bakış

Denetim düzlemi API'leri , Azure Digital Twins örneğinizi bir bütün olarak yönetmek için kullanılan ARM API'leridir, bu nedenle örneğinizin tamamını oluşturma veya silme gibi işlemleri kapsar. Uç noktaları oluşturmak ve silmek için de bu API'leri kullanacaksınız.

API'leri doğrudan çağırmak için, denetim düzlemi Swagger deposundaki en son Swagger klasörüne başvurun. Bu klasör, kullanımı gösteren örneklerden oluşan bir klasör de içerir.

Azure Digital Twins denetim düzlemi API'leri için şu anda kullanılabilen SDK'lar aşağıdadır.

SDK dili Paket bağlantısı Başvuru belgeleri Kaynak kodu
.NET (C#) NuGet üzerinde Azure.ResourceManager.DigitalTwins .NET için Azure DigitalTwins SDK başvurusu GitHub'da .NET için Microsoft Azure Digital Twins yönetim istemci kitaplığı
Java Azure-resourcemanager-digitaltwins Maven üzerinde Kaynak Yönetimi için Referans - Digital Twins GitHub'da Java için Azure Resource Manager AzureDigitalTwins istemci kitaplığı
JavaScript npm üzerinde JavaScript için AzureDigitalTwinsManagement istemci kitaplığı GitHub'da JavaScript için AzureDigitalTwinsManagement istemci kitaplığı
Piton PyPI üzerinde azure-mgmt-digitaltwins GitHub'da Python için Microsoft Azure SDK
Başlayın azure-sdk-for-go/services/digitaltwins/mgmt GitHub'da Go için Azure SDK

Ayrıca Azure portalı ve CLI aracılığıyla Azure Digital Twins ile etkileşim kurarak denetim düzlemi API'lerini de kullanabilirsiniz.

Veri düzlemi genel bakış

Veri düzlemi API'leri, Azure Digital Twins örneğinizdeki öğeleri yönetmek için kullanılan Azure Digital Twins API'leridir. Bunlar yol oluşturma, modelleri karşıya yükleme, ilişki oluşturma ve ikizleri yönetme gibi işlemleri içerir ve geniş bir şekilde aşağıdaki kategorilere ayrılabilir:

API'leri doğrudan çağırmak için veri düzlemi Swagger deposundaki en son Swagger klasörüne başvurun. Bu klasör, kullanımı gösteren örneklerden oluşan bir klasör de içerir. Veri düzlemi API başvuru belgelerini de görüntüleyebilirsiniz.

Azure Digital Twins veri düzlemi API'leri için şu anda kullanılabilen SDK'lar aşağıdadır.

SDK dili Paket bağlantısı Başvuru belgeleri Kaynak kodu
.NET (C#) NuGet üzerinde Azure.DigitalTwins.Core Azure IoT Digital Twins için .NET istemci kitaplığı referansı GitHub'da .NET için Azure IoT Digital Twins istemci kitaplığı
Java com.azure:azure-digitaltwins-core Maven üzerinde Java için Azure Digital Twins SDK'sı başvurusu GitHub'da Java için Azure IoT Digital Twins istemci kitaplığı
JavaScript npm üzerinde JavaScript için Azure Digital Twins Core istemci kitaplığı Reference for @azure/digital-twins-core GitHub'da JavaScript için Azure Digital Twins Core istemci kitaplığı
Piton PyPI üzerinde Python için Azure Digital Twins Core istemci kitaplığı azure-digitaltwins-core için referans GitHub'da Python için Azure Digital Twins Core istemci kitaplığı

Cli aracılığıyla Azure Digital Twins ile etkileşim kurarak veri düzlemi API'lerini de kullanabilirsiniz.

Import İşleri API'si ile Toplu İthalat

Import İşleri API'si, tek bir API çağrısında bir dizi modeli, ikizi ve/veya ilişkiyi içeri aktarmanızı sağlayan bir veri düzlemi API'sidir. İçeri Aktarma İşleri API'leri işlemleri, CLI komutlarına ve veri düzlemi SDK'larına da dahildir. İşleri İçeri Aktar API'sini kullanmak için Azure Blob Depolama kullanılması gerekir.

İzinleri denetleme

İşleri İçeri Aktar API'sini kullanmak için bu bölümde açıklanan izin ayarlarını etkinleştirmeniz gerekir.

İlk olarak, Azure Digital Twins örneğiniz için sistem tarafından atanan bir yönetilen kimliğe ihtiyacınız vardır. Örnek için sistem tarafından yönetilen kimlik ayarlama yönergeleri için bkz . Örnek için yönetilen kimliği etkinleştirme/devre dışı bırakma.

Aşağıdaki veri eylemi kategorileri için Azure Digital Twins örneğinizde yazma izinlerine sahip olmanız gerekir:

  • Microsoft.DigitalTwins/jobs/*
  • İşler çağrısına eklemek istediğiniz tüm grafik öğeleri. Bu, Microsoft.DigitalTwins/models/*, Microsoft.DigitalTwins/digitaltwins/* ve/veya Microsoft.DigitalTwins/digitaltwins/relationships/* içerebilir.

Bu izinlerin tümünü sağlayan yerleşik rol, Azure Digital Twins Veri Sahibi'dir. Yalnızca ihtiyacınız olan veri türlerine ayrıntılı erişim vermek için özel bir rol de kullanabilirsiniz. Azure Digital Twins'deki roller hakkında daha fazla bilgi için bkz . Azure Digital Twins çözümleri için güvenlik.

Not

Import Jobs API'sini çağırmayı denerseniz ve içeri aktarmaya çalıştığınız grafik öğesi türlerinden birine yazma izniniz yoksa, görev bu türü atlar ve diğerlerini içeri aktarır. Örneğin, modeller ve ikizlere yazma erişiminiz varsa ancak ilişkiler yoksa, üç öğe türünün tümünü toplu içeri aktarma girişimi yalnızca modelleri ve ikizleri içeri aktarmada başarılı olur. İş durumu bir hatayı yansıtır ve ileti hangi izinlerin eksik olduğunu gösterir.

Ayrıca, Azure Blob Depolama kapsayıcısında giriş ve çıkış dosyalarına erişebilmesi için Azure Digital Twins örneğinizin sistem tarafından atanan yönetilen kimliğine aşağıdaki RBAC izinlerini vermeniz gerekir:

Son olarak, İşler API'sine yönelik isteklerinizde kullanılabilecek bir taşıyıcı belirteci oluşturun. Yönergeler için Taşıyıcı jeton ekle bölümüne bakın.

Verileri biçimlendirme

API, bir NDJSON dosyasından gelen ve Azure blob depolama kapsayıcısına yüklenmesi gereken grafik bilgileri girişini kabul eder. Dosya bir Header bölümle başlar, ardından isteğe bağlı Models, Twins ve Relationships bölümleri gelir. Dosyaya üç grafik verisi türünü de eklemeniz gerekmez, ancak mevcut bölümlerin bu sıraya uyması gerekir. Bu API ile oluşturulan ikizler ve ilişkiler isteğe bağlı olarak özelliklerinin başlatılmasını içerebilir.

İçeri aktarma API'sine yönelik örnek bir giriş veri dosyası aşağıda verilmişti:

{"Section": "Header"}
{"fileVersion": "1.0.0", "author": "foobar", "organization": "contoso"}
{"Section": "Models"}
{"@id":"dtmi:com:microsoft:azure:iot:model0;1","@type":"Interface","contents":[{"@type":"Property","name":"property00","schema":"integer"},{"@type":"Property","name":"property01","schema":{"@type":"Map","mapKey":{"name":"subPropertyName","schema":"string"},"mapValue":{"name":"subPropertyValue","schema":"string"}}},{"@type":"Relationship","name":"has","target":"dtmi:com:microsoft:azure:iot:model1;1","properties":[{"@type":"Property","name":"relationshipproperty1","schema":"string"},{"@type":"Property","name":"relationshipproperty2","schema":"integer"}]}],"description":{"en":"This is the description of model"},"displayName":{"en":"This is the display name"},"@context":"dtmi:dtdl:context;2"}
{"@id":"dtmi:com:microsoft:azure:iot:model1;1","@type":"Interface","contents":[{"@type":"Property","name":"property10","schema":"string"},{"@type":"Property","name":"property11","schema":{"@type":"Map","mapKey":{"name":"subPropertyName","schema":"string"},"mapValue":{"name":"subPropertyValue","schema":"string"}}}],"description":{"en":"This is the description of model"},"displayName":{"en":"This is the display name"},"@context":"dtmi:dtdl:context;2"}
{"Section": "Twins"}
{"$dtId":"twin0","$metadata":{"$model":"dtmi:com:microsoft:azure:iot:model0;1"},"property00":10,"property01":{"subProperty1":"subProperty1Value","subProperty2":"subProperty2Value"}}
{"$dtId":"twin1","$metadata":{"$model":"dtmi:com:microsoft:azure:iot:model1;1"},"property10":"propertyValue1","property11":{"subProperty1":"subProperty1Value","subProperty2":"subProperty2Value"}}
{"Section": "Relationships"}
{"$dtId":"twin0","$relationshipId":"relationship","$targetId":"twin1","$relationshipName":"has","relationshipProperty1":"propertyValue1","relationshipProperty2":10}

İpucu

Modelleri, ikizleri ve ilişkileri içeri aktarma API'sinin desteklediği NDJSON'a dönüştüren bir örnek proje için bkz. Azure Digital Twins Toplu İçeri Aktarma NDJSON Oluşturucu. Örnek proje .NET için yazılmıştır ve kendi içeri aktarma dosyalarınızı oluşturmanıza yardımcı olmak için indirilebilir veya uyarlanabilir.

Dosya oluşturulduktan sonra, tercih ettiğiniz karşıya yükleme yöntemini kullanarak Azure Blob Depolama bir blok bloba yükleyin (bazı seçenekler AzCopy komutu, Azure CLI veya Azure portalıdır). İşleri İçeri Aktar API çağrısının gövdesinde NDJSON dosyasının blob depolama URL'sini kullanırsınız.

İçe aktarma işini çalıştır

Artık İşleri İçeri Aktar API'sini çağırmaya devam edebilirsiniz. Bir API çağrısında tam grafiği içeri aktarma hakkında ayrıntılı yönergeler için İçeri Aktarma İşleri API'siyle modelleri, ikizleri ve ilişkileri toplu olarak yükleme bölümüne bakın. Her kaynak türünü bağımsız olarak içeri aktarmak için İşleri İçeri Aktar API'sini de kullanabilirsiniz. Belirli kaynak türleriyle İşleri İçeri Aktarma API'sini kullanma hakkında daha fazla bilgi için modeller, ikizler ve ilişkiler için İşleri Aktarma API'si talimatlarına bakın.

API çağrısının gövdesinde NDJSON giriş dosyasının blob depolama URL'sini sağlarsınız. Yeni bir blob depolama URL'si vererek, hizmet oluşturduğunda sonuç günlüğünün nerede saklanmasını istediğinizi belirtirsiniz.

Önemli

Azure Digital Twins örneğinizin sistem tarafından atanan yönetilen kimliğinin İzinleri denetle bölümünde açıklanan depolama blobu RBAC izinlerine sahip olduğundan emin olun.

İçeri aktarma işi yürütülürken, hizmet tarafından yapılandırılmış bir çıkış günlüğü oluşturulur ve istekteki çıkış blobu için belirttiğiniz URL konumunda blob kapsayıcınızda yeni bir ekleme blobu olarak depolanır. Modelleri, ikizleri ve ilişkileri içeri aktaran başarılı bir iş için örnek çıkış günlüğü aşağıda verilmiştir:

{"timestamp":"2022-12-30T19:50:34.5540455Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"status":"Started"}}
{"timestamp":"2022-12-30T19:50:37.2406748Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Models","status":"Started"}}
{"timestamp":"2022-12-30T19:50:38.1445612Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Models","status":"Succeeded"}}
{"timestamp":"2022-12-30T19:50:38.5475921Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Twins","status":"Started"}}
{"timestamp":"2022-12-30T19:50:39.2744802Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Twins","status":"Succeeded"}}
{"timestamp":"2022-12-30T19:50:39.7494663Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Relationships","status":"Started"}}
{"timestamp":"2022-12-30T19:50:40.4480645Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"section":"Relationships","status":"Succeeded"}}
{"timestamp":"2022-12-30T19:50:41.3043264Z","jobId":"test1","jobType":"Import","logType":"Info","details":{"status":"Succeeded"}}

İş tamamlandığında BulkOperationEntityCount ölçümünü kullanarak alınan varlıkların toplam sayısını görebilirsiniz.

İçeri Aktarma İşleri API'sindeki İptal Etme operasyonuyla devam eden bir içeri aktarma işini iptal etmek de mümkündür. İş iptal edildikten ve artık çalışmadıktan sonra silebilirsiniz.

Sınırlar ve dikkat edilmesi gerekenler

İşleri İçeri Aktarma API'siyle çalışırken aşağıdaki noktaları göz önünde bulundurun:

  • İçeri Aktarma İşleri atomik işlemler değildir. Başarısızlık, kısmi iş tamamlama veya İptal işleminin kullanılması durumunda geri alma işlemi gerçekleştirilemez.
  • Azure Digital Twins örneğinde aynı anda yalnızca bir toplu iş desteklenir. Bu bilgileri ve Azure Digital Twins sınırlarındaki İş API'lerinin diğer sayısal sınırlarını görüntüleyebilirsiniz.

İşleri Sil API'siyle toplu silme

İşleri Sil API'si, tek bir API çağrısıyla bir örnekteki tüm modelleri, ikizleri ve ilişkileri silmenizi sağlayan bir veri düzlemi API'dir. İşleri Sil API'si işlemleri CLI komutları olarak da kullanılabilir. Silme işi oluşturma ve durumunu denetlemeye yönelik istek ayrıntılarını görmek için API belgelerini ziyaret edin.

Tüm öğelerin silindiğinden emin olmak için, İşleri Sil API'sini kullanırken şu önerileri izleyin:

  • API isteklerinin kimliğini doğrulamak için taşıyıcı belirteci oluşturma yönergeleri için bkz . Taşıyıcı belirteci ekleme.
  • Kısa süre önce grafınıza çok sayıda varlık aktardıysanız, silme işine başlamadan önce bir süre bekleyin ve tüm öğelerin grafiğinizde eşitlendiğini doğrulayın.
  • Silme işi tamamlanana kadar örnekteki tüm işlemleri, özellikle karşıya yükleme işlemlerini durdurun.

Silinen grafiğin boyutuna bağlı olarak, silme işi birkaç dakika ile birden çok saat arasında sürebilir.

Silme işi için varsayılan zaman aşımı süresi 12 saattir ve bu süre API'de sorgu parametresi kullanılarak 15 dakika ile 24 saat arasında herhangi bir değere ayarlanabilir. Silme işinin zaman aşımına uğramadan önce çalıştığı süre budur; bu aşamada, hizmet henüz tamamlanmadıysa işi durdurmaya çalışır.

Sınırlar ve diğer önemli noktalar

İşleri Sil API'siyle çalışırken aşağıdaki noktaları göz önünde bulundurun:

  • Silme İşlemleri atomik işlemler değildir. Başarısızlık, kısmi iş tamamlama veya süre aşımı durumlarında geri alınma yoktur.
  • Azure Digital Twins örneğinde aynı anda yalnızca bir toplu iş desteklenir. Bu bilgileri ve Azure Digital Twins sınırlarındaki İş API'lerinin diğer sayısal sınırlarını görüntüleyebilirsiniz.

Kullanım ve kimlik doğrulama notları

Bu bölüm, API'leri ve SDK'ları kullanma hakkında daha ayrıntılı bilgiler içerir.

API notları

Azure Digital Twins API'lerini doğrudan çağırmaya yönelik bazı genel bilgiler aşağıdadır.

API istekleri için kimlik doğrulaması hakkında daha fazla bilgi aşağıda verilmiştir.

  • Azure Digital Twins API istekleri için taşıyıcı belirteç oluşturmanın bir yolu az account get-access-token CLI komutudur. Ayrıntılı yönergeler için bkz . Taşıyıcı belirteci ekleme.
  • Azure Digital Twins API'lerine yönelik istekler, Azure Digital Twins örneğinin bulunduğu aynı Microsoft Entra ID kiracısı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. Birden çok kiracı arasında erişim elde etme hakkında bilgi için bkz . Uygulama kimlik doğrulama kodu yazma.

SDK notları

Azure Digital Twins kapsamında kullanılan temel SDK, Azure.Core'dir. SDK altyapısı ve türleri hakkında başvuru için Azure ad alanı belgelerine bakın.

SDK'larla kimlik doğrulaması hakkında daha fazla bilgi aşağıdadır.

  • Sınıf örneğini DigitalTwinsClient oluşturarak başlayın. Oluşturucu, paketteki Azure.Identity farklı kimlik doğrulama yöntemleriyle elde edilebilen kimlik bilgileri gerektirir. Azure.Identity hakkında daha fazla bilgi için ad alanı belgelerine bakın.
  • Kullanmaya başlarken InteractiveBrowserCredential yararlı bulabilirsiniz, ancak yönetilen kimlik için kimlik bilgileri de dahil olmak üzere, MSI kullanılarak yapılandırılmış Azure işlevlerinin Azure Digital Twins'e karşı doğrulanması için yararlı olabilecek birkaç seçenek daha vardır. hakkında daha fazla bilgi InteractiveBrowserCredentialiçin sınıf belgelerine bakın.

İşlevler ve döndürülen veriler hakkında daha fazla bilgi aşağıdadır.

  • Tüm hizmet API'leri çağrıları sınıfta üye işlevleri DigitalTwinsClient olarak kullanıma sunulur.
  • Tüm hizmet işlevleri zaman uyumlu ve zaman uyumsuz sürümlerde bulunur.
  • Tüm hizmet işlevleri, 400 veya üzeri herhangi bir dönüş durumu için bir istisna fırlatır. Çağrıları bir try bölüme sarmaladığınızdan emin olun ve en azından RequestFailedExceptionsöğesini yakalayın. Bu özel durum türü hakkında daha fazla bilgi için başvuru belgelerine bakın.
  • Çoğu hizmet yöntemi Response<T> veya zaman uyumsuz çağrılar için Task<Response<T>> döndürür; burada T, hizmet çağrısının dönüş nesnesinin sınıfıdır. Yanıt sınıfı, hizmet dönüşünü kapsüller ve alanında Value dönüş değerleri sunar.
  • Sayfalanmış sonuçları olan hizmet yöntemleri sonuç olarak Pageable<T> veya AsyncPageable<T> döndürür. Pageable<T> sınıfı hakkında daha fazla bilgi için başvuru belgelerine bakın; AsyncPageable<T> hakkında daha fazla bilgi için başvuru belgelerine bakın.
  • Sayfalanmış sonuçları bir döngü kullanarak await foreach yineleyebilirsiniz. Bu işlem hakkında daha fazla bilgi için bkz. C# 8'de Asenkron Numaralandırılabilirlerle Yineleme.
  • Servis yöntemleri, mümkün olan her yerde güçlü bir şekilde yazılmış nesneler döndürür. Ancak Azure Digital Twins, kullanıcı tarafından çalışma zamanında özel olarak yapılandırılan modelleri temel aldığı için (hizmete yüklenen DTDL modelleri aracılığıyla), birçok hizmet API'si JSON biçiminde ikiz verileri alır ve döndürür.

.NET (C#) SDK'sında serileştirme yardımcıları

Serileştirme yardımcıları, temel bilgilere erişmek üzere ikiz verilerini hızlı bir şekilde oluşturmak veya seri durumdan çıkarma amacıyla .NET (C#) SDK'sı içinde kullanılabilen yardımcı işlevlerdir. Temel SDK yöntemleri ikiz verilerini varsayılan olarak JSON olarak döndüreceğinden, ikiz verilerini daha fazla bölmek için bu yardımcı sınıfları kullanmak yararlı olabilir.

Kullanılabilir yardımcı sınıflar şunlardır:

  • BasicDigitalTwin: Bir dijital ikizin temel verilerini genel olarak temsil eder
  • BasicDigitalTwinComponent: Bir Contents bileşeninin BasicDigitalTwin özelliklerinde genel olarak temsil eder
  • BasicRelationship: Bir ilişkinin temel verilerini genel olarak temsil eder
  • DigitalTwinsJsonPropertyName: Özel dijital ikiz türleri için JSON serileştirme ve seri durumdan çıkarmada kullanılacak dize sabitlerini içerir

API ölçümlerini izleme

İstekler, gecikme süresi ve hata oranı gibi API ölçümleri Azure portalında görüntülenebilir.

Azure Digital Twins ölçümlerini görüntüleme ve yönetme hakkında bilgi için kendi örneğinizi izleme konusuna bakın. Azure Digital Twins için kullanılabilen API ölçümlerinin tam listesi için bkz . Azure Digital Twins API istek ölçümleri.

Sonraki adımlar

Azure Digital Twins API'lerine doğrudan istekte bulunmayı öğrenin:

Veya bu öğreticiyle bir istemci uygulaması oluşturarak .NET SDK'sını kullanma alıştırması yapın:

  • Last updated on