Cara menggunakan REST API IoT Central untuk mengelola organisasi

Artikel
10/27/2023

IoT Central REST API memungkinkan Anda mengembangkan aplikasi klien yang terintegrasi dengan aplikasi IoT Central. Anda dapat menggunakan REST API untuk mengelola organisasi di aplikasi IoT Central Anda.

Setiap panggilan IoT Central REST API memerlukan header otorisasi. Untuk mempelajari selengkapnya, lihat Cara mengautentikasi dan mengotorisasi panggilan IoT Central REST API.

Untuk dokumentasi referensi untuk IoT Central REST API, lihat Referensi IoT Central REST API.

Untuk mempelajari selengkapnya tentang organisasi di Aplikasi IoT Central, lihat Mengelola organisasi IoT Central.

Tip

Anda dapat menggunakan Postman untuk mencoba panggilan REST API yang dijelaskan dalam artikel ini. Unduh koleksi IoT Central Postman dan impor ke Postman. Dalam koleksi, Anda harus mengatur variabel seperti subdomain aplikasi dan token admin.

REST API Organisasi

IoT Central REST API memungkinkan Anda:

Menambahkan organisasi ke aplikasi Anda
Mendapatkan organisasi berdasarkan ID
Memperbarui organisasi di aplikasi Anda
Mendapatkan daftar organisasi dalam aplikasi
Menghapus organisasi di aplikasi Anda

Membuat organisasi

REST API memungkinkan Anda membuat organisasi di aplikasi IoT Central Anda. Gunakan permintaan berikut untuk membuat organisasi di aplikasi Anda:

PUT https://{your app subdomain}.azureiotcentral.com/api/organizations/{organizationId}?api-version=2022-07-31

organizationId - ID unik organisasi

Contoh berikut menunjukkan isi permintaan yang menambahkan organisasi ke aplikasi IoT Central.

{
  "displayName": "Seattle",
}

Isi permintaan memiliki beberapa bidang yang diperlukan:

@displayName: Nama tampilan organisasi.

Isi permintaan memiliki beberapa bidang opsional:

@parent: ID induk organisasi.

Jika Anda tidak menentukan induk, organisasi akan mendapatkan organisasi tingkat atas default sebagai induknya.

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

{
  "id": "seattle",
  "displayName": "Seattle"
}

Anda dapat membuat organisasi dengan hierarki, misalnya Anda dapat membuat organisasi penjualan dengan organisasi induk.

Contoh berikut menunjukkan isi permintaan yang menambahkan organisasi ke aplikasi IoT Central.

{
  "displayName": "Sales",
  "parent":"seattle"
}

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

{
  "id": "sales",
  "displayName": "Sales",
  "parent":"Seattle"
}

Mendapatkan organisasi

Gunakan permintaan berikut untuk mengambil detail organisasi individual dari aplikasi Anda:

GET https://{your app subdomain}.azureiotcentral.com/api/organizations/{organizationId}?api-version=2022-07-31

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

{
  "id": "seattle",
  "displayName": "Seattle",
  "parent": "washington"
}

Memperbarui organisasi

Gunakan permintaan berikut untuk memperbarui detail organisasi di aplikasi Anda:

PATCH https://{your app subdomain}.azureiotcentral.com/api/organizations/{organizationId}?api-version=2022-07-31

Contoh berikut menunjukkan isi permintaan yang memperbarui induk organisasi:

{
  "parent": "washington"
}

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

{
  "id": "seattle",
  "displayName": "Seattle Sales",
  "parent": "washington"
}

Mencantumkan organisasi

Gunakan permintaan berikut untuk mengambil daftar organisasi dari aplikasi Anda:

GET https://{your app subdomain}.azureiotcentral.com/api/organizations?api-version=2022-07-31

Respons terhadap permintaan ini akan terlihat seperti contoh berikut.

{
    "value": [
        {
            "id": "washington",
            "displayName": "Washington"
        },
        {
            "id": "redmond",
            "displayName": "Redmond"
        },
        {
            "id": "bellevue",
            "displayName": "Bellevue"
        },
        {
            "id": "spokane",
            "displayName": "Spokane",
            "parent": "washington"
        },
        {
            "id": "seattle",
            "displayName": "Seattle",
            "parent": "washington"
        }
    ]
}

Organisasi Washington, Redmond, dan Bellevue secara otomatis memiliki organisasi tingkat atas default aplikasi sebagai induk mereka.

Menghapus organisasi

Gunakan permintaan berikut untuk menghapus organisasi:

DELETE https://{your app subdomain}.azureiotcentral.com/api/organizations/{organizationId}?api-version=2022-07-31

Menggunakan organisasi

Gunakan organisasi untuk mengelola akses ke sumber daya di aplikasi Anda.

Mengelola peran

REST API memungkinkan Anda mencantumkan peran yang ditentukan dalam aplikasi IoT Central Anda. Gunakan permintaan berikut untuk mengambil daftar peran aplikasi dan ID peran organisasi dari aplikasi Anda. Untuk mempelajari selengkapnya, lihat Cara mengelola organisasi IoT Central:

GET https://{your app subdomain}.azureiotcentral.com/api/roles?api-version=2022-07-31

Respons terhadap permintaan ini terlihat seperti contoh berikut yang menyertakan peran aplikasi dan ID peran organisasi.

{
    "value": [
        {
            "id": "ca310b8d-2f4a-44e0-a36e-957c202cd8d4",
            "displayName": "Administrator"
        },
        {
            "id": "ae2c9854-393b-4f97-8c42-479d70ce626e",
            "displayName": "Operator"
        },
        {
            "id": "344138e9-8de4-4497-8c54-5237e96d6aaf",
            "displayName": "Builder"
        },
        {
            "id": "c495eb57-eb18-489e-9802-62c474e5645c",
            "displayName": "Org Admin"
        },
        {
            "id": "b4935647-30e4-4ed3-9074-dcac66c2f8ef",
            "displayName": "Org Operator"
        },
        {
            "id": "84cc62c1-dabe-49d3-b16e-8b291232b285",
            "displayName": "Org Viewer"
        }
    ]
}

Membuat token API yang dilampirkan ke simpul dalam hierarki organisasi

Gunakan permintaan berikut untuk membuat buat token API yang dilampirkan ke simpul dalam hierarki organisasi di aplikasi Anda:

PUT https://{your app subdomain}.azureiotcentral.com/api/apiTokens/{tokenId}?api-version=2022-07-31

tokenId - ID unik token

Contoh berikut menunjukkan isi permintaan yang membuat token API untuk organisasi seattle dalam aplikasi IoT Central.

{
    "roles": [
        {
            "role": "84cc62c1-dabe-49d3-b16e-8b291232b285",
            "organization": "seattle"
        }
    ]
}

Isi permintaan memiliki beberapa bidang yang diperlukan:

Nama	Deskripsi
role	ID salah satu peran organisasi
organization	ID organisasi

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

{
    "id": "token1",
    "roles": [
        {
            "role": "84cc62c1-dabe-49d3-b16e-8b291232b285",
            "organization": "seattle"
        }
    ],
    "expiry": "2023-07-07T17:05:08.407Z",
    "token": "SharedAccessSignature sr=8a0617**********************4c0d71c&sig=3RyX69G4%2FBZZnG0LXOjQv*************e8s%3D&skn=token1&se=1688749508407"
}

Mengaitkan pengguna dengan simpul dalam hierarki organisasi

Gunakan permintaan berikut untuk membuat dan mengaitkan pengguna dengan simpul dalam hierarki organisasi di aplikasi Anda. ID dan email harus unik dalam aplikasi:

PUT https://{your app subdomain}.azureiotcentral.com/api/users/user-001?api-version=2022-07-31

Dalam isi permintaan berikut, role adalah ID dari salah satu peran organisasi dan organization merupakan ID organisasi

{
  "id": "user-001",
  "type": "email",
    "roles": [
        {
            "role": "84cc62c1-dabe-49d3-b16e-8b291232b285",
            "organization": "seattle"
        }
    ],
    "email": "user5@contoso.com"

}

Respons terhadap permintaan ini akan terlihat seperti contoh berikut. Nilai peran mengidentifikasi peran mana yang dikaitkan dengan pengguna:

{
    "id": "user-001",
    "type": "email",
    "roles": [
        {
            "role": "84cc62c1-dabe-49d3-b16e-8b291232b285",
            "organization": "seattle"
        }
    ],
    "email": "user5@contoso.com"
}

Menambahkan dan mengaitkan perangkat ke organisasi

Gunakan permintaan berikut untuk mengaitkan perangkat baru dengan organisasi

PUT https://{your app subdomain}.azureiotcentral.com/api/devices/{deviceId}?api-version=2022-07-31

Contoh berikut menunjukkan isi permintaan yang menambahkan perangkat untuk templat perangkat. Anda bisa mendapatkan template detail dari halaman templat perangkat di antarmuka pengguna aplikasi IoT Central.

{
    "displayName": "CheckoutThermostat",
    "template": "dtmi:contoso:Thermostat;1",
    "simulated": true,
    "enabled": true,
    "organizations": [
        "seattle"
    ]
}

Isi permintaan memiliki beberapa bidang yang diperlukan:

@displayName: Nama tampilan perangkat.
@enabled: menyatakan bahwa objek ini adalah antarmuka.
@etag: ETag digunakan untuk mencegah konflik dalam pembaruan perangkat.
simulated: Apakah perangkat disimulasikan?
template : Definisi templat perangkat untuk perangkat.
organizations : Daftar ID organisasi yang menjadi bagian perangkat. Saat ini, Anda hanya dapat mengaitkan perangkat dengan satu organisasi.

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

{
    "id": "thermostat1",
    "etag": "eyJoZWFkZXIiOiJcIjI0MDAwYTdkLTAwMDAtMDMwMC0wMDAwLTYxYjgxZDIwMDAwMFwiIiwiZGF0YSI6IlwiMzMwMDQ1M2EtMDAwMC0wMzAwLTAwMDAtNjFiODFkMjAwMDAwXCIifQ",
    "displayName": "CheckoutThermostat",
    "simulated": true,
    "provisioned": false,
    "template": "dtmi:contoso:Thermostat;1",
    "enabled": true,
   "organizations": [
    "seattle"
  ]

}

Menambahkan dan mengaitkan grup perangkat ke organisasi

Gunakan permintaan berikut untuk membuat dan mengaitkan grup perangkat baru dengan organisasi.

PUT https://{your app subdomain}.azureiotcentral.com/api/deviceGroups/{deviceGroupId}?api-version=2022-07-31

Saat membuat grup perangkat, Anda menentukan filter yang memilih perangkat untuk ditambahkan ke grup. filter Mengidentifikasi templat perangkat dan properti apa pun yang cocok. Contoh berikut membuat grup perangkat yang berisi semua perangkat yang terkait dengan dtmi:modelDefinition:dtdlv2 templat tempat provisioned properti tersebut benar.

{
  "displayName": "Device group 1",
  "description": "Custom device group.",
  "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
  "organizations": [
    "seattle"
  ]
}

Isi permintaan memiliki beberapa bidang yang diperlukan:

@displayName: Nama tampilan grup perangkat.
@filter: Kueri menentukan perangkat mana yang harus berada dalam grup ini.
description: Ringkasan singkat grup perangkat.
organizations : Daftar ID organisasi yang menjadi bagian perangkat. Saat ini, Anda hanya dapat mengaitkan perangkat dengan satu organisasi.

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

{
  "id": "group1",
  "displayName": "Device group 1",
  "description": "Custom device group.",
  "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
  "organizations": [
    "seattle"
  ]
}

Langkah berikutnya

Sekarang setelah Anda mempelajari cara mengelola organisasi dengan REST API, langkah selanjutnya yang disarankan adalah Cara menggunakan REST API IoT Central untuk mengelola ekspor data.

Cara menggunakan REST API IoT Central untuk mengelola organisasi

REST API Organisasi

Membuat organisasi

Mendapatkan organisasi

Memperbarui organisasi

Mencantumkan organisasi

Menghapus organisasi

Menggunakan organisasi

Mengelola peran

Membuat token API yang dilampirkan ke simpul dalam hierarki organisasi

Mengaitkan pengguna dengan simpul dalam hierarki organisasi

Menambahkan dan mengaitkan perangkat ke organisasi

Menambahkan dan mengaitkan grup perangkat ke organisasi

Langkah berikutnya

Sumber Daya Tambahan: