Documentação do Oracle Cloud Infrastructure

Cenário: Adicionar Validação de Esquema JSON a um Modelo Digital Twin

Use uma extensão de validação personalizada do Oracle DTDL para aplicar regras de validação de dados do esquema JSON aos payloads do dispositivo em seu modelo de gêmeo digital.

Se você fizer referência à extensão de validação em seu modelo de gêmeo digital usando anexando o Digital Twin Model Identifier (DTMI): dtmi:com:oracle:dtdl:extension:validation;1 e adicionando metadados de validação @type às propriedades, à telemetria ou aos elementos de comando em seu modelo de gêmeo digital, poderá aplicar regras de validação e restrições a intervalos de valores, padrões regex, enumerações, campos obrigatórios ou lógica condicional. Essas regras de validação são aplicadas no runtime, para dados válidos que são ingeridos e transmitidos aos aplicativos são normalizados.

Para obter uma lista completa das regras de propriedades de validação suportadas, consulte Referência de Extensão de Validação DTMI.

Antes de começar

Verifique se você tem as permissões necessárias e se a CLI do OCI está configurada. Para obter mais informações, consulte Pré-requisitos, Detalhes da Política da Plataforma Internet of Things (IoT) e Usando um Arquivo JSON para Entrada Complexa.

Entender os trechos de código neste cenário

Os trechos de código abaixo são exemplos de um modelo gêmeo digital baseado em DTDL v3 e demonstra como usar a extensão de validação personalizada da Oracle.

Etapa 1: Definir a Extensão de Validação no @context do Modelo Digital Twin

O contexto do modelo de gêmeo digital obrigatório que indica o modelo de gêmeo digital usa especificações DTDL v3: dtmi:dtdl:context;3

Para definir a extensão de validação, ao criar um modelo de gêmeo digital ou atualizar um modelo de gêmeo digital, anexe a extensão de validação ao valor do URI DTMI no @context. O modelo de gêmeo digital lê esses blocos de validação para impor regras de validação aos dados do dispositivo de entrada. Todos os dados que falharem em uma regra de validação serão rejeitados. Os dados normalizados e rejeitados estão no esquema de banco de dadosIoT. 

{
  "@context": [
    "dtmi:dtdl:context;3",
    "dtmi:com:oracle:dtdl:extension:validation;1"
  ],
  ...
  }

Etapa 2: Adicionar uma Propriedade validation aos Elementos em um Modelo Digital Twin

Em modelos de gêmeos digitais, use Especificações de Validação do Esquema JSON para adicionar propriedades de validação aos dados ingeridos de validação.
  • Para propriedades primitivas, como strings ou inteiros, as restrições de validação são adicionadas como propriedades irmãs ao lado do campo de esquema dentro da definição de propriedade ou telemetria.
  • Para matrizes, as validações se aplicam ao próprio array, como minItems ou uniqueItems, e são definidas como irmãos do esquema de array, enquanto as restrições que se aplicam a cada elemento, como intervalos de valores ou padrões de string, são colocadas dentro do esquema de array, como propriedades irmãs para elementSchema.

Use os trechos de código a seguir como exemplos para seus modelos de gêmeos digitais. Para obter uma lista completa de propriedades e regras de validação suportadas, consulte Referência de Extensão de Validação DTMI.

Snippet de Modelo Digital Twin: Telemetria com Validação de Número

Este trecho de código de um modelo de gêmeo digital mostra como validar as pressões de um sensor entre 950.0 e 1050.0, inclusive, e deve ser um múltiplo de 0.1.

{
  "@context": [
    "dtmi:dtdl:context;3",
    "dtmi:com:oracle:dtdl:extension:validation;1"
  ],
  "@id": "dtmi:com:example:Sensor;1",
  "@type": "Interface",
  "displayName": "Example Sensor",
  "contents": [
    {
      "@type": ["Telemetry", "Validated"],
      "name": "pressure",
      "schema": "double",
      "displayName": "Pressure",
      "minimum": 950.0,
      "maximum": 1050.0,
      "multipleOf": 0.1
  ]
  }

Snippet de Modelo Digital Twin: Validação de Padrão de String

Este exemplo valida o número de série que segue um padrão de string específico. Neste exemplo, o padrão de string é uma expressão regular que os valores de número de série de entrada devem corresponder. O valor do número de série deve começar com "SN-", seguido por 4 a 8 letras maiúsculas (A-Z) ou dígitos (0-9) e nada mais é permitido antes ou depois:

"pattern": "^SN-[A-Z0-9]{4,8}$"
{
  "@type": ["Property", "Validated"]
  "name": "serialNumber",
  "schema": "string",
  "pattern": "^SN-[A-Z0-9]{4,8}$"
  }

Snippet de Modelo Digital Twin: Validação de Array com Restrições de Elemento

Valida os códigos de alarme que devem ser uma matriz de números inteiros entre 100 e 900. O array deve ter pelo menos 1, no máximo 5 itens e todos os itens devem ser exclusivos.
{
  "@type": ["Property", "Validated"]
  "name": "alarmCodes",
  "schema": {
    "@type": "Array",
    "elementSchema": "integer",
      "minimum": 100,
      "maximum": 900
  },
  "minItems": 1,
  "maxItems": 5,
  "uniqueItems": true
}

Digital Twin Model Snippet: Telemetria de Dupla Precisão com Validação Explícita

Este exemplo valida o valor deve ser um número inteiro duplo e deve ser inclusivo entre -50,0 e 150,0.
{
  "@type": ["Telemetry", "Validated"]
  "name": "temperature_double",
  "schema": "double",
  "minimum": -50.0,
  "maximum": 150.0
}

Digital Twin Model Snippet: Telemetria de Precisão Única com Validação Explícita

Este exemplo valida o valor deve ser float e o valor deve estar no intervalo especificado entre -50.0 e 150.0.
{
  "@type": ["Telemetry", "Validated"]
  "name": "temperature_float",
  "schema": "float",
  "minimum": -50.0,
  "maximum": 150.0
}

Snippet de Modelo Digital Twin: Telemetria com Validação de Tipo, Faixa e Etapa

Este exemplo valida o valor é um double, um número inteiro e entre 0 e 360 graus e em incrementos de 0.1.

{
  "@type": ["Telemetry", "Validated"]
  "name": "angle",
  "schema": "double",
  "minimum": 0.0,
  "maximum": 360.0,
  "multipleOf": 0.1
}