Conexión a la base informática

10 Conexión a los recursos informáticos

En esta sección, se trata la conexión de los recursos informáticos de Oracle AI Data Platform con otras herramientas de inteligencia empresarial.

Temas:

Conexiones

Puede conectar su Oracle AI Data Platform con Oracle Analytics Cloud u otras herramientas de inteligencia empresarial.

Puede conectarse a AI Data Platform desde diferentes herramientas de inteligencia empresarial mediante un JDBC u ODBC personalizado proporcionado por AI Data Platform. AI Data Platform también soporta conexiones de herramientas de BI comerciales de terceros (Tableau, Power BI) o herramientas de BI de código abierto como DBeaver. Para conectarse desde estas herramientas, necesita los detalles de conexión del cluster de recursos informáticos en su plataforma de datos de IA, que puede encontrar en el separador Detalles de conexión. La información necesaria varía según el producto desde el que se conecte.

Separador Detalles de conexión para el cluster de recursos informáticos Dev_cluster_1

Conecte Oracle Analytics a Oracle AI Data Platform

Puede conectarse al catálogo o las tablas gestionadas por la instancia de Oracle AI Data Platform desde una instancia de Oracle Analytics Cloud.

Para crear una conexión de Oracle Analytics a AI Data Platform, necesita un archivo de conexión de AI Data Platform y una clave de API de Analytics Cloud.

Obtener un archivo de configuración de conexión de Oracle Analytics

Debe descargar un archivo config.json de la instancia de Oracle AI Data Platform para conectarlo a Oracle Analytics.

Necesita un cluster de recursos informáticos con al menos 2 OCPU, 32 GB de memoria tanto para los nodos de controlador como de trabajador, y al menos 2 trabajadores.

Vaya al espacio de trabajo y haga clic en Recursos informáticos.
Haga clic en el cluster al que desea conectarse a Oracle Analytics.
En el separador Detalles de conexión, haga clic en el icono Descargar debajo del logotipo de Oracle Analytics Cloud. Un archivo config.json se descarga en su máquina.

Conectarse a Oracle Analytics

Puede conectarse al catálogo o las tablas gestionadas por la instancia de Oracle AI Data Platform desde una instancia de Oracle Analytics.

Asegúrese de tener un archivo de configuración de conexión de AI Data Platform antes de crear la conexión en Oracle Analytics. Consulte Obtención de un archivo de configuración de conexión de Oracle Analytics.

Las conexiones de Oracle Analytics a instancias de AI Data Platform solo soportan un catálogo por conexión. Debe crear conexiones adicionales para utilizar más de un catálogo.

En la página de inicio de Oracle Analytics, haga clic en Crear y, a continuación, en Conexión.
Haga clic en Oracle AI Data Platform.
Introduzca el nombre y la descripción de la conexión.
En Ubicación, especifique dónde guardar la conexión. Para compartir la conexión con otros usuarios, guárdela en /Carpetas compartidas.
En Oracle Analytics Cloud, para Detalles de conexión, haga clic en Seleccionar, vaya al archivo config.json y haga clic en Abrir.
Seleccione Clave de API como tipo de autenticación.
En Clave de API pública, haga clic en Generar y, a continuación, en Copiar.
En OCI, agregue una clave de API.
1. En OCI, haga clic en el icono de usuario y, a continuación, en Configuración de usuario.
2. En Mi perfil, haga clic en Tokens y claves y, a continuación, en Agregar clave de API.
3. Seleccione Pegar una clave pública, copie la clave que ha generado en el paso 7 y, a continuación, haga clic en Agregar.
Espere de dos a tres minutos para que la clave de API se sincronice.
En Catálogo, especifique el nombre del catálogo que se utilizará en los juegos de datos.
Si la lista Catálogo no se carga y aparece el mensaje de alerta "El usuario no tiene privilegios suficientes para realizar la operación", espere un poco más para que la clave de API se sincronice.
Haga clic en Guardar.
Pruebe la nueva conexión creando un juego de datos.

Si ha seguido las instrucciones y aún tiene problemas para guardar la conexión o mostrar los esquemas, puede que sea necesario reiniciar el cluster.

Descargar controlador JDBC

Puede descargar el controlador JDBC desde el separador Detalles de conexión y configurarlo para diferentes herramientas de BI.

Vaya al espacio de trabajo y haga clic en Recursos informáticos.
Haga clic en el cluster que desea conectar a una herramienta de BI compatible con JDBC y haga clic en Conexiones.
Haga clic en Descargar controlador JDBC.

Configuración de DBeaver

Debe instalar DBeaver y preparar los archivos descargados de Oracle AI Data Platform antes de conectarlos a un cluster de recursos informáticos en su AI Data Platform.

Descargue e instale el cliente DBeaver. Puede utilizar las versiones de Community o Enterprise, pero deben ser al menos 22.x.DBeaver solo está disponible para Windows, Mac OS X, Eclipse Plugin y Linux.
Descomprima el archivo desde Descargar controlador JDBC.
En los archivos descomprimidos, descomprima el archivo de controlador simbaSpark.zip.

Configuración de DBeaver con el controlador JDBC de Spark Simba

Puede configurar DBeaver para conectarse a un cluster de recursos informáticos en su Oracle AI Data Platform.

Debe haber instalado DBeaver y extraído los archivos simbaSpark.zip descargados de AI Data Platform.

Abra DBeaver.
Haga clic en Navegador de base de datos.
Haga clic en Gestor de controladores.
Haga clic en Nuevo.
Introduzca AI Data Platform como Nombre del controlador.
Haga clic en Bibliotecas.
Haga clic en Agregar Carpeta.
Busque la ubicación de la extracción sparkSimba.zip.
Haga clic en Buscar clase.
Seleccione Aceptar.
Defina Clase de controlador en com.simba.spark.jdbc.Driver.
Haga clic en Configuración.
Defina Nombre de clase en com.simba.spark.jdbc.Driver.
Haga clic en Aceptar.

Creación de una conexión de base de datos en DBeaver

Para conectar DBeaver a un cluster de recursos informáticos en su Oracle AI Data Platform, primero debe crear una conexión de base de datos en DBeaver.

Debe haber configurado DBeaver con el controlador JDBC de Spark Simba descargado de AI Data Platform. Para obtener más información, consulte Configuración de DBeaver con el controlador JDBC de Spark Simba.

Abra DBeaver.
Haga clic en Base de datos.
Haga clic en Nueva Conexión a Base de Datos.
Haga clic en Todo.
Seleccione Plataforma de datos de IA.
Haga clic en Siguiente.
Introduzca la URL del controlador JDBC. Puede encontrar la URL de JDBC en el separador Detalles de conexión del cluster de recursos informáticos en AI Data Platform.
Haga clic en Finalizar.

Conecte DBeaver a Oracle AI Data Platform mediante JDBC

Una vez que DBeaver esté configurado y tenga una conexión de base de datos a su Oracle AI Data Platform, puede completar la conexión entre DBeaver y AI Data Platform.

Abra DBeaver.
Haga clic en Conectar.
Elija conectarse con un token de autorización o una clave de API.
- Conexión mediante token de autorización
  - Utilice un token al no especificar ningún perfil en la URL si no tiene un perfil DEFAULT. Por ejemplo: jdbc:spark://gateway.aidp.me-riyadh-1.oci.oraclecloud.com/default;SparkServerType=AIDP;httpPath=cliservice/cf18b4ef-b83e-41dd-82b6-8d391584f6c5
    La URL abre una ventana del explorador.
    
    Conéctese al arrendamiento en el que se crea la instancia de AI Data Platform.
    
    Para obtener más información, consulte Autenticación basada en token para CLI.
- Conéctese mediante una clave de API especificando el perfil de OCI con ociProfile=<profile_name> en la URL de conexión.
  - Utilice la autenticación de clave de API para conectarse a una instancia de AI Data Platform.
    Utilice la clave de API especificando el perfil de OCI con ociProfile=<profile_name> en la URL de conexión. Por ejemplo, para utilizar la demostración de nombre de perfil de OCI: jdbc:spark://gateway.aidp.me-riyadh-1.oci.oraclecloud.com/default;SparkServerType=AIDP;httpPath=cliservice/cf18b4ef-b83e-41dd-82b6-8d391584f6c5 ;ociProfile=Demo
    
    Para obtener más información, consulte Claves y OCID necesarios.
DBeaver crea una conexión para leer metadatos y una conexión para todas las demás operaciones. Si tiene limitaciones para las conexiones, puede desactivar la segunda para que DBeaver utilice una conexión para todas las operaciones.
1. Haga clic en Preferencias.
2. Haga clic en Común.
3. Haga clic en Metadatos.
4. Anule la selección de Abrir conexión independiente para lecturas de metadatos.

Descargar controlador ODBC

Puede descargar el controlador ODBC desde el separador Detalles de conexión y configurarlo para diferentes herramientas de BI.

Vaya al espacio de trabajo y haga clic en Recursos informáticos.
Haga clic en el cluster al que desea conectarse a una herramienta de BI compatible con ODBC y haga clic en Conexiones.
Haga clic en Descargar controlador ODBC.
Seleccione el sistema operativo adecuado de la lista.

API de Ejecución de Sentencias SQL

Puede utilizar la API de ejecución de sentencias SQL para ejecutar una sentencia SQL de solo lectura en un cluster de recursos informáticos desde una aplicación, automatización o agente externos.

La API devuelve el resultado directamente para juegos de resultados pequeños o proporciona un enlace temporal para resultados más grandes. La API de ejecución de sentencias SQL utiliza la firma de solicitudes de Oracle Cloud Infrastructure. Las sentencias se ejecutan mediante la identidad y los permisos del emisor de llamada autenticado. Puede enviar una sentencia, recuperar su estado y resultados y cancelar una sentencia en ejecución.

Asegúrese de tener lo siguiente antes de comenzar:

Un cluster de recursos informáticos iniciado con estado Activo
La clave (ID) del cluster de recursos informáticos. Puede encontrarlo en el separador Detalles del cluster, en Información general.
El nombre de host de la puerta de enlace para el cluster. Puede encontrar el nombre de host en el separador de detalles de conexión del cluster, en el controlador JDBC o en el controlador ODBC.
Perfil de token de seguridad de la CLI de OCI en el terminal o la aplicación de la CLI que está utilizando. Puede conectarse ejecutando oci session authenticate --profile-name <profile-name> y siguiendo las peticiones de datos.

Cómo definir valores de conexión

Asegúrese de que ha definido los valores de conexión para su entorno en el terminal o la aplicación donde está configurada la CLI de OCI.

Puede definir los valores de conexión para su entorno mediante los siguientes 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 ejemplo:

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"

Acciones de API de sentencias SQL

Para ejecutar acciones para la API de ejecución de sentencias SQL, debe llamar al punto final desde la CLI de Oracle Cloud Infrastructure.

Las siguientes acciones se ejecutan desde un terminal o aplicación configurados con la CLI de OCI.

Opciones de Solicitud de API de Ejecución de Sentencias SQL

Los siguientes campos de solicitud se utilizan al crear una solicitud de API de ejecución de sentencias SQL.

Campo	Descripción
`statement`	Es obligatorio. Sentencia SQL de sólo lectura.
`wait_timeout`	Opcional. Tiempo máximo que la API espera a que finalice la sentencia antes de devolver una respuesta.
`disposition`	Especifique INLINE o EXTERNAL_LINKS.
`row_limit`	Número máximo de filas retenidas para la sentencia.
`byte_limit`	Número máximo de bytes retenidos para la sentencia.
`catalog`	Opcional. Catálogo que se utilizará al ejecutar la sentencia.
`schema`	Opcional. Esquema que se utilizará al ejecutar la sentencia.
`parameters`	Opcional. Matriz de valores de parámetros con nombre para la sentencia SQL.
`query_tags`	Opcional. Etiquetas de clave-valor para identificar y realizar un seguimiento de una sentencia. No especifique más de 20 entradas.
`request_id`	Opcional. Un identificador de correlación o idempotencia proporcionado por el emisor de llamada. Vuelva a utilizar el valor solo para la misma solicitud lógica.
`opc-request-id`	Opcional. Cabecera de solicitud para rastrear la solicitud. Utilice sólo letras, números, guiones bajos y guiones.

Enviar una sentencia SQL

Las sentencias SQL se envían a este punto final de API:

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

El siguiente ejemplo incluye un valor wait_timeout opcional de 10 segundos para un 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"]}'

La respuesta esperada al ejemplo anterior es la siguiente:

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

El campo wait_timeout especifica cuánto tiempo espera la API a que finalice la sentencia antes de devolver una respuesta. Si la sentencia finaliza en el tiempo de espera especificado, la API devuelve 200 OK e incluye el resultado de la sentencia. Si la sentencia no se completa en este momento, la API devuelve 202 Accepted y continúa ejecutando la sentencia.

Puede modificar el filtro jq para mostrar los campos de respuesta que necesita la aplicación. El comando guarda la respuesta de API completa en el archivo temporal /tmp/sql-submit.json, que se puede revisar para obtener detalles de respuesta adicionales.

Enviar un extracto con enlaces externos

Puede enviar sentencias a través del mismo punto final POST que incluyen enlaces externos, como en el siguiente ejemplo:

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"]
    }'

La respuesta esperada al ejemplo anterior es la siguiente:

{
  "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"
}

En este ejemplo, el enlace de resultado externo temporal se guarda en /tmp/sql-external-submit.json y no se muestra en la respuesta del comando.

Note:

No comparta enlaces de resultados externos ni los almacene en código fuente, logs, tickets u otras ubicaciones de acceso amplio. Cualquier persona que tenga un vínculo válido puede acceder a los datos de resultados asociados hasta que el vínculo caduque.

Si truncated es true, el resultado devuelto alcanzó el límite de filas o bytes especificado.

Defina statement_id

statement_id es necesario para recuperar información sobre la sentencia, como el estado o los resultados, y para cancelar una sentencia. Puede definir statement_id cuando la sentencia se envíe de la siguiente forma:

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

Si la respuesta de envío se ha guardado en /tmp/sql-submit.json, puede definir statement_id de la siguiente manera:

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

Estado de Sentencia SQL de Solicitud

Puede recuperar el estado de una sentencia enviada mediante su statement_id desde este punto final:

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

En el siguiente ejemplo, se recupera el estado de una sentencia mediante 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"]}'

La respuesta esperada para esta solicitud es la siguiente:

{
  "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"
}

Una sentencia puede tener los siguientes estados:

PENDING
RUNNING
SUCCEEDED
FAILED
CANCELLED

Para una sentencia que devuelve 202 Accepted, recupere el estado hasta que la sentencia alcance un estado de terminal: SUCCEEDED, FAILED o CANCELLED.

Solicitar resultados de extracto

Cuando se completa una sentencia, puede recuperar su resultado mediante statement_id y el resultado chunk-index mediante el siguiente punto final:

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

Defina chunk-index para determinar qué resultados se recuperan al llamar al punto final. Un valor chunk-index de 0 recupera el primer resultado. Puede determinar el chunk-index del siguiente resultado comprobando el next_chunk_index en la respuesta. Si next_chunk_index es null, indica que no hay fragmentos de resultados adicionales.

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

Puede utilizar row_limit y byte_limit para controlar la cantidad de datos de resultados que el servicio conserva y devuelve. Cuando se alcanza cualquiera de los límites, la respuesta puede indicar que el resultado está truncado. Una sentencia correcta no implica que todas las filas de origen se hayan retenido en el resultado.

En este ejemplo se muestra una solicitud de resultados de sentencias:

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"]
    }'

La respuesta a los ejemplos anteriores se ve así:

{
  "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"
}

Cuando se completa una sentencia, la respuesta incluye el estado de la sentencia y los metadatos del resultado. Si especifica INLINE para disposition, el servicio devuelve los datos de resultado en la respuesta. Utilice INLINE para obtener resultados pequeños que una aplicación puede procesar inmediatamente. Si especifica EXTERNAL_LINKS, el servicio almacena el resultado y devuelve un enlace temporal en lugar de incluir los datos del resultado en la respuesta. Utilice EXTERNAL_LINKS para obtener resultados de gran tamaño.

La respuesta puede incluir la siguiente información de resultado:

data_array: datos de resultados cuando el resultado se devuelve en línea. Este valor es nulo cuando se utiliza EXTERNAL_LINKS.
external_links: enlaces temporales a datos de resultados cuando se utiliza EXTERNAL_LINKS.
row_count y byte_count: número de filas y bytes en el fragmento de resultados devuelto.
next_chunk_index: índice del siguiente fragmento de resultados, cuando hay más datos de resultados disponibles.
truncated: indica si el servicio ha retenido solo una parte del resultado porque se ha alcanzado el límite de fila o byte solicitado.
expires_at: el tiempo en que caducan los datos de resultados retenidos y los enlaces externos temporales.

Cancelar un estado de cuenta enviado

Puede cancelar una sentencia que se esté ejecutando. Necesita statement_id para la sentencia que está intentando cancelar.

Para cancelar una sentencia, envíe una solicitud POST al siguiente punto final:

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

En este ejemplo, se muestra una solicitud para cancelar una sentencia:

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"]}'

La respuesta a los ejemplos anteriores se ve así:

{
  "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"
}

Cuando finaliza la cancelación, la API devuelve 200 OK. La respuesta incluye el ID de sentencia y el estado CANCELED.

Puede confirmar la cancelación recuperando el estado de la sentencia con el mismo 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"]}'

La respuesta de verificación es similar a la siguiente:

{
  "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 un catálogo o esquema

Puede especificar un catálogo, un esquema o ambos al enviar una sentencia SQL. Los valores que especifique en la solicitud sustituyen el contexto de sesión actual. Especifique el catálogo y el esquema para ejecutar la sentencia en un catálogo y 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"
}

Solo puede especificar catalog para seleccionar un catálogo. Para asegurarse de que una sentencia utiliza un esquema específico, especifique catalog y schema.

Solo puede especificar schema para seleccionar un esquema en el catálogo actual. También puede especificar un nombre de esquema cualificado, como sales_catalog.reporting, al omitir catalog.

Si no especifica catalog o schema, la sentencia utiliza el catálogo y el esquema de la sesión actual. Si el catálogo o esquema especificado no existe o si el emisor de la llamada no tiene acceso, la sentencia se puede completar con el estado FAILED. Compruebe status.state y status.error en cada respuesta de sentencia terminada. La sintaxis de campo de esquema o catálogo no válida devuelve 400 Bad Request.

Paramaters nombrados

Puede utilizar parámetros con nombre en una sentencia SQL. Especifique un parámetro en la sentencia utilizando dos puntos seguidos del nombre del parámetro, como :id. Los parámetros de posición, como ?, no están soportados. Especifique valores de parámetros en la matriz parameters. Cada parámetro contiene los siguientes campos:

Campo	Descripción
`name`	Es obligatorio. Nombre del parámetro sin el prefijo de dos puntos (:).
`value`	Es obligatorio. Valor del parámetro. Proporcione el valor como una cadena.
`type`	Opcional. Indicación de tipo para el valor de parámetro.

Por ejemplo, la siguiente solicitud proporciona valores para :id y :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"
}

La API soporta la siguiente indicación de tipo de parámetro:

Booleano: BOOLEAN
Entero: BYTE, TINYINT, SHORT, SMALLINT, INT, INTEGER, LONG, BIGINT
Numérico: Liso, DOBLE, DECIMAL, NUMERIC
Fecha y hora: DATE, TIMESTAMP, TIMESTAMP_NTZ
Carácter: STRING, CHAR, VARCHAR

El valor de tipo es una indicación de tipo. No confíe en ella para preservar una precisión y escala decimales proporcionadas o una variante de registro de hora. Valide los valores y tipos devueltos en la aplicación.

Solución de Problemas de Respuestas de API de Ejecución de Sentencias SQL

Utilice la siguiente tabla para ayudar a solucionar posibles soluciones a respuestas de API comunes:

Respuesta	Solución
`400 Bad Request`	Verifique que la solicitud incluya una sentencia de solo lectura soportada y valores de solicitud válidos.
`401` o `403`	Verifique la autenticación de OCI y sus permisos para el cluster de recursos informáticos y los datos consultados.
`404 Not Found`	Verifique la región, la clave de cluster de recursos informáticos, la identidad del emisor de llamada y el ID de sentencia.
`503 Service Unavailable`	Espere hasta que el cluster de recursos informáticos esté activo y, a continuación, vuelva a intentarlo.

Conexión a aplicaciones externas con Spark Connect

Puede utilizar Spark Connect para ejecutar código de Spark en un cluster de recursos informáticos de Oracle AI Data Platform desde una aplicación Python o Java soportada.

Puede trabajar desde un IDE local o una aplicación externa mientras el cluster ejecuta las operaciones DataFrame y las consultas SQL de Spark. Por ejemplo, puede desarrollar una transformación de datos localmente, ejecutarla con los datos disponibles para el cluster y recuperar los resultados en la aplicación.

Para utilizar Spark Connect, asegúrese de que tiene lo siguiente:

Cluster de recursos informáticos con el estado Activo.
Utilice permisos o más para el cluster y los datos que está utilizando.
Acceso de red al nombre de host del cluster de Spark Connect en el puerto 443.
La clave (ID) del cluster de recursos informáticos. Puede encontrarlo en el separador Detalles del cluster, en Información general.
El nombre de host de la puerta de enlace para el cluster. Puede encontrar el nombre de host en el separador de detalles de conexión del cluster, en el controlador JDBC o en el controlador ODBC.
Perfil de autenticación de OCI y cliente de Spark Connect compatible.

AI Data Platform soporta clientes Python y Java y tiene los siguientes requisitos para cada uno:

Cliente	Requisitos
Python	Python 3.9–3.11, conexión PySpark 3.5.1
Java	JDK 17, Maven 3.8 o posterior, cliente JVM de Spark Connect 3.5.1

Conexión a Spark Connect con un cliente Python

En este ejemplo de Python se incluye la configuración de conexión necesaria para autenticarse con OCI y crear una sesión de Spark remota.

Este ejemplo requiere spark_connect_example.py y requirements.txt proporcionados en este grupo: Ejemplos de Spark Connect.

Abra un terminal en el directorio de ejemplo extraído. Cree un entorno virtual e instale las dependencias:
```
python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install -r requirements.txt
```
Utilice el archivo de dependencia proporcionado para instalar versiones compatibles de las bibliotecas de cliente.

En su terminal, defina el nombre de host, la clave de cluster y el perfil de 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>"

Sustituya los valores entre corchetes angulares por los detalles de conexión. El perfil de OCI seleccionado debe contener credenciales válidas de clave de API o de token de seguridad. Por ejemplo:

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"

Compruebe que la conexión:

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

Seleccione el método de autenticación que coincida con su perfil:

Tipo de Autenticación	Valor
Clave de API	`SPARK_CONNECT_OCI_AUTH_MODE=api_key`
Token de seguridad	`SPARK_CONNECT_OCI_AUTH_MODE=security_token`

En el ejemplo se ejecuta una operación DataFrame y una consulta SQL de Spark. Ambos devuelven los ID del 0 al 4 con sus valores cuadrados. El terminal muestra los resultados como filas recopiladas. Si se completan ambas operaciones, la aplicación se ha autenticado, conectado al cluster y ejecuta código de Spark.

Utilice la sesión de Spark autenticada creada por el ejemplo para ejecutar sus propias operaciones. Abra spark_connect_example.py y sustituya las operaciones de ejemplo dentro del bloque try por el código de aplicación. Mantenga el código existente que crea la sesión de Spark autenticada.
Por ejemplo, para trabajar con DataFrame, puede utilizar lo siguiente:
```
frame = spark.range(5)

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

result.show()
```
Para ejecutar Spark SQL puede utilizar lo siguiente:
```
spark.sql(
    "SELECT id, id * id AS squared FROM range(5)"
).show()
```
Al consultar sus propias tablas, utilice el catálogo y el esquema adecuados. Su identidad debe tener permisos para acceder a esas tablas.
Cuando termine la aplicación, cierre la sesión de Spark:
```
spark.stop()
```

Note:

El ejemplo proporcionado desactiva la ejecución que se puede volver a asociar para el cliente Spark 3.5.1 documentado:

spark.client.disable_reattachable_execute()

Mantenga esta configuración al adaptar el ejemplo.

Conexión a Spark Connect con un cliente Java

En este ejemplo de Java se incluye la configuración de conexión necesaria para autenticarse con OCI y crear una sesión de Spark remota.

Este ejemplo requiere SparkConnectExample.java y pom.xml proporcionados en este grupo: Ejemplos de Spark Connect.

Extraiga el paquete y abra filename. Siga las instrucciones que se proporcionan para instalar el contenido del paquete.

Abra un terminal en el directorio de ejemplo extraído. Defina el mismo nombre de host, clave de cluster, ruta de archivo de configuración y 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

Sustituya los valores entre corchetes angulares por los detalles de conexión. El perfil de OCI seleccionado debe contener credenciales válidas de clave de API o de token de seguridad. Por ejemplo:

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 las conexiones:

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

Seleccione el método de autenticación que coincida con su perfil:

Tipo de Autenticación	Valor
Clave de API	`SPARK_CONNECT_OCI_AUTH_MODE=api_key`
Token de seguridad	`SPARK_CONNECT_OCI_AUTH_MODE=security_token`

Utilice la sesión de Spark autenticada creada por el ejemplo para ejecutar sus propias operaciones.
Por ejemplo, para trabajar con DataFrame, puede utilizar lo siguiente:
```
frame = spark.range(5)

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

result.show()
```
Para ejecutar Spark SQL puede utilizar lo siguiente:
```
spark.sql(
    "SELECT id, id * id AS squared FROM range(5)"
).show()
```
Al consultar sus propias tablas, utilice el catálogo y el esquema adecuados. Su identidad debe tener permisos para acceder a esas tablas.
Cuando termine la aplicación, cierre la sesión de Spark:
```
spark.stop()
```

Solución de problemas de Spark Connect

En la tabla proporcionada se muestran los problemas comunes que puede encontrar al configurar conexiones de Spark Connect a Oracle AI Data Platform y se proporcionan posibles causas.

Problema	Qué comprobar
La aplicación no se puede conectar	Confirme que el cluster esté activo y que su entorno pueda acceder al nombre de host de la puerta de enlace en el puerto 443.
Fallo de autenticación	Compruebe la ruta del archivo de configuración de OCI, el nombre de perfil y las credenciales. Refrescar credenciales de sesión caducadas.
La autorización falla o no se encuentra el recurso	Compruebe el nombre de host y la clave de cluster. Confirme la activación del arrendamiento y el permiso para utilizar el cluster.
Una consulta no puede acceder a una tabla	Compruebe el catálogo, el esquema y el nombre de tabla, y confirme que la identidad autenticada tiene acceso a los datos.
Python informa que falta un módulo `pyspark` o `oci`	Instale las dependencias proporcionadas y ejecute el ejemplo con `.venv/bin/python`.
Python carga una versión de Spark inesperada	Utilice el comando documentado con PYTHONPATH y SPARK_HOME eliminado.
Java informa que falta una dependencia o una biblioteca incompatible	Siga las instrucciones de configuración proporcionadas con el paquete de Java y utilice las versiones de dependencia especificadas.