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

Importante

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

Para acessar a documentação do novo serviço, consulte a Documentação Ativa do Azure Digital Twins .

funções definidas pelo usuário permitem que os usuários configurem a lógica personalizada a ser executada a partir de mensagens de telemetria de entrada e metadados de grafo espacial. Os usuários também podem enviar eventos para pontos de extremidade predefinidos .

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

Nos exemplos abaixo, YOUR_MANAGEMENT_API_URL refere-se ao URI das APIs dos Gêmeos Digitais:

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

Nome	Substituir por
YOUR_INSTANCE_NAME	O nome da Instância do Azure Digital Twins
SUA_LOCALIZAÇÃO	A região em que sua instância está hospedada

Referência da biblioteca cliente

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

Criar um compatibilizador

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

• Comparações válidas de condições do método de correspondência:

  • Equals
  • NotEquals
  • Contains

• Destinos válidos da condição do comparador:

  • Sensor
  • SensorDevice
  • SensorSpace

O exemplo de correspondência a seguir é avaliado como verdadeiro em qualquer evento de telemetria do sensor com "Temperature" como seu 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	Substituir por
YOUR_SPACE_IDENTIFIER	Em qual região do servidor 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 a criação de uma solicitação HTTP de várias partes para as APIs de Gerenciamento dos Gêmeos Digitais do Azure.

Observação

As solicitações multipartes normalmente exigem três componentes:

• Um cabeçalho Content-Type:
  • application/json; charset=utf-8
  • multipart/form-data; boundary="USER_DEFINED_BOUNDARY"
• A Content-Disposition:
  • form-data; name="metadata"
• O conteúdo do arquivo a ser carregado

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

Solicitações de múltiplas partes podem ser feitas programaticamente (por meio de C#), por meio de um cliente REST ou ferramenta como Postman. As ferramentas de cliente REST podem ter diferentes níveis de suporte para solicitações de várias partes complexas. As configurações também podem variar ligeiramente de ferramenta para ferramenta. Verifique qual ferramenta é mais adequada para suas necessidades.

Importante

As solicitações de várias partes feitas para as APIs de Gerenciamento dos Gêmeos Digitais do Azure normalmente têm duas partes:

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

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

O código-fonte do Início Rápido de Ocupação contém exemplos completos em C# que demonstram como fazer solicitações multipartes nas 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 para:

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	Substituir por
LIMITE_DEFINIDO_PELO_USUÁRIO	Um nome de limite de conteúdo de várias partes
YOUR_SPACE_IDENTIFIER	O identificador de espaço
YOUR_MATCHER_IDENTIFIER	O ID do correlacionador que você deseja usar

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

2. Verifique se o corpo é de várias partes:

   • A primeira parte contém os metadados de função definidos pelo usuário necessários.
   • A segunda parte contém a lógica de computação 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

Configure diretamente a leitura de telemetria 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 exemplo a seguir, registraremos uma mensagem se a leitura de telemetria do sensor ultrapassar um limite predefinido. Se as configurações de diagnóstico estiverem habilitadas na instância de Azure Digital Twins, 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 subir acima da 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 guia rápido de ocupação .

Criar uma atribuição de função

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

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

   YOUR_MANAGEMENT_API_URL/system/roles
   

   Guarde o identificador de função desejado. Ele será passado como o atributo de corpo JSON roleId (YOUR_DESIRED_ROLE_IDENTIFIER) abaixo.

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

3. Encontre o valor do caminho (YOUR_ACCESS_CONTROL_PATH) fazendo consultas aos seus espaços com fullpath.

4. Copie o valor de spacePaths retornado. Você vai usar isso aqui embaixo. Faça uma solicitação HTTP GET autenticada para:

   YOUR_MANAGEMENT_API_URL/spaces?name=YOUR_SPACE_NAME&includes=fullpath
   

   Valor	Substituir por
   SEU_NOME_DE_ESPAÇO	O nome do espaço que você deseja usar

5. Cole o valor retornado spacePaths no caminho para criar uma atribuição de função definida pelo usuário, fazendo uma solicitação autenticada de HTTP POST 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	Substituir por
   IDENTIFICADOR_DO_SEU_PAPEL_DESEJADO	O identificador da função desejada
   SEU_ID_FUNÇÃO_DEFINIDA_PELO_USUÁRIO	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 do 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 definidos pelo usuário.

Enviar telemetria para ser processada

O sensor definido no grafo 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 captura 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 associados ao sensor do qual a leitura foi gerada.
2. Dependendo de quais comparadores 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 como criar endpoints dos Gêmeos Digitais do Azure para os quais enviar eventos.

• Para obter mais detalhes sobre roteamento no Azure Digital Twins, consulte Roteamento de eventos e mensagens.

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