Início Rápido: Crie um Gêmeo Digital e Envie Dados

Este cenário mostra como criar uma instância de gêmeo digital e como testar sua configuração enviando dados de amostra usando autenticação básica.

Pré-requisitos

Um administrador deve criar políticas para que seu usuário acesse os recursos do OCI com os quais você deseja trabalhar. As políticas a seguir são necessárias para configurar este cenário. Para obter mais informações sobre políticas adicionais relacionadas a outros cenários de IoT, consulte Pré-requisitos.

Políticas do IoT

Use esta política da família IoT para permitir que o grupo de usuários especificado gerencie qualquer recurso IoT em um compartimento específico ou que o administrador possa usar políticas IoT para configurar políticas específicas para recursos IoT específicos:

Allow group <group-name> to manage iot-family in compartment <your-compartment-name>

Políticas de segredo do vault

Ao usar o comando para a Etapa 3: Criar uma instância de gêmeo digital se você usar a autenticação básica, precisará criar um segredo para fazer isso, você precisará da política a seguir.

Deixe que qualquer usuário IoT leia segredos em um compartimento e vault específicos para um domínio IoT:

Allow any-user to {SECRET_BUNDLE_READ, SECRET_READ} in compartment <compartment-name> where ALL {request.principal.type = 'iotdomain', target.vault.id = '<vault-OCID>'}

Etapa 1: Criar um Grupo de Domínios IoT

Se você tiver um grupo de domínios IoT ou domínio IoT existente com o qual deseja trabalhar, ignore esta etapa e use esses OCIDs para criar a instância de gêmeo digital associada. Ou conclua estas etapas para criar um grupo de domínios IoT e um domínio IoT. Para obter uma lista completa de opções, consulte Criando um Grupo de Domínios IoT.

1. Na página da lista de grupos de domínios IoT, selecione Criar grupo de domínios. Se precisar de ajuda para localizar a página de lista, consulte Listando Grupos de Domínios IoT.
2. Na página Criar grupo de domínios, digite um nome amigável para o novo grupo de domínios e uma descrição opcional. Evite digitar informações confidenciais.
3. Selecione um compartimento no qual você deseja armazenar o novo grupo de domínios. Seu grupo de domínios IoT e o domínio IoT podem estar em compartimentos distintos. Todos os recursos do IoT devem estar na mesma região.
4. Selecione um tipo de grupo de domínios. O desenvolvedor é o tipo padrão; não é possível alterar o tipo de grupo de domínios; em vez disso, crie um novo grupo de domínios.
  
  Desenvolvedor: Use para desenvolvimento e teste, reduza custos e use menos recursos.
  
  Padrão: Para grupos de domínios de produção, desative a opção do desenvolvedor para dimensionar recursos e ativar a alta disponibilidade com failover automático.
  
  Observação
  
  Não é possível alterar o tipo de grupo de domínios; em vez disso, crie um novo grupo de domínios.
5. Selecione Criar.
Use o comando oci iot domain-group create e o parâmetro --compartment-id necessário para criar um grupo de domínios IoT em um compartimento específico. Substitua o valor <compartment-OCID> pelo OCID do compartimento:
oci iot domain-group create --compartment-id <compartment-OCID>
Opção Tipo:
Se você não especificar um --type, o tipo de grupo de domínios padrão será lightweight, para desenvolver e testar um grupo de domínios leve que custa menos e usa menos recursos. Quando quiser criar um grupo de domínios de produção, use a opção padrão.
Para um grupo de domínios de produção, use o parâmetro --type com o valor standard para criar um grupo de domínios padrão que seja dimensionado com alta disponibilidade e failover automático.
Para obter uma lista completa de parâmetros e valores para comandos CLI, consulte Referência de Comando CLI.
Execute a operação CreateIotDomainGroup para criar um grupo de domínios IoT em um compartimento.

Etapa 2: Criar um Domínio IoT

1. Na página de lista Domínio IoT, selecione um compartimento no qual você deseja armazenar seus domínios IoT. Seu grupo de domínios IoT e o domínio IoT podem estar em compartimentos distintos. Seus recursos de gêmeos digitais IoT podem estar em compartimentos distintos e devem estar na mesma região. Se precisar de ajuda para localizar a página de lista de domínios IoT, consulte Listando Domínios IoT.
2. Selecione Criar domínio.
3. Informe um nome amigável para o domínio IoT. Evite digitar informações confidenciais.
4. (Opcional) Digite uma descrição.
5. Selecione o compartimento do grupo de domínios associado e o grupo de domínios que você deseja associar a esse domínio.
6. Selecione Criar.
7. Exiba e copie Pontos Finais para o host do dispositivo do domínio IoT. O host do dispositivo exibe o id curto do domínio. Selecione Copiar para copiar este ponto final a ser usado na próxima etapa.
  device-host:<domain-short-id>.device.iot.<region>.oci.oraclecloud.com
  
  Para obter uma lista completa de opções, consulte Criando um domínio IoT.
1. Use o comando oci iot domain create e os parâmetros necessários para criar um domínio IoT.
2. Substitua o <iot-domain-group-OCID> pelo grupo de domínios IoT que você deseja associar ao domínio IoT. Substitua o <compartment-OCID> pelo OCID do compartimento para o domínio IoT:
  oci iot domain create --compartment-id <compartment-OCID> --iot-domain-group-id <iot-domain-group-OCID>
  
  Para obter uma lista completa de parâmetros e valores para comandos CLI, consulte Referência de Comando CLI.
Execute a operação CreateIotDomain para criar um domínio IoT.

Etapa 3: Criar uma Instância Digital Twin

Neste exemplo, a instância de gêmeo digital não está associada a um modelo de gêmeo digital ou a um adaptador de gêmeo digital. Você poderá usar esse método se estiver apenas testando sua configuração de gêmeo digital ou se estiver configurando uma instância de gêmeo digital para estabelecer conexão com um dispositivo que envie dados não estruturados. Para obter uma lista completa de opções, consulte Criando uma Instância Digital Twin.

Opções de Chave Externa: A chave externa é o nome do usuário do dispositivo quando você se conecta a um dispositivo para enviar dados na etapa 5. Se você não incluir um parâmetro --external-key, a chave externa será gerada na resposta. Se você especificar a chave externa, é recomendável não usar aspas com o valor da chave externa.
Opções de Autenticação: Quando você cria uma instância de gêmeo digital, a autenticação é opcional e só será necessária se você enviar dados de ou para um dispositivo. Adicione autenticação à instância do gêmeo digital usando o parâmetro --auth-id.

O exemplo a seguir usa um secret para autenticação. Você pode usar um segredo para um ambiente de teste. Para um ambiente de produção seguro, a instância de gêmeo digital deve usar um certificado mTLS para autenticação.

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 Instâncias gêmeas digitais e, em seguida, Criar.
3. Informe um Nome e, opcionalmente, uma Descrição. Evite inserir qualquer informação confidencial.
4. Opcional. Informe uma Chave externa que seja um identificador exclusivo. Se você não especificar uma chave externa, ela será gerada quando você salvar essa instância de gêmeo digital. Use a chave externa como o nome de usuário do dispositivo quando você se conectar ou enviar dados para o dispositivo.
5. Selecione o tipo:
  Conectado diretamente: Conecte um dispositivo ou entidade diretamente ao domínio IoT. Se o dispositivo ou a entidade enviar dados estruturados, selecione um adaptador. A seleção de um adaptador associa essa instância de gêmeo digital a uma camada de transformação que converte as cargas úteis do dispositivo de entrada na estrutura DTDL do modelo de gêmeo digital associado esperada pela instância.
  Selecionar adaptador: Ative e selecione um adaptador de gêmeo digital na lista para associar o adaptador a essa instância de gêmeo digital. Se não tiver um adaptador, crie um adaptador de gêmeo digital.
  Se o dispositivo enviar dados estruturados, você deverá selecionar um adaptador. Um adaptador não será necessário se o dispositivo ou a entidade com a qual você deseja se conectar enviar dados não estruturados ou receber comandos de dados não estruturados.
  Não conectado: Use esta opção para instâncias de gêmeos digitais que não são suportadas por um dispositivo IoT. Como resultado, essas instâncias não podem receber telemetria e não podem enviar ou receber comandos. Os modelos de gêmeos digitais associados a essas instâncias podem definir relacionamentos de gêmeos digitais, mas não podem incluir telemetria ou propriedades. Você pode usar essa opção para simular seu ambiente IoT sem a complexidade da autenticação de dados ou dispositivos.
  ID de Autenticação: Se o dispositivo ou a entidade enviar ou receber dados, especifique um ID de autenticação. Para testar o ID de autenticação criar um segredo do vault e para a produção, crie um certificado mTLS para o ID de autenticação da instância do gêmeo digital.
  Selecionar ID de autenticação: Selecione a opção de segredo ou certificado. Para um segredo, selecione o compartimento do vault, o vault e o segredo. Para um certificado, selecione o compartimento do certificado e, em seguida, selecione o certificado.
  Colar OCID de autenticação: Cole o OCID do certificado ou do segredo.
  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.
6. Selecione Criar.
1. Use o comando oci iot digital-twin-instance create e esses parâmetros para criar uma instância de gêmeo digital.
2. Substitua o <iot-domain-OCID> pelo domínio IoT que você deseja associar a esta instância de gêmeo digital IoT. Substitua o <secret-or-certificate-OCID> pelo OCID do segredo do vault:
  oci iot digital-twin-instance create --auth-id <secret-OCID> --iot-domain-id <iot-domain-OCID>
Para obter uma lista completa de parâmetros e valores, consulte IoT CLI command Reference, and CLI Command Reference.
Execute a operação CreateDigitalTwinInstance para criar uma instância de gêmeo digital.

Etapa 4: Obtenha os Detalhes do Domínio IoT

Se você tiver o ponto final do host do dispositivo para o domínio IoT que deseja usar, ignore esta etapa.

Os detalhes do domínio IoT contêm o host do dispositivo, incluindo o id curto do domínio, para obter mais Obtendo os Detalhes de um Domínio IoT,

1. Na página de lista IoT Domínios, selecione o domínio com o qual você deseja trabalhar. Se precisar de ajuda para localizar a página de lista de domínios IoT ou domínios IoT, consulte Listando Domínios IoT.
2. Detalhes: Exiba ou edite o nome do domínio e a descrição, copie o OCID, o ponto final do host do dispositivo, exiba o compartimento e o timestamp da criação do domínio.
  host do dispositivo: <domain-short-id>.device.iot.<region>.oci.oraclecloud.com
3. Acesse os vários recursos e tarefas associados ao domínio selecionando os links ou as guias. Para obter descrições das definições de domínio, consulte Criando um Domínio IoT
Use o comando oci iot domain get e o parâmetro necessário para obter os detalhes de um domínio IoT, incluindo o host do dispositivo com o id curto de domínio:
oci iot domain get --iot-domain-id <iot-domain-OCID>
Para obter uma lista completa de parâmetros e valores para comandos CLI, consulte Referência de Comando CLI.
Execute a operação GetIotDomain para obter os detalhes de um domínio.

Etapa 5: Enviar Dados

Envie dados de amostra para a instância do gêmeo digital criada na Etapa 3 anterior: Criar uma Instância do Gêmeo Digital.

Nome do usuário do dispositivo: Use o external key da instância do gêmeo digital como o nome do usuário do dispositivo.
Senha do dispositivo: Está associada ao ID de autenticação da instância do gêmeo digital. Se a instância do gêmeo digital usar um OCID de segredo do vault para autenticação, use o conteúdo do segredo de texto sem formatação como senha do dispositivo. Consulte Criando um Segredo e Obtendo o Conteúdo de um Segredo. O uso de um segredo de vault como senha de dispositivo só é recomendado para teste, não para produção.

O exemplo a seguir usa um segredo para autenticação. Como alternativa, para produção, a instância de gêmeo digital deve usar um certificado mTLS para autenticação.

Usando o Curl
Shells de estilo POSIX: Use este comando curl ao usar bash, zsh, Terminal macOS, Linux ou Git Bash no Windows.
curl -u '<digital-twin-instance-external-key>:<device-password>' \ -H 'Content-Type: text/plain' \ -d 'sample data 1' \ 'https://<iot-domain-short-id>.device.iot.<region>.oci.oraclecloud.com/sampletopic'
Windows Powershell: Use este comando curl neste exemplo, use -G para fazer uma solicitação GET e anexar qualquer dado fornecido com --data-urlencode ao URL como parâmetros de consulta. Ou você pode usar as variáveis ambientais.
```
curl.exe -u "<digital-twin-instance-external-key>:<device-password>" `
  -H "Content-Type: text/plain" `
  -d "sample data 1" `
  "https://<iot-domain-short-id>.device.iot.<region>.oci.oraclecloud.com/sampletopic"
```
Ao concluir a Etapa 3: Criar uma Instância Gêmea Digital, se você tiver definido o valor do parâmetro de chave externa com aspas, deverá incluir as aspas ao enviar os dados: "external-key". Para obter informações sobre melhores práticas, consulte Diagnosticando e Solucionando Problemas.
Use qualquer cliente MQTT, este exemplo usa MQTTX com as seguintes configurações.
1. Faça download e configure o MQTTX, siga estas instruções. Consulte Conceitos Básicos do MQTTX. Abra o MQTTX.
2. Selecione + Nova Conexão para criar uma nova conexão.
3. Informe o valor <unique-id> da chave externa como o Nome do Usuário. Você pode encontrar a chave externa na resposta oci iot digital-twin-instance create, na Etapa 3 anterior: Criar uma Instância Digital Twin:
  "external-key": "<unique-id>"
4. Insira a senha do dispositivo. Se você testar usar o segredo do vault, esse deverá ser o conteúdo do segredo de texto sem formatação. Ou, para um ambiente de produção seguro, use um certificado mTLS.
5. Informe o Host. Selecione o protocolo mqtts:// na lista drop-down host e informe o host do dispositivo: <domain-short-id>.device.iot.<region>.oci.oraclecloud.com no domínio IoT.
6. Informe a porta. Por exemplo: 8883
  Observação
  
  Atualmente, o MQTT Secure (MQTTS) só é suportado usando a porta 8883.
7. Ative a opção SSL/TLS.
8. Ative a opção SSL Secure.
9. Para o Certificado, selecione a opção Certificado do servidor assinado pela CA.
10. Ao configurar a conexão MQTTX, certifique-se de estabelecer conexão usando um clean session e defina a opção Last-Will-Retain como false para permitir que as assinaturas do cliente sejam retidas se o dispositivo for desconectado brevemente.
11. Defina o Último QoS como 1.
12. Selecione Conexão.
Depois de concluir essas etapas, você terá uma instância de gêmeo digital na plataforma IoT que poderá receber dados de um dispositivo.

O que fazer a seguir

Revise os arquivos de amostra IoT para configurar ambientes de teste e produção.
Configure o APEX para exibir seus dados de domínio IoT no APEX e, em seguida, instale um exemplo de aplicativo APEX IoT Explorer para monitorar visualmente seus dispositivos e mensagens IoT.
Se você não planeja manter os recursos, exclua os domínios IoT associados ao grupo de domínios IoT e exclua o grupo de domínios IoT.

Documentação do Oracle Cloud Infrastructure