Bagikan melalui

Cara menggunakan REST API IoT Central untuk mengunggah file

  • Artikel

IoT Central memungkinkan Anda mengunggah media dan file lain dari perangkat yang tersambung ke penyimpanan cloud. Anda mengonfigurasi kemampuan pengunggahan file di aplikasi IoT Central Anda, lalu menerapkan pengunggahan file di kode perangkat Anda. Dalam artikel ini, pelajari cara:

  • Gunakan REST API untuk mengonfigurasi kemampuan unggahan file di aplikasi IoT Central Anda.
  • Uji unggahan file dengan menjalankan beberapa contoh kode perangkat.

IoT Central REST API memungkinkan Anda:

  • Menambahkan konfigurasi akun penyimpanan unggahan file
  • Memperbarui konfigurasi akun penyimpanan unggahan file
  • Mendapatkan konfigurasi akun penyimpanan unggahan file
  • Menghapus konfigurasi penyimpanan unggahan file

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.

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 mengunggah file dengan menggunakan UI IoT Central, lihat Cara mengonfigurasi unggahan file.

Prasyarat

Untuk menguji unggahan file, instal prasyarat berikut di lingkungan pengembangan lokal Anda:

Menambahkan konfigurasi akun penyimpanan unggahan file

Untuk menambahkan konfigurasi akun penyimpanan unggahan file:

Buat akun penyimpanan

Untuk menggunakan AZURE Storage REST API, Anda memerlukan token pembawa untuk management.azure.com sumber daya. Untuk mendapatkan token pembawa, Anda dapat menggunakan Azure CLI:

az account get-access-token --resource https://management.azure.com

Jika Anda tidak memiliki akun penyimpanan untuk blob, Anda dapat menggunakan permintaan berikut untuk membuatnya di langganan Anda:

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{accountName}?api-version=2021-09-01

Header permintaan memiliki bidang berikut:

  • subscriptionId : ID langganan target.
  • resourceGroupName: Nama grup sumber daya dalam langganan Anda. Nama tidak peka huruf besar/kecil.
  • accountName : Nama akun penyimpanan dalam grup sumber daya yang ditentukan. Nama akun penyimpanan harus sepanjang antara 3 dan 24 karakter dan hanya menggunakan angka dan huruf kecil.

Isi permintaan memiliki bidang yang diperlukan berikut:

  • kind : Jenis akun penyimpanan
  • location : Lokasi geografis tempat sumber daya berada
  • sku: Nama SKU.
{
 "kind": "BlockBlobStorage",
 "location": "West US",
 "sku": "Premium_LRS"
}

Membuat kontainer

Gunakan permintaan berikut untuk membuat kontainer yang disebut fileuploads di akun penyimpanan Anda untuk blob Anda:

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{accountName}/blobServices/default/containers/fileuploads?api-version=2021-09-01
  • containerName : Nama kontainer blob harus berukuran antara 3 dan 63 karakter dan menggunakan angka, huruf kecil dan tanda hubung (-) saja. Setiap karakter tanda hubung (-) harus segera didahului dan diikuti dengan huruf atau angka.

Kirim isi permintaan kosong dengan permintaan ini yang terlihat seperti contoh berikut:

{
}

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

{
  "id": "/subscriptions/your-subscription-id/resourceGroups/yourResourceGroupName/providers/Microsoft.Storage/storageAccounts/yourAccountName/blobServices/default/containers/fileuploads",
  "name": "fileuploads",
  "type": "Microsoft.Storage/storageAccounts/blobServices/containers"
}

Mendapatkan kunci akun penyimpanan

Gunakan permintaan berikut untuk mengambil kunci akun penyimpanan yang Anda butuhkan saat mengonfigurasi unggahan di IoT Central:

POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{accountName}/listKeys?api-version=2021-09-01

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

{
  "keys": [
    {
      "creationTime": "2022-05-19T19:22:40.9132287Z",
      "keyName": "key1",
      "value": "j3UTm**************==",
      "permissions": "FULL"
    },
    {
      "creationTime": "2022-05-19T19:22:40.9132287Z",
      "keyName": "key2",
      "value": "Nbs3W**************==",
      "permissions": "FULL"
    }
  ]
}

Membuat konfigurasi unggahan

Gunakan permintaan berikut untuk membuat konfigurasi akun penyimpanan blob unggahan file di aplikasi IoT Central Anda:

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

Isi permintaan memiliki bidang berikut:

  • account: Nama akun penyimpanan tempat mengunggah file.
  • connectionString: string koneksi untuk menyambungkan ke akun penyimpanan. Gunakan salah value satu nilai dari permintaan sebelumnya listKeys sebagai AccountKey nilai .
  • container: Nama kontainer di dalam akun penyimpanan. Contoh berikut menggunakan nama fileuploads.
  • etag: ETag untuk mencegah konflik dengan beberapa unggahan
  • sasTtl: Standar durasi ISO 8601, Jumlah waktu permintaan perangkat untuk mengunggah file valid sebelum kedaluwarsa.
{
  "account": "yourAccountName",
  "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/",
  "container": "fileuploads",
  "sasTtl": "PT1H"
}

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

{
  "account": "yourAccountName",
  "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/",
  "container": "fileuploads",
  "sasTtl": "PT1H",
  "state": "pending",
  "etag": "\"7502ac89-0000-0300-0000-627eaf100000\""

}

Mendapatkan konfigurasi akun penyimpanan unggahan file

Gunakan permintaan berikut untuk mengambil detail konfigurasi akun penyimpanan blob unggahan file di aplikasi IoT Central Anda:

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

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:

{
  "account": "yourAccountName",
  "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/",
  "container": "yourContainerName",
  "state": "succeeded",
  "etag": "\"7502ac89-0000-0300-0000-627eaf100000\""

}

Memperbarui konfigurasi akun penyimpanan unggahan file

Gunakan permintaan berikut untuk memperbarui akun penyimpanan blob unggahan file string koneksi di aplikasi IoT Central Anda:

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

{
  "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/"
}

Respons terhadap permintaan ini akan terlihat seperti contoh berikut:


{
  "account": "yourAccountName",
  "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/",
  "container": "yourContainerName",
  "sasTtl": "PT1H",
  "state": "succeeded",
  "etag": "\"7502ac89-0000-0300-0000-627eaf100000\""
}

Menghapus konfigurasi akun penyimpanan unggahan file

Gunakan permintaan berikut untuk menghapus konfigurasi akun penyimpanan:

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

Uji unggahan file

Setelah mengonfigurasi unggahan file di aplikasi IoT Central, Anda dapat mengujinya dengan kode sampel. Jika Anda belum mengkloning repositori sampel unggahan file, gunakan perintah berikut untuk mengkloningnya ke lokasi yang sesuai di komputer lokal Anda dan instal paket dependen:

git clone https://github.com/azure-Samples/iot-central-file-upload-device
cd iotc-file-upload-device
npm i
npm build

Membuat templat perangkat dan mengimpor model

Untuk menguji unggahan file, Anda menjalankan aplikasi perangkat sampel. Buat templat perangkat untuk perangkat sampel yang akan digunakan.

  1. Buka aplikasi Anda di UI IoT Central.

  2. Navigasi ke tab Templat Perangkat di panel kiri, pilih + Baru:

  3. Pilih perangkat IoT sebagai jenis templat.

  4. Pada halaman Kustomisasi wizard, masukkan nama seperti Sampel Perangkat Unggah File untuk templat perangkat.

  5. Pada halaman Tinjau, pilih Buat.

  6. Pilih Impor model dan unggah file model FileUploadDeviceDcm.json dari folder iotc-file-upload-device\setup di repositori yang Anda unduh sebelumnya.

  7. Pilih Terbitkan untuk menerbitkan templat perangkat.

Menambahkan perangkat

Untuk menambahkan perangkat ke aplikasi Azure IoT Central Anda:

  1. Pilih Perangkat di panel kiri.

  2. Pilih templat perangkat Sampel Perangkat Unggah File yang Anda buat sebelumnya.

  3. Pilih + Baru dan pilih Buat.

  4. Pilih perangkat yang Anda buat dan Pilih Koneksi

Salin nilai untuk ID scope, Device ID, dan Primary key. Anda menggunakan nilai-nilai ini dalam kode sampel perangkat.

Jalankan kode sampel

Buka repositori git yang Anda unduh di Visual Studio Code. Buat file ".env" di akar proyek Anda dan tambahkan nilai yang Anda salin sebelumnya. File akan terlihat seperti sampel berikut dengan nilai yang Anda catat sebelumnya.

scopeId=<YOUR_SCOPE_ID>
deviceId=<YOUR_DEVICE_ID>
deviceKey=<YOUR_PRIMARY_KEY>
modelId=dtmi:IoTCentral:IotCentralFileUploadDevice;1

Buka repositori git yang Anda unduh di Visual Studio Code. Tekan F5 untuk menjalankan/men-debug sampel. Di jendela terminal Anda, Anda melihat bahwa perangkat terdaftar dan terhubung ke IoT Central:

Starting IoT Central device...
 > Machine: Windows_NT, 8 core, freemem=6674mb, totalmem=16157mb
Starting device registration...
DPS registration succeeded
Connecting the device...
IoT Central successfully connected device: 7z1xo26yd8
Sending telemetry: {
    "TELEMETRY_SYSTEM_HEARTBEAT": 1
}
Sending telemetry: {
    "TELEMETRY_SYSTEM_HEARTBEAT": 1
}
Sending telemetry: {
    "TELEMETRY_SYSTEM_HEARTBEAT": 1
}

Proyek sampel dilengkapi dengan file sampel bernama datafile.json. File ini diunggah saat Anda menggunakan perintah Unggah File di aplikasi IoT Central Anda.

Untuk menguji unggahan, buka aplikasi Anda dan pilih perangkat yang Anda buat. Pilih tab Perintah dan Anda melihat tombol bernama Jalankan. Saat Anda memilih tombol tersebut, aplikasi IoT Central memanggil metode langsung di perangkat Anda untuk mengunggah file. Anda dapat melihat metode langsung ini dalam kode sampel dalam file /device.ts. Metode ini diberi nama uploadFileCommand.

Pilih tab Data mentah untuk memverifikasi status unggahan file.

Screenshot showing the U I of how to verify a file upload.

Anda juga dapat melakukan panggilan REST API untuk memverifikasi status unggahan file di kontainer penyimpanan.

Langkah berikutnya

Sekarang setelah Anda mempelajari cara mengonfigurasi unggahan file dengan REST API, langkah selanjutnya yang disarankan adalah Cara membuat templat perangkat dari IoT Central GUI.