Azure Digital Twins'de uç noktalar oluşturma

Bu makalede, Azure portalını veya Azure CLI'yi kullanarak Azure Digital Twin olayları için nasıl uç nokta oluşturulacağı açıklanmaktadır. Ayrıca DigitalTwinsEndpoint denetim düzlemi API'leri ile uç noktaları yönetebilirsiniz.

Azure Digital Twins'den aşağı akış hizmetlerine veya bağlı işlem kaynaklarına olay bildirimlerini yönlendirmek iki adımlı bir işlemdir: uç noktalar oluşturma ve ardından bu uç noktalara veri göndermek için olay yolları oluşturma. Bu makale, olayları alabilecek uç noktaları ayarlamanın ilk adımını kapsar. Daha sonra, Azure Digital Twins tarafından oluşturulan olayların hangi uç noktalara teslimleneceğini belirten olay yolları oluşturabilirsiniz.

Ön koşullar

  • Ücretsiz olarak ayarlanabilen bir Azure hesabına ihtiyacınız olacak

  • Azure aboneliğinizde bir Azure Digital Twins örneğine ihtiyacınız olacaktır. Henüz bir örneğiniz yoksa Örneği ayarlama ve kimlik doğrulaması adımlarını kullanarak bir örnek oluşturabilirsiniz. Bu makalenin devamında kullanmak için kurulumdan elde edilen aşağıdaki değerlerin kullanışlı olmasını sağlar:

    • Örnek adı
    • Kaynak grubu

    Örneğinizi ayarladıktan sonra bu ayrıntıları Azure portalında bulabilirsiniz.

    Screenshot of the Overview page for an Azure Digital Twins instance in the Azure portal. The name and resource group are highlighted.

Ardından, bu kılavuzu izlerken Azure CLI kullanmayı planlıyorsanız aşağıdaki yönergeleri izleyin.

Ortamınızı Azure CLI’ye hazırlama

  • Azure Cloud Shell'de Bash ortamını kullanın. Daha fazla bilgi için bkz . Azure Cloud Shell'de Bash için hızlı başlangıç.

  • CLI başvuru komutlarını yerel olarak çalıştırmayı tercih ediyorsanız Azure CLI'yı yükleyin . Windows veya macOS üzerinde çalışıyorsanız Azure CLI’yi bir Docker kapsayıcısında çalıştırmayı değerlendirin. Daha fazla bilgi için bkz . Docker kapsayıcısında Azure CLI'yi çalıştırma.

    • Yerel yükleme kullanıyorsanız az login komutunu kullanarak Azure CLI ile oturum açın. Kimlik doğrulama işlemini tamamlamak için terminalinizde görüntülenen adımları izleyin. Diğer oturum açma seçenekleri için bkz . Azure CLI ile oturum açma.

    • İstendiğinde, ilk kullanımda Azure CLI uzantısını yükleyin. Uzantılar hakkında daha fazla bilgi için bkz. Azure CLI ile uzantıları kullanma.

    • Yüklü sürümü ve bağımlı kitaplıkları bulmak için az version komutunu çalıştırın. En son sürüme yükseltmek için az upgrade komutunu çalıştırın.

Gerekli kaynakları oluşturma

Bu hizmetler, örneğiniz için oluşturabileceğiniz desteklenen uç nokta türleridir:

Bir uç noktayı Azure Digital Twins'e bağlamak için, uç nokta için kullandığınız Event Grid konusu, olay hub'ı veya Service Bus konusunun zaten mevcut olması gerekir.

Uç noktanızı oluşturmadan önce hangi kaynakların ayarlanması gerektiğini görmek için aşağıdaki grafiği kullanın.

Uç nokta türü Gerekli kaynaklar (oluşturma yönergelerine bağlı)
Event Grid uç noktası Event Grid konusu
*olay şeması Event Grid Şeması veya Bulut Olay Şeması v1.0 olmalıdır
Event Hubs uç noktası Event Hubs ad alanı

olay hub'ı

(İsteğe bağlı) anahtar tabanlı kimlik doğrulaması için yetkilendirme kuralı
Service Bus uç noktası Service Bus ad alanı

Service Bus konusu

(İsteğe bağlı) anahtar tabanlı kimlik doğrulaması için yetkilendirme kuralı

Uç noktayı oluşturma

Uç nokta kaynaklarını oluşturduktan sonra, bunları bir Azure Digital Twins uç noktası için kullanabilirsiniz.

Yeni bir uç nokta oluşturmak için Örneğinizin Azure portalındaki sayfasına gidin (portal arama çubuğuna adını girerek örneği bulabilirsiniz).

  1. Örnek menüsünde Uç Noktalar'ı seçin. Ardından, izleyen Uç Noktalar sayfasında + Uç nokta oluştur'u seçin. Bunu yaptığınızda, Aşağıdaki adımlarda alanları dolduracağınız Uç nokta oluştur sayfası açılır.

    Screenshot of creating an endpoint of type Event Grid in the Azure portal.

  2. Uç noktanız için bir Ad girin ve Uç nokta türünü seçin.

  3. Aboneliğiniz ve daha önce açıklanan uç nokta kaynakları dahil olmak üzere uç nokta türünüz için gereken diğer ayrıntıları tamamlayın.

    1. Yalnızca Event Hubs ve Service Bus uç noktaları için bir Kimlik Doğrulama türü seçmeniz gerekir. Anahtar tabanlı kimlik doğrulamayı önceden oluşturulmuş bir yetkilendirme kuralıyla veya sistem tarafından atanan veya kullanıcı tarafından atanan yönetilen kimlikle kullanabilirsiniz. Kimlik doğrulama seçeneklerini kullanma hakkında daha fazla bilgi için bkz . Uç nokta seçenekleri: Kimlik tabanlı kimlik doğrulaması.

    Screenshot of creating an endpoint of type Event Hubs in the Azure portal.

  4. Kaydet'i seçerek uç noktanızı oluşturmayı tamamlayın.

Uç noktanızı oluşturduktan sonra üst Azure portal çubuğundaki bildirim simgesini denetleyerek uç noktanın başarıyla oluşturulduğunu doğrulayabilirsiniz:

Screenshot of the notification to verify the creation of an endpoint in the Azure portal.

Uç nokta oluşturma işlemi başarısız olursa hata iletisini gözlemleyin ve birkaç dakika sonra yeniden deneyin.

Azure Digital Twins örneğinizin Uç Noktalar sayfasında yeniden oluşturulan uç noktayı da görüntüleyebilirsiniz.

Artık Event Grid konusu, olay hub'ı veya Service Bus konusu, uç nokta için seçtiğiniz adla Azure Digital Twins'de uç nokta olarak kullanılabilir. Bu adı genellikle bir olay yolunun hedefi olarak kullanırsınız ve bu yolu ve filtreleri oluşturma bölümünde oluşturabilirsiniz.

Uç nokta seçenekleri: Kimlik tabanlı kimlik doğrulaması

Bu bölümde, olayları desteklenen yönlendirme hedeflerine iletirken Azure Digital Twins örneği için yönetilen kimliğin nasıl kullanılacağı açıklanmaktadır. Yönlendirme için yönetilen kimlik ayarlamak gerekli değildir, ancak örneğin Event Hubs, Service Bus hedefleri ve Azure Depolama Kapsayıcısı gibi diğer Microsoft Entra korumalı kaynaklarına kolayca erişmesine yardımcı olabilir. Yönetilen kimlikler sistem tarafından veya kullanıcı tarafından atanabilir.

Bu bölümün geri kalanında yönetilen kimlikle uç nokta ayarlamaya yönelik üç adım gösterilmektedir.

1. Örnek için yönetilen kimliği etkinleştirme

Tercih ettiğiniz deneyimle eşleşen yönergeler için aşağıdaki sekmeleri kullanın.

İlk olarak, Azure Digital Twins örneğiniz için yönetilen kimliği etkinleştirdiğinizden emin olun.

Ayrıca örnekte Azure Digital Twins Veri Sahibi rolünüz olduğundan emin olun. Yönergeleri Kullanıcı erişim izinlerini ayarlama bölümünde bulabilirsiniz.

2. Kimliğe Azure rolleri atama

Azure Digital Twins örneğiniz için yönetilen kimlik oluşturulduktan sonra, olayları desteklenen hedeflere yönlendirmek için farklı uç nokta türleriyle kimlik doğrulaması yapmak için uygun roller atamanız gerekir. Bu bölümde rol seçenekleri ve bunların yönetilen kimliğe nasıl atandığı açıklanmaktadır.

Önemli

Bu adımı tamamladığınızdan emin olun. Bu olmadan kimlik uç noktalarınıza erişemez ve olaylar teslim edilmeyecektir.

Azure Digital Twins kimliğinizin hedef türüne bağlı olarak bir uç noktaya erişmesi için gereken minimum roller aşağıdadır. Daha yüksek izinlere sahip roller (Veri Sahibi rolleri gibi) da çalışır.

Hedef Azure rolü
Azure Event Hubs Azure Event Hubs Veri Göndereni
Azure Service Bus Azure Service Bus Veri Göndereni
Azure depolama kapsayıcısı Depolama Blobu Veri Katılımcısı

Tercih ettiğiniz deneyimi kullanarak rolü atamak için aşağıdaki sekmeleri kullanın.

Kimliğe rol atamak için azure portalını tarayıcıda açarak işe başlayın.

  1. Portal arama çubuğunda adını arayarak uç nokta kaynağınıza (olay hub'ınız, Service Bus konu başlığınız veya depolama kapsayıcınız) gidin.

  2. Erişim denetimi (IAM) öğesini seçin.

  3. Rol ataması ekle sayfasını açmak için Rol ataması ekle'yi>seçin.

  4. Aşağıdaki bilgileri kullanarak azure digital twins örneğinizin yönetilen kimliğine istediğiniz rolü atayın. Ayrıntılı adımlar için bkz. Azure portalı kullanarak Azure rolleri atama.

    Ayar Değer
    Rol Seçeneklerden istediğiniz rolü seçin.
    Şu kişiye erişim ata: Yönetilen kimlik
    Üyeler Rol atanan Azure Digital Twins örneğinizin kullanıcı tarafından atanan veya sistem tarafından atanan yönetilen kimliğini seçin. Kullanıcı tarafından atanan kimlik, kimliği oluştururken seçtiğiniz ada sahip olur ve sistem tarafından atanan bir kimlik, Azure Digital Twins örneğinizin adıyla eşleşen bir ada sahip olur.

    Screenshot of the 'Add role assignment' page for an Azure Digital Twins instance.

3. Kimlik tabanlı kimlik doğrulaması ile uç nokta oluşturma

Azure Digital Twins örneğiniz için yönetilen kimlik ayarladıktan ve uygun rolleri atadıktan sonra kimlik doğrulaması için kimliği kullanan uç noktaları oluşturabilirsiniz. Bu seçenek yalnızca Event Hubs ve Service Bus türündeki uç noktalarda kullanılabilir (Event Grid için desteklenmez).

Dekont

Kimlik tabanlı kimlik doğrulamasına geçmek için anahtar tabanlı kimlikle önceden oluşturulmuş bir uç noktayı düzenleyemezsiniz. Uç nokta ilk oluşturulduğunda kimlik doğrulama türünü seçmeniz gerekir.

Tercih ettiğiniz deneyimi kullanarak uç nokta oluşturmak için aşağıdaki sekmeleri kullanın.

Azure Digital Twins uç noktası oluşturmak için genel yönergeleri izleyin.

Uç nokta türünüz için gereken ayrıntıları tamamlama adımına gittiğinizde, Kimlik doğrulama türü için Sistem tarafından atanan veya Kullanıcı tarafından atanan (önizleme) öğesini seçin.

Screenshot of creating an endpoint of type Event Hubs.

Uç noktanızı ayarlamayı tamamlayın ve Kaydet'i seçin.

Yönetilen kimlikleri devre dışı bırakmak için dikkat edilmesi gerekenler

Bir kimlik, onu kullanan uç noktalardan ayrı yönetildiğinden, kimlikte veya rollerinde yapılan değişikliklerin Azure Digital Twins örneğinizdeki uç noktalar üzerindeki etkilerini göz önünde bulundurmanız önemlidir. Kimlik devre dışı bırakılırsa veya bir uç nokta için gerekli bir rol kaldırılırsa uç noktaya erişilemez hale gelebilir ve olay akışı kesintiye uğrayacaktır.

Artık devre dışı bırakılmış yönetilen kimlikle ayarlanmış bir uç noktayı kullanmaya devam etmek için, uç noktayı silmeniz ve farklı bir kimlik doğrulaması türüyle yeniden oluşturmanız gerekir. Bu değişiklik sonrasında, olayların uç noktaya tesliminin sürdürülmesi bir saat kadar sürebilir.

Uç nokta seçenekleri: Teslim edilemeyen harfleme

Bir uç nokta belirli bir süre içinde veya olayı belirli bir sayıda teslim etmeye çalıştıktan sonra olayı teslim edemeyen olayı bir depolama hesabına gönderebilir. Bu işlem, geçersiz harfleme olarak bilinir.

Azure portalını veya Azure Digital Twins CLI'yı kullanarak gerekli depolama kaynaklarını ayarlayabilirsiniz. Ancak, teslim edilemeyen harfleme etkin bir uç nokta oluşturmak için Azure Digital Twins CLI veya denetim düzlemi API'lerini kullanmanız gerekir.

Teslim edilemeyen harf oluşturma hakkında daha fazla bilgi edinmek için bkz . Uç noktalar ve olay yolları. Teslim edilemeyen harfle uç nokta ayarlama yönergeleri için bu bölümün geri kalanından devam edin.

Depolama kaynaklarını ayarlama

Teslim edilemeyen harf konumunu ayarlamadan önce Azure hesabınızda ayarlanmış bir kapsayıcı içeren bir depolama hesabınız olmalıdır.

Uç noktayı oluştururken bu kapsayıcı için URI'yi daha sonra sağlayacaksınız. Teslim edilemeyen harf konumu, uç noktaya SAS belirteci içeren bir kapsayıcı URI'si olarak sağlanacaktır. Bu belirtecin depolama hesabı içindeki hedef kapsayıcı için izin alması gerekir write . Tam olarak biçimlendirilmiş teslim edilemeyen SAS URI'sinin biçimi: https://<storage-account-name>.blob.core.windows.net/<container-name>?<SAS-token>.

Sonraki bölümde uç nokta bağlantısını ayarlamaya hazırlanmak üzere Azure hesabınızda bu depolama kaynaklarını ayarlamak için aşağıdaki adımları izleyin.

  1. Azure aboneliğinizde depolama hesabı oluşturmak için Depolama hesabı oluşturma bölümündeki adımları izleyin. Daha sonra kullanmak için depolama hesabı adını not edin.
  2. Yeni depolama hesabında kapsayıcı oluşturmak için Kapsayıcı oluşturma'daki adımları izleyin. Daha sonra kullanmak için kapsayıcı adını not edin.

SAS belirteci oluşturma

Ardından depolama hesabınız için uç noktanın erişebileceği bir SAS belirteci oluşturun.

  1. Azure portalında depolama hesabınıza giderek başlayın (portal arama çubuğuyla adıyla bulabilirsiniz).

  2. DEPOLAMA hesabı sayfasında, SAS belirtecini ayarlamaya başlamak için sol gezinti çubuğunda paylaşılan erişim imzası bağlantısını seçin.

    Screenshot of the storage account page in the Azure portal.

  3. Paylaşılan erişim imzası sayfasındaki İzin verilen hizmetler ve İzin verilen kaynak türleri altında istediğiniz ayarları seçin. Her kategoride en az bir kutu seçmeniz gerekir. İzin verilen izinler'in altında Yaz'ı seçin (isterseniz diğer izinleri de seçebilirsiniz).

  4. Kalan ayarlar için istediğiniz değerleri ayarlayın.

  5. İşiniz bittiğinde SAS belirtecini oluşturmak için SAS oluştur ve bağlantı dizesi düğmesini seçin.

    Screenshot of the storage account page in the Azure portal showing all the setting selection to generate a SAS token.

  6. Bunu yaptığınızda, ayar seçimlerinin altında, aynı sayfanın en altında birkaç SAS ve bağlantı dizesi değeri oluşturulur. Değerleri görüntülemek için aşağı kaydırın ve SAS belirteci değerini kopyalamak için Panoya kopyala simgesini kullanın. Daha sonra kullanmak için kaydedin.

    Screenshot of the storage account page in the Azure portal highlighting how to copy the SAS token to use in the dead-letter secret.

Teslim edilemeyen harf uç noktasını oluşturma

Teslim edilemeyen harfleme etkin bir uç nokta oluşturmak için, Azure portalı yerine uç noktanızı oluşturmak için CLI komutlarını veya denetim düzlemi API'lerini kullanmanız gerekir.

Azure CLI ile bu tür uç nokta oluşturma yönergeleri için bu bölümün CLI sekmesine geçin.

İleti depolama şeması

Teslim edilemeyen harfli uç nokta ayarlandıktan sonra, teslim edilemeyen iletiler depolama hesabınızda aşağıdaki biçimde depolanır:

<container>/<endpoint-name>/<year>/<month>/<day>/<hour>/<event-ID>.json

Teslim edilemeyen iletiler, özgün uç noktanıza teslim edilmesi amaçlanan özgün olayın şemasıyla eşleşecektir.

İkiz oluşturma bildirimi için bir teslim edilemeyen ileti örneği aşağıda verilmişti:

{
  "specversion": "1.0",
  "id": "xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "type": "Microsoft.DigitalTwins.Twin.Create",
  "source": "<your-instance>.api.<your-region>.da.azuredigitaltwins-test.net",
  "data": {
    "$dtId": "<your-instance>xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "$etag": "W/\"xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx\"",
    "TwinData": "some sample",
    "$metadata": {
      "$model": "dtmi:test:deadlettermodel;1",
      "room": {
        "lastUpdateTime": "2020-10-14T01:11:49.3576659Z"
      }
    }
  },
  "subject": "<your-instance>xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "time": "2020-10-14T01:11:49.3667224Z",
  "datacontenttype": "application/json",
  "traceparent": "00-889a9094ba22b9419dd9d8b3bfe1a301-f6564945cb20e94a-01"
}

Sonraki adımlar

Azure Digital Twins'den uç noktaya veri göndermek için bir olay yolu tanımlamanız gerekir. Bu yollar geliştiricilerin olay akışını sistem genelinde ve aşağı akış hizmetlerine aktarmasına olanak tanır. Tek bir yol, birden çok bildirimin ve olay türünün seçilmesine izin verebilir. Yol ve filtreler oluşturma bölümünde uç noktanıza bir olay yolu oluşturmak için devam edin.