Cenário: Consultar Dados IoT com o Select AI no APEX

• Antes de Começar
• Fazer upload, personalizar e executar o Select AI Setup Script no APEX
• Exemplos de Consulta
• Práticas Recomendadas
• Perguntas Frequentes
• O Que Vem a Seguir

Você precisa dessas permissões para ler dados IoT e usar a família de recursos de IA generativa.

Allow group <your-group-name> to read <iot-domain> in compartment <compartment-name>

allow dynamic-group <your-group-name> to manage generative-ai-family in compartment <compartment-name>

Administradores: Se você for iniciante em políticas, para saber mais sobre como configurar políticas, consulte Como as Políticas do Serviço IAM Funcionam para o Oracle Cloud Infrastructure. Para obter exemplos específicos, consulte Detalhes da Política da Plataforma Internet of Things (IoT).

Confirme se você tem:

• Acesso configurado ao espaço de trabalho do APEX para o usuário do banco de dados IoT.
• Políticas do IAM obrigatórias para que você tenha permissões para consultar o banco de dados ou a origem de dados de destino.

1. Copie este exemplo de script SQL e salve o trecho de código como um arquivo para upload, por exemplo: select_ai_apex_setup.sql
   O script cria um object_list para os objetos de esquema da IoT, incluindo RAW_DATA, HISTORIZED_DATA, SNAPSHOT_DATA, DIGITAL_TWIN_MODELS, DIGITAL_TWIN_INSTANCES e DIGITAL_TWIN_ADAPTERS.

   Exemplo de script SQL

   -- APEX SQL Commands setup script.
   -- Run this code block first in APEX SQL Commands or SQL Scripts.
   
   alter session set nls_language = 'ENGLISH';
   
   declare
     c_domain_short_id       constant varchar2(128)  := '<domain short id in upper case>';
     c_genai_user_ocid       constant varchar2(4000) := 'ocid1.user.oc1..unique';
     c_genai_tenancy_ocid    constant varchar2(4000) := 'ocid1.tenancy.oc1..unique';
     c_genai_fingerprint     constant varchar2(4000) := 'unique';
     c_genai_region          constant varchar2(128)  := 'region';
     c_genai_model           constant varchar2(4000) := 'xai.grok-4.20-reasoning';
     c_genai_credential_name constant varchar2(128)  := 'GENAI_CRED';
     c_genai_profile_name    constant varchar2(128)  := 'GENAI_XAI_GROK_420';
   
     c_private_key constant clob := q'~-----BEGIN PRIVATE KEY-----
   <private key>
   -----END PRIVATE KEY-----~';
   
     type t_name_list is table of varchar2(128);
     l_objects t_name_list := t_name_list(
       'RAW_DATA',
       'HISTORIZED_DATA',
       'REJECTED_DATA',
       'SNAPSHOT_DATA',
       'RAW_COMMAND_DATA',
       'DIGITAL_TWIN_MODEL_SPECS',
       'DIGITAL_TWIN_MODELS',
       'DIGITAL_TWIN_INSTANCES',
       'DIGITAL_TWIN_RELATIONSHIPS',
       'DIGITAL_TWIN_ADAPTERS'
     );
   
     l_iot_owner   varchar2(130);
     l_attributes  clob;
     l_object_list clob := '[';
   begin
     l_iot_owner := upper(trim(c_domain_short_id)) || '__IOT';
   
     begin
       dbms_cloud_ai.drop_profile(c_genai_profile_name);
     exception
       when others then
         null;
     end;
   
     begin
       dbms_cloud.drop_credential(c_genai_credential_name);
     exception
       when others then
         null;
     end;
   
     dbms_cloud.create_credential(
       credential_name => c_genai_credential_name,
       user_ocid       => c_genai_user_ocid,
       tenancy_ocid    => c_genai_tenancy_ocid,
       private_key     => c_private_key,
       fingerprint     => c_genai_fingerprint
     );
   
     for i in 1 .. l_objects.count loop
       if i > 1 then
         l_object_list := l_object_list || ',';
       end if;
       l_object_list := l_object_list ||
         '{"owner":"' || l_iot_owner || '","name":"' || l_objects(i) || '"}';
     end loop;
     l_object_list := l_object_list || ']';
   
     l_attributes := '{' ||
       '"provider":"oci",' ||
       '"credential_name":"' || c_genai_credential_name || '",' ||
       '"region":"' || c_genai_region || '",' ||
       '"oci_compartment_id":"' || c_genai_tenancy_ocid || '",' ||
       '"model":"' || c_genai_model || '",' ||
       '"annotations":false,' ||
       '"comments":true,' ||
       '"object_list":' || l_object_list ||
     '}';
   
     dbms_cloud_ai.create_profile(
       profile_name => c_genai_profile_name,
       attributes   => l_attributes
     );
   end;
   /

2. No APEX, selecione SQL Workshop e SQL Scripts.

3. Selecione Upload para adicionar o arquivo select_ai_apex_setup.sql ao APEX.
4. Selecione Editar para atualizar o script com variáveis para o seu ambiente.
   Substitua-os pelos valores do seu ambiente:

   c_domain_short_id       constant varchar2(128)  := '<DOMAIN_SHORT_ID>';
   c_genai_region          constant varchar2(128)  := '<region>';
   c_genai_model           constant varchar2(4000) := 'xai.grok-4.20-reasoning';
   c_genai_profile_name    constant varchar2(128)  := 'GENAI_XAI_GROK_420';

   Esse script usa o serviço GenAI que usa essas constantes e "provider": "oci". Se você quiser usar outro modelo, poderá atualizar esses valores no script. Consulte Configurar Selecionar IA para Usar Provedores de IA Suportados.
5. Substitua o texto select e prompt pela pergunta que você deseja que a IA responda.

   Substitua o profile_name pelo perfil do AI no qual você deseja executar.

   select 'GENAI_XAI_GROK_420' as profile_name,
          upper(trim('IN2AHR4KWKIRC')) || '__IOT' as iot_owner,
          'Setup complete' as status
   from dual;
   
   
   select 'which digital twin instances with the model spec uri dtmi:com:oracle:iot:sample:hvac:iot-domain-short-id' as prompt_text,
          dbms_lob.substr(
            replace(
              replace(
                dbms_cloud_ai.generate(
                  prompt       => 'which model spec uri has exactly two digital twin instances and both in active state',
                  profile_name => 'GENAI_XAI_GROK_420',

6. Selecione Executar e, em seguida, Executar Agora.
7. Selecione Exibir e, em seguida, Ir, role para baixo para revisar o SQL gerado com base na pergunta IoT no prompt.
8. Copie o SQL Gerado, selecione SQL Workshop e SQL Commands.
9. Cole o SQL gerado e selecione Executar para executar o SQL gerado.
10. Para esse prompt, os Resultados mostram o OCID da instância gêmea digital, seu nome para exibição, a temperatura e os valores de umidade.

Use esses exemplos como prompts iniciais em APEX SQL Commands ou SQLcl. No APEX, use o texto dentro das aspas como o valor prompt.

Encontre a telemetria mais recente de um dispositivo

'Show the most recent telemetry readings for device <device-id>';

Encontre a instância de HVAC mais quente

'Which HVAC instance and model has the highest temperature in the last 1 hour?';

Localizar erros recentes do dispositivo

'Which devices reported errors in the last 24 hours?';

Resuma a umidade por dispositivo

'Show average humidity by device for the last 7 days';

Encontre dispositivos sem telemetria hoje, identifique dispositivos que podem estar off-line ou configurados incorretamente

'List devices that have not sent telemetry today';

Resumir leituras de fábrica anormais

'Summarize abnormal readings for factory floor sensors this week';

Contar registros de dados históricos

'How many historized data records are in the IoT domain?';

Contar instâncias de gêmeos digitais historiadas

'How many digital twin instances are in historized data?';

Localize a instância de dados brutos mais movimentada

'What instance sent most of the raw data last day?';

Adaptadores de contagem no domínio

'How many adapters are in the domain?';

Contar instâncias no domínio

'How many instances are in the domain?';

Média de instâncias por modelo

'What is the average number of instances that implement one model?';

Verificar dados rejeitados

'Is there rejected data in the domain?';

Taxa de ingestão de dados brutos por hora

'What is the average raw data ingestion rate per hour last day, each hour?';

Tamanho da carga útil do registro bruto

'What is the average and max raw record payload size?';

Tamanho da carga útil do registro histórico

'What is the average and max historized record payload size?';

Tendência de temperatura por hora

'Show the average temperature by hour for the last day';

Agrupar erros de dispositivo por tipo

'Show devices with error events in the last 7 days grouped by error type';

• Use showsql primeiro para que você possa revisar a SQL gerada antes de ela ser executada.
• Faça uma pergunta de IoT por vez.
• Inclua o tipo de dispositivo, o nome da métrica, o URI de especificação do modelo ou o intervalo de tempo quando for importante.
• Use nomes de perfil separados para modelos separados, por exemplo, OpenAI, GOOGLE_GEMINI ou CLAUDE.

• Configure uma conexão direta com o banco de dados do domínio IoT.
• Revise o esquema do banco de dados do domínio IoT.
• Configure uma conexão com o servidor MCP IoT.