Öğretici: Örnek istemci uygulamasını kullanarak Azure Digital Twins grafı oluşturma

Makale
01/04/2024

Bu öğreticide modelleri, ikizleri ve ilişkileri kullanarak Azure Digital Twins'de bir grafik oluşturacaksınız. Bu öğreticinin aracı, Azure Digital Twins örneğiyle etkileşime yönelik örnek komut satırı istemci uygulamasıdır. İstemci uygulaması, İstemci uygulaması kodla'da yazılana benzer.

Modelleri karşıya yükleme, ikiz oluşturma ve değiştirme ve ilişkiler oluşturma gibi temel Azure Digital Twins eylemlerini gerçekleştirmek için bu örneği kullanabilirsiniz. Azure Digital Twins API'leri hakkında bilgi edinmek için örneğin koduna da bakabilir ve örnek projeyi istediğiniz gibi değiştirerek kendi komutlarınızı uygulama alıştırması yapabilirsiniz.

Bu öğreticide,...

Bir ortamı modelleme
Dijital ikizleri oluşturma
Grafik oluşturmak için ilişkiler ekleme
Soruları yanıtlamak için grafı sorgulama

Önkoşullar

Bu öğreticiye başlamadan önce şu önkoşullarla başlayın:

Azure aboneliğiniz yoksa başlamadan önce ücretsiz bir hesap oluşturun.
Bu öğreticide .NET kullanılır. .NET'i İndir'den birden çok platform için .NET SDK'sının en son sürümünü indirebilirsiniz.

Ardından, kalan önkoşulları ayarlamak için bu bölümün geri kalanından devam edin.

Örnek kaynakları alma

Öğretici, C# dilinde yazılmış bir uçtan uca Azure Digital Twins örnek projesi tarafından yönlendirilir. Örnek bağlantıya gidip başlığın altındaki Koda gözat düğmesini seçerek makinenizdeki örnek projeyi alın.

Bu işlem sizi örneklerin GitHub deposuna götürür. Bu depoyu kod düğmesini ve ardından ZIP İndir'i seçerek .zip olarak indirebilirsiniz.

Bu işlem makinenize digital-twins-samples-main.zip olarak bir .zip klasörü indirir. Klasörün sıkıştırmasını açın ve dosyaları ayıklayın.

Azure Digital Twins örneği hazırlama

Bu makalede Azure Digital Twins ile çalışmak için bir Azure Digital Twins örneğine ve bunu kullanmak için gerekli izinlere sahip olmanız gerekir. Zaten ayarlanmış bir Azure Digital Twins örneğiniz varsa bu örneği kullanabilir ve sonraki bölüme atlayabilirsiniz. Aksi takdirde, Örnek ve kimlik doğrulaması ayarlama başlığındaki yönergeleri izleyin. Yönergeler, her adımı başarıyla tamamladığınızdan emin olmanıza yardımcı olacak bilgiler içerir.

Örneğinizi ayarladıktan sonra, örneğin ana bilgisayar adını not edin. Konak adını Azure portalında bulabilirsiniz.

Örnek projeyi yapılandırma

Ardından, Azure Digital Twins örneğiniz ile etkileşim kuracak örnek bir istemci uygulaması ayarlayın.

Makinenizde daha önce Azure Digital Twins uçtan uca örneklerden indirdiğiniz klasöre gidin (henüz yapmadıysanız sıkıştırmasını açın).

Klasörün içine girdikten sonra digital-twins-samples-main\AdtSampleApp\SampleClientApp konumuna gidin ve appsettings.json dosyasını açın. Bu JSON dosyası, projeyi çalıştırmak için gereken bir yapılandırma değişkeni içerir.

Dosya gövdesinde öğesini Azure Digital Twins örneği ana bilgisayar adı URL'niz olarak değiştirin instanceUrl (aşağıda gösterildiği gibi konak adının önüne https:// ekleyerek).

{
  "instanceUrl": "https://<your-Azure-Digital-Twins-instance-host-name>"
}

Dosyayı kaydedip kapatın

Yerel Azure kimlik bilgilerini ayarlama

Bu örnek, yerel makinenizde çalıştırdığınızda Azure Digital Twins örneğiyle kullanıcıların kimliğini doğrulamak için DefaultAzureCredential (kitaplığın bir parçasıAzure.Identity) kullanır. bir istemci uygulamasının Azure Digital Twins ile kimlik doğrulaması yapmanın farklı yolları hakkında daha fazla bilgi için bkz . Uygulama kimlik doğrulama kodu yazma.

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.

Örnek projeyi çalıştırma

Uygulama ve kimlik doğrulaması ayarlandıklarına göre, projeyi çalıştırmak için kullanacağınız yerel bir konsol penceresi açın. Konsolda digital-twins-samples-main\AdtSampleApp\SampleClientApp klasörüne gidin ve projeyi şu dotnet komutuyla çalıştırın:

dotnet run

Proje çalışmaya başlar, kimlik doğrulamasını gerçekleştirir ve bir komut bekler.

İşte proje konsolunun nasıl göründüğüne ilişkin bir ekran görüntüsü:

İpucu

Bu projede kullanabileceğiniz tüm olası komutların listesi için proje konsoluna girin help ve return tuşuna basın.

Uygulamanın başarıyla çalıştığını onayladıktan sonra projeyi çalıştırmayı durdurabilirsiniz. Öğreticinin ilerleyen bölümlerinde yeniden çalıştıracaksınız.

DTDL ile fiziksel ortam modelleme

Artık Azure Digital Twins örneği ve örnek uygulaması ayarlandıysa bir senaryonun grafiğini oluşturmaya başlayabilirsiniz.

Azure Digital Twins çözümü oluşturmanın ilk adımı, ortamınız için ikiz modelleri tanımlamaktır.

Modeller nesne odaklı programlama dillerindeki sınıflara benzer; bunlar, dijital ikizler oluşturmak için örnek oluşturabileceğiniz kullanıcı tanımlı şablonlardır. Azure Digital Twins modelleri Digital Twins Tanım Dili (DTDL) adlı JSON benzeri bir dilde yazılır ve özellikleri, ilişkileri ve bileşenleri açısından bir ikiz türü tanımlar.

Not

DTDL ayrıca dijital ikizlerde komutların tanımlanmasını sağlar. Ancak şu anda Azure Digital Twins hizmetinde komutlar desteklenmiyor.

Daha önce indirdiğiniz örnek proje klasöründe digital-twins-samples-main\AdtSampleApp\SampleClientApp\Models klasörüne gidin. Bu klasör örnek modeller içerir.

Düzenlemek üzere Room.json açın ve kodda aşağıdaki değişiklikleri yapın:

Bu modelin daha güncelleştirilmiş bir sürümünü sağladığınızı belirtmek için sürüm numarasını güncelleştirin. Değerin sonundaki @id 1 değerini 2 olarak değiştirerek bunu yapın. Geçerli sürüm numarasından daha büyük herhangi bir sayı da çalışır.
Bir özelliği düzenleyin. Özelliğin Humidity adını HumidityLevel (veya isterseniz farklı bir şey) olarak değiştirin. HumidityLevel'den farklı bir şey kullanıyorsanız, ne kullandığınızı unutmayın ve öğretici boyunca HumidityLevel yerine bunu kullanmaya devam edin).
Özellik ekleyin. HumidityLevel 15. satırda biten özelliğin altına aşağıdaki kodu yapıştırarak odaya bir RoomName özellik ekleyin:
```
,{
  "@type": "Property",
  "name": "RoomName",
  "schema": "string"
}
```
İlişki ekleme. Yeni eklediğiniz özelliğin RoomName altına aşağıdaki kodu yapıştırarak bu tür ikizlerin diğer ikizlerle ilişki oluşturma contains yeteneğini ekleyin:
```
,{
  "@type": "Relationship",
  "name": "contains"
}
```

İşiniz bittiğinde, güncelleştirilmiş model aşağıdakiyle eşleşmelidir:

{
    "@id": "dtmi:example:Room;2",
    "@type": "Interface",
    "displayName": "Room",
    "contents": [
      {
        "@type": "Property",
        "name": "Temperature",
        "schema": "double"
      },
      {
        "@type": "Property",
        "name": "HumidityLevel",
        "schema": "double"
      }
      ,{
        "@type": "Property",
        "name": "RoomName",
        "schema": "string"
      }
      ,{
        "@type": "Relationship",
        "name": "contains"
      }
    ],
    "@context": "dtmi:dtdl:context;3"
  }

Devam etmeden önce dosyayı kaydettiğinizden emin olun.

Modelleri Azure Digital Twins'e yükleme

Modelleri tasarladıktan sonra Azure Digital Twins örneğine yüklemeniz gerekir. Bunu yaptığınızda Azure Digital Twins hizmet örneğinizi kendi özel etki alanı sözlüğünüzle yapılandırabilirsiniz. Modelleri karşıya yükledikten sonra, bunları kullanan ikiz örnekleri oluşturabilirsiniz.

digital-twins-samples-main\AdtSampleApp\SampleClientApp klasörüne açık olan konsol pencerenize dönün ve konsol uygulamasını ile dotnet runyeniden çalıştırın.
Proje konsolu penceresinde aşağıdaki komutu çalıştırarak güncelleştirilmiş Oda modelinizi ve sonraki bölümde farklı ikiz türleri oluşturmak için kullanacağınız Floor modelini karşıya yükleyin.
```
CreateModels Room Floor
```
Çıkış, modellerin başarıyla oluşturulduğunu göstermelidir.
komutunu GetModels trueçalıştırarak modellerin oluşturulduğunu doğrulayın. Bu komut, Azure Digital Twins örneğine yüklenmiş olan tüm modeller için tam bilgileri yazdırır. Sonuçlarda düzenlenmiş Oda modelini arayın:

Sonraki adımlar için konsol uygulamasını çalışır durumda tutun.

Hatalar

Örnek uygulama hizmetten gelen hataları da işler.

Bunu test etmek için komutunu yeniden çalıştırarak CreateModels zaten karşıya yüklediğiniz Oda modelini yeniden yüklemeyi deneyin:

CreateModels Room

Modellerin üzerine yazılamayacağı için bu komut artık oluşturmaya çalıştığınız model kimliklerinden bazılarının zaten var olduğunu belirten bir hizmet hatası döndürür.

Mevcut modelleri silme hakkında ayrıntılı bilgi için bkz . DTDL modellerini yönetme.

Dijital ikizleri oluşturma

Artık bazı modeller Azure Digital Twins örneğinize yüklendiğine göre, model tanımlarını temel alarak dijital ikizler oluşturabilirsiniz. Dijital ikizler, iş ortamınızdaki varlıkları (bir çiftlikteki algılayıcılar, bir binadaki odalar veya bir arabadaki ışıklar gibi) temsil eder.

Dijital ikiz oluşturmak için komutunu kullanırsınız CreateDigitalTwin . İkizi temel alan modele başvurmanız gerekir ve isteğe bağlı olarak modeldeki herhangi bir özellik için başlangıç değerleri tanımlayabilirsiniz. Bu aşamada herhangi bir ilişki bilgisi geçirmeniz gerekmez.

Daha önce güncelleştirdiğiniz Oda modeline ve başka bir model olan Floor'a göre birkaç ikiz oluşturmak için bu kodu çalışan proje konsolunda çalıştırın. Room'un üç özelliği olduğunu hatırlayın, bu nedenle bu özellikler için ilk değerleri içeren bağımsız değişkenler sağlayabilirsiniz. (Özellik değerlerinin başlatılması genel olarak isteğe bağlıdır, ancak bu öğretici için gereklidir.)
```
CreateDigitalTwin dtmi:example:Room;2 room0 RoomName string Room0 Temperature double 70 HumidityLevel double 30
CreateDigitalTwin dtmi:example:Room;2 room1 RoomName string Room1 Temperature double 80 HumidityLevel double 60
CreateDigitalTwin dtmi:example:Floor;1 floor0
CreateDigitalTwin dtmi:example:Floor;1 floor1
```
Bu komutlardan elde edilen çıkış ikizlerin başarıyla oluşturulduğunu göstermelidir.
komutunu çalıştırarak ikizlerin oluşturulduğunu Query doğrulayabilirsiniz. Bu komut, içerdiği tüm dijital ikizler için Azure Digital Twins örneğinizi sorgular. Sonuçlarda room0, room1, floor0 ve floor1 ikizlerini arayın.

Not

Grafiğinizdeki verilerde değişiklik yaptıktan sonra değişikliklerin sorgulara yansıtılması için 10 saniyeye kadar gecikme süresi olabilir.

DigitalTwins API'sinde değişiklikler hemen yansıtılır. Bu nedenle anlık yanıta ihtiyacınız varsa sorgu yerine ikizi veri almak için API isteği (DigitalTwins GetById) veya SDK çağrısı (GetDigitalTwin) kullanın.

Dijital ikizi değiştirme

Oluşturduğunuz ikizin özelliklerini de değiştirebilirsiniz.

Not

Temel alınan REST API, ikiz güncelleştirmelerini tanımlamak için JSON Düzeltme Eki biçimini kullanır. Komut satırı uygulaması da bu biçimi kullanarak temel API'lerin beklediğiyle ilgili daha gerçek bir deneyim sunar.

Room0'un RoomName değerini "Room0" olan "PresidentialSuite" olarak değiştirmek için şu komutu çalıştırın:
```
UpdateDigitalTwin room0 add /RoomName string PresidentialSuite
```
Çıkış, ikizin başarıyla güncelleştirildiğini göstermelidir.
Room0'un bilgilerini görmek için şu komutu çalıştırarak güncelleştirmenin başarılı olduğunu doğrulayabilirsiniz:
```
GetDigitalTwin room0
```
Çıktı güncelleştirilmiş adı yansıtmalıdır.

İlişkiler ekleyerek grafik oluşturma

Ardından, bu ikizler arasında bir ikiz grafiğine bağlamak için bazı ilişkiler oluşturabilirsiniz. İkiz grafikler ortamın tamamını temsil etmek için kullanılır.

Bir ikizden diğerine oluşturabileceğiniz ilişki türleri, daha önce karşıya yüklediğiniz modellerde tanımlanır. Floor için model tanımı, zeminlerin adlı containsbir ilişki türüne sahip olabileceğini belirtir ve bu da her Floor ikizinden içerdiği ilgili odayla bir -type ilişkisi oluşturmayı containsmümkün kılar.

İlişki eklemek için komutunu kullanın CreateRelationship . İlişkinin geldiği ikizi, ilişkinin türünü ve ilişkinin bağlandığını ikizini belirtin. Son olarak, ilişkiye benzersiz bir kimlik verin.

Daha önce oluşturduğunuz Floor ikizlerinin her birinden ilgili Oda ikizine ilişki eklemek contains için aşağıdaki komutları çalıştırın. İlişkiler relationship0 ve relationship1 olarak adlandırılır.
```
CreateRelationship floor0 contains room0 relationship0
CreateRelationship floor1 contains room1 relationship1
```
İpucu

contains Floor modelindeki ilişki iki dize özelliği ve ownershipDepartmentile de tanımlanmıştır. Bu nedenle, ownershipUser ilişkileri oluştururken bunların ilk değerlerini içeren bağımsız değişkenler de sağlayabilirsiniz. Yukarıdaki komutun, bu özellikler için ilk değerleri de belirten relationship0 oluşturmak için alternatif bir sürümü verilmiştir:
```
CreateRelationship floor0 contains room0 relationship0 ownershipUser string MyUser ownershipDepartment string myDepartment
```
Bu komutlardan elde edilen çıkış, ilişkilerin başarıyla oluşturulduğunu onaylar:
aşağıdaki komutlardan herhangi biriyle ilişkileri doğrulayabilirsiniz. Bu komut, Azure Digital Twins örneğinizdeki ilişkileri yazdırır.
- Her kattan çıkan tüm ilişkileri görmek için (ilişkileri bir taraftan görüntüleme):
```
GetRelationships floor0
GetRelationships floor1
```
- Her odaya gelen tüm ilişkileri görmek için (ilişkiyi "diğer" taraftan görüntüleme):
```
GetIncomingRelationships room0
GetIncomingRelationships room1
```
- Bu ilişkileri kimliklerine göre ayrı ayrı aramak için:
```
GetRelationship floor0 relationship0
GetRelationship floor1 relationship1
```

Bu öğreticide ayarladığınız ikizler ve ilişkiler aşağıdaki kavramsal grafiği oluşturur:

Ortam sorularını yanıtlamak için ikiz grafını sorgulama

Azure Digital Twins'in temel özelliklerinden biri, ortamınızla ilgili soruları yanıtlamak için ikiz grafınızı kolayca ve verimli bir şekilde sorgulama olanağıdır.

Not

Grafiğinizdeki verilerde değişiklik yaptıktan sonra değişikliklerin sorgulara yansıtılması için 10 saniyeye kadar gecikme süresi olabilir.

Örnek ortamla ilgili bazı soruları yanıtlamak için çalışan proje konsolunda aşağıdaki komutları çalıştırın.

Ortamımdaki tüm varlıklar Azure Digital Twins'de temsil edilir? (tümünü sorgula)
```
Query
```
Bu komut, ortamınızın stoklarını bir bakışta almanıza ve her şeyin Azure Digital Twins içinde olmasını istediğiniz şekilde temsil edilmesini sağlar. Bu komutun sonucu, her dijital ikizin ayrıntılarını içeren bir çıkıştır. İşte bir alıntı:

İpucu

Örnek projede, ek bağımsız değişken içermeyen komut Query ile eşdeğerdir Query SELECT * FROM DIGITALTWINS. Sorgu API'lerini veya CLI komutlarını kullanarak örneğinizdeki tüm ikizleri sorgulamak için daha uzun (eksiksiz) sorguyu kullanın.
Ortamımdaki tüm odalar nelerdir? (modele göre sorgu)
```
Query SELECT * FROM DIGITALTWINS T WHERE IS_OF_MODEL(T, 'dtmi:example:Room;2')
```
Temsil edilenler hakkında daha ayrıntılı bilgi almak için sorgunuzu belirli bir tür ikizle kısıtlayabilirsiniz. Bunun sonucunda room0 ve room1 gösterilir, ancak floor0 veya floor1 gösterilmez (odalar değil, zemin oldukları için).
Zemindeki tüm odalar nedir0? (ilişkiye göre sorgula)
```
Query SELECT room FROM DIGITALTWINS floor JOIN room RELATED floor.contains where floor.$dtId = 'floor0'
```
İkizlerin nasıl bağlandığı hakkında bilgi almak veya sorgunuzu belirli bir alanla kısıtlamak için grafiğinizdeki ilişkileri temel alarak sorgulayabilirsiniz. Sadece room0 kattadır0, bu nedenle sonuçtaki tek odadır.
Ortamımdaki sıcaklığı 75'in üzerinde olan tüm ikizler nelerdir? (özelliğe göre sorgula)
```
Query SELECT * FROM DigitalTwins T WHERE T.Temperature > 75
```
Ortamınızda dikkat gerektiren aykırı değerleri bulmak da dahil olmak üzere çeşitli soruları yanıtlamak için grafı özelliklere göre sorgulayabilirsiniz. Diğer karşılaştırma işleçleri de (<,>, =, veya !=) desteklenir. room1 burada sonuçlarda görünür, çünkü sıcaklığı 80'tir.
Sıcaklığı 75'in üzerinde olan floor0'da tüm odalar nelerdir? (bileşik sorgu)
```
Query SELECT room FROM DIGITALTWINS floor JOIN room RELATED floor.contains where floor.$dtId = 'floor0' AND IS_OF_MODEL(room, 'dtmi:example:Room;2') AND room.Temperature > 75
```
Ayrıca, , OR, NOTgibi birleşim işleçlerini kullanarak SQL'de yaptığınız gibi ANDönceki sorguları birleştirebilirsiniz. Bu sorgu, ikiz sıcaklıklarıyla ilgili önceki sorguyu daha belirgin hale getirmek için kullanır AND . Sonuç artık yalnızca 75'in üzerinde sıcaklıkları olan ve 0'ın üzerinde olan odaları içerir; bu durumda bunların hiçbiri değildir. Sonuç kümesi boş.

Ayarladığınız senaryo üzerinde birkaç sorgu çalıştırdığınıza göre, öğretici tamamlanır. Projeyi çalıştırmayı durdurun ve konsol penceresini kapatın.

Kaynakları temizleme

Bu öğreticiyi tamamladıktan sonra, bundan sonra ne yapmak istediğinize bağlı olarak hangi kaynakları kaldırmak istediğinizi seçebilirsiniz.

Sonraki öğreticiye devam etmek istiyorsanız, bu Azure Digital Twins örneğini kullanmaya ve sonraki öğretici için yapılandırılmış örnek uygulamayı kullanmaya devam etmek için burada ayarladığınız kaynakları tutabilirsiniz
Azure Digital Twins örneğini kullanmaya devam etmek ancak tüm modellerini, ikizlerini ve ilişkilerini temizlemek istiyorsanız örnek uygulamanın DeleteAllTwins ve DeleteAllModels komutlarını kullanarak örneğinizdeki ikizleri ve modelleri temizleyebilirsiniz.

Bu öğreticide oluşturduğunuz kaynaklardan herhangi birine ihtiyacınız yoksa az group delete CLI komutuyla Azure Digital Twins örneğini ve diğer tüm kaynakları bu makaleden silebilirsiniz . Bu işlem, kaynak grubundaki tüm Azure kaynaklarının yanı sıra kaynak grubunun kendisini de siler.

Önemli

Silinen kaynak grupları geri alınamaz. Kaynak grubu ve içindeki tüm kaynaklar kalıcı olarak silinir. Yanlış kaynak grubunu veya kaynakları yanlışlıkla silmediğinizden emin olun.

Azure Cloud Shell'i veya yerel cli penceresini açın ve kaynak grubunu ve içerdiği her şeyi silmek için aşağıdaki komutu çalıştırın.
```
az group delete --name <your-resource-group>
```

İndirilen proje klasörünü yerel makinenizden de silmek isteyebilirsiniz.

Sonraki adımlar

Bu öğreticide örnek istemci uygulamasını kullanarak örneğinizde bir grafik oluşturarak Azure Digital Twins'i kullanmaya başladınız. Graf oluşturmak için modeller, dijital ikizler ve ilişkiler oluşturdunuz. Ayrıca, Azure Digital Twins'in bir ortam hakkında ne tür sorulara yanıt verebileceği hakkında fikir edinmek için grafikte bazı sorgular çalıştırmıştınız.

Veri odaklı, uçtan uca bir senaryoyu tamamlamak için Azure Digital Twins'i diğer Azure hizmetleriyle birleştirmek için sonraki öğreticiye geçin:

Uçtan uca çözüm bağlama

Aracılığıyla paylaş