Creare un hub IoT con l'API REST del provider di risorse (.NET)

È possibile usare l'API REST del provider di risorse dell'hub IoT per creare e gestire hub IoT di Azure a livello di codice. In questa esercitazione viene illustrato come usare l'API REST del provider di risorse hub IoT per creare un hub IoT da un programma C#.

Nota

Azure offre due modelli di distribuzione per creare e usare le risorse: modello di distribuzione classica e Azure Resource Manager. In questo articolo viene illustrato l'uso del modello di distribuzione Azure Resource Manager.

Per completare l'esercitazione, sono necessari gli elementi seguenti:

  • Visual Studio 2015 o Visual Studio 2017.
  • Un account Azure attivo.
    Se non si ha un account, è possibile crearne uno gratuito in pochi minuti.
  • Azure PowerShell 1.0 o versione successiva.

Prepararsi all'autenticazione delle richieste di Azure Resource Manager

Si devono autenticare tutte le attività da eseguire sulle risorse mediante Gestione risorse di Azure con Azure Active Directory (AD). Il modo più semplice per configurare questa impostazione è usare PowerShell o l’interfaccia della riga di comando di Azure.

Installare i cmdlet di Azure PowerShell prima di continuare.

La procedura seguente illustra come configurare l'autenticazione della password per un'applicazione di AD mediante PowerShell. È possibile eseguire questi comandi in una sessione standard di PowerShell.

  1. Accedere alla sottoscrizione di Azure usando il comando seguente:

    Login-AzureRmAccount
    
  2. Se si usano più sottoscrizioni Azure e si esegue l'accesso ad Azure, è possibile accedere a tutte le sottoscrizioni di Azure associate alle credenziali. Usare il comando seguente per elencare gli account Azure che è possibile usare:

    Get-AzureRMSubscription
    

    Usare il comando seguente per selezionare la sottoscrizione che si vuole usare per eseguire i comandi per gestire l'hub IoT. È possibile usare il nome o l'ID della sottoscrizione dall'output del comando precedente:

    Select-AzureRMSubscription `
        -SubscriptionName "{your subscription name}"
    
  3. Prendere nota dei valori di TenantId e SubscriptionId. Saranno necessari più avanti.

  4. Creare una nuova applicazione Azure Active Directory mediante il comando seguente, sostituendo i segnaposto:

    • {Display name}: un nome visualizzato per l'applicazione, ad esempio MySampleApp.
    • {Home page URL}: l'URL della home page dell'app, ad esempio http://mysampleapp/home. Non è necessario che questo URL punti a un'applicazione reale.
    • {Application identifier}: un identificatore univoco, ad esempio http://mysampleapp. Non è necessario che questo URL punti a un'applicazione reale.
    • {Password}: password da usare per l'autenticazione con l'app.

      New-AzureRmADApplication -DisplayName {Display name} -HomePage {Home page URL} -IdentifierUris {Application identifier} -Password {Password}
      
  5. Annotare l’ ApplicationId dell'applicazione creata. Sarà necessario più avanti.
  6. Creare una nuova entità servizio usando il comando seguente, sostituendo {MyApplicationId} con il valore di ApplicationId del passaggio precedente:

    New-AzureRmADServicePrincipal -ApplicationId {MyApplicationId}
    
  7. Configurare un'assegnazione di ruolo usando il comando seguente, sostituendo {MyApplicationId} con il valore di ApplicationId.

    New-AzureRmRoleAssignment -RoleDefinitionName Owner -ServicePrincipalName {MyApplicationId}
    

A questo punto è terminata la creazione dell'applicazione Azure AD che consentirà di eseguire l'autenticazione dall'applicazione C# personalizzata. Più avanti in questa esercitazione saranno necessari i valori seguenti:

  • TenantId
  • SubscriptionId
  • ApplicationId
  • Password

Preparare il progetto di Visual Studio

  1. In Visual Studio creare un progetto desktop classico di Windows Visual C# usando il modello di progetto App console (.NET Framework). Denominare il progetto CreateIoTHubREST.

  2. In Esplora soluzioni fare clic con il pulsante destro del mouse sul progetto, quindi scegliere Gestisci pacchetti NuGet.

  3. In Gestione pacchetti NuGet selezionare Includi versione preliminare e nella pagina Sfoglia cercare Microsoft.Azure.Management.ResourceManager. Selezionare il pacchetto, fare clic su Installa, in Rivedi modifiche fare clic su OK, quindi fare clic su I Accept (Accetto) per accettare le licenze.

  4. In Gestione pacchetti NuGet cercare Microsoft.IdentityModel.Clients.ActiveDirectory. Fare clic su Installa, in Rivedi modifiche fare clic su OK, quindi fare clic su I Accept (Accetto) per accettare la licenza.

  5. In Program.cs sostituire le istruzioni using esistenti con il codice seguente:

    using System;
    using System.Net.Http;
    using System.Net.Http.Headers;
    using System.Text;
    using Microsoft.Azure.Management.ResourceManager;
    using Microsoft.Azure.Management.ResourceManager.Models;
    using Microsoft.IdentityModel.Clients.ActiveDirectory;
    using Newtonsoft.Json;
    using Microsoft.Rest;
    using System.Linq;
    using System.Threading;
    
  6. In Program.cs aggiungere le seguenti variabili statiche sostituendo i valori dei segnaposto. Nella parte precedente di questa esercitazione si è preso nota di ApplicationId, SubscriptionId, TenantId e Password. Nome gruppo di risorse è il nome del gruppo di risorse che viene usato quando si crea l'hub IoT. È possibile usare un gruppo di risorse preesistente o nuovo. Nome hub IoT è il nome dell'hub IoT creato, ad esempio MioHubIoT. Il nome dell'hub IoT deve essere globalmente univoco. Nome distribuzione è un nome per la distribuzione, ad esempio Deployment_01.

    static string applicationId = "{Your ApplicationId}";
    static string subscriptionId = "{Your SubscriptionId}";
    static string tenantId = "{Your TenantId}";
    static string password = "{Your application Password}";
    
    static string rgName = "{Resource group name}";
    static string iotHubName = "{IoT Hub name including your initials}";
    

    Importante

    L'hub IoT sarà individuabile pubblicamente come endpoint DNS, quindi evitare di indicare informazioni riservate nell'assegnazione del nome.

Ottenere un token di Azure Resource Manager

Azure Active Directory deve autenticare tutte le attività da eseguire sulle risorse con Gestione risorse di Azure. Nell'esempio illustrato di seguito si usa l'autenticazione della password. Per altri approcci, vedere Autenticazione delle richieste di Azure Resource Manager.

  1. Aggiungere il codice seguente al metodo Main in Program.cs per recuperare un token da Azure AD tramite l'id dell'applicazione e la password.

    var authContext = new AuthenticationContext(string.Format  
      ("https://login.microsoftonline.com/{0}", tenantId));
    var credential = new ClientCredential(applicationId, password);
    AuthenticationResult token = authContext.AcquireTokenAsync
      ("https://management.core.windows.net/", credential).Result;
    
    if (token == null)
    {
      Console.WriteLine("Failed to obtain the token");
      return;
    }
    
  2. Creare un oggetto ResourceManagementClient che usa il token aggiungendo il codice seguente alla fine del metodo Main:

    var creds = new TokenCredentials(token.AccessToken);
    var client = new ResourceManagementClient(creds);
    client.SubscriptionId = subscriptionId;
    
  3. Creare o ottenere un riferimento al gruppo di risorse in uso:

    var rgResponse = client.ResourceGroups.CreateOrUpdate(rgName,
        new ResourceGroup("East US"));
    if (rgResponse.Properties.ProvisioningState != "Succeeded")
    {
      Console.WriteLine("Problem creating resource group");
      return;
    }
    

Usare l'API REST del provider di risorse per creare un hub IoT

Usare l'API REST del provider di risorse dell'hub IoT per creare un hub IoT nel gruppo di risorse. È possibile usare l'API REST del provider di risorse anche per apportare modifiche a un hub IoT esistente.

  1. Aggiungere il metodo seguente a Program.cs:

    static void CreateIoTHub(string token)
    {
    
    }
    
  2. Aggiungere il codice seguente al metodo CreateIoTHub. Questo codice crea un oggetto HttpClient con il token di autenticazione nelle intestazioni:

    HttpClient client = new HttpClient();
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);
    
  3. Aggiungere il codice seguente al metodo CreateIoTHub. Questo codice descrive l'hub IoT per creare e genera una rappresentazione JSON. Per un elenco aggiornato delle località in cui è supportato l'hub IoT, vedere lo Stato di Azure:

    var description = new
    {
      name = iotHubName,
      location = "East US",
      sku = new
      {
        name = "S1",
        tier = "Standard",
        capacity = 1
      }
    };
    
    var json = JsonConvert.SerializeObject(description, Formatting.Indented);
    
  4. Aggiungere il codice seguente al metodo CreateIoTHub. Questo codice invia la richiesta REST ad Azure. Il codice verifica quindi la risposta e recupera l'URL da usare per monitorare lo stato dell'attività di distribuzione:

    var content = new StringContent(JsonConvert.SerializeObject(description), Encoding.UTF8, "application/json");
    var requestUri = string.Format("https://management.azure.com/subscriptions/{0}/resourcegroups/{1}/providers/Microsoft.devices/IotHubs/{2}?api-version=2016-02-03", subscriptionId, rgName, iotHubName);
    var result = client.PutAsync(requestUri, content).Result;
    
    if (!result.IsSuccessStatusCode)
    {
      Console.WriteLine("Failed {0}", result.Content.ReadAsStringAsync().Result);
      return;
    }
    
    var asyncStatusUri = result.Headers.GetValues("Azure-AsyncOperation").First();
    
  5. Alla fine del metodo CreateIoTHub aggiungere il codice seguente. Questo codice usa l'indirizzo asyncStatusUri recuperato nel passaggio precedente per attendere il completamento della distribuzione:

    string body;
    do
    {
      Thread.Sleep(10000);
      HttpResponseMessage deploymentstatus = client.GetAsync(asyncStatusUri).Result;
      body = deploymentstatus.Content.ReadAsStringAsync().Result;
    } while (body == "{\"status\":\"Running\"}");
    
  6. Alla fine del metodo CreateIoTHub aggiungere il codice seguente. Questo codice recupera le chiavi dell'hub IoT creato e le visualizza nella console:

    var listKeysUri = string.Format("https://management.azure.com/subscriptions/{0}/resourceGroups/{1}/providers/Microsoft.Devices/IotHubs/{2}/IoTHubKeys/listkeys?api-version=2016-02-03", subscriptionId, rgName, iotHubName);
    var keysresults = client.PostAsync(listKeysUri, null).Result;
    
    Console.WriteLine("Keys: {0}", keysresults.Content.ReadAsStringAsync().Result);
    

Compilare ed eseguire l'applicazione

È ora possibile completare l'applicazione chiamando il metodo CreateIoTHub prima di compilarla ed eseguirla.

  1. Alla fine del metodo Main aggiungere il codice seguente:

    CreateIoTHub(token.AccessToken);
    Console.ReadLine();
    
  2. Fare clic su Compila e quindi su Compila soluzione. Correggere eventuali errori.

  3. Fare clic su Debug e quindi su Avvia debug per eseguire l'applicazione. Potrebbero occorrere alcuni minuti per l'esecuzione della distribuzione.

  4. Per verificare che l'applicazione abbia aggiunto il nuovo hub IoT, visitare il portale di Azure e visualizzare l'elenco delle risorse. In alternativa, usare il cmdlet di PowerShell Get-AzureRmResource.

Nota

Questa applicazione di esempio aggiunge un hub IoT Standard S1 che viene addebitato. Al termine è possibile eliminare l'hub IoT tramite il portale di Azure o usando il cmdlet di PowerShell Remove-AzureRmResource.

Passaggi successivi

Dopo aver distribuito un hub IoT mediante l'API REST del provider di risorse, può essere opportuno approfondire gli argomenti seguenti:

Per altre informazioni sulle attività di sviluppo per l'hub IoT, vedere gli articoli seguenti:

Per altre informazioni sulle funzionalità dell'hub IoT, vedere: