Azure Digital Twins API'leri ve SDK'ları

  • Makale

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'larıyla (Postman gibi bir araç aracılığıyla) veya bir SDK aracılığıyla 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 API'leri

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 Maven üzerinde azure-resourcemanager-digitaltwins Kaynak Yönetimi başvurusu - 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ığı
Python PyPI üzerinde azure-mgmt-digitaltwins GitHub'da Python için Microsoft Azure SDK
Go 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 API'leri

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 .NET için Azure IoT Digital Twins istemci kitaplığı başvurusu GitHub'da .NET için Azure IoT Digital Twins istemci kitaplığı
Java maven üzerinde com.azure:azure-digitaltwins-core 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ığı
Python PyPI üzerinde Python için Azure Digital Twins Core istemci kitaplığı azure-digitaltwins-core başvurusu 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.

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.

  • Postman gibi bir HTTP REST test aracını kullanarak Azure Digital Twins API'lerine doğrudan çağrı yapabilirsiniz. Bu işlem hakkında daha fazla bilgi için bkz . Postman ile Azure Digital Twins API'lerini çağırma.
  • Azure Digital Twins şu anda Çıkış Noktaları Arası Kaynak Paylaşımı'nı (CORS) desteklememektedir. Etki ve çözüm stratejileri hakkında daha fazla bilgi için bkz . Azure Digital Twins için Çıkış Noktaları Arası Kaynak Paylaşımı (CORS).

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 alma.
  • 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 için temel alınan SDK' dır Azure.Core. 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ın örneğini DigitalTwinsClient ekleyerek başlayın. Oluşturucu, paketteki Azure.Identity farklı kimlik doğrulama yöntemleriyle elde edilebilen kimlik bilgileri gerektirir. hakkında daha fazla bilgi Azure.Identityiçin ad alanı belgelerine bakın.
  • Kullanmaya başlarken yararlı bulabilirsinizInteractiveBrowserCredential, ancak yönetilen kimliğin kimlik bilgileri de dahil olmak üzere, Azure Digital Twins'de MSI ile ayarlanmış Azure işlevlerinin kimliğini doğrulamak için büyük olasılıkla kullanacağınız 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 özel durum oluşturur. Ç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 veya Response<T> (Task<Response<T>> zaman uyumsuz çağrılar için) döndürür; burada T hizmet çağrısının dönüş nesnesi 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 veya AsyncPageable<T> döndürürPageable<T>. Sınıfı hakkında daha fazla bilgi Pageable<T> için başvuru belgelerine bakın; hakkında daha fazla bilgi AsyncPageable<T>için başvuru belgelerine bakın.
  • Döngü kullanarak await foreach sayfalanmış sonuçları yineleyebilirsiniz. Bu işlem hakkında daha fazla bilgi için bkz . C# 8'de Zaman Uyumsuz Numaralandırılabilir Öğelerle Yineleme.
  • Hizmet yöntemleri, mümkün olan her yerde kesin olarak yazılan 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 bileşenin özelliklerinde Contents genel olarak temsil eder BasicDigitalTwin
  • 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

İşleri İçeri Aktarma API'siyle toplu içeri aktarma

İşleri İçeri Aktarma 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'dir. İç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 olacaktı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/digitaltwins/*ve/veya Microsoft.DigitalTwins/digitaltwins/relationships/*içerebilirMicrosoft.DigitalTwins/models/*.

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.

Dekont

İşleri İçeri Aktarma API çağrısı yapmaya çalışırsanız ve içeri aktarmaya çalıştığınız grafik öğesi türlerinden birinde yazma izinleri eksikse, iş bu türü atlar ve diğerlerini içeri aktarır. Örneğin, modellere 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 bkz . Taşıyıcı belirtecini alma.

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 ve ardından isteğe bağlı , Twinsve Relationshipsbölümleriyle Modelsbaşlar. 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}

Bahşiş

Modelleri, ikizleri ve ilişkileri içeri aktarma API'sinin desteklediği NDJSON'a dönüştüren örnek bir 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 kullanacaksınız.

İçeri aktarma işini çalıştırma

Artık İşleri İçeri Aktar API'sini çağırmaya devam edebilirsiniz. Bir API çağrısında tam grafı içeri aktarma hakkında ayrıntılı yönergeler için bkz . İçeri Aktarma İşleri API'siyle modelleri, ikizleri ve ilişkileri toplu olarak karşıya yükleme. Her kaynak türünü bağımsız olarak içeri aktarmak için İşleri İçeri Aktar API'sini de kullanabilirsiniz. İşleri İçeri Aktar API'sini tek tek kaynak türleriyle kullanma hakkında daha fazla bilgi için bkz. Modeller, ikizler ve ilişkiler için İşleri İçeri Aktarma API'sinin yönergeleri.

API çağrısının gövdesinde NDJSON giriş dosyasının blob depolama URL'sini sağlayacaksınız. Ayrıca, hizmet oluşturduğunda çıkış günlüğünün nerede depolanmasını istediğinizi belirtmek için yeni bir blob depolama URL'si de sağlayacaksınız.

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

İşleri İçeri Aktarma API'sinden İptal etme işlemiyle çalışan 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. Hata, kısmi iş tamamlama veya İptal işleminin kullanımı durumunda geri alma 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.

İş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 alma.
  • 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şinin varsayılan zaman aşımı süresi 12 saattir ve bu süre API'de bir sorgu parametresi kullanılarak 15 dakika ile 24 saat arasında herhangi bir değere ayarlanabilir. Bu, silme işinin zaman aşımına uğramadan önce çalıştırılacağı süredir ve bu noktada hizmet henüz tamamlanmamışsa 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 İşleri atomik işlemler değildir. Hata, kısmi iş tamamlama veya işin zaman aşımı durumunda geri alma 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.

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 bkz . Örneğinizi izleme. 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

Postman kullanarak 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: