Konfigurowanie przekazywania plików usługi IoT Hub przy użyciu interfejsu wiersza polecenia platformy Azure

  • Artykuł

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.

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.

  1. 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.

  2. 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

Następne kroki