Conectar-se à Computação

10 Conecte-se à Computação

Esta seção aborda como conectar a computação no Oracle AI Data Platform a outras ferramentas de business intelligence.

Tópicos:

Conexões

Você pode conectar seu Oracle AI Data Platform ao Oracle Analytics Cloud ou a outras ferramentas de business intelligence.

Você pode se conectar à AI Data Platform de diferentes ferramentas de business intelligence usando um JDBC ou ODBC personalizado fornecido pela AI Data Platform. A Plataforma de Dados de IA também suporta conexões de ferramentas de BI comercial de terceiros (Tableau, Power BI) ou ferramentas de BI de código aberto, como DBeaver. Para estabelecer conexão com essas ferramentas, você precisa dos detalhes da conexão do cluster de computação na sua Plataforma de Dados AI, que você pode encontrar na guia Detalhes da conexão. As informações necessárias variam de acordo com o produto do qual você está se conectando.

Guia de detalhes da conexão do cluster de computação Dev_cluster_1

Conecte o Oracle Analytics à Oracle AI Data Platform

Você pode se conectar ao catálogo ou tabelas gerenciadas pela sua instância do Oracle AI Data Platform de uma instância do Oracle Analytics Cloud.

Para criar uma conexão do Oracle Analytics com a AI Data Platform, você precisa de um arquivo de conexão da AI Data Platform e uma chave de API do Analytics Cloud.

Obter um Arquivo de Configuração de Conexão do Oracle Analytics

Você precisa fazer download de um arquivo config.json da sua instância do Oracle AI Data Platform para conectá-lo ao Oracle Analytics.

Você precisa de um cluster de computação com pelo menos 2 OCPUs, 32 GB de memória para nós de driver e de trabalho e pelo menos 2 workers.

Navegue até seu espaço de trabalho e clique em Compute.
Clique no cluster ao qual você deseja estabelecer conexão com o Oracle Analytics.
Na guia Detalhes da conexão, clique no ícone Fazer Download abaixo do logotipo do Oracle Analytics Cloud. Um arquivo config.json será baixado para sua máquina.

Conectar-se ao Oracle Analytics

Você pode se conectar ao catálogo ou tabelas gerenciadas pela sua instância do Oracle AI Data Platform de uma instância do Oracle Analytics.

Certifique-se de ter um arquivo de configuração de conexão da AI Data Platform antes de criar sua conexão no Oracle Analytics. Consulte Obter um Arquivo de Configuração de Conexão do Oracle Analytics.

As conexões do Oracle Analytics com instâncias da AI Data Platform suportam apenas um catálogo por conexão. Você precisa criar conexões adicionais para usar mais de um catálogo.

Na página inicial do Oracle Analytics, clique em Criar, em seguida, clique em Conexão.
Clique em Oracle AI Data Platform.
Informe um nome e descrição para a sua conexão.
Em Local, especifique onde salvar a conexão. Para compartilhar a conexão com outros usuários, salve-a em /Shared Folders.
No Oracle Analytics Cloud, para Detalhes da Conexão, clique em Selecionar, navegue até o arquivo config.json e clique em Abrir.
Selecione Chave de API como o tipo de autenticação.
Em Chave de API Pública, clique em Gerar e depois em Copiar.
No OCI, adicione uma Chave de API.
1. No OCI, clique no ícone do usuário e depois clique em Definições do Usuário.
2. Em Meu perfil, clique em Tokens e chaves e, em seguida, clique em Adicionar chave de API.
3. Selecione Colar uma chave pública e copie a chave gerada na Etapa 7. Em seguida, clique em Adicionar.
Aguarde de dois a três minutos para que a chave da API seja sincronizada.
Em Catálogo, especifique o nome do Catálogo a ser usado em seus conjuntos de dados.
Se a lista Catálogo não for carregada e você vir a mensagem de alerta "O usuário não tem privilégios suficientes para executar a operação", aguarde um pouco mais para que a chave da API seja sincronizada.
Clique em Salvar.
Teste sua nova conexão criando um conjunto de dados.

Se você tiver seguido as instruções e ainda estiver tendo problemas para salvar sua conexão ou listar seus esquemas, talvez seja necessário reiniciar o cluster.

Fazer Download do Driver JDBC

Você pode fazer download do driver JDBC na guia Detalhes da conexão e configurá-lo para diferentes ferramentas de BI.

Navegue até seu espaço de trabalho e clique em Compute.
Clique no cluster que deseja conectar a uma ferramenta de BI compatível com JDBC e clique em Conexões.
Clique em Download do Driver JDBC.

Configurar DBeaver

Você precisa instalar o DBeaver e preparar arquivos baixados do Oracle AI Data Platform para poder conectá-lo a um cluster de computação na sua AI Data Platform.

Faça download e instale o cliente DBeaver. Você pode usar versões Community ou Enterprise, mas elas devem ser pelo menos 22.x.DBeaver só está disponível para Windows, Mac OS X, Eclipse Plugin e Linux.
Descompacte o arquivo em Download JDBC Driver.
Nos arquivos descompactados, descompacte o arquivo do driver simbaSpark.zip.

Configurar o DBeaver com o Driver JDBC Spark Simba

Você pode configurar o DBeaver para estabelecer conexão com um cluster de computação no Oracle AI Data Platform.

Você deve ter instalado o DBeaver e extraído os arquivos simbaSpark.zip baixados da Plataforma de Dados AI.

Abra o DBeaver.
Clique em Navegador de Banco de Dados.
Clique em Gerenciador de Drivers.
Clique em Novo.
Digite AI Data Platform como o Nome do Driver.
Clique em Bibliotecas.
Clique em Adicionar Pasta.
Navegue até o local da extração sparkSimba.zip.
Clique em Localizar Classe.
Selecione OK.
Defina Classe do driver como com.simba.spark.jdbc.Driver.
Clique em Definições.
Defina Nome da Classe como com.simba.spark.jdbc.Driver.
Clique em OK.

Criar uma Conexão de Banco de Dados no DBeaver

Para conectar o DBeaver a um cluster de computação no Oracle AI Data Platform, primeiro você precisa criar uma conexão de banco de dados no DBeaver.

Você deve ter configurado o DBeaver com o driver JDBC Spark Simba baixado da Plataforma de Dados AI. Para obter mais informações, consulte Configurar DBeaver com o Driver JDBC do Spark Simba.

Abra o DBeaver.
Clique em Banco de Dados.
Clique em Nova Conexão de Banco de Dados.
Clique em All.
Selecione Plataforma de Dados de IA.
Clique em Próximo.
Informe o URL do driver JDBC. Você pode encontrar o URL JDBC na guia Detalhes da conexão do seu cluster de computação na Plataforma de Dados AI.
Clique em Concluir.

Conecte o DBeaver ao Oracle AI Data Platform usando JDBC

Depois que o DBeaver estiver configurado e tiver uma conexão de banco de dados com o Oracle AI Data Platform, você poderá concluir a conexão entre o DBeaver e a AI Data Platform.

Abra o DBeaver.
Clique em Conectar.
Escolha estabelecer conexão com um token de autorização ou uma chave de API.
- Conectar usando token de autorização
  - Use um token não especificando nenhum perfil no URL se você não tiver um perfil DEFAULT. Por exemplo: jdbc:spark://gateway.aidp.me-riyadh-1.oci.oraclecloud.com/default;SparkServerType=AIDP;httpPath=cliservice/cf18b4ef-b83e-41dd-82b6-8d391584f6c5
    O URL abre uma janela do navegador.
    
    Acesse a tenancy em que a instância da AI Data Platform é criada.
    
    Para obter mais informações, consulte Autenticação Baseada em Token para a CLI.
- Estabeleça conexão usando uma chave de API especificando o Perfil do OCI com ociProfile=<profile_name> no URL de conexão.
  - Use a autenticação de chave de API para estabelecer conexão com uma instância da AI Data Platform.
    Use a chave de API especificando o Perfil do OCI com ociProfile=<profile_name> no URL de conexão. Por exemplo, para usar a Demonstração do nome do Perfil do OCI: jdbc:spark://gateway.aidp.me-riyadh-1.oci.oraclecloud.com/default;SparkServerType=AIDP;httpPath=cliservice/cf18b4ef-b83e-41dd-82b6-8d391584f6c5 ;ociProfile=Demo
    
    Para obter mais informações, consulte Chaves e OCIDs Necessários.
O DBeaver cria uma conexão para ler metadados e uma conexão para todas as outras operações. Se você estiver limitado para conexões, poderá desativar a segunda para que o DBeaver use uma conexão para todas as operações.
1. Clique em Preferências.
2. Clique em Comum.
3. Clique em Metadados.
4. Desmarque Abrir conexão separada para leituras de metadados.

Fazer Download do Driver ODBC

Você pode fazer download do driver ODBC na guia Detalhes da conexão e configurá-lo para diferentes ferramentas de BI.

Navegue até seu espaço de trabalho e clique em Compute.
Clique no cluster que deseja conectar a uma ferramenta de BI compatível com ODBC e clique em Conexões.
Clique em Fazer Download do Driver ODBC.
Selecione o sistema operacional apropriado na lista.

API de Execução de Instrução SQL

Você pode usar a API de Execução de Instrução SQL para executar uma instrução SQL somente leitura em um cluster de computação por meio de um aplicativo, automação ou agente externo.

A API retorna o resultado diretamente para pequenos conjuntos de resultados ou fornece um link temporário para resultados maiores. A API de Execução de Instrução SQL usa a assinatura de solicitação do Oracle Cloud Infrastructure. As instruções são executadas usando a identidade e as permissões do chamador autenticado. Você pode enviar um demonstrativo, recuperar seu status e resultados e cancelar um demonstrativo em execução.

Certifique-se de ter o seguinte antes de começar:

Um cluster de computação iniciado com um status Ativo
A chave do cluster de computação (ID). Você pode encontrar isso na guia Detalhes do seu cluster, em Informações Gerais.
O nome do host do gateway do seu cluster. Você pode encontrar o nome do host na guia de detalhes Conexão do seu cluster, no driver JDBC ou no driver ODBC.
Um perfil de token de segurança da CLI do OCI no terminal ou aplicativo da CLI que você está usando. Você pode acessar executando oci session authenticate --profile-name <profile-name> e seguindo os prompts.

Como definir valores de conexão

Certifique-se de ter definido os valores de conexão do seu ambiente no terminal ou no aplicativo em que a CLI do OCI está configurada.

Você pode definir os valores de conexão para seu ambiente usando os seguintes comandos:

export BASE_URI="https://<gateway-host>"
export COMPUTE_CLUSTER_KEY="<compute-cluster-key>"
export REGION="<region>"
export PROFILE="<oci-profile>"
export REQ_SUFFIX="$(date +%s)"

Por exemplo:

export BASE_URI="https://dev1.gateway.dataflow.us-phoenix-1.oci.oc-test.com:443"
export COMPUTE_CLUSTER_KEY="12345a67-b89c-1d23-4567-ef8912345ghi"
export REGION="us-phoenix-1"
export PROFILE="MYPROFILE"
export REQ_SUFFIX="20261022-123456"

Ações da API de Instrução SQL

Para executar ações para a API de Execução de Instrução SQL, você precisa chamar o ponto final na CLI do Oracle Cloud Infrastructure.

Você executa as ações a seguir em um terminal ou aplicativo configurado com a CLI do OCI.

Opções de Solicitação de API de Execução de Instrução SQL

Os campos de solicitação a seguir são usados ao criar uma solicitação de API de Execução de Instrução SQL.

Campo	Descrição
`statement`	Obrigatório. Instrução SQL somente leitura.
`wait_timeout`	Opcional. O tempo máximo que a API aguarda a conclusão da instrução antes de retornar uma resposta.
`disposition`	Especifique INLINE ou EXTERNAL_LINKS.
`row_limit`	O número máximo de linhas retidas para a instrução.
`byte_limit`	O número máximo de bytes retidos para a instrução.
`catalog`	Opcional. O catálogo a ser usado ao executar a instrução.
`schema`	Opcional. O esquema a ser usado durante a execução da instrução.
`parameters`	Opcional. Uma matriz de valores de parâmetro nomeados para a instrução SQL.
`query_tags`	Opcional. Tags de valor-chave para identificar e rastrear uma instrução. Especifique no máximo 20 entradas.
`request_id`	Opcional. Uma correlação ou identificador de idempotência fornecido pelo chamador. Reutilize o valor somente para a mesma solicitação lógica.
`opc-request-id`	Opcional. Um cabeçalho de solicitação para rastrear a solicitação. Use apenas letras, números, sublinhados e hifens.

Enviar uma Instrução SQL

As instruções SQL são submetidas a este ponto final de API:

POST /20200129/computeClusters/<compute-cluster-key>/workbench/sql/statements

O exemplo a seguir inclui um valor wait_timeout opcional de 10 segundos para um resultado:

oci raw-request \
  --target-uri "${BASE_URI}/20200129/computeClusters/${COMPUTE_CLUSTER_KEY}/workbench/sql/statements" \
  --http-method POST \
  --request-headers "$(printf '{"Content-Type":"application/json","opc-request-id":"sql-submit-%s","opc-retry-token":"sql-submit-%s"}' "$REQ_SUFFIX" "$REQ_SUFFIX")" \
  --request-body '{"statement":"SELECT 1 AS api_smoke_test","wait_timeout":"10s","on_wait_timeout":"CONTINUE","format":"JSON_ARRAY","disposition":"INLINE","row_limit":100,"byte_limit":1048576}' \
  --region "${REGION}" \
  --auth security_token \
  --profile "${PROFILE}" \
  | tee /tmp/sql-submit.json \
 | jq '{http_status:.status, statement_id:.data.statement_id, state:.data.status.state, result:.data.result.data_array, opc_request_id:.headers["opc-request-id"]}'

A resposta esperada para o exemplo acima tem esta aparência:

{
  "http_status": "200 OK",
  "statement_id": "095865c4-27ce-41cc-99bb-67af1de760b2",
  "state": "SUCCEEDED",
  "result": [
    [
      "1"
    ]
  ],
  "opc_request_id": "sql-submit-20261022-214855/FBBFDCB770BDEFBC654EAE933E45E811/6CD8518A6A62E6411552DBFEF5ECEAD7"
}

O campo wait_timeout especifica por quanto tempo a API aguarda a conclusão da instrução antes de retornar uma resposta. Se a instrução for concluída dentro do tempo de espera especificado, a API retornará 200 OK e incluirá o resultado da instrução. Se a instrução não for concluída nesse período, a API retornará 202 Accepted e continuará executando a instrução.

Você pode modificar o filtro jq para exibir os campos de resposta exigidos pelo aplicativo. O comando salva a resposta completa da API no arquivo temporário /tmp/sql-submit.json, que pode ser revisado para obter detalhes adicionais da resposta.

Enviar um Demonstrativo com Links Externos

Você pode enviar instruções por meio do mesmo ponto final POST que inclui links externos, como no exemplo a seguir:

oci raw-request \
  --target-uri "${BASE_URI}/20200129/computeClusters/${COMPUTE_CLUSTER_KEY}/workbench/sql/statements" \
  --http-method POST \
  --request-headers '{"Content-Type":"application/json","opc-request-id":"req-sql-external-'"$REQ_SUFFIX"'","opc-retry-token":"retry-sql-external-'"$REQ_SUFFIX"'"}' \
  --request-body "$(jq -nc --arg request_id "sql-external-$REQ_SUFFIX" '{
    statement: "SELECT id, sha2(cast(id AS STRING), 256) AS hash FROM range(2000)",
    wait_timeout: "30s",
    on_wait_timeout: "CONTINUE",
    format: "JSON_ARRAY",
    disposition: "EXTERNAL_LINKS",
    row_limit: 2000,
    byte_limit: 1048576,
    request_id: $request_id
  }')" \
  --no-retry \
  --region "${REGION}" \
  --auth security_token \
  --profile "${PROFILE}" \
  | tee /tmp/sql-external-submit.json \
  | jq '(.data.result // {}) as $result |
    {
      http_status: .status,
      statement_id: .data.statement_id,
      state: .data.status.state,
      disposition: .data.manifest.disposition,
      first_chunk_index: ($result.external_links[0].chunk_index // null),
      first_chunk_row_count: ($result.external_links[0].row_count // null),
      next_chunk_index: $result.next_chunk_index,
      external_link_count: (($result.external_links // []) | length),
      truncated: .data.manifest.truncated,
      opc_request_id: .headers["opc-request-id"]
    }'

A resposta esperada para o exemplo acima é a seguinte:

{
  "http_status": "200 OK",
  "statement_id": "661527ef-dd96-480f-b65a-ac63aad6b910",
  "state": "SUCCEEDED",
  "disposition": "EXTERNAL_LINKS",
  "first_chunk_index": 0,
  "first_chunk_row_count": 1000,
  "next_chunk_index": 1,
  "external_link_count": 1,
  "truncated": false,
  "opc_request_id": "req-sql-external-20261022-225359/6D4D256A0952BA3E8A21A8F4299E35FC/062DA0791BE4E344828CD8F4DE538FD6"
}

Neste exemplo, o link de resultado externo temporário é salvo em /tmp/sql-external-submit.json e não é exibido na resposta do comando.

Observação:

Não compartilhe links de resultados externos ou armazene-os em código-fonte, logs, tickets ou outros locais amplamente acessíveis. Qualquer pessoa que possua um vínculo válido pode acessar os dados de resultado associados até que o vínculo expire.

Se truncated for true, o resultado retornado atingiu o limite de linhas ou de bytes especificado.

Definir statement_id

O statement_id é necessário para recuperar informações sobre a instrução, como status ou resultados, e cancelar uma instrução. Você pode definir o statement_id quando a instrução for enviada da seguinte forma:

export STATEMENT_ID="095865c4-27ce-41cc-99bb-67af1de760b2"
echo "${STATEMENT_ID}"

Se a resposta de envio tiver sido salva em /tmp/sql-submit.json, você poderá definir a statement_id da seguinte forma:

export STATEMENT_ID="$(jq -r '.data.statement_id' /tmp/sql-submit.json)"

Status da Instrução SQL da Solicitação

Você pode recuperar o status de uma instrução submetida usando seu statement_id neste ponto final:

GET /20200129/computeClusters/<compute-cluster-key>/workbench/sql/statements/<statement-id>

O exemplo a seguir recupera o status de uma instrução usando seu statement_id:

oci raw-request \
  --target-uri "${BASE_URI}/20200129/computeClusters/${COMPUTE_CLUSTER_KEY}/workbench/sql/statements/${STATEMENT_ID}" \
  --http-method GET \
  --request-headers "$(printf '{"opc-request-id":"sql-status-%s"}' "$REQ_SUFFIX")" \
  --region "${REGION}" \
  --auth security_token \
  --profile "${PROFILE}" \
  | jq '{http_status:.status, statement_id:.data.statement_id, state:.data.status.state, error:.data.status.error, code:.data.code, message:.data.message, opc_request_id:.headers["opc-request-id"]}'

A resposta esperada para esta solicitação é a seguinte:

{
  "http_status": "200 OK",
  "statement_id": "095865c4-27ce-41cc-99bb-67af1de760b2",
  "state": "SUCCEEDED",
  "error": null,
  "code": null,
  "message": null,
  "opc_request_id": "sql-status-20261022-223517/A80E5E3A0BE5C2673C45E76C5A076B5F/890C178EA4CE5BC332681A546D3FB072"
}

Uma instrução pode ter estes estados:

PENDING
RUNNING
SUCCEEDED
FAILED
CANCELLED

Para uma instrução que retorna 202 Accepted, recupere o status até a instrução atingir um estado terminal: SUCCEEDED, FAILED ou CANCELLED.

Solicitar Resultados do Demonstrativo

Quando uma instrução é concluída, você pode recuperar seu resultado usando statement_id e chunk-index usando o seguinte ponto final:

GET /20200129/computeClusters/<compute-cluster-key>/workbench/sql/statements/<statement-id>/result/chunks/<chunk-index>

Defina o chunk-index para determinar quais resultados serão recuperados ao chamar o ponto final. Um chunk-index de 0 recupera o primeiro resultado. Você pode determinar o chunk-index do próximo resultado verificando o next_chunk_index na resposta. Se o next_chunk_index for null, isso indica que não há partes de resultado adicionais.

export CHUNK_INDEX="0"
export REQ_SUFFIX="$(date +%s)"

Você pode usar row_limit e byte_limit para controlar o volume de dados de resultado que o serviço retém e retorna. Quando um dos limites é atingido, a resposta pode indicar que o resultado está truncado. Uma instrução bem-sucedida não implica que todas as linhas de origem foram retidas no resultado.

Este exemplo demonstra uma solicitação de resultados de instrução:

oci raw-request \
  --target-uri "${BASE_URI}/20200129/computeClusters/${COMPUTE_CLUSTER_KEY}/workbench/sql/statements/${STATEMENT_ID}/result/chunks/${CHUNK_INDEX}" \
  --http-method GET \
  --request-headers "$(printf '{"opc-request-id":"sql-result-chunk-%s"}' "$REQ_SUFFIX")" \
  --region "${REGION}" \
  --auth security_token \
  --profile "${PROFILE}" \
  | jq '(.data.result // .data) as $result |
    {
      http_status: .status,
      statement_id: .data.statement_id,
      chunk_index: $result.chunk_index,
      row_count: $result.row_count,
      row_offset: $result.row_offset,
      result: $result.data_array,
      next_chunk_index: $result.next_chunk_index,
      external_link_count: (($result.external_links // []) | length),
      code: .data.code,
      message: .data.message,
      opc_request_id: .headers["opc-request-id"]
    }'

A resposta aos exemplos acima se assemelha a esta:

{
  "http_status": "200 OK",
  "statement_id": null,
  "chunk_index": 0,
  "row_count": 1,
  "row_offset": 0,
  "result": [
    [
      "1"
    ]
  ],
  "next_chunk_index": null,
  "external_link_count": 0,
  "code": null,
  "message": null,
  "opc_request_id": "sql-result-chunk-20261022-224623/A6702BBF95AEA1AA6D96EFA256B1062B/86AA007BC0A3E6824814EE1A7A246775"
}

Quando uma instrução é concluída, a resposta inclui o status da instrução e os metadados do resultado. Se você especificar INLINE para disposition, o serviço retornará os dados do resultado na resposta. Use INLINE para obter pequenos resultados que um aplicativo pode processar imediatamente. Se você especificar EXTERNAL_LINKS, o serviço armazenará o resultado e retornará um link temporário em vez de incluir os dados do resultado na resposta. Use EXTERNAL_LINKS para obter resultados grandes.

A resposta pode incluir as seguintes informações de resultado:

data_array – Dados de resultado quando o resultado é retornado em linha. Este valor é nulo quando você usa EXTERNAL_LINKS.
external_links – Links temporários para dados de resultado quando você usa EXTERNAL_LINKS.
row_count e byte_count – O número de linhas e bytes no bloco de resultados retornado.
next_chunk_index – O índice do próximo bloco de resultados, quando mais dados de resultados estão disponíveis.
truncated – Indica se o serviço retinha apenas parte do resultado porque o limite de linha ou byte solicitado foi atingido.
expires_at – O horário em que os dados de resultado retidos e os links externos temporários expiram.

Cancelar um Demonstrativo Enviado

É possível cancelar uma instrução em execução. Você precisa do statement_id para a instrução que está tentando cancelar.

Para cancelar uma instrução, envie uma solicitação POST para o seguinte ponto final:

POST /20200129/computeClusters/<compute-cluster-key>/workbench/sql/statements/<statement-id>/cancel

Este exemplo demonstra uma solicitação para cancelar uma instrução:

oci raw-request \
  --target-uri "${BASE_URI}/20200129/computeClusters/${COMPUTE_CLUSTER_KEY}/workbench/sql/statements/${STATEMENT_ID}/cancel" \
  --http-method POST \
  --request-headers "$(printf '{"Content-Type":"application/json","opc-request-id":"sql-cancel-%s"}' "$REQ_SUFFIX")" \
  --request-body '{}' \
  --region "${REGION}" \
  --auth security_token \
  --profile "${PROFILE}" \
  | jq '{http_status:.status, statement_id:.data.statement_id, cancel_state:.data.cancel_state, state:.data.status.state, error:.data.status.error, code:.data.code, message:.data.message, opc_request_id:.headers["opc-request-id"]}'

A resposta aos exemplos acima se parece com esta:

{
  "http_status": "200 OK",
  "statement_id": "9b8ca043-5620-469a-b07c-51d5b99b9963",
  "cancel_state": "COMPLETED",
  "state": "CANCELED",
  "error": null,
  "code": null,
  "message": null,
  "opc_request_id": "sql-cancel-20261022-231732/1BA0029F78EFABC8F3A7D7D8F52E278F/CFB5C5994AF3861143602D08794A2628"
}

Quando o cancelamento for concluído, a API retornará 200 OK. A resposta inclui o ID da instrução e um status CANCELED.

Você pode confirmar o cancelamento recuperando o status do demonstrativo usando o mesmo statement_id:

oci raw-request \
  --target-uri "${BASE_URI}/20200129/computeClusters/${COMPUTE_CLUSTER_KEY}/workbench/sql/statements/${LONG_STATEMENT_ID}" \
  --http-method GET \
  --request-headers "$(printf '{"opc-request-id":"req-sql-canceled-status-%s"}' "$REQ_SUFFIX")" \
  --no-retry \
  --region "${REGION}" \
  --auth security_token \
  --profile "${PROFILE}" \
  | jq '{http_status:.status, statement_id:.data.statement_id, state:.data.status.state, cancel_requested:.data.cancel_requested, error:.data.status.error, opc_request_id:.headers["opc-request-id"]}'

A resposta de verificação tem esta aparência:

{
  "http_status": "200 OK",
  "statement_id": "9b8ca043-5620-469a-b07c-51d5b99b9963",
  "state": "CANCELED",
  "cancel_requested": true,
  "error": null,
  "opc_request_id": "req-sql-canceled-status-20261022/727A96500CCB1BBCF311B91390F7370C/9231C1802E3466B9AF5FBDEA56D0A9EA"
}

Especificar um Catálogo ou Esquema

Você pode especificar um catálogo, um esquema ou ambos ao submeter uma instrução SQL. Os valores especificados na solicitação substituem o contexto da sessão atual. Especifique o catálogo e o esquema para executar a instrução em um catálogo e esquema específicos.

{
  "statement": "SELECT * FROM orders LIMIT 10",
  "catalog": "sales_catalog",
  "schema": "reporting",
  "wait_timeout": "10s",
  "on_wait_timeout": "CONTINUE",
  "format": "JSON_ARRAY",
  "disposition": "INLINE"
}

Você só pode especificar catalog para selecionar um catálogo. Para garantir que uma instrução use um esquema específico, especifique catalog e schema.

Você só pode especificar schema para selecionar um esquema no catálogo atual. Você também pode especificar um nome de esquema qualificado, como sales_catalog.reporting, quando omitir catalog.

Se você não especificar catalog ou schema, a instrução usará o catálogo e o esquema da sessão atual. Se o catálogo ou esquema especificado não existir ou se o chamador não tiver acesso, a instrução poderá ser concluída com o status FAILED. Verifique status.state e status.error em cada resposta de instrução concluída. Sintaxe de campo de esquema ou catálogo inválida retorna 400 Bad Request.

Parâmetros Nomeados

Você pode usar parâmetros nomeados em uma instrução SQL. Especifique um parâmetro na instrução usando dois-pontos seguido do nome do parâmetro, como :id. Não há suporte para parâmetros de posição, como ?. Especifique valores de parâmetro no array parameters. Cada parâmetro contém os seguintes campos:

Campo	Descrição
`name`	Obrigatório. O nome do parâmetro sem o prefixo dois-pontos (:).
`value`	Obrigatório. O valor do parâmetro. Forneça o valor como uma string.
`type`	Opcional. Uma dica de tipo para o valor do parâmetro.

Por exemplo, a seguinte solicitação fornece valores para :id e :name:

{
  "statement": "SELECT :id AS id, :name AS name",
  "parameters": [
    {
      "name": "id",
      "value": "42",
      "type": "INT"
    },
    {
      "name": "name",
      "value": "example",
      "type": "STRING"
    }
  ],
  "wait_timeout": "10s",
  "on_wait_timeout": "CONTINUE",
  "format": "JSON_ARRAY",
  "disposition": "INLINE"
}

A API suporta a seguinte dica de tipo de parâmetro:

Booliano: BOOLEAN
Inteiro: BYTE, TINYINT, SHORT, SMALLINT, INT, INTEGER, LONG, BIGINT
Numérico: FLOAT, DOUBLE, DECIMAL, NUMERIC
DATE and time: DATE, TIMESTAMP, TIMESTAMP_NTZ
Caractere: STRING, CHAR, VARCHAR

O valor do tipo é uma dica de tipo. Não confie nele para preservar uma precisão e escala decimais fornecidas ou uma variante de timestamp. Valide valores e tipos retornados em seu aplicativo.

Diagnosticar e Solucionar Problemas de Respostas de API de Execução de Instrução SQL

Use a tabela a seguir para ajudar a diagnosticar e solucionar problemas de possíveis soluções para respostas de API comuns:

Resposta	Solução
`400 Bad Request`	Verifique se a solicitação inclui uma instrução somente para leitura e valores de solicitação válidos suportados.
`401` ou `403`	Verifique a autenticação do OCI e suas permissões para o cluster de computação e os dados consultados.
`404 Not Found`	Verifique a região, a chave do cluster de computação, a identidade do chamador e o ID da instrução.
`503 Service Unavailable`	Aguarde até que o cluster de computação esteja ativo e tente novamente.

Estabelecer Conexão com Aplicativos Externos com o Spark Connect

Você pode usar o Spark Connect para executar código Spark em um cluster de computação do Oracle AI Data Platform com base em um aplicativo Python ou Java suportado.

Você pode trabalhar em um IDE local ou em um aplicativo externo enquanto o cluster executa suas operações DataFrame e consultas Spark SQL. Por exemplo, você pode desenvolver uma transformação de dados localmente, executá-la em dados disponíveis para seu cluster e recuperar os resultados em seu aplicativo.

Para usar o Spark Connect, certifique-se de ter o seguinte:

Um cluster de computação com um status Ativo.
USE permissões ou mais recentes para o cluster e os dados que você está usando.
Acesso à rede ao nome do host do cluster do Spark Connect na porta 443.
A chave do cluster de computação (ID). Você pode encontrar isso na guia Detalhes do seu cluster, em Informações Gerais.
O nome do host do gateway do seu cluster. Você pode encontrar o nome do host na guia de detalhes Conexão do seu cluster, no driver JDBC ou no driver ODBC.
Um perfil de autenticação do OCI e um cliente Spark Connect compatível.

A AI Data Platform suporta clientes Python e Java e tem os seguintes requisitos para cada um:

Cliente	Requisitos
Python	Python 3.9–3.11, PySpark Connect 3.5.1
Java	JDK 17, Maven 3.8 ou posterior, cliente JVM 3.5.1 do Spark Connect

Estabelecer Conexão com o Spark Connect com um Cliente Python

Este exemplo de Python inclui a configuração de conexão necessária para autenticar com o OCI e criar uma sessão remota do Spark.

Este exemplo requer o spark_connect_example.py e o requirements.txt fornecidos neste pacote: Exemplos de Conexão do Spark.

Abra um terminal no diretório de exemplo extraído. Crie um ambiente virtual e instale as dependências:
```
python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install -r requirements.txt
```
Use o arquivo de dependência fornecido para instalar versões compatíveis das bibliotecas do cliente.

Em seu terminal, defina o nome do host, a chave do cluster e o perfil do OCI:

export SPARK_CONNECT_HOST="<hostname>"
export SPARK_CONNECT_CLUSTER_KEY="<compute-cluster-key>"
export SPARK_CONNECT_OCI_CONFIG_FILE="$HOME/.oci/config"
export SPARK_CONNECT_OCI_CONFIG_PROFILE="<profile-name>"

Substitua os valores em colchetes angulares pelos detalhes da conexão. O perfil do OCI selecionado deve conter credenciais válidas de chave de API ou token de segurança. Por exemplo:

export SPARK_CONNECT_HOST="dev.gateway.example.us-phoenix-1.oci.oc-test.com"
export SPARK_CONNECT_CLUSTER_KEY="a12345b6-cdef-789g-123h-45678i9j1234"
export SPARK_CONNECT_OCI_CONFIG_FILE="$HOME/.oci/config"
export SPARK_CONNECT_OCI_CONFIG_PROFILE="MYPROFILE"

Verifique a conexão:

SPARK_CONNECT_OCI_AUTH_MODE=config \
SPARK_CONNECT_EXAMPLE_TYPE=both \
env -u PYTHONPATH -u SPARK_HOME \
.venv/bin/python spark_connect_example.py

Selecione o método de autenticação que corresponde ao seu perfil:

Tipo de autenticação	Definição
Chave de API	`SPARK_CONNECT_OCI_AUTH_MODE=api_key`
Token de segurança	`SPARK_CONNECT_OCI_AUTH_MODE=security_token`

O exemplo executa uma operação DataFrame e uma consulta Spark SQL. Ambos retornam os IDs de 0 a 4 com seus valores ao quadrado. O terminal exibe os resultados como linhas coletadas. Se as duas operações forem concluídas, o aplicativo será autenticado, conectado ao cluster e executará o código Spark.

Use a sessão do Spark autenticada criada pelo exemplo para executar suas próprias operações. Abra spark_connect_example.py e substitua as operações de amostra dentro do bloco try pelo código do seu aplicativo. Mantenha o código existente que cria a sessão do Spark autenticada.
Por exemplo, para trabalhar com uma DataFrame, você pode usar o seguinte:
```
frame = spark.range(5)

result = frame.withColumn(
    "squared",
    frame["id"] * frame["id"]
)

result.show()
```
Para executar o Spark SQL, você pode usar o seguinte:
```
spark.sql(
    "SELECT id, id * id AS squared FROM range(5)"
).show()
```
Ao consultar suas próprias tabelas, use o catálogo e o esquema apropriados. Sua identidade deve ter permissões para acessar essas tabelas.
Quando seu aplicativo for finalizado, feche a sessão do Spark:
```
spark.stop()
```

Observação:

O exemplo fornecido desativa a execução reanexável para o cliente Spark 3.5.1 documentado:

spark.client.disable_reattachable_execute()

Mantenha essa configuração ao adaptar o exemplo.

Estabelecer Conexão com o Spark Connect com um Cliente Java

Este exemplo de Java inclui a configuração de conexão necessária para autenticar com o OCI e criar uma sessão remota do Spark.

Este exemplo requer o SparkConnectExample.java e o pom.xml fornecidos neste pacote: Exemplos de Conexão do Spark.

Extraia o pacote e abra filename. Siga as instruções fornecidas ao instalar o conteúdo do pacote.

Abra um terminal no diretório de exemplo extraído. Defina o mesmo nome de host, chave de cluster, caminho do arquivo de configuração e perfil:

export SPARK_CONNECT_HOST="<hostname>"
export SPARK_CONNECT_CLUSTER_KEY="<compute-cluster-key>"
export SPARK_CONNECT_OCI_CONFIG_FILE="$HOME/.oci/config"
export SPARK_CONNECT_OCI_CONFIG_PROFILE="<profile-name>"
export SPARK_CONNECT_EXAMPLE_TYPE=both

Substitua os valores em colchetes angulares pelos detalhes da conexão. O perfil do OCI selecionado deve conter credenciais válidas de chave de API ou token de segurança. Por exemplo:

export SPARK_CONNECT_HOST="dev.gateway.example.us-phoenix-1.oci.oc-test.com"
export SPARK_CONNECT_CLUSTER_KEY="a12345b6-cdef-789g-123h-45678i9j1234"
export SPARK_CONNECT_OCI_CONFIG_FILE="$HOME/.oci/config"
export SPARK_CONNECT_OCI_CONFIG_PROFILE="MYPROFILE"
export SPARK_CONNECT_EXAMPLE_TYPE=both

Verifique as conexões:

SPARK_CONNECT_OCI_AUTH_MODE=config \
SPARK_CONNECT_EXAMPLE_TYPE=both \
env -u PYTHONPATH -u SPARK_HOME \
.venv/bin/python spark_connect_example.py"

Selecione o método de autenticação que corresponde ao seu perfil:

Tipo de autenticação	Definição
Chave de API	`SPARK_CONNECT_OCI_AUTH_MODE=api_key`
Token de segurança	`SPARK_CONNECT_OCI_AUTH_MODE=security_token`

Use a sessão do Spark autenticada criada pelo exemplo para executar suas próprias operações.
Por exemplo, para trabalhar com uma DataFrame, você pode usar o seguinte:
```
frame = spark.range(5)

result = frame.withColumn(
    "squared",
    frame["id"] * frame["id"]
)

result.show()
```
Para executar o Spark SQL, você pode usar o seguinte:
```
spark.sql(
    "SELECT id, id * id AS squared FROM range(5)"
).show()
```
Ao consultar suas próprias tabelas, use o catálogo e o esquema apropriados. Sua identidade deve ter permissões para acessar essas tabelas.
Quando seu aplicativo for finalizado, feche a sessão do Spark:
```
spark.stop()
```

Diagnóstico e Solução de Problemas do Spark Connect

A tabela fornecida lista os problemas comuns que você pode encontrar ao configurar as conexões do Spark Connect com o Oracle AI Data Platform e fornece possíveis causas.

Problema	O que verificar
O aplicativo não pode se conectar	Confirme se o cluster está ativo e se o seu ambiente pode acessar o nome do host do gateway na porta 443.
Falha na autenticação	Verifique o caminho do arquivo de configuração, o nome do perfil e as credenciais do OCI. Atualize as credenciais da sessão expirada.
Falha na autorização ou o recurso não pode ser encontrado	Verifique o nome do host e a chave do cluster. Confirme a ativação e a permissão da tenancy para usar o cluster.
Uma consulta não pode acessar uma tabela	Verifique o catálogo, o esquema e o nome da tabela e confirme se a identidade autenticada tem acesso aos dados.
O Python reporta um módulo `pyspark` ou `oci` ausente	Instale as dependências fornecidas e execute o exemplo usando `.venv/bin/python`.
O Python carrega uma versão inesperada do Spark	Use o comando documentado com PYTHONPATH e SPARK_HOME removidos.
O Java reporta uma dependência ausente ou uma biblioteca incompatível	Siga as instruções de configuração fornecidas com o pacote Java e use suas versões de dependência especificadas.