Documentação do Oracle Cloud Infrastructure

Criando um Adaptador Digital Twin

Crie um adaptador de gêmeo digital para converter cargas úteis de dados brutos provenientes de um dispositivo físico ou de um sistema externo para dados de telemetria normalizados com base no modelo de gêmeo digital.

Os dados são passados para o adaptador de gêmeo digital como um objeto JSON que contém os dados e o mapeamento.

Conceitos

É necessário um adaptador de gêmeo digital ao trabalhar com dados estruturados.

Há duas maneiras de usar um adaptador digital twin, dependendo se o dispositivo com o qual você está trabalhando pode ser programado para enviar dados:

  • Formato de adaptador padrão: Se o dispositivo puder ser programado para enviar dados no formato com o qual você deseja trabalhar, crie um adaptador de gêmeo digital sem especificar inbound-envelope ou inbound-routes. A resposta conterá dados no formato padrão do dispositivo. Se o mapeamento de envelope for especificado e contiver um timeObserved, receivedTime será usado como valor timeObserved. Para obter um exemplo específico, consulte Cenário: Enviando Dados Estruturados em um Formato Padrão usando HTTPs.
  • Formato de adaptador personalizado: Para dispositivos que não podem ser programados para enviar dados, você pode criar um adaptador de gêmeo digital personalizado definindo um inbound-envelope e um envelope-mapping personalizado, transformando o payload e os metadados para obter a saída com a qual deseja trabalhar. Para obter um exemplo específico, consulte Cenário: Enviando Dados Estruturados em um Formato Personalizado usando HTTPs.
  • ID de Autenticação: Ao criar um adaptador de gêmeo digital se você conectar um dispositivo, a instância de gêmeo digital associada deverá usar um parâmetro de ID de autenticação, com um certificado ou um segredo para autenticar o dispositivo.
  • Chave externa: Depois de criar um adaptador de gêmeo digital, você pode atualizar o adaptador de gêmeo digital para alterar a chave externa de um dispositivo. Quando você enviar dados, use a chave externa como o nome de usuário do dispositivo.
  • Limite: O número máximo de rotas de entrada para um adaptador de gêmeo digital é 128.
Exemplo de entrada de payload do dispositivo, mapeamento JSON e resultado transformado

Você pode tentar o mapeamento do adaptador no JQ Playground colando o payload como entrada de consulta, adicionando o mapeamento JSON na seção JSON e, em seguida, exibindo o resultado da saída.

Exemplo JSON de payload do dispositivo:

{ "time": "<timestamp>", "temp": 65, "hum": 55 }

Use uma expressão JQ ou a Notação JsonPath para criar uma saída de mapeamento JSON de payload do adaptador.

Este exemplo usa uma expressão JQ: 
{ "temperature": ".temp", "humidity": ".hum", "timeObserved": ".time" }
Este exemplo usa a Notação JsonPath para criar uma saída de mapeamento JSON de payload do adaptador:
{ "temperature": "$.temp", "humidity": "$.hum", "timeObserved": "$.time" }
Resultado de saída transformado:
{ "temperature": 65, "humidity": 55, "timeObserved": "<timestamp>" }

Para obter mais exemplos, consulte Referência: Expressões JQ para Adaptadores Gêmeos Digitais e Cenários.

  • Se o dispositivo enviar ou receber dados não estruturados, não será necessário especificar um adaptador de gêmeo digital.

    1. Na página de lista Domínios IoT, selecione o domínio IoT com o qual você deseja trabalhar. Se precisar de ajuda para localizar a página de lista de domínios IoT, consulte Listando Domínios IoT.
    2. Selecione a guia Adaptadores gêmeos digitais e selecione Criar.
    3. Informe um Nome e, opcionalmente, uma Descrição. Evite inserir qualquer informação confidencial.
    4. Para localizar o modelo de gêmeo digital que você deseja associar:
      • Selecionar modelo: Para procurar o modelo de gêmeo digital por nome.
      • Selecionar com URI de especificação de modelo: Para procurar o modelo de gêmeo digital usando o DTMI. Por exemplo, dtmi:com:example:iot:demo;1
    5. Depende se o dispositivo com o qual você está trabalhando pode ser programado para enviar dados em formatos específicos:
      • Se o dispositivo puder ser programado para enviar dados em um formato específico, não será necessário especificar o envelope e as rotas do adaptador; o adaptador será gerado a partir do payload do dispositivo.
      • Se o dispositivo não puder ser programado para enviar dados no formato desejado, especifique um adaptador para converter o payload de entrada no formato de dados com o qual você deseja trabalhar. Ative a opção Especificar envelope de entrada e rotas:
        • Fazer upload do arquivo .json do envelope de entrada: Faça upload de um arquivo .json que contenha o envelope de entrada para este adaptador.
        • Colar JSON do envelope de entrada: Adicione o JSON do envelope de entrada a este adaptador.
    6. Especificação de rotas de entrada: Adicione uma lista de definições de rota com condições e mapeamentos de payload opcionais. As rotas são avaliadas em ordem.
      • Fazer upload do arquivo .json de rotas de entrada: Faça upload das rotas de entrada em um arquivo .json.
      • Colar rotas de entrada JSON: Adicione as rotas de entrada no formato JSON.
    7. Tags: (Opcional) Adicione uma ou mais tags ao adaptador de gêmeos digitais. Se você tiver permissões para criar um recurso, também terá permissões para aplicar tags de formato livre a esse recurso. Para aplicar uma tag definida, você deverá ter permissões para usar o namespace de tag. Para obter mais informações sobre tags, consulte Tags de Recurso. Se você não tiver certeza se deseja aplicar tags, ignore essa opção ou pergunte a um administrador. Você pode aplicar tags posteriormente.
    8. Selecione Criar.

  • Use o comando oci iot digital-twin-adapter create e os parâmetros necessários para criar um adaptador de gêmeo digital.

    Para criar um adaptador de gêmeo digital para dados estruturados em um formato padrão: Se o dispositivo puder ser programado, crie um adaptador de gêmeo digital sem especificar o inbound-envelope ou o envelope-mapping como resultado, os dados padrão provenientes do dispositivo serão aceitos na resposta.

    Duas opções para associar o modelo de gêmeo digital:

    • Usando a DTMI:

      O exemplo a seguir usa o parâmetro DTMI URI para associar o adaptador ao modelo de gêmeo digital. Substitua <digital-twin-model-spec-uri> pelo URI DTMI do seu modelo gêmeo digital associado. 
      oci iot digital-twin-adapter create --iot-domain-id <iot-domain-OCID> --digital-twin-model-spec-uri '<digital-twin-model-spec-uri>'
    • Usando o OCID do modelo gêmeo digital:
      Como alternativa, o exemplo a seguir usa o parâmetro --digital-twin-model-id com o <digital-twin-model-OCID> para o modelo de gêmeo digital que você deseja associar a um adaptador de gêmeo digital:
      oci iot digital-twin-adapter create --iot-domain-id <iot-domain-OCID> --digital-twin-model-id <digital-twin-model-OCID>

    Para criar um adaptador de gêmeo digital para dados estruturados em um formato personalizado:

    Use o comando oci iot digital-twin-adapter create e o parâmetro --iot-domain-id necessário. Para criar um adaptador de gêmeo digital personalizado, defina um valor inbound-envelope ou inbound-route específico para obter a saída com a qual você deseja trabalhar. Para isso, defina o mapeamento de payload personalizado para seu gêmeo digital usando um arquivo <file://inbound-envelope.json> e um arquivo <file://inbound-routes.json> usando expressões JQ.

    Substitua <digital-twin-model-spec-uri> pelo URI DTMI do seu modelo gêmeo digital associado e substitua o <iot-domain-OCID> pelo OCID do domínio IoT que você deseja associar a este adaptador de gêmeo digital:

    oci iot digital-twin-adapter create --iot-domain-id <iot-domain-OCID> --digital-twin-model-spec-uri '<digital-twin-model-spec-uri>' --inbound-envelope <file://inbound-envelope.json> --inbound-routes <file://inbound-routes.json>

    Para obter mais informações sobre como referenciar arquivos, consulte Usando um Arquivo JSON para Entrada Complexa.

    Para obter uma lista completa de parâmetros e valores para comandos CLI, consulte Referência de Comando CLI.

  • Execute a operação CreateDigitalTwinAdapter para criar um adaptador de gêmeo digital no domínio IoT especificado.