Como criar funções definidas pelo usuário em Gêmeos Digitais do Azure

Importante

Uma nova versão do serviço dos Gêmeos Digitais do Azure foi lançada. À luz dos recursos expandidos do novo serviço, o serviço original dos Gêmeos Digitais do Azure (descrito neste conjunto de documentação) foi desativado.

Para exibir a documentação do novo serviço, visite a documentação ativa dos Gêmeos Digitais do Azure.

As funções definidas pelo usuário permitem que o usuário execute uma lógica personalizada em relação às mensagens de telemetria recebidas e aos metadados de grafo espacial. Os usuários também podem enviar eventos para pontos de extremidade pré-definidos.

Este guia apresenta um exemplo que demonstra como detectar e alertar sobre qualquer leitura que exceda uma determinada temperatura dos eventos de temperatura recebidos.

Nos exemplos a seguir, YOUR_MANAGEMENT_API_URL refere-se ao URI de APIs de Gêmeos Digitais:

https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/api/v1.0

Nome	Substitua por
NOME_DA_SUA_INSTÂNCIA	O nome da sua instância de Gêmeos Digitais do Azure
SUA_LOCALIZAÇÃO	A região em que sua instância está hospedada

Referência da biblioteca de clientes

As funções disponíveis como métodos auxiliares no runtime de funções definidas pelo usuário são listadas no documento de referência da biblioteca de clientes.

Criar um correspondente

Correspondentes são objetos de grafo que determinam quais funções definidas pelo usuário são executadas para uma determinada mensagem de telemetria.

• Comparações de condição de correspondente válidas:

  • Equals
  • NotEquals
  • Contains

• Destinos de condição de correspondente válidos:

  • Sensor
  • SensorDevice
  • SensorSpace

O correspondente de exemplo a seguir é avaliado como verdadeiro em qualquer evento de telemetria do sensor "Temperature" como valor de tipo de dados. Você pode criar vários correspondentes em uma função definida pelo usuário fazendo uma solicitação HTTP POST autenticada para:

YOUR_MANAGEMENT_API_URL/matchers

Com o corpo JSON:

{
  "id": "3626464-f39b-46c0-d9b0c-436aysj55",
  "name": "Temperature Matcher",
  "spaceId": "YOUR_SPACE_IDENTIFIER",
  "conditions": [
    {
      "id": "ag7gq35cfu3-e15a-4e9c-6437-sj6w68sy44s",
      "target": "Sensor",
      "path": "$.dataType",
      "value": "\"Temperature\"",
      "comparison": "Equals"
    }
  ]
}

Valor	Substitua por
YOUR_SPACE_IDENTIFIER	Em qual região do servidor de sua instância está hospedada

Criar uma função definida pelo usuário

A criação de uma função definida pelo usuário envolve fazer uma solicitação HTTP com várias partes para as APIs de Gerenciamento dos Gêmeos Digitais do Azure.

Observação

Normalmente, solicitações com várias partes requerem três partes:

• Um Content-Type cabeçalho:
  • application/json; charset=utf-8
  • multipart/form-data; boundary="USER_DEFINED_BOUNDARY"
• Uma Disposição de Conteúdo:
  • form-data; name="metadata"
• O conteúdo do arquivo que será carregado

Content-Type e Content-Disposition variam dependendo do cenário de uso.

Solicitações com várias partes podem ser feitas de forma programática (usando C#), por meio de um cliente REST ou de uma ferramenta como Postman. Ferramentas de cliente REST podem ter diferentes níveis de suporte para solicitações com várias partes complexas. As definições de configuração também podem variar ligeiramente de uma ferramenta para outra. Verifique qual ferramenta é mais adequada às suas necessidades.

Importante

As solicitações com várias partes feitas para as APIs de Gerenciamento dos Gêmeos Digitais do Azure normalmente são divididas em duas partes:

• metadados de blob (como um tipo MIME associado), declarados por Content-Type e/ou Content-Disposition
• Conteúdo do blob, que inclui o conteúdo não estruturado de um arquivo a ser carregado

Nenhuma das duas partes é necessária para solicitações de PATCH. Ambos são necessários para POST ou criam operações.

O Código-fonte do Início Rápido da Ocupação contém exemplos de C# completos que demonstram como fazer solicitações com várias partes para as APIs de Gerenciamento dos Gêmeos Digitais do Azure.

Depois que os correspondentes forem criados, carregue o snippet de função com a seguinte solicitação HTTP POST de várias partes autenticada:

YOUR_MANAGEMENT_API_URL/userdefinedfunctions

Use o seguinte corpo:

--USER_DEFINED_BOUNDARY
Content-Type: application/json; charset=utf-8
Content-Disposition: form-data; name="metadata"

{
  "spaceId": "YOUR_SPACE_IDENTIFIER",
  "name": "User Defined Function",
  "description": "The contents of this udf will be executed when matched against incoming telemetry.",
  "matchers": ["YOUR_MATCHER_IDENTIFIER"]
}
--USER_DEFINED_BOUNDARY
Content-Disposition: form-data; name="contents"; filename="userDefinedFunction.js"
Content-Type: text/javascript

function process(telemetry, executionContext) {
  // Code goes here.
}

--USER_DEFINED_BOUNDARY--

Valor	Substitua por
USER_DEFINED_BOUNDARY	Um nome de limite de conteúdo com diversas partes
YOUR_SPACE_IDENTIFIER	O identificador de espaço
YOUR_MATCHER_IDENTIFIER	A ID do correspondente que você quer usar

1. Verifique se os cabeçalhos incluem: Content-Type: multipart/form-data; boundary="USER_DEFINED_BOUNDARY".

2. Verifique se o corpo tem diversas partes:

   • A primeira parte contém os metadados de função definida pelo usuário necessários.
   • A segunda parte contém a lógica de computação do JavaScript.

3. Na seção USER_DEFINED_BOUNDARY , substitua os valores spaceId (YOUR_SPACE_IDENTIFIER) e matchers (YOUR_MATCHER_IDENTIFIER).

4. Verifique se a função definida pelo usuário do JavaScript é fornecida como Content-Type: text/javascript.

Funções de exemplo

Defina a leitura da telemetria do sensor diretamente para o sensor com o tipo de dados Temperatura, que é sensor.DataType:

function process(telemetry, executionContext) {

  // Get sensor metadata
  var sensor = getSensorMetadata(telemetry.SensorId);

  // Retrieve the sensor value
  var parseReading = JSON.parse(telemetry.Message);

  // Set the sensor reading as the current value for the sensor.
  setSensorValue(telemetry.SensorId, sensor.DataType, parseReading.SensorValue);
}

O parâmetro de telemetria expõe os atributos SensorId e Message , correspondentes a uma mensagem enviada por um sensor. O parâmetro executionContext expõe os seguintes atributos:

var executionContext = new UdfExecutionContext
{
    EnqueuedTime = request.HubEnqueuedTime,
    ProcessorReceivedTime = request.ProcessorReceivedTime,
    UserDefinedFunctionId = request.UserDefinedFunctionId,
    CorrelationId = correlationId.ToString(),
};

No próximo exemplo, registramos uma mensagem se a leitura da telemetria do sensor ultrapassar um limite predefinido. Se as configurações de diagnóstico estiverem habilitadas na instância dos Gêmeos Digitais do Azures, os logs das funções definidas pelo usuário também serão encaminhados:

function process(telemetry, executionContext) {

  // Retrieve the sensor value
  var parseReading = JSON.parse(telemetry.Message);

  // Example sensor telemetry reading range is greater than 0.5
  if(parseFloat(parseReading.SensorValue) > 0.5) {
    log(`Alert: Sensor with ID: ${telemetry.SensorId} detected an anomaly!`);
  }
}

O código a seguir disparará uma notificação se o nível de temperatura ultrapassar a constante predefinida:

function process(telemetry, executionContext) {

  // Retrieve the sensor value
  var parseReading = JSON.parse(telemetry.Message);

  // Define threshold
  var threshold = 70;

  // Trigger notification 
  if(parseInt(parseReading) > threshold) {
    var alert = {
      message: 'Temperature reading has surpassed threshold',
      sensorId: telemetry.SensorId,
      reading: parseReading
    };

    sendNotification(telemetry.SensorId, "Sensor", JSON.stringify(alert));
  }
}

Para obter um exemplo de código de função definido pelo usuário mais complexo, leia o início rápido de ocupação.

Criar uma atribuição de função

Crie uma atribuição de função para que a função definida pelo usuário seja executada. Se não houver nenhuma atribuição de função para a função definida pelo usuário, ela não terá as permissões corretas para interagir com a API de Gerenciamento ou para ter acesso para executar ações nos objetos de grafo. As ações que a função definida pelo usuário pode executar são especificadas por meio do controle de acesso baseado em função nas APIs do Gerenciamento de Gêmeos Digitais do Azure. Por exemplo, funções definidas pelo usuário podem ser limitadas no escopo, especificando determinadas funções ou certos caminhos de controle de acesso. Para obter mais informações, leia a documentação do controle de acesso baseado em função.

1. Consulte a API do sistema de todas as funções para obter a ID da função que você deseja atribuir à sua função definida pelo usuário. Faça isso, executando uma solicitação HTTP GET autenticada para:

   YOUR_MANAGEMENT_API_URL/system/roles
   

   Guarde a ID da função desejada. Ele será passado como roleId do atributo de corpo JSON (YOUR_DESIRED_ROLE_IDENTIFIER) abaixo.

2. objectId (YOUR_USER_DEFINED_FUNCTION_ID) será a ID de função definida pelo usuário que foi criada anteriormente.

3. Localize o valor do caminho (YOUR_ACCESS_CONTROL_PATH) consultando seus espaços com fullpath.

4. Copie o valor spacePaths retornado. Esse valor será utilizado posteriormente. Faça uma solicitação HTTP GET autenticada para:

   YOUR_MANAGEMENT_API_URL/spaces?name=YOUR_SPACE_NAME&includes=fullpath
   

   Valor	Substitua por
   YOUR_SPACE_NAME	O nome do espaço que você deseja usar

5. Cole o valor spacePaths retornado no caminho para criar uma atribuição de função definida pelo usuário, fazendo uma solicitação HTTP POST autenticada para:

   YOUR_MANAGEMENT_API_URL/roleassignments
   

   Com o corpo JSON:

   {
     "roleId": "YOUR_DESIRED_ROLE_IDENTIFIER",
     "objectId": "YOUR_USER_DEFINED_FUNCTION_ID",
     "objectIdType": "YOUR_USER_DEFINED_FUNCTION_TYPE_ID",
     "path": "YOUR_ACCESS_CONTROL_PATH"
   }
   

   Valor	Substitua por
   YOUR_DESIRED_ROLE_IDENTIFIER	O identificador para a função desejada
   YOUR_USER_DEFINED_FUNCTION_ID	A ID da função definida pelo usuário que você deseja usar
   YOUR_USER_DEFINED_FUNCTION_TYPE_ID	A ID que especifica o tipo de função definido pelo usuário (UserDefinedFunctionId)
   YOUR_ACCESS_CONTROL_PATH	O caminho de controle de acesso

Dica

Leia o artigo Como criar e gerenciar atribuições de função para obter mais informações sobre operações e pontos de extremidade da API de Gerenciamento de funções definidas pelo usuário.

Enviar telemetria para ser processada

O sensor definido no gráfico de inteligência espacial envia telemetria. Por sua vez, a telemetria dispara a execução da função definida pelo usuário que foi carregada. O processador de dados pega a telemetria. Em seguida, um plano de execução é criado para a invocação da função definida pelo usuário.

1. Recupere os correspondentes para o sensor de onde a leitura foi gerada.
2. Dependendo de quais correspondentes foram avaliados com êxito, recupere as funções definidas pelo usuário associadas.
3. Execute cada função definida pelo usuário.

Próximas etapas

• Saiba com criar pontos de extremidade de Gêmeos Digitais do Azure para envio de eventos.

• Para obter mais detalhes sobre o roteamento em Gêmeos Digitais do Azure, leia Roteamento de eventos e mensagens.

• Revise a documentação de referência da biblioteca de clientes.