Konfigurowanie przekazywania plików usługi IoT Hub przy użyciu interfejsu wiersza polecenia platformy Azure
W tym artykule pokazano, jak skonfigurować przekazywanie plików w centrum IoT przy użyciu interfejsu wiersza polecenia platformy Azure.
Aby użyć funkcji przekazywania plików w usłudze IoT Hub, musisz najpierw skojarzyć konto usługi Azure Storage i kontener obiektów blob z centrum IoT Hub. Usługa IoT Hub automatycznie generuje identyfikatory URI sygnatur dostępu współdzielonego z uprawnieniami do zapisu w tym kontenerze obiektów blob dla urządzeń do użycia podczas przekazywania plików. Oprócz konta magazynu i kontenera obiektów blob można ustawić czas wygaśnięcia dla identyfikatora URI sygnatury dostępu współdzielonego oraz typ uwierzytelniania używanego przez usługę IoT Hub z usługą Azure Storage. Możesz również skonfigurować ustawienia dla opcjonalnych powiadomień przekazywania plików, które usługa IoT Hub może dostarczać do usług zaplecza.
Wymagania wstępne
Aktywne konto platformy Azure. Jeśli go nie masz, możesz utworzyć bezpłatne konto w zaledwie kilka minut.
Centrum Azure IoT Hub. Jeśli nie masz centrum IoT Hub, możesz użyć polecenia , aby utworzyć centrum IoT hub przy użyciu portalu.
az iot hub create
Konto usługi Azure Storage. Jeśli nie masz konta usługi Azure Storage, możesz go utworzyć przy użyciu interfejsu wiersza polecenia platformy Azure. Aby uzyskać więcej informacji, zobacz temat Tworzenie konta.
Użyj środowiska powłoki Bash w usłudze Azure Cloud Shell. Aby uzyskać więcej informacji, zobacz Szybki start dotyczący powłoki Bash w usłudze Azure Cloud Shell.
Jeśli wolisz uruchamiać polecenia referencyjne interfejsu wiersza polecenia lokalnie, zainstaluj interfejs wiersza polecenia platformy Azure. Jeśli korzystasz z systemu Windows lub macOS, rozważ uruchomienie interfejsu wiersza polecenia platformy Azure w kontenerze Docker. Aby uzyskać więcej informacji, zobacz Jak uruchomić interfejs wiersza polecenia platformy Azure w kontenerze platformy Docker.
Jeśli korzystasz z instalacji lokalnej, zaloguj się do interfejsu wiersza polecenia platformy Azure za pomocą polecenia az login. Aby ukończyć proces uwierzytelniania, wykonaj kroki wyświetlane w terminalu. Aby uzyskać inne opcje logowania, zobacz Logowanie się przy użyciu interfejsu wiersza polecenia platformy Azure.
Po wyświetleniu monitu zainstaluj rozszerzenie interfejsu wiersza polecenia platformy Azure podczas pierwszego użycia. Aby uzyskać więcej informacji na temat rozszerzeń, zobacz Korzystanie z rozszerzeń w interfejsie wiersza polecenia platformy Azure.
Uruchom polecenie az version, aby znaleźć zainstalowane wersje i biblioteki zależne. Aby uaktualnić do najnowszej wersji, uruchom polecenie az upgrade.
Uwaga
W tym artykule jest używana najnowsza wersja rozszerzenia Usługi Azure IoT o nazwie azure-iot
. Starsza wersja nosi nazwę azure-cli-iot-ext
. Jednocześnie powinna być zainstalowana tylko jedna wersja. Możesz użyć polecenia az extension list
, aby zweryfikować aktualnie zainstalowane rozszerzenia.
Użyj az extension remove --name azure-cli-iot-ext
polecenia , aby usunąć starszą wersję rozszerzenia.
Użyj az extension add --name azure-iot
polecenia , aby dodać nową wersję rozszerzenia.
Aby zobaczyć, jakie rozszerzenia zostały zainstalowane, użyj polecenia az extension list
.
Logowanie się i ustawianie konta platformy Azure
Zaloguj się do konta platformy Azure i wybierz subskrypcję. Jeśli używasz usługi Azure Cloud Shell, musisz być już zalogowany; Jednak nadal może być konieczne wybranie subskrypcji platformy Azure, jeśli masz wiele subskrypcji.
W wierszu polecenia uruchom polecenie logowania:
az login
Postępuj zgodnie z instrukcjami w celu uwierzytelnienia przy użyciu kodu i zaloguj się na konto platformy Azure za pośrednictwem przeglądarki internetowej.
Jeśli masz wiele subskrypcji platformy Azure, zalogowanie się do platformy Azure zapewnia dostęp do wszystkich kont platformy Azure skojarzonych z poświadczeniami użytkownika. Użyj następującego polecenia, aby wyświetlić listę kont platformy Azure dostępnych do użycia:
az account list
Użyj następującego polecenia, aby wybrać subskrypcję, której chcesz użyć do uruchomienia poleceń w celu utworzenia centrum IoT. Można użyć nazwy subskrypcji lub identyfikatora z danych wyjściowych poprzedniego polecenia:
az account set --subscription {your subscription name or id}
Pobieranie szczegółów konta magazynu
W poniższych krokach założono, że konto magazynu zostało utworzone przy użyciu modelu wdrażania przy użyciu usługi Resource Manager, a nie klasycznego modelu wdrażania.
Aby skonfigurować przekazywanie plików z urządzeń, potrzebujesz parametry połączenia dla konta usługi Azure Storage. Konto magazynu musi znajdować się w tej samej subskrypcji co centrum IoT. Potrzebna jest również nazwa kontenera obiektów blob na koncie magazynu. Użyj następującego polecenia, aby pobrać klucze konta magazynu:
az storage account show-connection-string --name {your storage account name} \
--resource-group {your storage account resource group}
Parametry połączenia będą podobne do następujących danych wyjściowych:
{
"connectionString": "DefaultEndpointsProtocol=https;EndpointSuffix=core.windows.net;AccountName={your storage account name};AccountKey={your storage account key}"
}
Zanotuj wartość parametru connectionString
. Są one potrzebne w poniższych krokach.
Możesz użyć istniejącego kontenera obiektów blob do przekazywania plików lub utworzyć nowy:
Aby wyświetlić listę istniejących kontenerów obiektów blob na koncie magazynu, użyj następującego polecenia:
az storage container list --connection-string "{your storage account connection string}"
Aby utworzyć kontener obiektów blob na koncie magazynu, użyj następującego polecenia:
az storage container create --name {container name} \ --connection-string "{your storage account connection string}"
Konfigurowanie centrum IoT Hub
Teraz możesz skonfigurować centrum IoT, aby umożliwić przekazywanie plików do centrum IoT Hub przy użyciu szczegółów konta magazynu.
Konfiguracja wymaga następujących wartości:
Kontener magazynu: kontener obiektów blob na koncie usługi Azure Storage w bieżącej subskrypcji platformy Azure do skojarzenia z centrum IoT Hub. W poprzedniej sekcji pobrano niezbędne informacje o koncie magazynu. Usługa IoT Hub automatycznie generuje identyfikatory URI sygnatur dostępu współdzielonego z uprawnieniami do zapisu w tym kontenerze obiektów blob dla urządzeń do użycia podczas przekazywania plików.
Otrzymywanie powiadomień o przekazanych plikach: włączanie lub wyłączanie powiadomień dotyczących przekazywania plików.
Czas wygaśnięcia sygnatury dostępu współdzielonego: to ustawienie jest czasem wygaśnięcia identyfikatorów URI sygnatur dostępu współdzielonego zwracanych do urządzenia przez usługę IoT Hub. Ustaw wartość domyślnie na jedną godzinę.
Domyślny czas wygaśnięcia ustawień powiadomień dotyczących plików: czas wygaśnięcia powiadomienia o przekazaniu pliku przed jego wygaśnięciem. Ustaw wartość na jeden dzień domyślnie.
Maksymalna liczba dostarczania powiadomień o pliku: liczba prób dostarczenia powiadomienia o przekazaniu pliku w usłudze IoT Hub. Domyślnie ustaw wartość 10.
Czas trwania blokady powiadomień o pliku: czas trwania blokady kolejki powiadomień pliku. Domyślnie ustaw wartość 60 sekund.
Typ uwierzytelniania: typ uwierzytelniania usługi IoT Hub do użycia z usługą Azure Storage. To ustawienie określa sposób uwierzytelniania i autoryzacji centrum IoT w usłudze Azure Storage. Wartość domyślna to uwierzytelnianie oparte na kluczach; można jednak użyć tożsamości zarządzanych przypisanych przez system i przypisanych przez użytkownika. Tożsamości zarządzane zapewniają usługom platformy Azure automatycznie zarządzaną tożsamość w usłudze Microsoft Entra ID w bezpieczny sposób. Aby dowiedzieć się, jak skonfigurować tożsamości zarządzane na koncie usługi IoT Hub i azure Storage, zobacz Obsługa tożsamości zarządzanych w usłudze IoT Hub. Po skonfigurowaniu można ustawić jedną z tożsamości zarządzanych do użycia na potrzeby uwierzytelniania w usłudze Azure Storage.
Uwaga
Ustawienie typu uwierzytelniania konfiguruje sposób uwierzytelniania centrum IoT Hub przy użyciu konta usługi Azure Storage. Urządzenia zawsze uwierzytelniają się w usłudze Azure Storage przy użyciu identyfikatora URI sygnatury dostępu współdzielonego uzyskiwanego z centrum IoT.
Poniższe polecenia pokazują, jak skonfigurować ustawienia przekazywania plików w centrum IoT. Te polecenia są wyświetlane oddzielnie w celu zapewnienia przejrzystości, ale zazwyczaj należy wydać jedno polecenie ze wszystkimi wymaganymi parametrami dla danego scenariusza. Dołącz cudzysłowy, w których są wyświetlane w wierszu polecenia. Nie dołączaj nawiasów klamrowych. Więcej szczegółów na temat każdego parametru można znaleźć w dokumentacji interfejsu wiersza polecenia platformy Azure dla polecenia az iot hub update .
Następujące polecenie konfiguruje konto magazynu i kontener obiektów 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}"
Następujące polecenie ustawia czas wygaśnięcia identyfikatora URI sygnatury dostępu współdzielonego na wartość domyślną (jedna godzina).
az iot hub update --name {your iot hub name} \
--fileupload-sas-ttl 1
Następujące polecenie włącza powiadomienia dotyczące plików i ustawia właściwości powiadomienia pliku na wartości domyślne. (Czas przekazywania powiadomień o przekazaniu pliku na żywo jest ustawiony na jedną godzinę, a czas trwania blokady to 60 sekund).
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
Następujące polecenie konfiguruje uwierzytelnianie oparte na kluczach:
az iot hub update --name {your iot hub name} \
--fileupload-storage-auth-type keyBased
Następujące polecenie konfiguruje uwierzytelnianie przy użyciu przypisanej przez system tożsamości zarządzanej centrum IoT Hub. Przed uruchomieniem tego polecenia należy włączyć tożsamość zarządzaną przypisaną przez system dla centrum IoT i przyznać jej prawidłową rolę RBAC na koncie usługi Azure Storage. Aby dowiedzieć się, jak to zrobić, zobacz Obsługa usługi IoT Hub dla tożsamości zarządzanych.
az iot hub update --name {your iot hub name} \
--fileupload-storage-auth-type identityBased \
--fileupload-storage-identity [system]
Następujące polecenia pobierają tożsamości zarządzane przypisane przez użytkownika skonfigurowane w centrum IoT i konfigurują uwierzytelnianie przy użyciu jednego z nich. Aby można było uwierzytelnić tożsamość zarządzaną przypisaną przez użytkownika, należy ją skonfigurować w centrum IoT i przyznać odpowiednią rolę RBAC na koncie usługi Azure Storage. Aby uzyskać więcej szczegółów i kroków, zobacz Obsługa usługi IoT Hub dla tożsamości zarządzanych.
Aby wykonywać zapytania dotyczące tożsamości zarządzanych przypisanych przez użytkownika w centrum IoT, użyj polecenia az iot hub identity show .
az iot hub identity show --name {your iot hub name} --query userAssignedIdentities
Polecenie zwraca kolekcję tożsamości zarządzanych przypisanych przez użytkownika skonfigurowanych w centrum IoT Hub. Poniższe dane wyjściowe przedstawiają kolekcję zawierającą jedną tożsamość zarządzaną przypisaną przez użytkownika.
{
"/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>"
}
}
Następujące polecenie konfiguruje uwierzytelnianie w celu używania tożsamości przypisanej przez użytkownika powyżej.
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}"
Możesz przejrzeć ustawienia w centrum IoT Hub przy użyciu następującego polecenia:
az iot hub show --name {your iot hub name}
Aby przejrzeć tylko ustawienia przekazywania plików, użyj następującego polecenia:
az iot hub show --name {your iot hub name}
--query '[properties.storageEndpoints, properties.enableFileUploadNotifications, properties.messagingEndpoints.fileNotifications]'
W większości sytuacji użycie nazwanych parametrów w poleceniach interfejsu wiersza polecenia platformy Azure jest najłatwiejsze. Można jednak również skonfigurować ustawienia przekazywania plików za pomocą parametru --set
. Poniższe polecenia mogą pomóc zrozumieć, jak to zrobić.
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