使用 Azure CLI 來設定 IoT 中樞檔案上傳

發行項
05/10/2024

本文說明如何使用 Azure CLI 在 IoT 中樞上設定檔案上傳。

若要使用 IoT 中樞的檔案上傳功能，您必須先將 Azure 儲存體帳戶和 blob 容器與您的 IoT 中樞建立關聯。 IoT 中樞會自動產生具有此 Blob 容器寫入權限的 SAS URI，以供裝置上傳檔案時使用。除了儲存體帳戶和 blob 容器之外，您還可設定 SAS URI 的存留時間，以及 IoT 中樞搭配 Azure 儲存體使用的驗證類型。您也可設定選擇性檔案上傳通知的設定，讓 IoT 中樞可傳遞至後端服務。

必要條件

使用中的 Azure 帳戶。如果您沒有帳戶，只需要幾分鐘的時間就可以建立免費帳戶。
Azure IoT 中樞。如果您沒有 IoT 中樞，您可以使用 az iot hub create 命令來建立一個，或使用入口網站建立 IoT 中樞。
Azure 儲存體帳戶。如果您沒有 Azure 儲存體帳戶，您可以使用 Azure CLI 來建立帳戶。如需詳細資訊，請參閱建立儲存體帳戶。

在 Azure Cloud Shell 中使用 Bash 環境。如需詳細資訊，請參閱 Azure Cloud Shell 中的 Bash 快速入門。
若要在本地執行 CLI 參考命令，請安裝 Azure CLI。若您在 Windows 或 macOS 上執行，請考慮在 Docker 容器中執行 Azure CLI。如需詳細資訊，請參閱〈如何在 Docker 容器中執行 Azure CLI〉。
- 如果您使用的是本機安裝，請使用 az login 命令，透過 Azure CLI 來登入。請遵循您終端機上顯示的步驟，完成驗證程序。如需其他登入選項，請參閱使用 Azure CLI 登入。
- 出現提示時，請在第一次使用時安裝 Azure CLI 延伸模組。如需擴充功能詳細資訊，請參閱使用 Azure CLI 擴充功能。
- 執行 az version 以尋找已安裝的版本和相依程式庫。若要升級至最新版本，請執行 az upgrade。

注意

本文使用最新版的 Azure IoT 擴充功能，稱為 azure-iot。舊版則稱為 azure-cli-iot-ext。您一次只能安裝一個版本。您可以使用 az extension list 命令來驗證目前安裝的延伸模組。

使用 az extension remove --name azure-cli-iot-ext 移除舊版的擴充功能。

使用 az extension add --name azure-iot 新增新版的擴充功能。

若要查看您已安裝的擴充功能，請使用 az extension list。

登入您的 Azure 帳戶並選取您的訂用帳戶。如果您使用 Azure Cloud Shell，則應該已登入；不過，如果您有多個訂用帳戶，您仍可能需要選取您的 Azure 訂用帳戶。

在命令提示字元中，執行登入命令：
```
az login
```
依照指示使用程式碼進行驗證，並透過網頁瀏覽器登入 Azure 帳戶。
如果您有多個 Azure 訂用帳戶，則登入 Azure 會授予您所有與認證相關聯之 Azure 帳戶的存取權。使用下列命令列出 Azure 帳戶 \(英文\) 以供您使用：
```
az account list
```
使用下列命令，來選取您想要用來執行命令以建立 IoT 中樞的訂用帳戶。您可以使用來自上一個命令之輸出內的訂用帳戶名稱或識別碼︰
```
az account set --subscription {your subscription name or id}
```

擷取您的儲存體帳戶詳細資料

下列步驟假設您使用 [Resource Manager] 部署模型，而非 [傳統] 部署模型，建立了儲存體帳戶。

若要從裝置設定檔案上傳，您需要 Azure 儲存體帳戶的連接字串。儲存體帳戶必須與您的 IoT 中樞位於相同的訂用帳戶中。您也需要儲存體帳戶中 blob 容器的名稱。使用下列命令來擷取儲存體帳戶金鑰：

az storage account show-connection-string --name {your storage account name} \
  --resource-group {your storage account resource group}

連接字串會類似於下列輸出：

{
  "connectionString": "DefaultEndpointsProtocol=https;EndpointSuffix=core.windows.net;AccountName={your storage account name};AccountKey={your storage account key}"
}

記下 connectionString 的值。您需要在後續步驟中用到此值。

您可以使用現有的 Blob 容器進行檔案上傳，或建立新的容器：

若要列出儲存體帳戶中現有的 blob 容器，使用下列命令：

az storage container list --connection-string "{your storage account connection string}"

若要在儲存體帳戶中建立 blob 容器，使用下列命令：

az storage container create --name {container name} \
  --connection-string "{your storage account connection string}"

設定 IoT 中樞

您現在可以設定 IoT 中樞，以便能夠使用您的儲存體帳戶詳細資料將檔案上傳到 IoT 中樞。

設定需要下列值：

儲存體容器︰您目前 Azure 訂用帳戶內 Azure 儲存體帳戶中的 blob 容器，會與您的 IoT 中樞產生關聯。您已在上一節中擷取了必要的儲存體帳戶資訊。 IoT 中樞會自動產生具有此 Blob 容器寫入權限的 SAS URI，以供裝置上傳檔案時使用。
接收已上傳檔案的通知︰啟用或停用檔案上傳通知。
SAS TTL︰這個設定是「IoT 中樞」傳回給裝置之 SAS URI 的存留時間。預設會設為一小時。
檔案通知設定預設 TTL：檔案上傳通知到期前的存留時間。預設會設為一天。
檔案通知最大傳遞計數︰IoT 中樞可嘗試傳遞檔案上傳通知的次數。預設會設為 10。
檔案通知鎖定持續時間：檔案通知佇列的鎖定持續時間。依預設設定為 60 秒。
驗證類型：要與Azure 儲存體搭配使用的 IoT 中樞驗證類型。此設定會決定 IoT 中樞如何使用 Azure 儲存體進行驗證和授權。預設值為金鑰型驗證；不過，也可以使用系統指派和使用者指派的受控識別。受控識別在 Microsoft Entra ID 中以安全的方式為 Azure 服務提供自動受控的身分識別。若要了解如何在 IoT 中樞和Azure 儲存體帳戶上設定受控識別，請參閱受控識別的 IoT 中樞支援。一旦設定之後，您便可以設定其中一個受控識別，以用於向 Azure 儲存體進行驗證。

注意

驗證類型設定可設定 IoT 中樞驗證 Azure 儲存體帳戶的方式。裝置一律會使用從 IoT 中樞取得的 SAS URI 向Azure 儲存體進行驗證。

下列命令顯示如何設定 IoT 中樞上的檔案上傳設定。為了清楚起見，這些命令會個別顯示，但您通常會發出單一命令，其中包含案例的所有必要參數。包含其在命令列中顯示位置的引號。請勿包含大括號。如需每個參數的詳細資料，請參閱 az iot hub update 命令的 Azure CLI 文件。

下列命令會設定儲存體帳戶和 blob 容器。

az iot hub update --name {your iot hub name} \
    --fileupload-storage-connectionstring "{your storage account connection string}" \
    --fileupload-storage-container-name "{your container name}"

下列命令會將 SAS URI 存留時間設定為預設值 (一小時)。

az iot hub update --name {your iot hub name} \
    --fileupload-sas-ttl 1

下列命令會啟用檔案通知，並將檔案通知屬性設定為其預設值。 (檔案上傳通知存留時間會設定為一小時，而鎖定持續時間會設定為 60 秒。)

az iot hub update --name {your iot hub name} \
    --fileupload-notifications true  \
    --fileupload-notification-max-delivery-count 10 \
    --fileupload-notification-ttl 1 \
    --fileupload-notification-lock-duration 60

下列命令會設定金鑰型驗證：

az iot hub update --name {your iot hub name} \
    --fileupload-storage-auth-type keyBased

下列命令會使用 IoT 中樞的系統指派受控識別來設定驗證。執行此命令之前，您需要為 IoT 中樞啟用系統指派的受控識別，並在 Azure 儲存體帳戶上授與其正確的 RBAC 角色。若要深入了解，請參閱受控識別的 IoT 中樞支援。

az iot hub update --name {your iot hub name} \
    --fileupload-storage-auth-type identityBased \
    --fileupload-storage-identity [system]

下列命令會擷取 IoT 中樞上設定的使用者指派受控識別，並使用其中一個來設定驗證。您必須先在 IoT 中樞上設定使用者指派的受控識別，並在Azure 儲存體帳戶上授與適當的 RBAC 角色，才能使用使用者指派的受控識別進行驗證。如需詳細資料和步驟，請參閱受控識別的 IoT 中樞支援。

若要查詢 IoT 中樞上的使用者指派受控識別，請使用 az iot hub identity show 命令。

az iot hub identity show --name {your iot hub name} --query userAssignedIdentities

此命令會傳回 IoT 中樞上設定的使用者指派受控識別集合。下列輸出顯示包含單一使用者指派受控識別的集合。

{
  "/subscriptions/{your subscription ID}/resourcegroups/{your resource group}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{your user-assigned managed identity name}": 
  {
    "clientId": "<client ID GUID>",
    "principalId": "<principal ID GUID>"
  }
}

下列命令會設定驗證以使用上述的使用者指派身分識別。

az iot hub update --name {your iot hub name} \
    --fileupload-storage-auth-type identityBased \
    --fileupload-storage-identity  "/subscriptions/{your subscription ID}/resourcegroups/{your resource group}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{your user-assigned managed identity name}"

您可以使用下列命令來檢閱 IoT 中樞上的設定︰

az iot hub show --name {your iot hub name}

若要僅檢閱檔案上傳設定，請使用下列命令：

az iot hub show --name {your iot hub name}
    --query '[properties.storageEndpoints, properties.enableFileUploadNotifications, properties.messagingEndpoints.fileNotifications]'

在多數情況下，在 Azure CLI 命令中使用具名參數最簡單；不過，您也可以使用 --set 參數來設定檔案上傳設定。下列命令可協助您了解做法。

az iot hub update --name {your iot hub name} \
  --set properties.storageEndpoints.'$default'.connectionString="{your storage account connection string}"

az iot hub update --name {your iot hub name} \
  --set properties.storageEndpoints.'$default'.containerName="{your storage container name}"

az iot hub update --name {your iot hub name} \
  --set properties.storageEndpoints.'$default'.sasTtlAsIso8601=PT1H0M0S

az iot hub update --name {your iot hub name} \
  --set properties.enableFileUploadNotifications=true

az iot hub update --name {your iot hub name} \
  --set properties.messagingEndpoints.fileNotifications.maxDeliveryCount=10

az iot hub update --name {your iot hub name} \
  --set properties.messagingEndpoints.fileNotifications.ttlAsIso8601=PT1H0M0S

下一步

從裝置上傳檔案概觀
IoT 中樞支援受控識別
檔案上傳操作指南
Azure CLI az iot hub update、az iot hub identity show 和 az iot hub create 命令

使用 Azure CLI 來設定 IoT 中樞檔案上傳

必要條件

登入並設定 Azure 帳戶

擷取您的儲存體帳戶詳細資料

設定 IoT 中樞

下一步

其他資源