Azure Time Series Insights 1. Nesil Başvuru Verileri API'si

Bu makalede, bir başvuru veri kümesindeki öğeleri yönetmek için kullanılan Azure Time Series Insights 1. Nesil Başvuru Veri Yönetimi API'si açıklanmaktadır. Başvuru veri kümesinin ortamda zaten oluşturulduğunu varsayar.

Başvuru verileri, nadiren değişen üretici veya konum verilerini içerir. Başvuru verileri, telemetri verilerini bağlamsal hale getirmek için kullanılır ve telemetri verilerini karşılaştırmaya hizmet eder.

Veri kümeleri önceden var olduğundan ve düzeltildiğinden, bir cihaz tarafından gönderilen her veri paketi aynı bilgileri içerir. Sonuç olarak, başvuru verileri cihazlardan gönderilmez ve Başvuru Veri Yönetimi API'sini veya Azure portal kullanarak verileri yönetirsiniz.

API’ye genel bakış

Başvuru Veri Yönetimi API'si bir toplu iş API'sidir.

Geçerli JSON isteği işlemi özellik adları şunlardır:

• Koymak
• Patch
• Özellikleri silme
• Silme
• Al

Başvuru verisi öğelerini yerleştirme

Başvuru veri öğesinin $.put[i] tamamını (dizideki i^. öğe, anahtar koyarak) ekler veya değiştirir. İşleme $.put[i]. birimi, İşlem bir kez etkili olur.

• Uç nokta ve işlem:

  POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12
  

• İstek gövdesi örneği:

  {
    "put": [{
      "deviceId": "Fan1",
      "color": "Red",
      "maxSpeed": 5
    },
    {
      "deviceId": "Fan2",
      "color": "White",
      "floor": 2
    }]
  }
  

• Yanıt örneği:

  {
    "put": [
      null,
      null
    ]
  }
  

Başvuru veri öğelerine düzeltme eki uygulama

Güncelleştirmeler ve başvuru veri öğesi $.patch[i]için belirli özellikler ekler.

• Uç nokta ve işlem:

  POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12
  

• İstek gövdesi örneği:

  {
    "patch": [
      {
        "deviceId": "Fan1",
        "maxSpeed": 108
      },
      {
        "deviceId": "Fan2",
        "floor": 18
      }
    ]
  }
  

• Yanıt gövdesi örneği:

  {
    "patch": [
      null,
      null
    ]
  }
  

Başvuru veri öğelerindeki özellikleri silme

Belirtilen özellikleri başvuru veri öğesinden $.deleteproperties[i]siler.

• Uç nokta ve işlem:

  POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12
  

• İstek gövdesi örneği:

  {
    "deleteProperties":[
      {
        "key":{
          "deviceId":"Fan2"
        },
        "properties":[
          "floor"
        ]
      }
    ]
  }
  

• Yanıt gövdesi örneği:

  {
    "deleteProperties": [
      null
    ]
  }
  

Başvuru veri öğelerini silme

Her $.delete[i]birinde belirtilen anahtar özellik değerleriyle tanımlanan başvuru veri öğesinin tamamını siler.

• Uç nokta ve işlem:

  POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12
  

• İstek gövdesi örneği:

  {
    "delete": [{
      "deviceId": "Fan1"
    }]
  }
  

• Yanıt gövdesi örneği:

  {
    "delete": [
      null
    ]
  }
  

Başvuru veri öğelerini alma

Her $.get[i]birinde belirtilen anahtar özellik değerleriyle tanımlanan başvuru veri öğesinin tamamını alır.

• Uç nokta ve işlem:

  POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12
  

• İstek gövdesi örneği:

  {
    "get": [{
      "deviceId": "Fan1"
    },
    {
      "deviceId": "Fan2"
    }]
  }
  

• Yanıt gövdesi örneği:

  {
    "get": [
      {
        "code": "InvalidInput",
        "message": "Key not found.",
        "target": null,
        "details": null,
        "innerError": null
      },
      {
        "id": "Fan2",
        "floor": 18
      }
    ]
  }
  

Doğrulama ve hata işleme

Başvuru Veri Yönetimi API'si her öğeyi ayrı ayrı işler ve bir öğeyle ilgili bir hata diğerlerinin başarıyla yazılmasını engellemez. Örneğin, isteğinizde 100 öğe varsa ve bir öğede hata varsa, 99 öğe yazılır ve biri reddedilir.

Öğe hata kodları

Öğe hata kodları, HTTP durum kodu 200 olan başarılı bir JSON yanıt gövdesinde oluşur.

• InvalidInput: Anahtar bulunamadı.: Sorgulanan öğenin başvuru veri kümesinde bulunamadığını gösterir.

  {
    "code": "InvalidInput",
    "message": "Key not found.",
    "target": null,
    "details": null,
    "innerError": null
  }
  

• InvalidInput: Payload anahtarı anahtar olmayan bir özellik içermemelidir.: JSON istek gövdesi sorgu öğelerinin anahtar özellikleri (başvuru kümesi şemasında belirtilen özellikler) olmayan hiçbir özellik içermemesi gerektiğini gösterir. Anahtar özellikler Azure portal bulunabilir.

  {
    "code": "InvalidInput",
    "message": "Payload key should not contain any non-key property.",
    "target": null,
    "details": null,
    "innerError": null
  }
  

• InvalidInput: Payload öğesi tüm anahtar özelliklerini içermelidir.: JSON istek gövdesi sorgu öğelerinin tüm anahtar özelliklerini (başvuru kümesi şemasında belirtilen özellikler) içermesi gerektiğini gösterir. Anahtar özellikleri Azure portal bulunabilir.

  {
    "code": "InvalidInput",
    "message": "Payload item should contain all key properties.",
    "target": null,
    "details": null,
    "innerError": null
  }
  

Başvuru verileri birleştirme örneği

Aşağıdaki yapıya sahip bir olay hub'ı iletisi düşünün:

[
  {
    "deviceId":"Fan1",
    "timestamp":"1/5/2015T00:10:30Z"
  },
  {
    "deviceId":"Fan2",
    "timestamp":"1/5/2015T00:10:30Z"
  }
]

String türünde name contoso ve key deviceId değeriyle ayarlanmış ve aşağıdaki yapıya sahip bir başvuru veri öğesi düşünün:

Olay hub'ı iletisindeki iki olay Azure Time Series Insights 1. Nesil giriş altyapısı tarafından işlendiğinde, bunlar doğru başvuru veri öğesiyle birleştirilir. Olay çıktısı aşağıdaki yapıya sahiptir:

[
  {
    "deviceId":"Fan1",
    "timestamp":"1/5/2015T00:10:30Z",
    "color":"Red",
    "maxSpeed":5
  },
  {
    "deviceId":"Fan2",
    "timestamp":"1/5/2015T00:10:30Z",
    "color":"White",
    "floor":2
  }
]

Kuralları ve semantiği birleştirme

Başvuru verilerini birleştirirken aşağıdaki kısıtlamalara uyun:

• Anahtar adı karşılaştırması büyük/küçük harfe duyarlıdır.
• Anahtar değeri karşılaştırması, dize özellikleri için büyük/küçük harfe duyarlıdır.

Birden fazla başvuru veri kümesine sahip ortamlar için birleştirmeler sırasında üç kısıtlama daha uygulanır:

• Bir başvuru veri kümesindeki her öğe kendi anahtar olmayan özellikler listesini belirtebilir.
• A ve B iki başvuru veri kümesi için anahtar olmayan özelliklerin kesişmemesi gerekir.
• Başvuru veri kümeleri yalnızca olaylara doğrudan katılır, hiçbir zaman diğer başvurulmuş veri kümelerine (ve ardından olaylara) katılmaz. Bir başvuru veri öğesini bir olaya eklemek için, başvuru veri öğesinde kullanılan tüm anahtar özelliklerin olayda mevcut olması gerekir. Ayrıca, anahtar özellikleri başka bir başvuru veri öğesi aracılığıyla bir olaya katılmış anahtar olmayan özelliklerden gelmemelidir.

Bu kısıtlamalar göz önüne alındığında, birleştirme altyapısı birleştirmeyi belirli bir olay için herhangi bir sırada uygulayabilir. Hiyerarşi ve sıralama dikkate alınmaz.

Geçerli sınırlar

Azure Time Series Insights 1. Nesil ortamı başına en fazla iki başvuru veri kümesi ekleyebilirsiniz. Azure Time Series Insights 1. Nesil başvuru verileriyle ilişkili ek sınırlamalar aşağıdaki tabloda listelenmiştir:

Ayrıca bkz.

Uygulama kaydı ve Azure Active Directory programlama modeli hakkında daha fazla bilgi için bkz. Geliştiriciler için Azure Active Directory.

İstek ve kimlik doğrulama parametreleri hakkında bilgi edinmek için bkz. Kimlik doğrulaması ve yetkilendirme.

HTTP isteklerini ve yanıtlarını test etme konusunda yardımcı olan araçlar şunlardır:

• Fiddler. Bu ücretsiz web hata ayıklama proxy'si REST isteklerinizi kesebilir, böylece HTTP isteğini ve yanıt iletilerini tanılayabilirsiniz.
• JWT.io. Bu aracı kullanarak talepleri taşıyıcı belirtecinize hızla atabilir ve ardından içeriklerini doğrulayabilirsiniz.
• Postacı. Bu, REST API'lerinde hata ayıklamaya yönelik ücretsiz bir HTTP isteği ve yanıt testi aracıdır.

1. Nesil belgelerini gözden geçirerek Azure Time Series Insights 1. Nesil hakkında daha fazla bilgi edinin.