Cara menggunakan IoT Central REST API untuk mengelola pengguna dan peran

  • Artikel

IoT Central REST API memungkinkan Anda mengembangkan aplikasi klien yang terintegrasi dengan aplikasi IoT Central. Anda dapat menggunakan REST API untuk mengelola pengguna dan peran 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.

Catatan

Operasi pada pengguna dan peran dicatat di log audit IoT Central.

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

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.

Untuk mempelajari cara mengelola pengguna dan peran dengan menggunakan UI IoT Central, lihat Mengelola pengguna dan peran di aplikasi IoT Central Anda.

Mengelola peran

REST API memungkinkan Anda mencantumkan peran yang ditentukan dalam aplikasi IoT Central Anda. Gunakan REST API untuk mengambil daftar ID peran dari aplikasi Anda:

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

Respons terhadap permintaan ini terlihat seperti contoh berikut yang menyertakan tiga peran bawaan dan peran kustom:

{
  "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": "16f8533f-6b82-478f-8ba8-7e676b541b1b",
      "displayName": "Example custom role"
    }
  ]
}

Catatan

Perintah ini hanya menampilkan peran yang terkait dengan aplikasi dan bukan peran tingkat organisasi kustom.

Mengelola pengguna

REST API memungkinkan Anda:

  • Mencantumkan pengguna dalam aplikasi
  • Mengambil detail pengguna individual
  • Buat pengguna
  • Mengubah pengguna
  • Menghapus pengguna

Mencantumkan pengguna

Gunakan permintaan berikut untuk mengambil daftar pengguna dari aplikasi Anda:

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

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

{
  "value": [
    {
      "id": "91907508-04fe-4349-91b5-b872f3055a95",
      "type": "email",
      "roles": [
        {
          "role": "ca310b8d-2f4a-44e0-a36e-957c202cd8d4"
        }
      ],
      "email": "user1@contoso.com"
    },
    {
      "id": "dc1c916b-a652-49ea-b128-7c465a54c759",
      "type": "email",
      "roles": [
        {
          "role": "ae2c9854-393b-4f97-8c42-479d70ce626e"
        }
      ],
      "email": "user2@contoso.com"
    },
    {
      "id": "3ab9375e-d2d9-42da-b419-6ae86a938321",
      "type": "email",
      "roles": [
        {
          "role": "344138e9-8de4-4497-8c54-5237e96d6aaf"
        }
      ],
      "email": "user3@contoso.com"
    },
    {
      "id": "fc5a250b-83fb-433d-892c-e0a144f68c2b",
      "type": "email",
      "roles": [
        {
          "role": "16f8533f-6b82-478f-8ba8-7e676b541b1b"
        }
      ],
      "email": "user4@contoso.com"
    }
  ]
}

Mendapatkan pengguna

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

GET https://{your app subdomain}.azureiotcentral.com/api/users/dc1c916b-a652-49ea-b128-7c465a54c759?api-version=2022-07-31

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

{
  "id": "dc1c916b-a652-49ea-b128-7c465a54c759",
  "type": "email",
  "roles": [
    {
      "role": "ae2c9854-393b-4f97-8c42-479d70ce626e"
    }
  ],
  "email": "user2@contoso.com"
}

Buat pengguna

Gunakan permintaan berikut untuk membuat pengguna 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, nilai role adalah untuk peran operator yang Anda ambil sebelumnya:

{
  "id": "user-001",
  "type": "email",
  "roles": [
    {
      "role": "ae2c9854-393b-4f97-8c42-479d70ce626e"
    }
  ],
  "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": "ae2c9854-393b-4f97-8c42-479d70ce626e"
    }
  ],
  "email": "user5@contoso.com"
}

Anda juga dapat menambahkan pengguna perwakilan layanan yang berguna jika Anda perlu menggunakan autentikasi perwakilan layanan untuk panggilan REST API. Untuk mempelajari selengkapnya, lihat Menambahkan atau memperbarui pengguna perwakilan layanan.

Mengubah peran pengguna

Gunakan permintaan berikut untuk mengubah peran yang ditetapkan ke pengguna. Contoh ini menggunakan ID peran penyusun yang Anda ambil sebelumnya:

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

Isi permintaan. Nilainya adalah untuk peran penyusun yang Anda ambil sebelumnya:

{
  "roles": [
    {
      "role": "344138e9-8de4-4497-8c54-5237e96d6aaf"
    }
  ]
}

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

{
  "id": "user-001",
  "type": "email",
  "roles": [
    {
      "role": "344138e9-8de4-4497-8c54-5237e96d6aaf"
    }
  ],
  "email": "user5@contoso.com"
}

Menghapus pengguna

Gunakan permintaan berikut untuk menghapus pengguna:

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

Langkah berikutnya

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