API Data Referensi Azure Time Series Insights Gen1

Artikel
07/19/2023

Perhatian

Ini adalah artikel Gen1.

Artikel ini menjelaskan Azure Time Series Insights Api Manajemen Data Referensi Gen1 yang digunakan untuk mengelola item dalam himpunan data referensi. Ini mengasumsikan bahwa himpunan data referensi telah dibuat dalam lingkungan.

Data referensi mencakup data produsen atau lokasi yang jarang berubah. Data referensi digunakan untuk mengonteksualisasikan data telemetri dan berfungsi untuk membandingkan data telemetri.

Tip

Untuk membuat himpunan data referensi, lihat Cara membuat himpunan data referensi.

Karena himpunan data sudah ada sebelumnya dan diperbaiki, setiap paket data yang dikirim oleh perangkat akan berisi informasi yang identik. Akibatnya, data referensi tidak dikirim dari perangkat, dan Anda mengelola data dengan menggunakan API Manajemen Data Referensi atau portal Azure.

Ringkasan API

API Manajemen Data Referensi adalah API batch.

Penting

Semua operasi terhadap API ini adalah operasi HTTP POST.
Setiap operasi menerima objek JSON sebagai payload permintaan.
Objek JSON permintaan HTTP menentukan satu nama properti yang menentukan operasi yang akan dijalankan oleh API.

Nama properti operasi permintaan JSON yang valid adalah:

Menempatkan
Patch
Hapus properti
Hapus
Dapatkan

Penting

Nilai properti adalah array item data referensi tempat operasi harus diterapkan.
Setiap item diproses satu per satu, dan kesalahan dengan satu item tidak mencegah yang lain berhasil ditulis. Misalnya, jika permintaan Anda memiliki 100 item dan satu item memiliki kesalahan, 99 item ditulis dan satu ditolak.
Item data referensi dikueri menggunakan properti kunci yang sepenuhnya dijumlahkan.

Catatan

Semua contoh isi JSON berikut mengasumsikan himpunan data referensi dengan satu kunci properti dengan nama deviceId dan jenis String.

Letakkan item data referensi

Menyisipkan atau mengganti seluruh item $.put[i] data referensi (item i^th dalam array dengan tombol put). Unit penerapan adalah $.put[i]. Operasinya idempotensi.

Titik akhir dan operasi:

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

Contoh isi permintaan:

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

Contoh respons:
```
{
  "put": [
    null,
    null
  ]
}
```

Item data referensi patch

Updates dan menyisipkan properti tertentu untuk item $.patch[i]data referensi .

Titik akhir dan operasi:

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

Contoh isi permintaan:

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

Contoh badan respons:

{
  "patch": [
    null,
    null
  ]
}

Menghapus properti dalam item data referensi

Menghapus properti yang ditentukan dari item $.deleteproperties[i]data referensi .

Titik akhir dan operasi:

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

Contoh isi permintaan:

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

Contoh badan respons:

{
  "deleteProperties": [
    null
  ]
}

Menghapus item data referensi

Menghapus seluruh item data referensi yang diidentifikasi oleh nilai properti kunci yang ditentukan di setiap $.delete[i].

Titik akhir dan operasi:

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

Contoh isi permintaan:

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

Contoh badan respons:
```
{
  "delete": [
    null
  ]
}
```

Mendapatkan item data referensi

Mendapatkan seluruh item data referensi yang diidentifikasi oleh nilai properti kunci yang ditentukan di setiap $.get[i].

Titik akhir dan operasi:

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

Contoh isi permintaan:

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

Contoh badan respons:

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

Validasi dan penanganan kesalahan

API Manajemen Data Referensi memproses setiap item satu per satu, dan kesalahan dengan satu item tidak mencegah yang lain berhasil ditulis. Misalnya, jika permintaan Anda memiliki 100 item dan satu item memiliki kesalahan, 99 item ditulis dan satu ditolak.

Kode kesalahan item

Kode kesalahan item terjadi dalam isi respons JSON yang berhasil yang memiliki kode status HTTP 200.

InvalidInput: Kunci tidak ditemukan.: Menunjukkan bahwa item yang dikueri tidak dapat ditemukan di himpunan data referensi.
```
{
  "code": "InvalidInput",
  "message": "Key not found.",
  "target": null,
  "details": null,
  "innerError": null
}
```
InvalidInput: Kunci payload tidak boleh berisi properti non-kunci.: Menunjukkan bahwa item kueri isi permintaan JSON tidak boleh berisi properti apa pun yang bukan properti kunci (yaitu, properti yang ditentukan dalam skema set referensi). Properti utama dapat ditemukan di portal Azure.
```
{
  "code": "InvalidInput",
  "message": "Payload key should not contain any non-key property.",
  "target": null,
  "details": null,
  "innerError": null
}
```
InvalidInput: Item payload harus berisi semua properti utama.: Menunjukkan bahwa item kueri isi permintaan JSON harus menyertakan semua properti kunci (yaitu, properti yang ditentukan dalam skema set referensi). Properti utama dapat ditemukan di portal Azure.
```
{
  "code": "InvalidInput",
  "message": "Payload item should contain all key properties.",
  "target": null,
  "details": null,
  "innerError": null
}
```

Contoh gabungan data referensi

Pertimbangkan pesan pusat aktivitas yang memiliki struktur berikut:

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

Pertimbangkan item data referensi yang diatur dengan nama contoso dan deviceId kunci dari jenis String, dan yang memiliki struktur berikut:

deviceId	warna	maxSpeed	floor
Kipas 1	Merah	5
Kipas 2	Putih		2

Saat dua peristiwa dalam pesan pusat aktivitas diproses oleh mesin masuk Azure Time Series Insights Gen1, peristiwa tersebut digabungkan dengan item data referensi yang benar. Output peristiwa memiliki struktur berikut:

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

Menggabungkan aturan dan semantik

Saat Anda bergabung dengan data referensi, patuhi batasan berikut:

Perbandingan nama kunci peka huruf besar/kecil.
Perbandingan nilai kunci peka huruf besar/kecil untuk properti string.

Untuk lingkungan dengan lebih dari satu himpunan data referensi, tiga batasan lebih lanjut diberlakukan selama gabungan:

Setiap item dalam himpunan data referensi dapat menentukan daftar properti non-kuncinya sendiri.
Untuk dua himpunan data referensi A dan B, properti non-kunci tidak boleh bersinggungan.
Himpunan data referensi digabungkan langsung hanya ke peristiwa, tidak pernah ke himpunan data lain yang direferensikan (lalu ke peristiwa). Untuk menggabungkan item data referensi ke peristiwa, semua properti kunci yang digunakan dalam item data referensi harus ada dalam peristiwa tersebut. Selain itu, properti utama tidak boleh berasal dari properti non-kunci yang digabungkan ke peristiwa melalui beberapa item data referensi lainnya.

Mengingat batasan ini, mesin gabungan dapat menerapkan gabungan dalam urutan apa pun untuk peristiwa tertentu. Hierarki dan pengurutan tidak dipertimbangkan.

Batas saat ini

Anda dapat menambahkan hingga dua himpunan data referensi per lingkungan Azure Time Series Insights Gen1. Batasan tambahan yang terkait dengan data referensi Azure Time Series Insights Gen1 tercantum dalam tabel berikut:

Nama batas	Nilai batas	SKU terpengaruh	Catatan
Jumlah properti kunci	3	S1, S2	Per himpunan data referensi; Azure Resource Manager dan portal Azure saja
Ukuran properti kunci	1 KB	S1, S2	Per himpunan data referensi
Jumlah item data referensi	2.000/20.000 (S1/S2)	S1, S2	Per unit; misalnya, 4 unit SKU S1 = 8.000 item (4 x 2.000)
Transaksi bersamaan maks	2/10 (S1/S2)	S1, S2
Transaksi data referensi maksimum	120/600 (S1/S2)	S1, S2	Per jam
Jumlah item data referensi maksimum	1\.000	S1, S2	Per transaksi
Ukuran item data referensi maksimum	8.192 KB	S1, S2	Per transaksi

Lihat juga

Untuk informasi selengkapnya tentang pendaftaran aplikasi dan model pemrograman Azure Active Directory, lihat Azure Active Directory untuk pengembang.

Untuk mempelajari tentang parameter permintaan dan autentikasi, lihat Autentikasi dan otorisasi.

Alat yang membantu menguji permintaan dan respons HTTP meliputi:

Fiddler. Proksi penelusuran kesalahan web gratis ini dapat mencegat permintaan REST Anda, sehingga Anda dapat mendiagnosis pesan permintaan dan respons HTTP.
JWT.io. Anda dapat menggunakan alat ini untuk dengan cepat membuang klaim dalam token pembawa Anda lalu memvalidasi kontennya.
Tukang pos. Ini adalah alat pengujian permintaan dan respons HTTP gratis untuk men-debug REST API.

Pelajari selengkapnya tentang Azure Time Series Insights Gen1 dengan meninjau dokumentasi Gen1.

Share via

API Data Referensi Azure Time Series Insights Gen1

Ringkasan API

Letakkan item data referensi

Item data referensi patch

Menghapus properti dalam item data referensi

Menghapus item data referensi

Mendapatkan item data referensi

Validasi dan penanganan kesalahan

Kode kesalahan item

Contoh gabungan data referensi

Menggabungkan aturan dan semantik

Batas saat ini

Lihat juga

Sumber Daya Tambahan: