10 Connettiti a Compute

In questa sezione viene descritto come connettere la computazione nella tua Oracle AI Data Platform ad altri strumenti di business intelligence.

connessioni

Puoi connettere la tua Oracle AI Data Platform con Oracle Analytics Cloud o altri strumenti di business intelligence.

È possibile connettersi a AI Data Platform da diversi strumenti di business intelligence utilizzando un JDBC o un ODBC personalizzato fornito da AI Data Platform. AI Data Platform supporta anche le connessioni da strumenti di BI commerciali di terze parti (Tableau, Power BI) o strumenti di BI open source come DBeaver. Per connettersi da questi strumenti, è necessario disporre dei dettagli di connessione del cluster di computazione nella piattaforma dati AI, che è possibile trovare nella scheda Dettagli connessione. Le informazioni richieste variano a seconda del prodotto da cui ci si connette.


Scheda Dettagli connessione per il cluster di computazione Dev_cluster_1

Connetti Oracle Analytics a Oracle AI Data Platform

È possibile connettersi al catalogo o alle tabelle gestite dall'istanza di Oracle AI Data Platform da un'istanza di Oracle Analytics Cloud.

Per creare una connessione da Oracle Analytics a AI Data Platform, è necessario un file di connessione da AI Data Platform e una chiave API da Analytics Cloud.

Ottenere un file di configurazione della connessione di Oracle Analytics

Per connetterlo a Oracle Analytics, devi scaricare un file config.json dall'istanza di Oracle AI Data Platform.

Hai bisogno di un cluster di computazione con almeno 2 OCPU, 32 GB di memoria sia per i nodi driver che per quelli di lavoro e almeno 2 lavoratori.
  1. Passare all'area di lavoro e fare clic su Computazione.

    Pagina Compute aperta con il cluster di computazione Cluster_High evidenziato

  2. Fare clic sul cluster a cui connettersi a Oracle Analytics.
  3. Nella scheda Dettagli connessione fare clic sull'icona Scarica sotto il logo di Oracle Analytics Cloud. Un file config.json viene scaricato sul computer.

    Pagina Compute per il cluster Cluster_High aperta con la scheda Dettagli connessione e download di Oracle Analytics Cloud evidenziato

Connettersi a Oracle Analytics

È possibile connettersi al catalogo o alle tabelle gestite dall'istanza di Oracle AI Data Platform da un'istanza di Oracle Analytics.

Assicurarsi di disporre di un file di configurazione della connessione da AI Data Platform prima di creare la connessione in Oracle Analytics. Vedere Recuperare un file di configurazione della connessione a Oracle Analytics.
Le connessioni di Oracle Analytics alle istanze di AI Data Platform supportano un solo catalogo per connessione. È necessario creare connessioni aggiuntive per utilizzare più cataloghi.
  1. Nella home page di Oracle Analytics, fare clic su Crea, quindi su Connessione.
  2. Fare clic su Oracle AI Data Platform.
  3. Immettere un nome e un'indicazione per la connessione.
  4. In Posizione specificare dove salvare la connessione. Per condividere la connessione con altri utenti, salvarla in /Cartelle condivise.
  5. In Oracle Analytics Cloud, per Dettagli connessione, fare clic su Seleziona, andare al file config.json e fare clic su Apri.
  6. Selezionare Chiave API come tipo di autenticazione.
  7. In Chiave API pubblica, fare clic su Genera, quindi su Copia.
  8. In OCI, aggiungere una chiave API.
    1. In OCI, fare clic sull'icona utente, quindi fare clic su Impostazioni utente.
    2. Nel profilo personale, fare clic su Tasti e tasti, quindi su Aggiungi chiave API.
    3. Selezionare Incolla una chiave pubblica, quindi copiare la chiave generata nel Passo 7, quindi fare clic su Aggiungi.
    Attendere da due a tre minuti per la sincronizzazione della chiave API.
  9. In Catalogo specificare il nome del catalogo da utilizzare nei set di dati.
    Se la lista Catalogo non viene caricata e viene visualizzato il messaggio di avviso "L'utente non dispone di privilegi sufficienti per eseguire l'operazione", attendere un po' di più per la sincronizzazione della chiave API.
  10. Fare clic su Save.
  11. Eseguire il test della nuova connessione creando un data set.

Se si sono seguite le istruzioni e si stanno ancora salvando problemi durante il salvataggio della connessione o la creazione di una lista degli schemi, potrebbe essere necessario riavviare il cluster.

Scarica driver JDBC

È possibile scaricare il driver JDBC dalla scheda Dettagli connessione e configurarlo per diversi strumenti BI.

  1. Passare all'area di lavoro e fare clic su Computazione.
  2. Fare clic sul cluster che si desidera connettere a uno strumento BI compatibile con JDBC e fare clic su Connessioni.
  3. Fare clic su Scarica driver JDBC.

Configura DBeaver

Devi installare DBeaver e preparare i file scaricati da Oracle AI Data Platform prima di poterli connettere a un cluster di computazione nella tua AI Data Platform.

  1. Scarica e installa il client DBeaver. Puoi utilizzare le versioni Community o Enterprise, ma devono essere almeno 22.x.DBeaver è disponibile solo per Windows, Mac OS X, Eclipse Plugin e Linux.
  2. Estrarre il file da Scarica driver JDBC.
  3. Dai file estratti, decomprimere il file del driver simbaSpark.zip.

Configura DBeaver con il driver JDBC Spark Simba

Puoi configurare DBeaver per la connessione a un cluster di computazione in Oracle AI Data Platform.

È necessario aver installato DBeaver ed estratto i file simbaSpark.zip scaricati da AI Data Platform.
  1. Apri DBeaver.
  2. Fare clic su Navigator database.
  3. Fare clic su Gestione driver.
  4. Fare clic su Nuovo.
  5. Immettere AI Data Platform come Nome driver.
  6. Fare clic su Librerie.
  7. Fare clic su Aggiungi cartella.
  8. Cercare la posizione dell'estrazione sparkSimba.zip.
  9. Fare clic su Trova classe.
  10. Selezionare OK.
  11. Impostare la classe driver su com.simba.spark.jdbc.Driver.
  12. Fare clic su Impostazioni.
  13. Impostare Nome classe su com.simba.spark.jdbc.Driver.
  14. Fare clic su OK.

Creare una connessione al database in DBeaver

Per connettere DBeaver a un cluster di computazione in Oracle AI Data Platform, devi prima creare una connessione al database in DBeaver.

È necessario aver configurato DBeaver con il driver JDBC Spark Simba scaricato da AI Data Platform. Per ulteriori informazioni, vedere Configurare DBeaver con il driver JDBC Spark Simba.
  1. Apri DBeaver.
  2. Fare clic su Database.
  3. Fare clic su Nuova connessione al database.
  4. Fare clic su Tutto.
  5. Seleziona AI Data Platform.
  6. Fare clic su Avanti.
  7. Immettere l'URL del driver JDBC. L'URL JDBC è disponibile nella scheda Dettagli connessione del cluster di computazione in AI Data Platform.
  8. Fare clic su Fine.

Connettere DBeaver a Oracle AI Data Platform utilizzando JDBC

Una volta che DBeaver è configurato e ha una connessione al database con Oracle AI Data Platform, puoi completare la connessione tra DBeaver e AI Data Platform.

  1. Apri DBeaver.
  2. Fare clic su Connetti.
  3. Scegliere di connettersi con un token di autorizzazione o una chiave API.
    • Connetti tramite token di autorizzazione
      • Utilizzare un token non specificando alcun profilo nell'URL se non si dispone di un profilo DEFAULT. Ad esempio: jdbc:spark://gateway.aidp.me-riyadh-1.oci.oraclecloud.com/default;SparkServerType=AIDP;httpPath=cliservice/cf18b4ef-b83e-41dd-82b6-8d391584f6c5

        L'URL apre una finestra del browser.

        Connettersi alla tenancy in cui viene creata l'istanza di AI Data Platform.

        Per ulteriori informazioni, vedere Autenticazione basata su token per l'interfaccia CLI.

    • Connettersi utilizzando una chiave API specificando il profilo OCI con ociProfile=<profile_name> nell'URL di connessione.

      • Utilizza l'autenticazione API key per connettersi a un'istanza di AI Data Platform.

        Utilizzare la chiave API specificando il profilo OCI con ociProfile=<profile_name> nell'URL di connessione. Ad esempio, per utilizzare la demo del nome del profilo OCI: jdbc:spark://gateway.aidp.me-riyadh-1.oci.oraclecloud.com/default;SparkServerType=AIDP;httpPath=cliservice/cf18b4ef-b83e-41dd-82b6-8d391584f6c5 ;ociProfile=Demo

        Per ulteriori informazioni, vedere Chiavi e OCID obbligatori.

  4. DBeaver crea una connessione per la lettura dei metadati e una connessione per tutte le altre operazioni. Se sei limitato alle connessioni, puoi disabilitare la seconda in modo che DBeaver utilizzi una connessione per tutte le operazioni.
    1. Fare clic su Preferenze.
    2. Fare clic su Comune.
    3. Fare clic su Metadati.
    4. Deselezionare Aprire una connessione separata per le letture dei metadati.

Scarica driver ODBC

È possibile scaricare il driver ODBC dalla scheda Dettagli connessione e configurarlo per diversi strumenti BI.

  1. Passare all'area di lavoro e fare clic su Computazione.
  2. Fare clic sul cluster che si desidera connettere a uno strumento BI compatibile con ODBC e fare clic su Connessioni.
  3. Fare clic su Scarica driver ODBC.
  4. Selezionare il sistema operativo appropriato dall'elenco.

    Il menu a discesa ODBC Driver OS si apre con le opzioni Mac, Windows e Linx visualizzate

API esecuzione istruzioni SQL

È possibile utilizzare l'API di esecuzione delle istruzioni SQL per eseguire un'istruzione SQL di sola lettura su un cluster di computazione da un'applicazione esterna, un'automazione o un agente.

L'API restituisce il risultato direttamente per set di risultati di piccole dimensioni o fornisce un collegamento temporaneo per risultati più grandi. L'API di esecuzione delle istruzioni SQL utilizza la firma della richiesta di Oracle Cloud Infrastructure. Le istruzioni vengono eseguite utilizzando l'identità e le autorizzazioni del chiamante autenticato. È possibile sottomettere un rendiconto, recuperarne lo stato e i risultati e annullare un rendiconto in esecuzione.

Prima di iniziare, accertarsi di disporre dei seguenti elementi:
  • Cluster di computazione avviato con stato Attivo
  • Chiave del cluster di computazione (ID). Lo si può trovare nella scheda Dettagli del cluster, in Informazioni generali.
  • Il nome host del gateway per il cluster. Il nome host può essere trovato nella scheda Dettagli connessione del cluster, sotto il driver JDBC o il driver ODBC.
  • Profilo del token di sicurezza CLI OCI nel terminale o nell'applicazione CLI in uso. È possibile accedere eseguendo oci session authenticate --profile-name <profile-name> e seguendo i prompt.

Come impostare i valori di connessione

Assicurarsi di aver impostato i valori di connessione per l'ambiente nel terminale o nell'applicazione in cui è configurata l'interfaccia CLI OCI.

È possibile impostare i valori di connessione per l'ambiente utilizzando i comandi riportati di seguito.
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)"
Ad esempio:
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"

Azioni API istruzione SQL

Per eseguire azioni per l'API di esecuzione delle istruzioni SQL, è necessario chiamare l'endpoint dall'interfaccia CLI di Oracle Cloud Infrastructure.

È possibile eseguire le azioni riportate di seguito da un terminale o da un'applicazione configurata con l'interfaccia CLI OCI.

Opzioni richiesta API esecuzione istruzione SQL

I seguenti campi di richiesta vengono utilizzati durante la creazione di una richiesta API di esecuzione delle istruzioni SQL.

Campo Descrizione
statement Obbligatoria. Istruzione SQL di sola lettura.
wait_timeout Facoltativa. Il tempo massimo durante il quale l'API attende il completamento dell'istruzione prima di restituire una risposta.
disposition Specificare INLINE o EXTERNAL_LINKS.
row_limit Il numero massimo di righe mantenute per l'istruzione.
byte_limit Il numero massimo di byte conservati per l'istruzione.
catalog Facoltativa. Il catalogo da utilizzare durante l'esecuzione dell'istruzione.
schema Facoltativa. Schema da utilizzare durante l'esecuzione dell'istruzione.
parameters Facoltativa. Array di valori dei parametri denominati per l'istruzione SQL.
query_tags Facoltativa. Tag chiave-valore per identificare e tenere traccia di un'istruzione. Specificare non più di 20 voci.
request_id Facoltativa. Identificativo di correlazione o idempotenza fornito dal chiamante. Riutilizzare il valore solo per la stessa richiesta logica.
opc-request-id Facoltativa. Intestazione di richiesta per il trace della richiesta. Utilizzare solo lettere, numeri, caratteri di sottolineatura e trattini.

Sottometti un'istruzione SQL

Le istruzioni SQL vengono sottomesse a questo endpoint API:

POST /20200129/computeClusters/<compute-cluster-key>/workbench/sql/statements
L'esempio seguente include un valore wait_timeout facoltativo di 10 secondi per un risultato:
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 risposta prevista all'esempio precedente è la seguente:
{
  "http_status": "200 OK",
  "statement_id": "095865c4-27ce-41cc-99bb-67af1de760b2",
  "state": "SUCCEEDED",
  "result": [
    [
      "1"
    ]
  ],
  "opc_request_id": "sql-submit-20261022-214855/FBBFDCB770BDEFBC654EAE933E45E811/6CD8518A6A62E6411552DBFEF5ECEAD7"
}

Il campo wait_timeout specifica per quanto tempo l'API attende il completamento dell'istruzione prima di restituire una risposta. Se l'istruzione viene completata entro il tempo di attesa specificato, l'API restituisce 200 OK e include il risultato dell'istruzione. Se l'istruzione non viene completata entro questo periodo di tempo, l'API restituisce 202 Accepted e continua a eseguire l'istruzione.

È possibile modificare il filtro jq per visualizzare i campi di risposta richiesti dall'applicazione. Il comando salva la risposta API completa nel file temporaneo /tmp/sql-submit.json, che può essere esaminato per ulteriori dettagli sulla risposta.

Sottometti rendiconto con collegamenti esterni

È possibile sottomettere istruzioni tramite lo stesso endpoint POST che includono collegamenti esterni, come nell'esempio riportato di seguito.
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 risposta prevista all'esempio precedente è la seguente:
{
  "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"
}

In questo esempio, il collegamento temporaneo dei risultati esterni viene salvato in /tmp/sql-external-submit.json e non viene visualizzato nella risposta del comando.

Nota

Non condividere link di risultati esterni o memorizzarli in codice sorgente, registri, ticket o altre posizioni ampiamente accessibili. Chiunque disponga di un collegamento valido può accedere ai dati dei risultati associati fino alla scadenza del collegamento.

Se truncated è true, il risultato restituito ha raggiunto il limite di righe o byte specificato.

Imposta statement_id

Il file statement_id è necessario per recuperare le informazioni sull'istruzione, ad esempio lo stato o i risultati, e per annullare un'istruzione. È possibile impostare statement_id quando l'istruzione viene sottomessa come indicato di seguito.
export STATEMENT_ID="095865c4-27ce-41cc-99bb-67af1de760b2"
echo "${STATEMENT_ID}"
Se la risposta di sottomissione è stata salvata in /tmp/sql-submit.json, è possibile impostare statement_id come indicato di seguito.
export STATEMENT_ID="$(jq -r '.data.statement_id' /tmp/sql-submit.json)"

Stato richiesta istruzione SQL

È possibile recuperare lo stato di un'istruzione sottomessa utilizzando il relativo statement_id da questo endpoint:
GET /20200129/computeClusters/<compute-cluster-key>/workbench/sql/statements/<statement-id>

L'esempio seguente recupera lo stato di un'istruzione utilizzando il relativo 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 risposta prevista per questa richiesta è la seguente:
{
  "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"
}
Un'istruzione può avere gli stati riportati di seguito.
  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELLED
Per un'istruzione che restituisce 202 Accepted, recuperare lo stato finché l'istruzione non raggiunge lo stato terminale: SUCCEEDED, FAILED o CANCELLED.

Richiedi risultati rendiconto

Al termine di un'istruzione, è possibile recuperare il risultato utilizzando statement_id e il risultato chunk-index utilizzando l'endpoint seguente:

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

Impostare chunk-index per determinare i risultati recuperati durante la chiamata dell'endpoint. Un chunk-index di 0 recupera il primo risultato. È possibile determinare il valore chunk-index del risultato successivo selezionando il valore next_chunk_index nella risposta. Se next_chunk_index è null, significa che non ci sono chunk di risultati aggiuntivi.

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

È possibile utilizzare row_limit e byte_limit per controllare la quantità di dati dei risultati che il servizio conserva e restituisce. Quando viene raggiunto uno dei due limiti, la risposta può indicare che il risultato viene troncato. Un'istruzione riuscita non implica che tutte le righe di origine siano state mantenute nel risultato.

In questo esempio viene illustrata una richiesta di risultati dell'istruzione.

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 risposta agli esempi precedenti è simile alla seguente:

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

Al termine di un'istruzione, la risposta include lo stato dell'istruzione e i metadati dei risultati. Se si specifica INLINE per disposition, il servizio restituisce i dati dei risultati nella risposta. Utilizzare INLINE per ottenere risultati di piccole dimensioni che un'applicazione può elaborare immediatamente. Se si specifica EXTERNAL_LINKS, il servizio memorizza il risultato e restituisce un collegamento temporaneo invece di includere i dati dei risultati nella risposta. Utilizzare EXTERNAL_LINKS per ottenere risultati di grandi dimensioni.

La risposta può includere le seguenti informazioni sui risultati:
  • data_array: dati dei risultati quando il risultato viene restituito in linea. Questo valore è nullo quando si utilizza EXTERNAL_LINKS.
  • external_links: collegamenti temporanei ai dati dei risultati quando si utilizza EXTERNAL_LINKS.
  • row_count e byte_count: il numero di righe e byte nel chunk dei risultati restituito.
  • next_chunk_index: l'indice del chunk dei risultati successivo, quando sono disponibili ulteriori dati sui risultati.
  • truncated: indica se il servizio ha mantenuto solo parte del risultato perché è stato raggiunto il limite di righe o byte richiesto.
  • expires_at: l'ora di scadenza dei dati dei risultati conservati e dei collegamenti esterni temporanei.

Annulla un rendiconto sottomesso

È possibile annullare un'istruzione in esecuzione. È necessario il file statement_id per l'istruzione che si sta tentando di annullare.

Per annullare un'istruzione, inviare una richiesta POST all'endpoint seguente:
POST /20200129/computeClusters/<compute-cluster-key>/workbench/sql/statements/<statement-id>/cancel
In questo esempio viene illustrata una richiesta di annullamento di un rendiconto:
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 risposta agli esempi precedenti è simile alla seguente:
{
  "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"
}

Al termine dell'annullamento, l'API restituisce 200 OK. La risposta include l'ID istruzione e lo stato CANCELED.

È possibile confermare l'annullamento recuperando lo stato dell'estratto conto utilizzando lo stesso 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 risposta di verifica è simile alla seguente:
{
  "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"
}

Specificare un catalogo o uno schema

È possibile specificare un catalogo, uno schema o entrambi quando si sottomette un'istruzione SQL. I valori specificati nella richiesta sostituiscono il contesto della sessione corrente. Specificare sia il catalogo che lo schema per eseguire l'istruzione in un catalogo e uno schema specifici.

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

È possibile specificare solo catalog per selezionare un catalogo. Per assicurarsi che un'istruzione utilizzi uno schema specifico, specificare sia catalog che schema.

È possibile specificare solo schema per selezionare uno schema nel catalogo corrente. È inoltre possibile specificare un nome di schema qualificato, ad esempio sales_catalog.reporting, quando si omette catalog.

Se non si specifica catalog o schema, l'istruzione utilizza il catalogo e lo schema della sessione corrente. Se il catalogo o lo schema specificato non esiste o se il chiamante non dispone dell'accesso, l'istruzione può essere completata con lo stato FAILED. Controllare status.state e status.error in ogni risposta di dichiarazione completata. La sintassi del campo catalogo o schema non valida restituisce 400 Bad Request.

Parametri denominati

È possibile utilizzare parametri denominati in un'istruzione SQL. Specificare un parametro nell'istruzione utilizzando i due punti seguiti dal nome del parametro, ad esempio :id. I parametri posizionali, ad esempio ?, non sono supportati. Specificare i valori dei parametri nell'array parameters. Ogni parametro contiene i campi riportati di seguito.

Campo Descrizione
name Obbligatoria. Nome del parametro senza il prefisso due punti (:).
value Obbligatoria. Il valore del parametro. Fornire il valore come stringa.
type Facoltativa. Suggerimento di tipo per il valore del parametro.
Ad esempio, la richiesta seguente fornisce i valori per :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"
}
L'API supporta il seguente suggerimento per il tipo di parametro:
  • Booleano: BOOLEAN
  • Numero intero: BYTE, TINYINT, SHORT, SMALLINT, INT, INTEGER, LONG, BIGINT
  • Numerico: FLOAT, DOUBLE, DECIMAL, NUMERIC
  • Data e ora: DATE, TIMESTAMP, TIMESTAMP_NTZ
  • Carattere: STRING, CHAR, VARCHAR
Il valore del tipo è un suggerimento di tipo. Non fare affidamento su di esso per preservare una precisione e una scala decimali fornite o una variante dell'indicatore orario. Convalidare i valori e i tipi restituiti nell'applicazione.

Risolvere i problemi relativi alle risposte API di esecuzione delle istruzioni SQL

Utilizzare la tabella seguente per risolvere i problemi relativi alle possibili soluzioni alle risposte API comuni:
Risposta Soluzione
400 Bad Request Verificare che la richiesta includa un'istruzione di sola lettura supportata e valori di richiesta validi.
401 o 403 Verificare l'autenticazione OCI e le autorizzazioni per il cluster di computazione e i dati sottoposti a query.
404 Not Found Verificare l'area, la chiave cluster di computazione, l'identità del chiamante e l'ID istruzione.
503 Service Unavailable Attendere che il cluster di computazione sia attivo, quindi riprovare.

Connessione ad applicazioni esterne con Spark Connect

Puoi utilizzare Spark Connect per eseguire il codice Spark su un cluster di computazione Oracle AI Data Platform da un'applicazione Python o Java supportata.

Puoi lavorare da un IDE locale o da un'applicazione esterna mentre il cluster esegue le operazioni DataFrame e le query SQL Spark. Ad esempio, è possibile sviluppare una trasformazione dei dati localmente, eseguirla in base ai dati disponibili per il cluster e recuperare i risultati nell'applicazione.

Per utilizzare Spark Connect, assicurarsi di disporre dei seguenti elementi:
  • Cluster di computazione con stato Attivo.
  • Autorizzazioni USE o successive per il cluster e i dati in uso.
  • Accesso di rete al nome host del cluster Spark Connect sulla porta 443.
  • Chiave del cluster di computazione (ID). Lo si può trovare nella scheda Dettagli del cluster, in Informazioni generali.
  • Il nome host del gateway per il cluster. Il nome host può essere trovato nella scheda Dettagli connessione del cluster, sotto il driver JDBC o il driver ODBC.
  • Profilo di autenticazione OCI e client Spark Connect compatibile.

AI Data Platform supporta i client Python e Java e ha i requisiti seguenti per ciascuno di essi:

Client Requisiti
Python Python 3.9–3.11, PySpark Connetti 3.5.1
Java JDK 17, Maven 3.8 o versioni successive, client JVM Spark Connect 3.5.1

Connettersi a Spark Connect con un client Python

Questo esempio Python include l'impostazione della connessione necessaria per l'autenticazione con OCI e la creazione di una sessione Spark remota.

In questo esempio sono richiesti i valori spark_connect_example.py e requirements.txt forniti in questo bundle: Esempi di connessione Spark.
  1. Aprire un terminale nella directory di esempio estratta. Creare un ambiente virtuale e installare le dipendenze:
    python3 -m venv .venv
    .venv/bin/python -m pip install --upgrade pip
    .venv/bin/python -m pip install -r requirements.txt

    Utilizzare il file delle dipendenze fornito per installare versioni compatibili delle librerie client.

  2. Nel terminale, impostare il nome host, la chiave cluster e il profilo 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>"
    Sostituire i valori tra parentesi angolari con i dettagli di connessione. Il profilo OCI selezionato deve contenere credenziali API-key o security-token valide. Ad esempio:
    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"
  3. Verificare la connessione:
    SPARK_CONNECT_OCI_AUTH_MODE=config \
    SPARK_CONNECT_EXAMPLE_TYPE=both \
    env -u PYTHONPATH -u SPARK_HOME \
    .venv/bin/python spark_connect_example.py

    Selezionare il metodo di autenticazione corrispondente al profilo:

    Tipo di autenticazione Impostazione
    Chiave API SPARK_CONNECT_OCI_AUTH_MODE=api_key
    Token di sicurezza SPARK_CONNECT_OCI_AUTH_MODE=security_token

    L'esempio esegue un'operazione DataFrame e una query SQL Spark. Entrambi restituiscono gli ID da 0 a 4 con i relativi valori quadrati. Il terminale visualizza i risultati come righe raccolte. Se entrambe le operazioni vengono completate, l'applicazione è stata autenticata, connessa al cluster ed esegue il codice Spark.

  4. Utilizzare la sessione Spark autenticata creata dall'esempio per eseguire operazioni personalizzate. Aprire spark_connect_example.py e sostituire le operazioni di esempio all'interno del blocco di prova con il codice dell'applicazione. Conservare il codice esistente che crea la sessione Spark autenticata.
    Ad esempio, per utilizzare un DataFrame è possibile utilizzare quanto segue:
    frame = spark.range(5)
    
    result = frame.withColumn(
        "squared",
        frame["id"] * frame["id"]
    )
    
    result.show()
    Per eseguire Spark SQL è possibile utilizzare quanto segue:
    spark.sql(
        "SELECT id, id * id AS squared FROM range(5)"
    ).show()

    Quando si esegue una query sulle proprie tabelle, utilizzare il catalogo e lo schema appropriati. L'identità deve disporre delle autorizzazioni per accedere a tali tabelle.

  5. Al termine dell'applicazione, chiudere la sessione Spark:
    spark.stop()

Nota

L'esempio fornito disabilita l'esecuzione ricollegabile per il client Spark 3.5.1 documentato:
spark.client.disable_reattachable_execute()
Mantenere questa impostazione quando si adatta l'esempio.

Connettersi a Spark Connect con un client Java

Questo esempio Java include l'impostazione della connessione necessaria per l'autenticazione con OCI e la creazione di una sessione Spark remota.

In questo esempio sono richiesti i valori SparkConnectExample.java e pom.xml forniti in questo bundle: Esempi di connessione Spark.
  1. Estrarre il bundle e aprire filename. Seguire le istruzioni fornite per installare il contenuto del bundle.
  2. Aprire un terminale nella directory dell'esempio estratta. Impostare lo stesso nome host, la stessa chiave cluster, il percorso del file di configurazione e lo stesso profilo:
    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
    Sostituire i valori tra parentesi angolari con i dettagli di connessione. Il profilo OCI selezionato deve contenere credenziali API-key o security-token valide. Ad esempio:
    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
  3. Verificare le connessioni:
    SPARK_CONNECT_OCI_AUTH_MODE=config \
    SPARK_CONNECT_EXAMPLE_TYPE=both \
    env -u PYTHONPATH -u SPARK_HOME \
    .venv/bin/python spark_connect_example.py"

    Selezionare il metodo di autenticazione corrispondente al profilo:

    Tipo di autenticazione Impostazione
    Chiave API SPARK_CONNECT_OCI_AUTH_MODE=api_key
    Token di sicurezza SPARK_CONNECT_OCI_AUTH_MODE=security_token

    L'esempio esegue un'operazione DataFrame e una query SQL Spark. Entrambi restituiscono gli ID da 0 a 4 con i relativi valori quadrati. Il terminale visualizza i risultati come righe raccolte. Se entrambe le operazioni vengono completate, l'applicazione è stata autenticata, connessa al cluster ed esegue il codice Spark.

  4. Utilizzare la sessione Spark autenticata creata dall'esempio per eseguire operazioni personalizzate.
    Ad esempio, per utilizzare un DataFrame è possibile utilizzare quanto segue:
    frame = spark.range(5)
    
    result = frame.withColumn(
        "squared",
        frame["id"] * frame["id"]
    )
    
    result.show()
    Per eseguire Spark SQL è possibile utilizzare quanto segue:
    spark.sql(
        "SELECT id, id * id AS squared FROM range(5)"
    ).show()

    Quando si esegue una query sulle proprie tabelle, utilizzare il catalogo e lo schema appropriati. L'identità deve disporre delle autorizzazioni per accedere a tali tabelle.

  5. Al termine dell'applicazione, chiudere la sessione Spark:
    spark.stop()

Risoluzione dei problemi di Spark Connect

La tabella fornita elenca i problemi comuni che possono verificarsi durante la configurazione delle connessioni Spark Connect a Oracle AI Data Platform e fornisce potenziali cause.

Problema Cosa controllare
L'applicazione non può connettersi Verificare che il cluster sia attivo e che l'ambiente in uso possa raggiungere il nome host del gateway sulla porta 443.
Autenticazione non completata Controllare il percorso del file di configurazione OCI, il nome del profilo e le credenziali. Aggiornare le credenziali della sessione scadute.
Autorizzazione non riuscita o risorsa non trovata Controllare il nome host e la chiave cluster. Confermare l'abilitazione della tenancy e l'autorizzazione per utilizzare il cluster.
Una query non può accedere a una tabella Controllare il catalogo, lo schema e il nome della tabella e verificare che l'identità autenticata abbia accesso ai dati.
Python segnala un modulo pyspark o oci mancante Installare le dipendenze fornite ed eseguire l'esempio utilizzando .venv/bin/python.
Python carica una versione Spark imprevista Utilizzare il comando documentato con PYTHONPATH e SPARK_HOME rimossi.
Java segnala una dipendenza mancante o una libreria incompatibile Seguire le istruzioni di impostazione fornite con il bundle Java e utilizzare le versioni di dipendenza specificate.