Azure Digital Twins API'ler ve API'ler

  • Makale
  • Okumak için 6 dakika

Bu makalede, kullanılabilir Azure Digital Twins api'lere ve onlarla etkileşim kurma yöntemlerine genel bir bakış sunulmaktadır. REST API'leri doğrudan ilişkili Swaggers ile (Postmangibi bir araç aracılığıyla) veya bir SDK aracılığıyla kullanabilirsiniz.

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

  • Kontrol düzlemi API'leri Azure Resource Manager (ARM) API'leridir ve örneğinizi oluşturma ve silme gibi kaynak yönetimi işlemlerini kapsayacaktır.
  • Veri düzlemi API'leri Azure Digital Twins api'lerdendir ve modelleri, ikizleri ve grafı yönetme gibi veri yönetimi işlemleri için kullanılır.
  • SDK'ler, mevcut API'lerden faydalanarak özel uygulamaların geliştirme kolaylığına olanak Azure Digital Twins. Kontrol düzlemi SDK'leri .NET (C#) ve Java'da, veri düzlemi SDK'leri ise .NET (C#), Java, JavaScriptve Python'da kullanılabilir.

Genel bakış: kontrol düzlemi API'leri

Kontrol 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 ele alırlar. Ayrıca bu API'leri kullanarak uç noktaları oluştur ve silebilirsiniz.

En güncel denetim düzlemi API'si sürümü 2020-12-01'tir.

Kontrol düzlemi API'lerini kullanmak için:

Ayrıca, Azure portal VE CLI aracılığıyla Azure Digital Twins etkileşim kurarak denetim düzlemi API'Azure portal alıştırması da yapın.

Genel bakış: veri düzlemi API'leri

Veri düzlemi API'leri, Azure Digital Twins örneğinizin içindeki öğeleri yönetmek için kullanılan Azure Digital Twins API'leridir. Bunlar rota 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:

  • DigitalTwinModels - DigitalTwinModels kategorisi, bir Azure Digital Twins örneği içinde modelleri yönetmeye yönelik API'Azure Digital Twins içerir. Yönetim etkinlikleri DTDL'de yazan modelleri karşıya yükleme, doğrulama, alma ve silme işlemlerini içerir.
  • DigitalTwins : DigitalTwins kategorisi, geliştiricilerin bir dijital ikiz örneğindeki dijital ikizleri ve ilişkilerini oluşturmasına, değiştirmesine ve silmesine izin Azure Digital Twins içerir.
  • Sorgu - Sorgu kategorisi geliştiricilerin ilişkiler arasındaki ikiz grafı içinde dijital ikiz kümelerini bulmalarını sağlar.
  • Olay Rotaları - Olay Rotaları kategorisi, verileri sistem üzerinden veaşağı akış hizmetleriyle yönlendirmeye yönelik API'ler içerir.

En güncel veri düzlemi API'si sürümü 2020-10-31'tir.

Veri düzlemi API'lerini kullanmak için:

Tarih düzlemi API'leri ile CLI aracılığıyla etkileşim Azure Digital Twins da alıştırması yapın.

.NET (C#) SDK 'sı (veri düzlemi)

.NET Azure Digital Twins (C#) SDK'sı, .NET için Azure SDK'sı'nın bir parçası. Açık kaynaktır ve veri düzlemi API'Azure Digital Twins tabanlıdır.

Not

SDK tasarımı hakkında daha fazla bilgi için bkz. Azure SDK'ları için genel tasarım ilkeleri ve belirli .NET tasarım yönergeleri.

SDK'yı kullanmak için Azure.DigitalTwins.Core NuGet paketini projenize dahil edin. Ayrıca Azure.Identity paketinin en son sürümüne de ihtiyacınız vardır. Bu Visual Studio, bu paketleri NuGet Paket Yöneticisi (Araçlar > NuGet Paket Yöneticisi > Çözüm için NuGet Paketlerini Yönet aracılığıyla erişilir) kullanarak abilirsiniz. Bu paketleri projenize eklemek için aşağıdaki paket bağlantılarında NuGet .NET komut satırı aracını da kullanabilirsiniz:

Pratikte API'leri kullanma hakkında ayrıntılı bir yol için bkz. İstemci uygulaması kodu.

Serileştirme yardımcıları

Serileştirme yardımcıları, temel bilgilere erişmek için ikiz verilerini hızlı bir şekilde oluşturmak veya seriden almak için SDK içinde kullanılabilen yardımcı işlevlerdir. Temel SDK yöntemleri varsayılan olarak ikiz verilerini JSON olarak iade eder. Bu yardımcı sınıfları kullanarak ikiz verilerini daha ayrıntılı bir şekilde kesmeniz yararlı olabilir.

Kullanılabilir yardımcı sınıflar:

  • BasicDigitalTwin: Bir dijital ikizin temel verilerini genel olarak temsil eder
  • BasicDigitalTwinComponent: Genel olarak bir bileşenin Contents özelliklerinde temsil eder BasicDigitalTwin
  • BasicRelationship: Genel olarak bir ilişkinin temel verilerini temsil eder
  • DigitalTwinsJsonPropertyName: Özel dijital ikiz türleri için JSON serileştirme ve seriyi seriden kaldırmada kullanmak üzere dize sabitlerini içerir

Genel API/SDK kullanım notları

Not

Lütfen şu Azure Digital Twins Çıkış Noktası Arası Kaynak Paylaşımını (CORS) desteklememektedir. Etki ve çözüm stratejileri hakkında daha fazla bilgi için Kavramlar: Kaynak çözümleri için güvenlik konularının Çıkış Noktası Arası Kaynak Paylaşımı (CORS) Azure Digital Twins bakın.

Aşağıdaki listede, API'leri ve API'leri kullanmaya ilgili daha ayrıntılı ve genel yönergeler yer almaktadır.

  • Postman gibi bir HTTP REST test aracını kullanarak api'lere doğrudan çağrı Azure Digital Twins kullanabilirsiniz. Bu işlem hakkında daha fazla bilgi için bkz. Postman ile API istekleri yapma.
  • SDK'yı kullanmak için sınıfının örneğini DigitalTwinsClient başlayın. Oluşturucu, pakette farklı kimlik doğrulama yöntemleriyle elde edilen kimlik bilgilerini Azure.Identity gerektirir. hakkında daha fazla bilgi Azure.Identity için ad alanı belgelerine bakın.
  • Başlarken yararlı olabilir, ancak yönetilen kimliğin kimlik bilgileri de dahil olmak üzere, MSI ile ayarlanmış Azure işlevlerinin kimliğini InteractiveBrowserCredential Azure Digital Twins. hakkında daha fazla bilgi InteractiveBrowserCredential için sınıf belgelerine bakın.
  • Azure Digital Twins API'lere yönelik istekler, Azure Active Directory örneğinin bulunduğu aynı Azure Active Directory (Azure AD) kiracının parçası olan bir kullanıcı Azure Digital Twins gerektirir. Uç noktaların kötü amaçlı Azure Digital Twins önlemek için, kaynak kiracının dışından erişim belirteçlerine sahip istekler "404 Sub-Domain bulunamadı" hata iletisi döndürülür. Kullanıcıya veya hizmet sorumlusuna Azure AD B2B işbirliği aracılığıyla Azure Digital Twins Veri Sahibi veya Azure Digital Twins Okuyucusu rolü verilmiş olsa bile bu hata döndürülür. Birden çok kiracı arasında erişim elde etmek için bkz. Uygulama kimlik doğrulama kodu yazma.
  • Tüm hizmet API'si çağrıları sınıfında üye işlevleri olarak DigitalTwinsClient açığa çıkar.
  • Tüm hizmet işlevleri zaman uyumlu ve zaman uyumsuz sürümlerde mevcuttur.
  • Tüm hizmet işlevleri 400 veya üzeri dönüş durumları için bir özel durum oluşturur. Çağrıları bir bölüme try sarmalayın ve en azından yakalayın. RequestFailedExceptions Bu özel durum türü hakkında daha fazla bilgi için başvuru belgelerine bakın.
  • Çoğu hizmet yöntemi veya (zaman uyumsuz çağrılar için) dönüştedir; burada, hizmet Response<T> çağrısı için dönüş Task<Response<T>> T nesnesinin sınıfıdır. Response sınıfı, hizmet dönüşlerini kapsüller ve alanında dönüş değerleri Value sunar.
  • Çağrılı sonuçları olan hizmet yöntemleri veya Pageable<T> sonuç AsyncPageable<T> olarak döner. sınıfı hakkında daha fazla Pageable<T> bilgi için başvuru belgelerine bakın;hakkında daha fazla bilgi AsyncPageable<T> için, başvuru belgelerine bakın.
  • Döngü kullanarak sayfalı sonuçların üzerinde tekrar await foreach edebilirsiniz. Bu işlem hakkında daha fazla bilgi için ilgili belgelere bakın.
  • Temel ALıNAN SDK şu Azure.Core şekildedir: . SDK altyapısı ve türleri hakkında başvuru için Azure ad alanı belgelerine bakın.

Hizmet yöntemleri, mümkün olan her yerde kesin olarak türü kesin olarak yazarak nesneleri geri döner. Ancak, Azure Digital Twins çalışma zamanında (hizmete yüklenen DTDL modelleri aracılığıyla) kullanıcı tarafından özel olarak yapılandırılan modelleri temel alması nedeniyle, birçok hizmet API'si JSON biçiminde ikiz verilerini alır ve geri alır.

API ölçümlerini izleme

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

Portal giriş sayfasından, ayrıntılarını çekmek Azure Digital Twins örnek için arama yapın. Ölçümler sayfasını görmek için Azure Digital Twins örneğinin menüsünden Ölçümler seçeneğini belirleyin.

Rapor için ölçümler sayfasını gösteren Azure Digital Twins.

Buradan örneğinizin ölçümlerini görüntüp özel görünümler oluşturabilirsiniz.

Sonraki adımlar

Postman kullanarak API'lere doğrudan istekte nasıl yer alanın:

Ya da bu öğreticiyle bir istemci uygulaması oluşturarak .NET SDK'sı kullanarak alıştırmalar da edinebilirsiniz: