Compartilhar via

Como depurar 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 .

Este artigo resume como diagnosticar e depurar funções definidas pelo usuário nos Gêmeos Digitais do Azure. Em seguida, ele identifica alguns dos cenários mais comuns encontrados ao depurá-los.

Dica

Leia Como configurar o monitoramento e o registro em log para saber mais sobre como configurar ferramentas de depuração nos Gêmeos Digitais do Azure usando Logs de Atividades, Logs de Diagnóstico e Azure Monitor.

Problemas de depuração

Saber como diagnosticar problemas nos Gêmeos Digitais do Azure permite que você analise efetivamente os problemas, identifique as causas dos problemas e forneça soluções apropriadas para eles.

Uma variedade de ferramentas de log, análise e diagnóstico são fornecidas para esse fim.

Habilitar o registro em log para sua instância

Os Gêmeos Digitais do Azure dão suporte a log, monitoramento e análise robustos. Os desenvolvedores de soluções podem usar logs do Azure Monitor, logs de diagnóstico, logs de atividades e outros serviços para dar suporte às necessidades complexas de monitoramento de um aplicativo IoT. As opções de registro em log podem ser combinadas para consultar ou exibir registros em vários serviços e fornecer registro em log detalhado para muitos serviços.

Depois de configurado, você poderá selecionar todas as categorias de log, métricas e usar workspaces avançados do Log Analytics do Azure Monitor para dar suporte aos esforços de depuração.

Telemetria do sensor de rastreamento

Para rastrear a telemetria do sensor, verifique se as configurações de diagnóstico estão habilitadas para sua instância dos Gêmeos Digitais do Azure. Em seguida, verifique se todas as categorias de log desejadas estão selecionadas. Por fim, confirme se os logs desejados estão sendo enviados para os logs do Azure Monitor.

Para corresponder uma mensagem de telemetria do sensor aos seus respectivos logs, você pode especificar uma ID de correlação nos dados do evento enviados. Para fazer isso, defina a x-ms-client-request-id propriedade como um GUID.

Depois de enviar a telemetria, abra o log analytics do Azure Monitor para consultar logs usando a ID de Correlação definida:

AzureDiagnostics
| where CorrelationId == 'YOUR_CORRELATION_IDENTIFIER'
Valor da consulta Substituir por
YOUR_CORRELATION_IDENTIFIER A ID de Correlação especificada nos dados do evento

Para ler todos os logs de telemetria recentes, faça uma consulta:

AzureDiagnostics
| order by CorrelationId desc

Se você habilitar o registro em log para sua função definida pelo usuário, esses logs aparecerão na instância do log analytics com a categoria UserDefinedFunction. Para recuperá-los, insira a seguinte condição de consulta no log analytics:

AzureDiagnostics
| where Category == 'UserDefinedFunction'

Para obter mais informações sobre operações de consulta avançadas, leia Introdução às consultas.

Identificar problemas comuns

Diagnosticar e identificar problemas comuns é importante ao solucionar problemas de sua solução. Vários problemas que normalmente são encontrados ao desenvolver funções definidas pelo usuário são resumidos nas subseções a seguir.

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
NOME_DA_SUA_INSTÂNCIA O nome da Instância do Azure Digital Twins
SUA_LOCALIZAÇÃO A região em que sua instância está hospedada

Verificar se uma atribuição de função foi criada

Sem uma atribuição de função criada dentro da API de Gerenciamento, a função definida pelo usuário não tem acesso para executar ações como enviar notificações, recuperar metadados e definir valores computados dentro da topologia.

Verifique se existe uma atribuição de função para sua função definida pelo usuário por meio da API de Gerenciamento:

GET YOUR_MANAGEMENT_API_URL/roleassignments?path=/&traverse=Down&objectId=YOUR_USER_DEFINED_FUNCTION_ID
Valor do parâmetro Substituir por
SEU_ID_FUNÇÃO_DEFINIDA_PELO_USUÁRIO A ID da função definida pelo usuário para recuperar atribuições de função para

Saiba como criar uma atribuição de função para sua função definida pelo usuário, se não houver atribuições de função.

Verificar se o validador funciona para a telemetria de um sensor

Com a chamada a seguir na API de Gerenciamento das instâncias dos Gêmeos Digitais do Azure, você poderá determinar se um determinado correspondente se aplica ao sensor especificado.

GET YOUR_MANAGEMENT_API_URL/matchers/YOUR_MATCHER_IDENTIFIER/evaluate/YOUR_SENSOR_IDENTIFIER?enableLogging=true
Parâmetro Substituir por
YOUR_MATCHER_IDENTIFIER A ID do correspondente que você deseja avaliar
YOUR_SENSOR_IDENTIFIER A ID do sensor que você deseja avaliar

Resposta:

{
    "success": true,
    "logs": [
        "$.dataType: \"Motion\" Equals \"Motion\" => True"
    ]
}

Verificar o que um sensor dispara

Ao realizar a chamada a seguir nas APIs de Gerenciamento dos Gêmeos Digitais do Azure, você poderá identificar os identificadores das suas funções definidas pelo usuário que são ativadas pela telemetria recebida do sensor especificado.

GET YOUR_MANAGEMENT_API_URL/sensors/YOUR_SENSOR_IDENTIFIER/matchers?includes=UserDefinedFunctions
Parâmetro Substituir por
YOUR_SENSOR_IDENTIFIER A ID do sensor para enviar telemetria

Resposta:

[
    {
        "id": "48a64768-797e-4832-86dd-de625f5f3fd9",
        "name": "MotionMatcher",
        "spaceId": "2117b3e1-b6ce-42c1-9b97-0158bef59eb7",
        "conditions": [
            {
                "id": "024a067a-414f-415b-8424-7df61392541e",
                "target": "Sensor",
                "path": "$.dataType",
                "value": "\"Motion\"",
                "comparison": "Equals"
            }
        ],
        "userDefinedFunctions": [
            {
                "id": "373d03c5-d567-4e24-a7dc-f993460120fc",
                "spaceId": "2117b3e1-b6ce-42c1-9b97-0158bef59eb7",
                "name": "Motion User-Defined Function",
                "disabled": false
            }
        ]
    }
]

Problema com o recebimento de notificações

Quando você não estiver recebendo notificações da função definida pelo usuário disparada, confirme se o parâmetro de tipo de objeto de topologia corresponde ao tipo de identificador que está sendo usado.

Incorreto Exemplo:

var customNotification = {
    Message: 'Custom notification that will not work'
};

sendNotification(telemetry.SensorId, "Space", JSON.stringify(customNotification));

Esse cenário surge porque o identificador usado se refere a um sensor enquanto o tipo de objeto de topologia especificado é Space.

Correto Exemplo:

var customNotification = {
    Message: 'Custom notification that will work'
};

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

A maneira mais fácil de não enfrentar esse problema é usar o método Notify no objeto de metadados.

Exemplo:

function process(telemetry, executionContext) {
    var sensorMetadata = getSensorMetadata(telemetry.SensorId);

    var customNotification = {
        Message: 'Custom notification'
    };

    // Short-hand for above methods where object type is known from metadata.
    sensorMetadata.Notify(JSON.stringify(customNotification));
}

Exceções de diagnóstico comuns

Se você habilitar as configurações de diagnóstico, poderá encontrar essas exceções comuns:

  1. Limitação: se a função definida pelo usuário exceder os limites de taxa de execução descritos no artigo Limites de Serviço , ela será limitada. Nenhuma operação adicional é executada com êxito até que os limites de controle expirem.

  2. Dados Não Encontrados: se a função definida pelo usuário tentar acessar metadados que não existem, a operação falhará.

  3. Não autorizado: se a função definida pelo usuário não tiver um conjunto de atribuição de função ou não tiver permissão suficiente para acessar determinados metadados da topologia, a operação falhará.

Próximas etapas