Tutorial: Utilizar políticas de alocação personalizadas com o Serviço de Aprovisionamento de Dispositivos (DPS)

As políticas de alocação personalizadas dão-lhe mais controlo sobre a forma como os dispositivos são atribuídos aos seus hubs IoT. Com as políticas de alocação personalizadas, pode definir as suas próprias políticas de alocação quando as políticas fornecidas pelo Hub IoT do Azure Serviço de Aprovisionamento de Dispositivos (DPS) não cumprem os requisitos do seu cenário. Uma política de alocação personalizada é implementada num webhook alojado nas funções do Azure e configurado numa ou mais inscrições individuais e/ou grupos de inscrição. Quando um dispositivo se regista no DPS através de uma entrada de inscrição configurada, o DPS chama o webhook para saber em que hub IoT o dispositivo deve ser registado e, opcionalmente, o respetivo estado inicial. Para saber mais, veja Compreender as políticas de alocação personalizadas.

Este tutorial demonstra uma política de alocação personalizada com uma Função do Azure escrita em C#. Os dispositivos são atribuídos a um dos dois hubs IoT que representam uma Divisão de Torradeiras contoso e uma Divisão de Bombas de Calor da Contoso. Os dispositivos que pedem o aprovisionamento têm de ter um ID de registo com um dos seguintes sufixos a aceitar para o aprovisionamento:

  • -contoso-tstrsd-007 para a Divisão de Torradeiras da Contoso
  • -contoso-hpsd-088 para a Divisão de Bombas de Calor da Contoso

Os dispositivos serão simulados com um exemplo de aprovisionamento incluído no SDK C do Azure IoT.

Neste tutorial, irá fazer o seguinte:

  • Utilize a CLI do Azure para criar uma instância DPS e para criar e ligar dois hubs IoT da divisão Contoso (Divisão de Torradeiras da Contoso e Divisão de Bombas de Calor da Contoso) ao mesmo
  • Criar uma Função do Azure que implementa a política de alocação personalizada
  • Criar um novo grupo de inscrição utiliza a Função do Azure para a política de alocação personalizada
  • Criar chaves simétricas do dispositivo para dois dispositivos simulados
  • Configurar o ambiente de desenvolvimento para o SDK C do Azure IoT
  • Simular os dispositivos e verificar se estão aprovisionados de acordo com o código de exemplo na política de alocação personalizada

Se não tiver uma subscrição do Azure, crie uma conta gratuita do Azure antes de começar.

Pré-requisitos

Os seguintes pré-requisitos destinam-se a um ambiente de desenvolvimento do Windows. Para Linux ou macOS, veja a secção adequada em Preparar o ambiente de desenvolvimento na documentação do SDK.

Criar o serviço de aprovisionamento e dois hubs IoT divisionais

Nesta secção, vai utilizar o Cloud Shell do Azure para criar um serviço de aprovisionamento e dois hubs IoT que representam a Divisão de Torradeiras da Contoso e a divisão Bombas de Calor da Contoso.

Dica

Os comandos utilizados neste tutorial criam o serviço de aprovisionamento e outros recursos na localização E.U.A. Oeste. Recomendamos que crie os seus recursos na região mais próxima de si que suporte o Serviço de Aprovisionamento de Dispositivos. Pode ver uma lista das localizações disponíveis ao executar o comando az provider show --namespace Microsoft.Devices --query "resourceTypes[?resourceType=='ProvisioningServices'].locations | [0]" --out table ou ao aceder à página Estado do Azure e procurar "Serviço Aprovisionamento de Dispositivos". Nos comandos, as localizações podem ser especificadas num formato de palavra ou de várias palavras; por exemplo: westus, E.U.A. Oeste, E.U.A. Oeste, etc. O valor não é sensível às maiúsculas e minúsculas. Se especificar a localização com o formato de várias palavras, ponha o valor entre aspas, como, por exemplo, -- location "West US".

  1. Utilize o Azure Cloud Shell para criar um grupo de recursos com o comando az group create. Um grupo de recursos do Azure é um contentor lógico no qual os recursos do Azure são implementados e geridos.

    O exemplo seguinte cria um grupo de recursos com o nome contoso-us-resource-group na região westus . Recomendamos que utilize este grupo para todos os recursos criados neste tutorial. Esta abordagem facilitará a limpeza depois de terminar.

    az group create --name contoso-us-resource-group --location westus
    
  2. Utilize o Azure Cloud Shell para criar um serviço de aprovisionamento de dispositivos (DPS) com o comando az iot dps create. O serviço de aprovisionamento será adicionado ao contoso-us-resource-group.

    O exemplo seguinte cria um serviço de aprovisionamento denominado contoso-provisioning-service-1098 na localização westus . Tem de utilizar um nome de serviço exclusivo. Crie o seu próprio sufixo no nome do serviço em vez de 1098.

    az iot dps create --name contoso-provisioning-service-1098 --resource-group contoso-us-resource-group --location westus
    

    Este comando pode demorar alguns minutos a ser concluído.

  3. Utilize o Azure Cloud Shell para criar o hub IoT da Divisão de Torradeiras da Contoso com o comando az iot hub create. O hub IoT será adicionado ao contoso-us-resource-group.

    O exemplo seguinte cria um hub IoT com o nome contoso-toasters-hub-1098 na localização westus . Tem de utilizar um nome de hub exclusivo. Crie o seu próprio sufixo no nome do hub no lugar 1098.

    Atenção

    O código de função do Azure de exemplo para a política de alocação personalizada requer a subcadeia -toasters- no nome do hub. Certifique-se de que utiliza um nome que contém as subcadeias de torradeiras necessárias.

    az iot hub create --name contoso-toasters-hub-1098 --resource-group contoso-us-resource-group --location westus --sku S1
    

    Este comando pode demorar alguns minutos a ser concluído.

  4. Utilize o Azure Cloud Shell para criar o hub IoT da Divisão de Bombas de Calor da Contoso com o comando az iot hub create. Este hub IoT também será adicionado ao contoso-us-resource-group.

    O exemplo seguinte cria um hub IoT com o nome contoso-heatpumps-hub-1098 na localização westus . Tem de utilizar um nome de hub exclusivo. Crie o seu próprio sufixo no nome do hub no lugar 1098.

    Atenção

    O código de função do Azure de exemplo para a política de alocação personalizada requer a subcadeia -heatpumps- no nome do hub. Certifique-se de que utiliza um nome que contém a subcadeia de lâmpadas térmicas necessária.

    az iot hub create --name contoso-heatpumps-hub-1098 --resource-group contoso-us-resource-group --location westus --sku S1
    

    Este comando pode demorar alguns minutos a ser concluído.

  5. Os hubs IoT têm de estar ligados ao recurso DPS.

    Execute os dois comandos seguintes para obter as cadeias de ligação dos hubs que criou. Substitua os nomes dos recursos do hub pelos nomes que escolheu em cada comando:

    hubToastersConnectionString=$(az iot hub connection-string show --hub-name contoso-toasters-hub-1098 --key primary --query connectionString -o tsv)
    hubHeatpumpsConnectionString=$(az iot hub connection-string show --hub-name contoso-heatpumps-hub-1098 --key primary --query connectionString -o tsv)
    

    Execute os seguintes comandos para ligar os hubs ao recurso DPS. Substitua o nome do recurso DPS pelo nome que escolheu em cada comando:

    az iot dps linked-hub create --dps-name contoso-provisioning-service-1098 --resource-group contoso-us-resource-group --connection-string $hubToastersConnectionString --location westus
    az iot dps linked-hub create --dps-name contoso-provisioning-service-1098 --resource-group contoso-us-resource-group --connection-string $hubHeatpumpsConnectionString --location westus
    

Criar a função de alocação personalizada

Nesta secção, vai criar uma função do Azure que implementa a sua política de alocação personalizada. Esta função decide para que hub IoT divisional deve ser registado um dispositivo com base no facto de o respetivo ID de registo conter a cadeia -contoso-tstrsd-007 ou -contoso-hpsd-088. Também define o estado inicial do dispositivo duplo com base no facto de o dispositivo ser uma torradeira ou uma bomba de calor.

  1. Inicie sessão no portal do Azure. Na home page, selecione + Criar um recurso.

  2. Na caixa de pesquisa Procurar no Marketplace , escreva "Aplicação de Funções". Na lista pendente, selecione Aplicação de Funções e, em seguida, selecione Criar.

  3. Na página Criação da Aplicação de Funções , no separador Noções Básicas , introduza as seguintes definições para a sua nova aplicação de funções e selecione Rever + criar:

    Grupo de Recursos: selecione o grupo contoso-us-resource para manter todos os recursos criados neste tutorial em conjunto.

    Nome da Aplicação de Funções: introduza um nome exclusivo da aplicação de funções. Este exemplo utiliza contoso-function-app-1098.

    Publicar: verifique se o Código está selecionado.

    Pilha de Runtime: selecione .NET no menu pendente.

    Versão: selecione 3.1 no menu pendente.

    Região: selecione a mesma região que o grupo de recursos. Este exemplo utiliza E.U.A. Oeste.

    Nota

    Por predefinição, o Application Insights está ativado. O Application Insights não é necessário para este tutorial, mas pode ajudá-lo a compreender e investigar quaisquer problemas que encontre com a alocação personalizada. Se preferir, pode desativar o Application Insights ao selecionar o separador Monitorização e, em seguida, selecionar Não para Ativar o Application Insights.

    Criar uma Aplicação de Funções do Azure para alojar a função de alocação personalizada

  4. Na página Resumo , selecione Criar para criar a aplicação de funções. A implementação poderá demorar vários minutos. Quando terminar, selecione Ir para recurso.

  5. No painel esquerdo da página Descrição geral da aplicação de funções, selecione Funções e, em seguida, + Criar para adicionar uma nova função.

  6. Na página Criar função , certifique-se de que o Ambiente de desenvolvimento está definido como Desenvolver no portal. Em seguida, selecione o modelo Acionador HTTP seguido do botão Criar .

  7. Quando a função HttpTrigger1 for aberta, selecione Código + Teste no painel esquerdo. Isto permite-lhe editar o código da função. O ficheiro de código run.csx deve ser aberto para edição.

  8. Referenciar os pacotes NuGet necessários. Para criar o dispositivo duplo inicial, a função de alocação personalizada utiliza classes definidas em dois pacotes NuGet que têm de ser carregados para o ambiente de alojamento. Com Funções do Azure, os pacotes NuGet são referenciados através de um ficheiro function.proj. Neste passo, vai guardar e carregar um ficheiro function.proj para as assemblagens necessárias. Para obter mais informações, veja Using NuGet packages with Funções do Azure (Utilizar pacotes NuGet com Funções do Azure).

    1. Copie as seguintes linhas para o seu editor favorito e guarde o ficheiro no seu computador como function.proj.

      <Project Sdk="Microsoft.NET.Sdk">  
          <PropertyGroup>  
              <TargetFramework>netstandard2.0</TargetFramework>  
          </PropertyGroup>  
          <ItemGroup>  
              <PackageReference Include="Microsoft.Azure.Devices.Provisioning.Service" Version="1.18.1" />
              <PackageReference Include="Microsoft.Azure.Devices.Shared" Version="1.30.1" />
          </ItemGroup>  
      </Project>
      
    2. Selecione o botão Carregar localizado acima do editor de código para carregar o ficheiro function.proj . Depois de carregar, selecione o ficheiro no editor de código com a caixa pendente para verificar o conteúdo.

    3. Selecione o ficheiro function.proj no editor de código e verifique o respetivo conteúdo. Se o ficheiro function.proj estiver vazio, copie as linhas acima para o ficheiro e guarde-o. (Por vezes, o carregamento cria o ficheiro sem carregar o conteúdo.)

  9. Certifique-se de que run.csx para HttpTrigger1 está selecionado no editor de código. Substitua o código da função HttpTrigger1 pelo seguinte código e selecione Guardar:

    #r "Newtonsoft.Json"
    
    using System.Net;
    using Microsoft.AspNetCore.Mvc;
    using Microsoft.Extensions.Primitives;
    using Newtonsoft.Json;
    
    using Microsoft.Azure.Devices.Shared;               // For TwinCollection
    using Microsoft.Azure.Devices.Provisioning.Service; // For TwinState
    
    public static async Task<IActionResult> Run(HttpRequest req, ILogger log)
    {
        log.LogInformation("C# HTTP trigger function processed a request.");
    
        // Get request body
        string requestBody = await new StreamReader(req.Body).ReadToEndAsync();
        dynamic data = JsonConvert.DeserializeObject(requestBody);
    
        log.LogInformation("Request.Body:...");
        log.LogInformation(requestBody);
    
        // Get registration ID of the device
        string regId = data?.deviceRuntimeContext?.registrationId;
    
        string message = "Uncaught error";
        bool fail = false;
        ResponseObj obj = new ResponseObj();
    
        if (regId == null)
        {
            message = "Registration ID not provided for the device.";
            log.LogInformation("Registration ID : NULL");
            fail = true;
        }
        else
        {
            string[] hubs = data?.linkedHubs?.ToObject<string[]>();
    
            // Must have hubs selected on the enrollment
            if (hubs == null)
            {
                message = "No hub group defined for the enrollment.";
                log.LogInformation("linkedHubs : NULL");
                fail = true;
            }
            else
            {
                // This is a Contoso Toaster Model 007
                if (regId.Contains("-contoso-tstrsd-007"))
                {
                    //Find the "-toasters-" IoT hub configured on the enrollment
                    foreach(string hubString in hubs)
                    {
                        if (hubString.Contains("-toasters-"))
                            obj.iotHubHostName = hubString;
                    }
    
                    if (obj.iotHubHostName == null)
                    {
                        message = "No toasters hub found for the enrollment.";
                        log.LogInformation(message);
                        fail = true;
                    }
                    else
                    {
                        // Specify the initial tags for the device.
                        TwinCollection tags = new TwinCollection();
                        tags["deviceType"] = "toaster";
    
                        // Specify the initial desired properties for the device.
                        TwinCollection properties = new TwinCollection();
                        properties["state"] = "ready";
                        properties["darknessSetting"] = "medium";
    
                        // Add the initial twin state to the response.
                        TwinState twinState = new TwinState(tags, properties);
                        obj.initialTwin = twinState;
                    }
                }
                // This is a Contoso Heat pump Model 008
                else if (regId.Contains("-contoso-hpsd-088"))
                {
                    //Find the "-heatpumps-" IoT hub configured on the enrollment
                    foreach(string hubString in hubs)
                    {
                        if (hubString.Contains("-heatpumps-"))
                            obj.iotHubHostName = hubString;
                    }
    
                    if (obj.iotHubHostName == null)
                    {
                        message = "No heat pumps hub found for the enrollment.";
                        log.LogInformation(message);
                        fail = true;
                    }
                    else
                    {
                        // Specify the initial tags for the device.
                        TwinCollection tags = new TwinCollection();
                        tags["deviceType"] = "heatpump";
    
                        // Specify the initial desired properties for the device.
                        TwinCollection properties = new TwinCollection();
                        properties["state"] = "on";
                        properties["temperatureSetting"] = "65";
    
                        // Add the initial twin state to the response.
                        TwinState twinState = new TwinState(tags, properties);
                        obj.initialTwin = twinState;
                    }
                }
                // Unrecognized device.
                else
                {
                    fail = true;
                    message = "Unrecognized device registration.";
                    log.LogInformation("Unknown device registration");
                }
            }
        }
    
        log.LogInformation("\nResponse");
        log.LogInformation((obj.iotHubHostName != null) ? JsonConvert.SerializeObject(obj) : message);
    
        return (fail)
            ? new BadRequestObjectResult(message) 
            : (ActionResult)new OkObjectResult(obj);
    }
    
    public class ResponseObj
    {
        public string iotHubHostName {get; set;}
        public TwinState initialTwin {get; set;}
    }
    

Criar a inscrição

Nesta secção, irá criar um novo grupo de inscrição que utiliza a política de alocação personalizada. Para simplificar, este tutorial utiliza o atestado de chave simétrica com a inscrição. Para uma solução mais segura, considere utilizar o atestado de certificado X.509 com uma cadeia de confiança.

  1. Ainda no portal do Azure, abra o serviço de aprovisionamento.

  2. Selecione Gerir inscrições no painel esquerdo e, em seguida, selecione o botão Adicionar grupo de inscrição na parte superior da página.

  3. Em Adicionar Grupo de Inscrição, introduza as seguintes informações e selecione o botão Guardar .

    Nome do grupo: introduza contoso-custom-allocated-devices.

    Tipo de Atestado: selecione Chave Simétrica.

    Gerar Chaves Automaticamente: esta caixa de verificação já deve estar selecionada.

    Selecione como pretende atribuir dispositivos a hubs: selecione Personalizado (Utilizar a Função do Azure).

    Subscrição: selecione a subscrição onde criou a Função do Azure.

    Aplicação de Funções: selecione a aplicação de funções pelo nome. contoso-function-app-1098 foi utilizado neste exemplo.

    Função: selecione a função HttpTrigger1 .

    Adicionar grupo de inscrição de alocação personalizado para atestado de chave simétrica

  4. Depois de guardar a inscrição, reabra-a e tome nota da Chave Primária. Primeiro tem de guardar a inscrição para que as chaves tenham sido geradas. Esta chave será utilizada para gerar chaves de dispositivo exclusivas para dispositivos simulados mais tarde.

Derivar chaves de dispositivo exclusivas

Os dispositivos não utilizam diretamente a chave simétrica principal do grupo de inscrição. Em vez disso, utiliza a chave primária para derivar uma chave de dispositivo para cada dispositivo. Nesta secção, vai criar duas chaves de dispositivo exclusivas. Será utilizada uma chave para um dispositivo de torradeira simulada. A outra chave será utilizada para um dispositivo de bomba de calor simulada.

Para derivar a chave do dispositivo, utilize o grupo de inscrição Chave Primária que anotou anteriormente para calcular o HMAC-SHA256 do ID de registo do dispositivo para cada dispositivo e converter o resultado no formato Base64. Para obter mais informações sobre como criar chaves de dispositivo derivadas com grupos de inscrição, veja a secção de inscrições de grupo do atestado de chave simétrica.

Para o exemplo neste tutorial, utilize os seguintes dois IDs de registo de dispositivos e calcule uma chave de dispositivo para ambos os dispositivos. Ambos os IDs de registo têm um sufixo válido para trabalhar com o código de exemplo para a política de alocação personalizada:

  • breakroom499-contoso-tstrsd-007
  • mainbuilding167-contoso-hpsd-088

A extensão IoT para a CLI do Azure fornece o iot dps enrollment-group compute-device-key comando para gerar chaves de dispositivo derivadas. Este comando pode ser utilizado em sistemas Baseados em Windows ou Linux, a partir do PowerShell ou de uma shell do Bash.

Substitua o valor do --key argumento pela Chave Primária do grupo de inscrição.

az iot dps enrollment-group compute-device-key --key oiK77Oy7rBw8YB6IS6ukRChAw+Yq6GC61RMrPLSTiOOtdI+XDu0LmLuNm11p+qv2I+adqGUdZHm46zXAQdZoOA== --registration-id breakroom499-contoso-tstrsd-007

"JC8F96eayuQwwz+PkE7IzjH2lIAjCUnAa61tDigBnSs="
az iot dps compute-device-key --key oiK77Oy7rBw8YB6IS6ukRChAw+Yq6GC61RMrPLSTiOOtdI+XDu0LmLuNm11p+qv2I+adqGUdZHm46zXAQdZoOA== --registration-id mainbuilding167-contoso-hpsd-088

"6uejA9PfkQgmYylj8Zerp3kcbeVrGZ172YLa7VSnJzg="

Nota

Também pode fornecer o ID do grupo de inscrição em vez da chave simétrica ao iot dps enrollment-group compute-device-key comando . Por exemplo:

az iot dps enrollment-group compute-device-key -g contoso-us-resource-group --dps-name contoso-provisioning-service-1098 --enrollment-id contoso-custom-allocated-devices --registration-id breakroom499-contoso-tstrsd-007

Os dispositivos simulados utilizarão as chaves de dispositivo derivadas com cada ID de registo para executar o atestado de chave simétrica.

Preparar um ambiente de programação para o SDK C do Azure IoT

Nesta secção, vai preparar o ambiente de desenvolvimento utilizado para criar o SDK C do Azure IoT. O SDK inclui o código de exemplo para o dispositivo simulado. Esse dispositivo simulado irá tentar fazer o aprovisionamento durante a respetiva sequência de arranque.

Esta secção está orientada para uma estação de trabalho baseada no Windows. Para obter um exemplo do Linux, veja a configuração das VMs no Tutorial: Aprovisionar para latência geográfica.

  1. Transfira o sistema de compilação CMake.

    É importante que os pré-requisitos do Visual Studio (Visual Studio e a carga de trabalho "Desenvolvimento do ambiente de trabalho com C++") sejam instalados no seu computador , antes de iniciar a CMake instalação. Depois de os pré-requisitos estarem assegurados e a transferência verificada, instale o sistema de compilação CMake.

  2. Localize o nome da etiqueta para a versão mais recente do SDK.

  3. Abra uma linha de comandos ou a shell do Git Bash. Execute os seguintes comandos para clonar a versão mais recente do repositório do GitHub do SDK C do Azure IoT . Utilize a etiqueta que encontrou no passo anterior como o valor do -b parâmetro :

    git clone -b <release-tag> https://github.com/Azure/azure-iot-sdk-c.git
    cd azure-iot-sdk-c
    git submodule update --init
    

    Esta operação deve demorar vários minutos a ser concluída.

  4. Crie um subdiretório cmake no diretório de raiz do repositório git e navegue para essa pasta. Execute os seguintes comandos a azure-iot-sdk-c partir do diretório:

    mkdir cmake
    cd cmake
    
  5. Execute o seguinte comando para compilar uma versão do SDK específica da plataforma de cliente de desenvolvimento. Será gerada uma solução do Visual Studio para o dispositivo simulado no diretório cmake.

    cmake -Dhsm_type_symm_key:BOOL=ON -Duse_prov_client:BOOL=ON  ..
    

    Se cmake não encontrar o compilador C++, poderá ver erros de compilação ao executar o comando . Se isso acontecer, experimente executar o comando na linha de comandos do Visual Studio.

    Assim que a compilação for concluída com êxito, as últimas linhas de saída terão um aspeto semelhante ao seguinte:

    $ cmake -Dhsm_type_symm_key:BOOL=ON -Duse_prov_client:BOOL=ON  ..
    -- Building for: Visual Studio 15 2017
    -- Selecting Windows SDK version 10.0.16299.0 to target Windows 10.0.17134.
    -- The C compiler identification is MSVC 19.12.25835.0
    -- The CXX compiler identification is MSVC 19.12.25835.0
    
    ...
    
    -- Configuring done
    -- Generating done
    -- Build files have been written to: E:/IoT Testing/azure-iot-sdk-c/cmake
    

Simular os dispositivos

Nesta secção, vai atualizar um exemplo de aprovisionamento com o nome prov_dev_client_sample localizado no SDK C do Azure IoT que configurou anteriormente.

Este código de exemplo simula uma sequência de arranque do dispositivo que envia o pedido de aprovisionamento para a instância do Serviço Aprovisionamento de Dispositivos. A sequência de arranque fará com que o dispositivo de torradeira seja reconhecido e atribuído ao hub IoT com a política de alocação personalizada.

  1. Na portal do Azure, selecione o separador Descrição geral do Serviço Aprovisionamento de Dispositivos e anote o valor Âmbito do ID.

    Extrair informações de ponto final do Serviço Aprovisionamento de Dispositivos do painel do portal

  2. No Visual Studio, abra o ficheiro de solução azure_iot_sdks.sln que foi gerado ao executar o CMake anteriormente. O ficheiro de solução deve estar na seguinte localização:

    azure-iot-sdk-c\cmake\azure_iot_sdks.sln
    
  3. Na janela de Explorador de Soluções do Visual Studio, navegue para a pasta Provision_Samples. Expanda o projeto de exemplo com o nome prov_dev_client_sample. Expanda Ficheiros de Origem e abra prov_dev_client_sample.c.

  4. Localize a constante id_scope e substitua o valor pelo seu Âmbito do ID que copiou anteriormente.

    static const char* id_scope = "0ne00002193";
    
  5. Localize a definição da função main() no mesmo ficheiro. Certifique-se de que a variável hsm_type está definida como SECURE_DEVICE_TYPE_SYMMETRIC_KEY, conforme mostrado abaixo:

    SECURE_DEVICE_TYPE hsm_type;
    //hsm_type = SECURE_DEVICE_TYPE_TPM;
    //hsm_type = SECURE_DEVICE_TYPE_X509;
    hsm_type = SECURE_DEVICE_TYPE_SYMMETRIC_KEY;
    
  6. Na função main() , localize a chamada para Prov_Device_Register_Device(). Imediatamente antes dessa chamada, adicione as seguintes linhas de código que utilizam Prov_Device_Set_Provisioning_Payload() para transmitir um payload JSON personalizado durante o aprovisionamento. Isto pode ser utilizado para fornecer mais informações às suas funções de alocação personalizadas. Isto também pode ser utilizado para transmitir o tipo de dispositivo em vez de examinar o ID de registo. Para obter mais informações sobre como enviar e receber payloads de dados personalizados com o DPS, veja Como transferir payloads entre dispositivos e DPS.

    // An example custom payload
    const char* custom_json_payload = "{\"MyDeviceFirmwareVersion\":\"12.0.2.5\",\"MyDeviceProvisioningVersion\":\"1.0.0.0\"}";
    
    prov_device_result = Prov_Device_Set_Provisioning_Payload(prov_device_handle, custom_json_payload);
    if (prov_device_result != PROV_DEVICE_RESULT_OK)
    {
        (void)printf("\r\nFailure setting provisioning payload: %s\r\n", MU_ENUM_TO_STRING(PROV_DEVICE_RESULT, prov_device_result));
    }
    
  7. Clique com o botão direito do rato no projeto prov_dev_client_sample e selecione Definir como Projeto de Arranque.

Simular o dispositivo de torradeira contoso

  1. Para simular o dispositivo de torradeira, localize a chamada para prov_dev_set_symmetric_key_info() em prov_dev_client_sample.c , que é comentada.

    // Set the symmetric key if using they auth type
    //prov_dev_set_symmetric_key_info("<symm_registration_id>", "<symmetric_Key>");
    

    Anule o comentário da chamada da função e substitua os valores do marcador de posição (incluindo os parênteses angulares) pelo ID de registo da torradeira e a chave de dispositivo derivada que gerou anteriormente. O valor da chave JC8F96eayuQwwz+PkE7IzjH2lIAjCUnAa61tDigBnSs= mostrado abaixo só é dado como exemplo.

    // Set the symmetric key if using they auth type
    prov_dev_set_symmetric_key_info("breakroom499-contoso-tstrsd-007", "JC8F96eayuQwwz+PkE7IzjH2lIAjCUnAa61tDigBnSs=");
    

    Guarde o ficheiro.

  2. No menu do Visual Studio, selecione Depurar>Iniciar sem depurar para executar a solução. Na linha de comandos para reconstruir o projeto, selecione Sim, para reconstruir o projeto antes de ser executado.

    O seguinte resultado é um exemplo do dispositivo de torradeira simulada a arrancar com êxito e a ligar-se à instância do serviço de aprovisionamento para ser atribuído ao hub IoT de torradeiras pela política de alocação personalizada:

    Provisioning API Version: 1.8.0
    
    Registering Device
    
    Provisioning Status: PROV_DEVICE_REG_STATUS_CONNECTED
    Provisioning Status: PROV_DEVICE_REG_STATUS_ASSIGNING
    Provisioning Status: PROV_DEVICE_REG_STATUS_ASSIGNING
    
    Registration Information received from service: contoso-toasters-hub-1098.azure-devices.net, deviceId: breakroom499-contoso-tstrsd-007
    
    Press enter key to exit:
    

    O resultado seguinte é o resultado de registo de exemplo do código de função de alocação personalizado em execução para o dispositivo de torradeira. Repare que um hub está selecionado com êxito para um dispositivo de torradeira. Repare também na payload propriedade que contém o conteúdo JSON personalizado que adicionou ao código. Esta opção está disponível para o seu código utilizar no deviceRuntimeContext.

    Este registo está disponível ao clicar em Registos no código de função no portal:

    2022-08-03T20:34:41.178 [Information] Executing 'Functions.HttpTrigger1' (Reason='This function was programmatically called via the host APIs.', Id=12950752-6d75-4f41-844b-c253a6653d4f)
    2022-08-03T20:34:41.340 [Information] C# HTTP trigger function processed a request.
    2022-08-03T20:34:41.341 [Information] Request.Body:...
    2022-08-03T20:34:41.341 [Information] {"enrollmentGroup":{"enrollmentGroupId":"contoso-custom-allocated-devices","attestation":{"type":"symmetricKey"},"capabilities":{"iotEdge":false},"etag":"\"0000f176-0000-0700-0000-62eaad1e0000\"","provisioningStatus":"enabled","reprovisionPolicy":{"updateHubAssignment":true,"migrateDeviceData":true},"createdDateTimeUtc":"2022-08-03T17:15:10.8464255Z","lastUpdatedDateTimeUtc":"2022-08-03T17:15:10.8464255Z","allocationPolicy":"custom","iotHubs":["contoso-toasters-hub-1098.azure-devices.net","contoso-heatpumps-hub-1098.azure-devices.net"],"customAllocationDefinition":{"webhookUrl":"https://contoso-function-app-1098.azurewebsites.net/api/HttpTrigger1?****","apiVersion":"2021-10-01"}},"deviceRuntimeContext":{"registrationId":"breakroom499-contoso-tstrsd-007","currentIotHubHostName":"contoso-toasters-hub-1098.azure-devices.net","currentDeviceId":"breakroom499-contoso-tstrsd-007","symmetricKey":{},"payload":{"MyDeviceFirmwareVersion":"12.0.2.5","MyDeviceProvisioningVersion":"1.0.0.0"}},"linkedHubs":["contoso-toasters-hub-1098.azure-devices.net","contoso-heatpumps-hub-1098.azure-devices.net"]}
    2022-08-03T20:34:41.382 [Information] Response
    2022-08-03T20:34:41.398 [Information] {"iotHubHostName":"contoso-toasters-hub-1098.azure-devices.net","initialTwin":{"properties":{"desired":{"state":"ready","darknessSetting":"medium"}},"tags":{"deviceType":"toaster"}}}
    2022-08-03T20:34:41.399 [Information] Executed 'Functions.HttpTrigger1' (Succeeded, Id=12950752-6d75-4f41-844b-c253a6653d4f, Duration=227ms)
    

Simular o dispositivo de bomba de calor da Contoso

  1. Para simular o dispositivo da bomba de calor, atualize a chamada para prov_dev_set_symmetric_key_info() em prov_dev_client_sample.c novamente com o ID de registo da bomba de calor e a chave de dispositivo derivada que gerou anteriormente. O valor da chave 6uejA9PfkQgmYylj8Zerp3kcbeVrGZ172YLa7VSnJzg= mostrado abaixo também é dado como exemplo.

    // Set the symmetric key if using they auth type
    prov_dev_set_symmetric_key_info("mainbuilding167-contoso-hpsd-088", "6uejA9PfkQgmYylj8Zerp3kcbeVrGZ172YLa7VSnJzg=");
    

    Guarde o ficheiro.

  2. No menu do Visual Studio, selecione Depurar>Iniciar sem depurar para executar a solução. Na linha de comandos para reconstruir o projeto, selecione Sim para reconstruir o projeto antes de ser executado.

    A saída seguinte é um exemplo do dispositivo de bomba de calor simulada que arranca e liga com êxito à instância do serviço de aprovisionamento a atribuir ao hub IoT das bombas de calor da Contoso pela política de alocação personalizada:

    Provisioning API Version: 1.8.0
    
    Registering Device
    
    Provisioning Status: PROV_DEVICE_REG_STATUS_CONNECTED
    Provisioning Status: PROV_DEVICE_REG_STATUS_ASSIGNING
    Provisioning Status: PROV_DEVICE_REG_STATUS_ASSIGNING
    
    Registration Information received from service: contoso-heatpumps-hub-1098.azure-devices.net, deviceId: mainbuilding167-contoso-hpsd-088
    
    Press enter key to exit:
    

Resolver problemas de políticas de alocação personalizadas

A tabela seguinte mostra os cenários esperados e os códigos de erro de resultados que poderá receber. Utilize esta tabela para ajudar a resolver falhas de políticas de alocação personalizadas com o seu Funções do Azure.

Scenario Resultado do registo do Serviço de Aprovisionamento Resultados do SDK de Aprovisionamento
O webhook devolve 200 OK com "iotHubHostName" definido como um nome de anfitrião do hub IoT válido Estado do resultado: Atribuído O SDK devolve PROV_DEVICE_RESULT_OK juntamente com as informações do hub
O webhook devolve 200 OK com "iotHubHostName" presente na resposta, mas definido como uma cadeia vazia ou nulo Estado do resultado: Falha

Código de erro: CustomAllocationIotHubNotSpecified (400208)
O SDK devolve PROV_DEVICE_RESULT_HUB_NOT_SPECIFIED
O webhook devolve 401 Não Autorizado Estado do resultado: Falha

Código de erro: CustomAllocationUnauthorizedAccess (400209)
O SDK devolve PROV_DEVICE_RESULT_UNAUTHORIZED
Foi criada uma Inscrição Individual para desativar o dispositivo Estado do resultado: Desativado O SDK devolve PROV_DEVICE_RESULT_DISABLED
O webhook devolve o código >de erro = 429 A orquestração do DPS repetirá várias vezes. A política de repetição está atualmente:

  - Contagem de repetições: 10
  - Intervalo inicial: 1 s
  - Incremento: 9 s
O SDK ignorará o erro e submeterá outra mensagem de estado get na hora especificada
O webhook devolve qualquer outro código de estado Estado do resultado: Falha

Código de erro: CustomAllocationFailed (400207)
O SDK devolve PROV_DEVICE_RESULT_DEV_AUTH_ERROR

Limpar os recursos

Se pretender continuar a trabalhar com os recursos criados neste tutorial, pode deixá-los. Se não planear continuar a utilizar os recursos, utilize os seguintes passos para eliminar todos os recursos criados neste tutorial para evitar custos desnecessários.

Os passos aqui pressupõem que criou todos os recursos neste tutorial, conforme indicado no mesmo grupo de recursos com o nome contoso-us-resource-group.

Importante

A eliminação de um grupo de recursos é irreversível. O grupo de recursos e todos os recursos nele contidos são eliminados permanentemente. Confirme que não elimina acidentalmente o grupo de recursos ou recursos errados. Se tiver criado o Hub IoT no interior de um grupo de recursos existente que contenha recursos que pretende manter, elimine apenas o recurso do Hub IoT, em vez de eliminar o grupo de recursos.

Para eliminar o grupo de recursos por nome:

  1. Inicie sessão no Portal do Azure e selecione Grupos de recursos.

  2. Na caixa de texto Filtrar por nome... , escreva o nome do grupo de recursos que contém os seus recursos, contoso-us-resource-group.

  3. À direita do grupo de recursos na lista de resultados, selecione ... e, em seguida, Eliminar grupo de recursos.

  4. Ser-lhe-á pedido para confirmar a eliminação do grupo de recursos. Escreva novamente o nome do grupo de recursos para confirmar e, em seguida, selecione Eliminar. Após alguns instantes, o grupo de recursos e todos os recursos contidos no mesmo são eliminados.

Passos seguintes

Para saber mais sobre as políticas de alocação personalizadas, consulte