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

Makale
07/19/2023

Dikkat

Bu bir Gen1 makalesi.

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.

İpucu

Başvuru veri kümesi oluşturmak için bkz. Başvuru veri kümesi oluşturma.

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.

Önemli

Bu API'ye yönelik tüm işlemler HTTP POST işlemleridir.
Her işlem JSON nesnelerini istek yükü olarak kabul eder.
HTTP isteği JSON nesneleri, API tarafından yürütülecek işlemi belirten tek bir özellik adı tanımlar.

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

Koymak
Patch
Özellikleri silme
Silme
Al

Önemli

Özellik değeri, işlemin uygulanması gereken bir başvuru veri öğeleri dizisidir.
Her öğe ayrı ayrı işlenir 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.
Başvuru veri öğeleri, tam olarak numaralandırılmış anahtar özellikleri kullanılarak sorgulanır.

Not

Aşağıdaki tüm JSON gövde örnekleri , deviceId adlı ve String türündeki tek bir özellik anahtarına sahip bir başvuru veri kümesi olduğunu varsayar.

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:

deviceId	color	Maxspeed	Kat
Fan1	Kırmızı	5
Fan2	Beyaz		2

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:

Sınır adı	Sınır değeri	Etkilenen SKU'lar	Notlar
Anahtar özellik sayısı	3	S1, S2	Başvuru veri kümesi başına; Yalnızca Azure Resource Manager ve Azure portal
Anahtar özellik boyutu	1 KB	S1, S2	Başvuru veri kümesi başına
Başvuru veri öğesi sayısı	2.000/20.000 (S1/S2)	S1, S2	Birim başına; Örneğin, 4 birim S1 SKU = 8.000 öğe (4 x 2.000)
En fazla eşzamanlı işlem	2/10 (S1/S2)	S1, S2
Maksimum başvuru verisi işlemleri	120/600 (S1/S2)	S1, S2	Saatte
En fazla başvuru verisi öğesi sayısı	1.000	S1, S2	İşlem başına
Maksimum başvuru veri öğesi boyutu	8.192 KB	S1, S2	İşlem başına

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.

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

API’ye genel bakış

Başvuru verisi öğelerini yerleştirme

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

Başvuru veri öğelerindeki özellikleri silme

Başvuru veri öğelerini silme

Başvuru veri öğelerini alma

Doğrulama ve hata işleme

Öğe hata kodları

Başvuru verileri birleştirme örneği

Kuralları ve semantiği birleştirme

Geçerli sınırlar

Ayrıca bkz.

Ek kaynaklar