Cara mengautentikasi dan mengotorisasi panggilan REST API IoT Central

  • Artikel

IoT Central REST API memungkinkan Anda mengembangkan aplikasi klien yang terintegrasi dengan aplikasi IoT Central. Gunakan REST API untuk bekerja dengan sumber daya di aplikasi IoT Central Anda seperti templat perangkat, perangkat, pekerjaan, pengguna, dan peran.

Setiap panggilan REST API IoT Central memerlukan header otorisasi yang digunakan IoT Central untuk menentukan identitas pemanggil dan izin yang diberikan pemanggil dalam aplikasi.

Artikel ini menjelaskan tipe token yang bisa Anda gunakan di header otorisasi dan cara mendapatkannya. Perwakilan layanan adalah pendekatan yang direkomendasikan untuk manajemen akses REST API IoT Central.

Tipe token

Untuk mengakses aplikasi IoT Central menggunakan REST API, Anda dapat menggunakan:

  • Token pembawa Microsoft Entra. Token pembawa dikaitkan dengan akun pengguna Microsoft Entra atau perwakilan layanan. Token memberikan izin yang sama seperti yang dimiliki oleh pengguna atau perwakilan layanan di aplikasi IoT Central kepada pemanggil.
  • Token API IoT Central. Token API dikaitkan dengan peran dalam aplikasi IoT Central Anda.

Gunakan token pembawa yang terkait dengan akun pengguna Saat Anda mengembangkan dan menguji otomatisasi dan skrip yang menggunakan REST API. Gunakan token pembawa yang terkait dengan perwakilan layanan untuk otomatisasi produksi dan skrip. Gunakan token pembawa di preferensi token API untuk mengurangi risiko kebocoran dan masalah saat token kedaluwarsa.

Untuk mempelajari pengguna dan peran di IoT Central selengkapnya, lihat Mengelola pengguna dan peran di aplikasi IoT Central Anda.

Mendapatkan token pembawa

Untuk mendapatkan token pembawa untuk akun pengguna Microsoft Entra Anda, gunakan perintah Azure CLI berikut:

az login
az account get-access-token --resource https://apps.azureiotcentral.com

Penting

Perintah az login ini diperlukan meskipun Anda menggunakan Cloud Shell.

Output JSON dari perintah sebelumnya akan terlihat seperti contoh berikut:

{
  "accessToken": "eyJ0eX...fNQ",
  "expiresOn": "2021-03-22 11:11:16.072222",
  "subscription": "{your subscription id}",
  "tenant": "{your tenant id}",
  "tokenType": "Bearer"
}

Token pembawa berlaku selama sekitar satu jam, setelah itu Anda perlu membuat yang baru.

Untuk mendapatkan token pembawa untuk perwakilan layanan, lihat Autentikasi perwakilan layanan.

Mendapatkan token API

Untuk mendapatkan token API, Anda dapat menggunakan UI IoT Central atau panggilan REST API. Administrator yang terkait dengan organisasi root dan pengguna yang ditugaskan untuk peran yang benar dapat membuat token API.

Tip

Operasi buat dan hapus pada token API dicatat di log audit.

Pada UI IoT Central:

  1. Navigasikan ke token API Izin>.

  2. Pilih + Baru atau Buat token API.

  3. Masukkan nama untuk token dan pilih peran dan organisasi.

  4. Pilih Hasilkan.

  5. IoT Central menampilkan token yang terlihat seperti contoh berikut:

    SharedAccessSignature sr=5782ed70...&sig=dvZZE...&skn=operator-token&se=1647948035850

    Layar ini adalah satu-satunya kesempatan Anda untuk melihat token API. Jika kehilangan layar ini, Anda perlu membuat layar baru.

Token API berlaku selama kurang lebih satu tahun. Anda dapat membuat token untuk peran bawaan dan kustom dalam aplikasi IoT Central Anda. Organisasi yang Anda pilih saat membuat token API menentukan perangkat mana yang dapat diakses API. Token API apa pun yang dibuat sebelum Anda menambahkan organisasi apa pun ke aplikasi Anda terkait dengan organisasi root.

Anda dapat menghapus token API di UI IoT Central jika Anda ingin mencabut akses.

Menggunakan REST API:

  1. 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 akan terlihat seperti contoh berikut:

    {
  "value": [
    {
      "displayName": "Administrator",
      "id": "ca310b8d-2f4a-44e0-a36e-957c202cd8d4"
    },
    {
      "displayName": "Operator",
      "id": "ae2c9854-393b-4f97-8c42-479d70ce626e"
    },
    {
      "displayName": "Builder",
      "id": "344138e9-8de4-4497-8c54-5237e96d6aaf"
    }
  ]
}

  2. Gunakan REST API untuk membuat token API untuk peran. Misalnya, untuk membuat token API yang disebut operator-token untuk peran operator:

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

    Isi permintaan:

    {
  "roles": [
    {
      "role": "ae2c9854-393b-4f97-8c42-479d70ce626e"
    }
  ]
}

    Respons terhadap perintah sebelumnya akan terlihat seperti JSON berikut:

    {
  "expiry": "2022-03-22T12:01:27.889Z",
  "id": "operator-token",
  "roles": [
    {
      "role": "ae2c9854-393b-4f97-8c42-479d70ce626e"
    }
  ],
  "token": "SharedAccessSignature sr=e8a...&sig=jKY8W...&skn=operator-token&se=1647950487889"
}

    Respons ini adalah satu-satunya kesempatan Anda memiliki akses ke token API, jika Anda kehilangannya, Anda perlu menghasilkan yang baru.

Anda dapat menggunakan REST API untuk mencantumkan dan menghapus token API dalam aplikasi.

Menggunakan token pembawa

Untuk menggunakan token pembawa saat Anda melakukan panggilan REST API, header otorisasi Anda terlihat seperti contoh berikut:

Authorization: Bearer eyJ0eX...fNQ

Menggunakan token API

Untuk menggunakan token API saat Anda melakukan panggilan REST API, header otorisasi Anda harus terlihat seperti contoh berikut:

Authorization: SharedAccessSignature sr=e8a...&sig=jKY8W...&skn=operator-token&se=1647950487889