Azure Digital Twins'de olay yolları ve filtreleri oluşturma

Bu makalede Azure portalını, Azure CLI az dt route komutlarını, Event Routes veri düzlemi API'lerini ve .NET (C#) SDK'sını kullanarak olay yolları oluşturma işleminde size yol gösterilir.

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, hangi olayların hangi Azure Digital Twin uç noktalarına teslim edilir denetlemek için yolların ayarlandığı ikinci adımı kapsar. Bu makaleye devam etmek için uç noktaların önceden oluşturulmuş olması gerekir.

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

  

• Uç nokta oluşturma başlığındaki yönergeleri kullanarak bir uç nokta oluşturun. Bu makalede, bu uç noktaya veri göndermek için bir yol oluşturacaksınız.

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.

Olay yolu oluşturma

Uç nokta oluşturduktan sonra , 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. Uç noktalar ve olay yolları'ndaki olay yolları hakkında daha fazla bilgi edinin.

Dekont

Yol oluşturmaya geçmeden önce Önkoşullar bölümünde açıklandığı gibi en az bir uç nokta oluşturduğunuzdan emin olun.

Uç noktalarınızı yalnızca yakın zamanda dağıttıysanız, yeni bir olay yolu için kullanmayı denemeden önce dağıtımlarının tamamlandığını doğrulayın. Uç noktalar hazır olmadığı için yol dağıtımı başarısız olursa, birkaç dakika bekleyip yeniden deneyin.

Bu akışı betik olarak oluşturuyorsanız, uç nokta hizmetinin rota kurulumuna geçmeden önce dağıtımı tamamlaması için 2-3 dakika içinde bekleme süresi oluşturarak bunu hesaba katmanız iyi olabilir.

Yol tanımı şu öğeleri içerebilir:

• Kullanmak istediğiniz yol adı
• Kullanmak istediğiniz uç noktanın adı
• Uç noktaya hangi olayların gönderileceğini tanımlayan filtre
  • Hiçbir olayın gönderilmemesi için yolu devre dışı bırakmak için false
  • Belirli bir filtrelemesi olmayan bir yolu etkinleştirmek için true
  • Diğer filtre türleriyle ilgili ayrıntılar için aşağıdaki Olayları filtreleme bölümüne bakın

Yol adı yoksa, Azure Digital Twins dışında hiçbir ileti yönlendirilmemiş olur. Bir yol adı varsa ve filtre ise true, tüm iletiler uç noktaya yönlendirilir. Yol adı varsa ve farklı bir filtre eklenirse, iletiler filtreye göre filtrelenir.

Olay yolları Azure portalı, EventRoutes veri düzlemi API'leri veya az dt route CLI komutları ile oluşturulabilir. Bu bölümün geri kalanı oluşturma işleminde yol gösterir.

Portal

Olay yolu oluşturmak için Azure portalında Azure Digital Twins örneğinizin ayrıntılar sayfasına gidin (portal arama çubuğuna adını girerek örneği bulabilirsiniz).

Örnek menüsünden Olay yolları'nı seçin. Ardından, izleyen Olay yolları sayfasında + Olay yolu oluştur'u seçin.

Açılan Olay rotası oluştur sayfasında en azından şunu seçin:

• Ad alanında yolunuz için bir ad
• Yolu oluşturmak için kullanmak istediğiniz Uç Nokta

Yolun etkinleştirilmesi için en az truebir olay yolu filtresi de eklemeniz gerekir. (varsayılan değerinin false bırakılması yolu oluşturur, ancak buna hiçbir olay gönderilmez.) Bunu yapmak için Gelişmiş düzenleyicinin anahtarını etkinleştirecek şekilde değiştirin ve Filtre kutusuna yazıntrue.

İşiniz bittiğinde Kaydet düğmesini seçerek olay rotanızı oluşturun.

CLI

Yollar, Azure Digital Twins CLI için az dt route komutları kullanılarak yönetilebilir.

CLI'yi kullanma ve hangi komutların kullanılabilir olduğu hakkında daha fazla bilgi için bkz . Azure Digital Twins CLI komut kümesi.

.NET SDK

Bu bölümde .NET (C#) SDK'sını kullanarak olay yolu oluşturma adımları gösterilmektedir.

CreateOrReplaceEventRouteAsync , olay yolu eklemek için kullanılan SDK çağrısıdır. Kullanım örneği aşağıda verilmiştir:

string eventFilter = "$eventType = 'DigitalTwinTelemetryMessages' or $eventType = 'DigitalTwinLifecycleNotification'";
var er = new DigitalTwinsEventRoute("endpointName", eventFilter);
await client.CreateOrReplaceEventRouteAsync("routeId", er);

Bahşiş

Tüm SDK işlevleri zaman uyumlu ve zaman uyumsuz sürümlerde gelir.

Olay yolu örnek SDK kodu

Aşağıdaki örnek yöntem, C# SDK'sı ile bir olay yolu oluşturmayı, listelemeyi ve silmeyi gösterir:

public static async Task CreateEventRouteAsync(DigitalTwinsClient client, string routeId, DigitalTwinsEventRoute er)
{
    try
    {
        Console.WriteLine("Create a route: testRoute1");

        // Make a filter that passes everything
        er.Filter = "true";
        await client.CreateOrReplaceEventRouteAsync(routeId, er);
        Console.WriteLine("Create route succeeded.");

        // List routes
        AsyncPageable<DigitalTwinsEventRoute> results = client.GetEventRoutesAsync();
        await foreach (DigitalTwinsEventRoute route in results)
        {
            Console.WriteLine($"Route {route.Id} to endpoint {route.EndpointName} with filter {route.Filter} ");
        }

        // Delete route created earlier
        Console.WriteLine($"Deleting route {routeId}:");
        await client.DeleteEventRouteAsync(routeId);
    }
    catch (RequestFailedException e)
    {
        Console.WriteLine($"*** Error in event route processing ({e.ErrorCode}):\n${e.Message}");
    }
}

Olayları filtreleme

Yukarıda açıklandığı gibi, yolların bir filtre alanı vardır. Rotanızdaki filtre değeri ise falseuç noktanıza hiçbir olay gönderilmez.

en düşük filtreyi trueetkinleştirdikten sonra uç noktalar Azure Digital Twins'den farklı türde olaylar alır:

• Azure Digital Twins hizmet API'sini kullanarak dijital ikizler tarafından tetiklenen telemetri
• İkiz özellik değişikliği bildirimleri, Azure Digital Twins örneğindeki herhangi bir ikiz için özellik değişiklikleri tetiklenir
• İkizler veya ilişkiler oluşturulduğunda veya silindiğinde tetiklenen yaşam döngüsü olayları

Daha özel bir filtre tanımlayarak gönderilen olay türlerini kısıtlayabilirsiniz.

Dekont

Filtreler büyük/küçük harfe duyarlıdır ve yük büyük/küçük harfle eşleşmelidir. Telemetri filtreleri için bu, kasanın cihaz tarafından gönderilen telemetrideki büyük/küçük harfle eşleşmesi gerektiği anlamına gelir.

Portal

Olay yolu oluştururken olay filtresi eklemek için Olay yolu oluştur sayfasının Olay yolu filtresi ekleme bölümünü kullanın.

Bazı temel yaygın filtre seçenekleri arasından seçim yapabilir veya kendi özel filtrelerinizi yazmak için gelişmiş filtre seçeneklerini kullanabilirsiniz.

Temel filtreleri kullanma

Temel filtreleri kullanmak için Olay türleri seçeneğini genişletin ve uç noktanıza göndermek istediğiniz olaylara karşılık gelen onay kutularını seçin.

Bunu yaptığınızda, filtre metin kutusu seçtiğiniz filtrenin metniyle otomatik olarak doldurulur:

Gelişmiş filtreleri kullanma

Kendi özel filtrelerinizi yazmak için gelişmiş filtre seçeneğini de kullanabilirsiniz.

Gelişmiş filtre seçenekleriyle bir olay yolu oluşturmak için Gelişmiş düzenleyicinin anahtarını etkinleştirecek şekilde değiştirin. Ardından Filtre kutusuna kendi olay filtrelerinizi yazabilirsiniz:

API

Özel filtreler yazmak için Event Routes veri düzlemi API'lerini kullanabilirsiniz. Filtre eklemek için aşağıdaki gövdeye sahip bir PUT isteği https://<Your-Azure-Digital-Twins-host-name>/eventRoutes/<event-route-name>?api-version=2020-10-31 kullanabilirsiniz:

{
    "endpointName": "<endpoint-name>",
    "filter": "<filter-text>"
}

Desteklenen yol filtreleri

Desteklenen yol filtreleri aşağıdadır.

Filtre adı	Açıklama	Filtre metin şeması	Desteklenen değerler
Doğru / Yanlış	Hiçbir olay gönderilmemesi için filtreleme olmadan yol oluşturmaya veya bir yolu devre dışı bırakmaya izin verir	<true/false>	true = yol filtreleme olmadan etkinleştirildi false = yol devre dışı
Tür	Dijital ikiz örneğinizde akan olay türü	type = '<event-type>'	Olası olay türü değerleri şunlardır: Microsoft.DigitalTwins.Twin.Create Microsoft.DigitalTwins.Twin.Delete Microsoft.DigitalTwins.Twin.Update Microsoft.DigitalTwins.Relationship.Create Microsoft.DigitalTwins.Relationship.Update Microsoft.DigitalTwins.Relationship.Delete microsoft.iot.telemetry
Source	Azure Digital Twins örneğinin adı	source = '<host-name>'	Olası ana bilgisayar adı değerleri şunlardır: Bildirimler için: <your-Digital-Twins-instance>.api.<your-region>.digitaltwins.azure.net Telemetri için: <your-Digital-Twins-instance>.api.<your-region>.digitaltwins.azure.net/<twin-ID>
Subject	Yukarıdaki olay kaynağı bağlamında olayın açıklaması	subject = '<subject>'	Olası konu değerleri şunlardır: Bildirimler için: Konu şudur: <twin-ID> veya birden çok parça veya kimlikle benzersiz olarak tanımlanan konular için bir URI biçimi: <twin-ID>/relationships/<relationship-ID> Telemetri için: Konu, bileşen yoludur (telemetri bir ikiz bileşeninden yayılıyorsa), örneğin comp1.comp2. Telemetri bir bileşenden yayılmıyorsa, konu alanı boş olur.
Veri şeması	DTDL model kimliği	dataschema = '<model-dtmi-ID>'	Telemetri için: Veri şeması, ikizi veya telemetriyi yayan bileşenin model kimliğidir. Örneğin dtmi:example:com:floor4;2 Bildirimler için (oluşturma/silme): Veri şemasına adresinden $body.$metadata.$modelbildirim gövdesinde erişilebilir. Bildirimler için (güncelleştirme): Veri şemasına adresinden bildirim gövdesinden erişilebilir $body.modelId
Content type	Veri değerinin içerik türü	datacontenttype = '<content-type>'	İçerik türü: application/json
Belirtim sürümü	Kullandığınız olay şemasının sürümü	specversion = '<version>'	Sürüm olmalıdır 1.0. Bu değer, CloudEvents şemasının 1.0 sürümünü gösterir
Bildirim gövdesi	Bildirim alanındaki herhangi bir özelliğe data başvurma	$body.<property>	Bildirim örnekleri için bkz . Olay bildirimleri. alandaki herhangi bir özelliğe data kullanılarak başvurulabilir $body

Dekont

Azure Digital Twins şu anda bir dizideki alanlara göre olayları filtrelemeyi desteklememektedir. Bu, dijital ikiz değişiklik bildiriminin bir patch bölümündeki özelliklere göre filtrelemeyi içerir.

Aşağıdaki veri türleri, yukarıdaki verilere başvurular tarafından döndürülen değerler olarak desteklenir:

Veri türü	Örnek
String	STARTS_WITH($body.$metadata.$model, 'dtmi:example:com:floor') CONTAINS(subject, '<twin-ID>')
Tamsayı	$body.errorCode > 200
Çift	$body.temperature <= 5.5
Boole	$body.poweredOn = true
Boş	$body.prop != null

Yol filtreleri tanımlanırken aşağıdaki işleçler desteklenir:

Aile	İşleçler	Örnek
Mantıksal	VE, VEYA, ( )	(type != 'microsoft.iot.telemetry' OR datacontenttype = 'application/json') OR (specversion != '1.0')
Karşılaştırma	<, <=, >, >=, =, !=	$body.temperature <= 5.5

Yol filtreleri tanımlanırken aşağıdaki işlevler desteklenir:

İşlev	Açıklama	Örnek
STARTS_WITH(x,y)	Değer x dizesiyle ybaşlıyorsa true döndürür.	STARTS_WITH($body.$metadata.$model, 'dtmi:example:com:floor')
ENDS_WITH(x,y)	Değer x dizesiyle ybitiyorsa true döndürür.	ENDS_WITH($body.$metadata.$model, 'floor;1')
CONTAINS(x,y)	Değer x dizesini yiçeriyorsa true döndürür.	CONTAINS(subject, '<twin-ID>')

Bir filtre uyguladığınızda veya güncelleştirdiğinizde, değişikliğin veri işlem hattına yansıtılması birkaç dakika sürebilir.

Olay yollarını izleme

Sayı, gecikme süresi ve hata oranı gibi yönlendirme ölçümleri Azure portalında görüntülenebilir.

Azure İzleyici ile ölçümleri görüntüleme ve yönetme hakkında bilgi için bkz . Ölçüm gezginini kullanmaya başlama. Azure Digital Twins için kullanılabilen yönlendirme ölçümlerinin tam listesi için bkz . Azure Digital Twins yönlendirme ölçümleri.

Sonraki adımlar

Alabileceğiniz farklı olay iletisi türleri hakkında bilgi edinin:

• Olay bildirimleri