IoT verilerini Web Kancası'na aktarma

Bu makalede, Web Kancası'na veri göndermek için veri dışarı aktarmanın nasıl yapılandırıldığı açıklanır.

Filtrelenmiş ve zenginleştirilmiş IoT verilerini IoT Central uygulamanızdan sürekli olarak dışarı aktarmak için bu özelliği kullanın. Veri dışarı aktarma, sıcak yol içgörüleri, analiz ve depolama için değişiklikleri neredeyse gerçek zamanlı olarak bulut çözümünüzün diğer bölümlerine iletir.

Örneğin, şunları yapabilirsiniz:

• Telemetri verilerini, özellik değişikliklerini, cihaz bağlantısını, cihaz yaşam döngüsünü, cihaz şablonu yaşam döngüsünü ve denetim günlüğü verilerini JSON biçiminde neredeyse gerçek zamanlı olarak sürekli dışarı aktarın.
• Özel koşullarla eşleşen verileri dışarı aktarmak için veri akışlarını filtreleyin.
• Veri akışlarını cihazdan özel değerler ve özellik değerleriyle zenginleştirin.
• Şekillerini ve içeriklerini değiştirmek için veri akışlarını dönüştürün.

İpucu

Veri dışarı aktarmayı açtığınızda, yalnızca o andan itibaren verileri alırsınız. Daha fazla geçmiş veri saklamak için veri dışarı aktarmayı erken açın. Verileri dışarı aktarmanın kapalı olduğu zamanlardan el ile dışarı aktarmak için bkz . Cihazları sorgulamak için IoT Central REST API'sini kullanma.

Not

Bazı durumlarda iletilerin dışarı aktarılması 60 saniye kadar sürebilir. Bu süre, IoT Central'ın temel alınan IoT hub'ından iletiyi aldığından iletinin hedef uç noktaya teslim edildiğinden ölçülür.

Önkoşullar

Veri dışarı aktarma özelliklerini kullanmak için Veri dışarı aktarma iznine sahip olmanız gerekir.

Web kancası dışarı aktarma hedefi ayarlama

Web kancası hedefleri için IoT Central verileri neredeyse gerçek zamanlı olarak dışarı aktarır. İleti gövdesindeki veriler Event Hubs ve Service Bus ile aynı biçimdedir.

Web kancası hedefi oluşturma

Verileri genel kullanıma açık bir HTTP Web kancası uç noktasına aktarabilirsiniz. RequestBin kullanarak test Web kancası uç noktası oluşturabilirsiniz. İstek sınırına ulaşıldığında RequestBin isteği kısıtlar:

1. RequestBin'e gidin.

2. RequestBin Oluştur'u seçin.

3. Kullanılabilir yöntemlerden biriyle oturum açın.

4. RequestBin'inizin URL'sini kopyalayın Verilerinizi dışarı aktarmayı test ederken bu URL'yi kullanırsınız.

Veri dışarı aktarma sayfasında IoT Central'da Azure Veri Gezgini hedefini oluşturmak için:

1. + Yeni hedef'i seçin.

2. Hedef türü olarak Web kancası'nı seçin.

3. Web kancası uç noktanız için geri çağırma URL'sini yapıştırın. İsteğe bağlı olarak Web kancası yetkilendirmesini yapılandırabilir ve özel üst bilgiler ekleyebilirsiniz.

   • OAuth2.0 için yalnızca istemci kimlik bilgileri verme akışı desteklenir. Hedefi kaydettiğinizde IoT Central, yetkilendirme belirtecini almak için OAuth sağlayıcınızla iletişim kurar. Bu belirteç, bu hedefe gönderilen her iletinin üst bilgisine eklenir Authorization .
   • Yetkilendirme belirteci için, bu hedefe gönderilen her ileti için doğrudan üst bilgisine Authorization eklenmiş bir belirteç değeri belirtebilirsiniz.

4. Kaydet'i seçin.

Örnek OAuth 2.0 yapılandırması

Bu örnekte, Bir Web Kancası hedefini Microsoft Entra oturum açma özelliği kullanılarak korunan bir Azure İşlev Uygulaması kullanacak şekilde yapılandırma adımları gösterilmektedir:

Ayar	Örnek	Notlar
Hedef türü	Web kancası
Geri arama URL'si	https://myapp.azurewebsites.net/api/HttpExample	İşlev URL'si.
Yetkilendirme	OAuth 2.0
Belirteç URL'si	https://login.microsoftonline.com/your-tenant-id/oauth2/v2.0/token	Belirteç almak için kullanılacak URL. Bu değeri İşlev Uygulamanızda bulabilirsiniz: Kimlik Doğrulaması > Microsoft Kimlik sağlayıcınızın > Uç Noktaları > OAuth 2.0 belirteç uç noktası (v2)
Client ID	your-client-id	İşlev Uygulamanızın istemci kimliği. Bu değeri İşlev Uygulamanızda bulabilirsiniz: Microsoft Kimlik sağlayıcı > uygulamanızın (istemci) kimliğini doğrulama >
İstemci gizli anahtarı	your-client-secret	İşlev Uygulamanızın istemci gizli dizisi. Bu değeri İşlev Uygulamanızda bulabilirsiniz: Kimlik Doğrulama > Microsoft Kimlik sağlayıcınız sertifikalar > ve gizli diziler
Hedef Kitle	Yok	İşlev Uygulaması kullanıyorsanız boş.
Kapsam	https://your-client-id/.default	Belirtecin kapsamı. İşlev Uygulaması için istemci kimliği değerini kullanın.**
Belirteç isteği içerik türü	Auto

Diğer web kancası hedefleri bu ayarlar için farklı değerler gerektirebilir.

Veri dışarı aktarmayı ayarlama

Artık verilerinizi dışarı aktarma hedefiniz olduğuna göre IoT Central uygulamanızda veri dışarı aktarmayı ayarlayın:

1. IoT Central uygulamanızda oturum açın.

2. Sol bölmede Veri dışarı aktarma'yı seçin.

   İpucu

   Sol bölmede Veri dışarı aktarma seçeneğini görmüyorsanız, uygulamanızda veri dışarı aktarmayı yapılandırma izniniz yoktur. Veri dışarı aktarmayı ayarlamak için bir yöneticiyle görüşün.

3. + Yeni dışarı aktarma'ya tıklayın.

4. Yeni dışarı aktarmanız için bir görünen ad girin ve veri dışarı aktarmanın Etkin olduğundan emin olun.

5. Dışarı aktaracak veri türünü seçin. Aşağıdaki tabloda desteklenen veri dışarı aktarma türleri listelenmektedir:

   Veri türü	Açıklama	Veri biçimi
   Telemetri	Cihazlardan telemetri iletilerini neredeyse gerçek zamanlı olarak dışarı aktarın. Dışarı aktarılan her ileti, normalleştirilmiş özgün cihaz iletisinin tam içeriğini içerir.	Telemetri ileti biçimi
   Özellik değişiklikleri	Cihaz ve bulut özelliklerindeki değişiklikleri neredeyse gerçek zamanlı olarak dışarı aktarın. Salt okunur cihaz özellikleri için, bildirilen değerlerde yapılan değişiklikler dışarı aktarılır. Okuma-yazma özellikleri için hem bildirilen hem de istenen değerler dışarı aktarılır.	Özellik değişikliği ileti biçimi
   Cihaz bağlantısı	Cihaz bağlı ve bağlantısı kesilmiş olayları dışarı aktarın.	Cihaz bağlantısı ileti biçimi
   Cihaz yaşam döngüsü	Kayıtlı, silinmiş, sağlanan, etkin, devre dışı, displayNameChanged ve deviceTemplateChanged olaylarını dışarı aktarın.	Cihaz yaşam döngüsü ileti biçimini değiştirir
   Cihaz şablonu yaşam döngüsü	Oluşturulan, güncelleştirilen ve silinenler de dahil olmak üzere yayımlanan cihaz şablonu değişikliklerini dışarı aktarın.	Cihaz şablonu yaşam döngüsü ileti biçimini değiştirir
   Denetim günlükleri	Uygulamadaki varlıklar için kullanıcı tarafından başlatılan güncelleştirmelerin günlükleri. Daha fazla bilgi edinmek için bkz . IoT Central uygulamanızdaki etkinlikleri izlemek için denetim günlüklerini kullanma	Denetim günlüğü ileti biçimi

6. İsteğe bağlı olarak, dışarı aktarılan veri miktarını azaltmak için filtreler ekleyin. Her veri dışarı aktarma türü için farklı filtre türleri vardır:

   Veri türü	Kullanılabilir filtreler
   Telemetri	Cihaz adına, cihaz kimliğine, cihaz şablonuna ve cihazın simülasyonu yapılmışsa göre filtreleyin Akışı yalnızca filtre koşullarına uyan telemetri verilerini içerecek şekilde filtreleyin Akışı yalnızca filtre koşullarıyla eşleşen özelliklere sahip cihazlardan telemetri içerecek şekilde filtreleyin Akışı yalnızca filtre koşuluna göre ileti özelliklerine sahip telemetriyi içerecek şekilde filtreleyin. İleti özellikleri (uygulama özellikleri olarak da bilinir) her telemetri iletisindeki anahtar-değer çiftleri paketinde gönderilir. İleti özelliği filtresi oluşturmak için, aradığınız ileti özellik anahtarını girin ve bir koşul belirtin. Yalnızca belirtilen filtre koşuluyla eşleşen özelliklere sahip telemetri iletileri dışarı aktarılır. IoT Hub belgelerinden uygulama özellikleri hakkında daha fazla bilgi edinin
   Özellik değişiklikleri	Cihaz adına, cihaz kimliğine, cihaz şablonuna ve cihazın simülasyonu yapılmışsa göre filtreleyin Akışı yalnızca filtre koşullarına uyan özellik değişikliklerini içerecek şekilde filtreleyin
   Cihaz bağlantısı	Cihaz adına, cihaz kimliğine, cihaz şablonuna, kuruluşlara ve cihazın simülasyonu yapılmışsa göre filtreleyin Akışı yalnızca filtre koşullarıyla eşleşen özelliklere sahip cihazlardan gelen değişiklikleri içerecek şekilde filtreleyin
   Cihaz yaşam döngüsü	Cihaz adına, cihaz kimliğine, cihaz şablonuna ve cihazın sağlanıp sağlanmadığını, etkinleştirildiğini veya simülasyonu yapılmış olup olmadığını filtreleyin Akışı yalnızca filtre koşullarıyla eşleşen özelliklere sahip cihazlardan gelen değişiklikleri içerecek şekilde filtreleyin
   Cihaz şablonu yaşam döngüsü	Cihaz şablonuna göre filtrele
   Denetim günlükleri	Yok

7. İsteğe bağlı olarak, dışarı aktarılan iletileri ek anahtar-değer çifti meta verileriyle zenginleştirin. Telemetri, özellik değişiklikleri, cihaz bağlantısı ve cihaz yaşam döngüsü veri dışarı aktarma türleri için aşağıdaki zenginleştirmeler kullanılabilir:

   • Özel dize: Her iletiye özel bir statik dize ekler. Herhangi bir anahtar girin ve herhangi bir dize değeri girin.
   • Her iletiye eklenen özellik:
     • Cihaz adı, cihaz şablonu adı, etkin, kuruluşlar, sağlanan ve simülasyon gibi cihaz meta verileri.
     • Her ileti için bildirilen geçerli cihaz özelliği veya bulut özelliği değeri. Dışarı aktarılan ileti belirtilen özelliğe sahip olmayan bir cihazdan geliyorsa, dışarı aktarılan ileti zenginleştirmeyi almaz.

Dışarı aktarma hedefini yapılandırın:

1. Önceden oluşturduğunuz bir hedefi eklemek için + Hedef'i seçin veya Yeni bir hedef oluştur'u seçin.

2. Verilerinizi dışarı aktarmadan önce dönüştürmek için + Dönüştür'ü seçin. Daha fazla bilgi edinmek için bkz . Dışarı aktarma için IoT Central uygulamanızın içindeki verileri dönüştürme.

3. Tek bir dışarı aktarmaya en fazla beş hedef eklemek için + Hedef'i seçin.

4. Dışarı aktarmanızı ayarlamayı bitirdiğinizde Kaydet'i seçin. Birkaç dakika sonra verileriniz hedeflerinizde görünür.

Dışarı aktarmanızı izleme

IoT Central'da Veri dışarı aktarma sayfası, dışarı aktarmalarınızın durumunu denetlemenize olanak tanır. Ne kadar veri dışarı aktardığınızı ve dışarı aktarma hatalarını görmek için Azure İzleyici'yi de kullanabilirsiniz. PowerShell'deki sorguları veya Azure CLI'yı kullanarak Azure portalındaki grafiklerde dışarı aktarma ve cihaz durumu ölçümlerine erişebilirsiniz. Şu anda Azure İzleyici'de aşağıdaki veri dışarı aktarma ölçümlerini izleyebilirsiniz:

• Filtreler uygulanmadan önce dışarı aktarılması gereken ileti sayısı.
• Filtrelerden geçen ileti sayısı.
• Hedeflere başarıyla dışarı aktarılan ileti sayısı.
• Bulunan hata sayısı.

Daha fazla bilgi edinmek için bkz . Uygulama durumunu izleme.

Veri biçimleri

Aşağıdaki bölümlerde dışarı aktarılan verilerin biçimleri açıklanmaktadır:

Telemetri biçimi

Dışarı aktarılan her ileti, cihazın ileti gövdesinde gönderdiği iletinin tamamının normalleştirilmiş bir biçimini içerir. İleti JSON biçimindedir ve UTF-8 olarak kodlanmıştır. Her iletideki bilgiler şunları içerir:

• applicationId: IoT Central uygulamasının kimliği.
• messageSource: İletinin kaynağı - telemetry.
• deviceId: Telemetri iletisini gönderen cihazın kimliği.
• schema: Yük şemasının adı ve sürümü.
• templateId: Cihaza atanan cihaz şablonunun kimliği.
• enqueuedTime: IoT Central'ın bu iletiyi aldığı saat.
• enrichments: Dışarı aktarmada ayarlanan tüm zenginleştirmeler.
• module: Bu iletiyi gönderen IoT Edge modülü. Bu alan yalnızca ileti bir IoT Edge modülünden geliyorsa görünür.
• component: Bu iletiyi gönderen bileşen. Bu alan yalnızca iletide gönderilen özellikler cihaz şablonunda bir bileşen olarak modellenmişse görüntülenir
• messageProperties: Cihazın iletiyle gönderdiği diğer özellikler. Bu özellikler bazen uygulama özellikleri olarak adlandırılır. IoT Hub belgelerinden daha fazla bilgi edinin.

İleti özellikleri

Telemetri iletileri hem meta veriler hem de telemetri yükü için özelliklere sahiptir. Önceki kod parçacığı ve gibi deviceIdenqueuedTimesistem iletilerinin örneklerini gösterir. Sistem iletisi özellikleri hakkında daha fazla bilgi edinmek için bkz . D2C IoT Hub iletilerinin Sistem Özellikleri.

Telemetri iletilerinize özel meta veriler eklemeniz gerekiyorsa telemetri iletilerine özellikler ekleyebilirsiniz. Örneğin, cihaz iletiyi oluştururken bir zaman damgası eklemeniz gerekir.

Aşağıdaki kod parçacığı, cihazda oluşturduğunuzda özelliğin iletiye nasıl ekleneceğini iothub-creation-time-utc gösterir:

Önemli

Bu zaman damgasının biçimi saat dilimi bilgisi olmadan UTC olmalıdır. Örneğin, 2021-04-21T11:30:16Z geçerli, 2021-04-21T11:30:16-07:00 geçersiz.

JavaScript

async function sendTelemetry(deviceClient, index) {
  console.log('Sending telemetry message %d...', index);
  const msg = new Message(
    JSON.stringify(
      deviceTemperatureSensor.updateSensor().getCurrentTemperatureObject()
    )
  );
  msg.properties.add("iothub-creation-time-utc", new Date().toISOString());
  msg.contentType = 'application/json';
  msg.contentEncoding = 'utf-8';
  await deviceClient.sendEvent(msg);
}

Java

private static void sendTemperatureTelemetry() {
  String telemetryName = "temperature";
  String telemetryPayload = String.format("{\"%s\": %f}", telemetryName, temperature);

  Message message = new Message(telemetryPayload);
  message.setContentEncoding(StandardCharsets.UTF_8.name());
  message.setContentTypeFinal("application/json");
  message.setProperty("iothub-creation-time-utc", Instant.now().toString());

  deviceClient.sendEventAsync(message, new MessageIotHubEventCallback(), message);
  log.debug("My Telemetry: Sent - {\"{}\": {}°C} with message Id {}.", telemetryName, temperature, message.getMessageId());
  temperatureReadings.put(new Date(), temperature);
}

C#

private async Task SendTemperatureTelemetryAsync()
{
  const string telemetryName = "temperature";

  string telemetryPayload = $"{{ \"{telemetryName}\": {_temperature} }}";
  using var message = new Message(Encoding.UTF8.GetBytes(telemetryPayload))
  {
      ContentEncoding = "utf-8",
      ContentType = "application/json",
  };
  message.Properties.Add("iothub-creation-time-utc", DateTime.UtcNow.ToString("yyyy-MM-ddTHH:mm:ssZ"));
  await _deviceClient.SendEventAsync(message);
  _logger.LogDebug($"Telemetry: Sent - {{ \"{telemetryName}\": {_temperature}°C }}.");
}

Python

async def send_telemetry_from_thermostat(device_client, telemetry_msg):
    msg = Message(json.dumps(telemetry_msg))
    msg.custom_properties["iothub-creation-time-utc"] = datetime.now(timezone.utc).isoformat()
    msg.content_encoding = "utf-8"
    msg.content_type = "application/json"
    print("Sent message")
    await device_client.send_message(msg)

Özellik değişiklikleri biçimi

Her ileti veya kayıt, cihaz ve bulut özelliklerindeki değişiklikleri temsil eder. Dışarı aktarılan iletideki bilgiler şunları içerir:

• applicationId: IoT Central uygulamasının kimliği.
• messageSource: İletinin kaynağı - properties.
• messageType: , cloudPropertyChangedevicePropertyDesiredChangeveya devicePropertyReportedChange.
• deviceId: Telemetri iletisini gönderen cihazın kimliği.
• schema: Yük şemasının adı ve sürümü.
• enqueuedTime: IoT Central'ın bu değişikliği algıladığı saat.
• templateId: Cihaza atanan cihaz şablonunun kimliği.
• properties: Değişen özelliklerin ve değerlerin adları da dahil olmak üzere değişen özellikler dizisi. Özellik bir bileşen veya IoT Edge modülü içinde modellenmişse bileşen ve modül bilgileri dahil edilir.
• enrichments: Dışarı aktarmada ayarlanan tüm zenginleştirmeler.

Cihaz bağlantısı değişiklikleri biçimi

Her ileti veya kayıt, tek bir cihazdan gelen bir bağlantı olayını temsil eder. Dışarı aktarılan iletideki bilgiler şunları içerir:

• applicationId: IoT Central uygulamasının kimliği.
• messageSource: İletinin kaynağı - deviceConnectivity.
• messageTypeconnected: veya disconnected.
• deviceId: Değiştirilen cihazın kimliği.
• schema: Yük şemasının adı ve sürümü.
• templateId: Cihaza atanan cihaz şablonunun kimliği.
• enqueuedTime: Bu değişikliğin IoT Central'da gerçekleştiği saat.
• enrichments: Dışarı aktarmada ayarlanan tüm zenginleştirmeler.

Cihaz yaşam döngüsü değişiklikleri biçimi

Her ileti veya kayıt, tek bir cihazda yapılan bir değişikliği temsil eder. Dışarı aktarılan iletideki bilgiler şunları içerir:

• applicationId: IoT Central uygulamasının kimliği.
• messageSource: İletinin kaynağı - deviceLifecycle.
• messageType: Oluşan değişikliğin türü. Bunlardan biri: registered, deleted, provisioned, enabled, disabled, , displayNameChangedve deviceTemplateChanged.
• deviceId: Değiştirilen cihazın kimliği.
• schema: Yük şemasının adı ve sürümü.
• templateId: Cihaza atanan cihaz şablonunun kimliği.
• enqueuedTime: Bu değişikliğin IoT Central'da gerçekleştiği saat.
• enrichments: Dışarı aktarmada ayarlanan tüm zenginleştirmeler.

Cihaz şablonu yaşam döngüsü değişiklikleri biçimi

Her ileti veya kayıt, yayımlanmış tek bir cihaz şablonunda yapılan bir değişikliği temsil eder. Dışarı aktarılan iletideki bilgiler şunları içerir:

• applicationId: IoT Central uygulamasının kimliği.
• messageSource: İletinin kaynağı - deviceTemplateLifecycle.
• messageType: , createdupdatedveya deleted.
• schema: Yük şemasının adı ve sürümü.
• templateId: Cihaza atanan cihaz şablonunun kimliği.
• enqueuedTime: Bu değişikliğin IoT Central'da gerçekleştiği saat.
• enrichments: Dışarı aktarmada ayarlanan tüm zenginleştirmeler.

Denetim günlüğü biçimi

Her denetim günlüğü iletisi, IoT Central uygulamasının içindeki denetlenebilir bir varlıkta kullanıcı tarafından başlatılan bir değişikliği temsil eder. Dışarı aktarılan iletideki bilgiler şunları içerir:

• actor: Varlığı değiştiren kullanıcı hakkındaki bilgiler.
• applicationId: IoT Central uygulamasının kimliği.
• messageSource: İletinin kaynağı - audit.
• messageType: Oluşan değişikliğin türü. Bunlardan biri: updated, created, deleted.
• updated: Yalnızca ise messageType mevcuttur updated. Güncelleştirme hakkında daha fazla ayrıntı sağlar.
• resource: Değiştirilen varlığın ayrıntıları.
• schema: Yük şemasının adı ve sürümü.
• deviceId: Değiştirilen cihazın kimliği.
• enqueuedTime: Bu değişikliğin IoT Central'da gerçekleştiği saat.
• enrichments: Dışarı aktarmada ayarlanan tüm zenginleştirmeler.

Sonraki adımlar

Service Bus'a nasıl aktaracağınızı bildiğinize göre, önerilen bir sonraki adım Event Hubs'a aktarmayı öğrenmektir.