Connexion à Compute

10Connexion à Compute

Cette section traite de la connexion du calcul dans Oracle AI Data Platform à d'autres outils décisionnels.

Rubriques :

Connexions

Vous pouvez connecter votre Oracle AI Data Platform à Oracle Analytics Cloud ou à d'autres outils décisionnels.

Vous pouvez vous connecter à la plate-forme de données d'IA à partir de différents outils décisionnels à l'aide d'un JDBC ou ODBC personnalisé fourni par la plate-forme de données d'IA. La plate-forme de données d'IA prend également en charge les connexions à partir d'outils BI commerciaux tiers (Tableau, Power BI) ou d'outils BI open source tels que DBeaver. Pour vous connecter à partir de ces outils, vous avez besoin des détails de connexion du cluster de calcul dans votre plate-forme de données AI, que vous pouvez trouver dans l'onglet Détails de connexion. Les informations requises varient en fonction du produit à partir duquel vous êtes connecté.

Onglet Détails de connexion pour le cluster de calcul Dev_cluster_1

Connexion d'Oracle Analytics à Oracle AI Data Platform

Vous pouvez vous connecter au catalogue ou aux tables gérées par votre instance Oracle AI Data Platform à partir d'une instance Oracle Analytics Cloud.

Pour créer une connexion entre Oracle Analytics et AI Data Platform, vous avez besoin d'un fichier de connexion à partir de AI Data Platform et d'une clé d'API à partir d'Analytics Cloud.

Obtention d'un fichier de configuration de connexion Oracle Analytics

Vous devez télécharger un fichier config.json à partir de votre instance Oracle AI Data Platform pour le connecter à Oracle Analytics.

Vous avez besoin d'un cluster de calcul avec au moins 2 OCPU, 32 Go de mémoire pour les noeuds de processus actif et de pilote, et au moins 2 processus actifs.

Accédez à votre espace de travail et cliquez sur Compute.
Cliquez sur le cluster auquel vous connecter à Oracle Analytics.
Dans l'onglet Détails de connexion, cliquez sur l'icône Télécharger sous le logo Oracle Analytics Cloud. Un fichier config.json est téléchargé sur votre ordinateur.

Connexion à Oracle Analytics

Vous pouvez vous connecter au catalogue ou aux tables gérées par votre instance Oracle AI Data Platform à partir d'une instance Oracle Analytics.

Assurez-vous que vous disposez d'un fichier de configuration de connexion à partir de AI Data Platform avant de créer la connexion dans Oracle Analytics. Reportez-vous à Obtention d'un fichier de configuration de connexion Oracle Analytics.

Les connexions Oracle Analytics aux instances AI Data Platform ne prennent en charge qu'un catalogue par connexion. Vous devez créer des connexions supplémentaires pour utiliser plusieurs catalogues.

Sur la page d'accueil d'Oracle Analytics, cliquez sur Créer, puis sur Connexion.
Cliquez sur Plate-forme de données Oracle AI.
Entrez le nom et la description de la connexion.
Dans Emplacement, indiquez où enregistrer la connexion. Pour partager la connexion avec d'autres utilisateurs, enregistrez-la dans /Dossiers partagés.
Dans Oracle Analytics Cloud, pour les détails de connexion, cliquez sur Sélectionner, accédez à votre fichier config.json et cliquez sur Ouvrir.
Sélectionnez Clé d'API comme type d'authentification.
Sous Clé d'API publique, cliquez sur Générer, puis sur Copier.
Dans OCI, ajoutez une clé d'API.
1. Dans OCI, cliquez sur l'icône utilisateur, puis sur Paramètres d'utilisateur.
2. Dans Mon profil, cliquez sur Jetons et clés, puis sur Ajouter une clé d'API.
3. Sélectionnez Coller une clé publique, puis copiez la clé que vous avez générée à l'étape 7, puis cliquez sur Ajouter.
Attendez deux à trois minutes que la clé d'API se synchronise.
Dans Catalogue, indiquez le nom du catalogue à utiliser dans vos jeux de données.
Si la liste Catalogue ne se charge pas et que le message d'alerte "L'utilisateur ne dispose pas de privilèges suffisants pour effectuer l'opération" s'affiche, attendez un peu plus longtemps que la clé d'API soit synchronisée.
Cliquez sur Enregistrer.
Testez votre nouvelle connexion en créant un ensemble de données.

Si vous avez suivi les instructions et que vous avez toujours rencontré des problèmes lors de l'enregistrement de votre connexion ou de la liste de vos schémas, un redémarrage de cluster peut être nécessaire.

Télécharger le pilote JDBC

Vous pouvez télécharger le pilote JDBC à partir de l'onglet Détails de connexion et le configurer pour différents outils BI.

Accédez à votre espace de travail et cliquez sur Compute.
Cliquez sur le cluster auquel vous voulez vous connecter à un outil BI compatible JDBC, puis sur Connexions.
Cliquez sur Télécharger le chauffeur JDBC.

Configuration de DBeaver

Vous devez installer DBeaver et préparer les fichiers téléchargés à partir d'Oracle AI Data Platform avant de pouvoir les connecter à un cluster de calcul dans votre plate-forme de données AI.

Téléchargez et installez le client DBeaver. Vous pouvez utiliser les versions Community ou Enterprise, mais elles doivent être au moins 22.x.DBeaver est uniquement disponible pour Windows, Mac OS X, Eclipse Plugin et Linux.
Décompressez le fichier dans Télécharger le pilote JDBC.
A partir des fichiers décompressés, décompressez le fichier du pilote simbaSpark.zip.

Configuration de DBeaver avec le pilote JDBC Simba Spark

Vous pouvez configurer DBeaver pour qu'il se connecte à un cluster de calcul dans Oracle AI Data Platform.

Vous devez avoir installé DBeaver et extrait les fichiers simbaSpark.zip téléchargés à partir de AI Data Platform.

Ouvrez DBeaver.
Cliquez sur Navigateur de base de données.
Cliquez sur Gestionnaire de pilotes.
Cliquez sur Nouveau.
Entrez Plate-forme de données AI dans le champ Nom de l'inducteur.
Cliquez sur Bibliothèques.
Cliquez sur Ajouter un dossier.
Accédez à l'emplacement de l'extraction sparkSimba.zip.
Cliquez sur Rechercher une classe.
Sélectionnez OK.
Définissez la classe de pilote sur com.simba.spark.jdbc.Driver.
Cliquez sur Paramètres.
Définissez le nom de classe sur com.simba.spark.jdbc.Driver.
Cliquez sur OK.

Créer une connexion de base de données dans DBeaver

Pour connecter DBeaver à un cluster de calcul dans Oracle AI Data Platform, vous devez d'abord créer une connexion de base de données dans DBeaver.

Vous devez avoir configuré DBeaver avec le pilote JDBC Simba Spark téléchargé à partir de la plate-forme de données AI. Pour plus d'informations, reportez-vous à Configuration de DBeaver avec le pilote JDBC Simba Spark.

Ouvrez DBeaver.
Cliquez sur Base de données.
Cliquez sur Nouvelle connexion de base de données.
Cliquez sur Tous.
Sélectionnez Plate-forme de données AI.
Cliquez sur Suivant.
Entrez l'URL du pilote JDBC. Vous pouvez trouver l'URL JDBC dans l'onglet Détails de connexion de votre cluster de calcul dans Plate-forme de données AI.
Cliquez sur Terminer.

Connexion de DBeaver à Oracle AI Data Platform à l'aide de JDBC

Une fois que DBeaver est configuré et dispose d'une connexion de base de données à votre Oracle AI Data Platform, vous pouvez établir la connexion entre DBeaver et AI Data Platform.

Ouvrez DBeaver.
Cliquez sur Connexion.
Choisissez de vous connecter à l'aide d'un jeton d'autorisation ou d'une clé d'API.
- Connexion à l'aide du jeton d'autorisation
  - Utilisez un jeton en ne spécifiant aucun profil dans l'URL si vous n'avez pas de profil DEFAULT. Par exemple : jdbc:spark://gateway.aidp.me-riyadh-1.oci.oraclecloud.com/default;SparkServerType=AIDP;httpPath=cliservice/cf18b4ef-b83e-41dd-82b6-8d391584f6c5
    L'URL ouvre une fenêtre de navigateur.
    
    Connectez-vous à la location dans laquelle l'instance AI Data Platform est créée.
    
    Pour plus d'informations, reportez-vous à Authentification basée sur un jeton pour l'interface de ligne de commande.
- Connectez-vous à l'aide d'une clé d'API en indiquant le profil OCI avec ociProfile=<profile_name> dans l'URL de connexion.
  - Utilisez l'authentification par clé d'API pour vous connecter à une instance AI Data Platform.
    Utilisez la clé d'API en indiquant le profil OCI avec ociProfile=<profile_name> dans l'URL de connexion. Par exemple, pour utiliser le nom de profil OCI Demo : jdbc:spark://gateway.aidp.me-riyadh-1.oci.oraclecloud.com/default;SparkServerType=AIDP;httpPath=cliservice/cf18b4ef-b83e-41dd-82b6-8d391584f6c5 ;ociProfile=Demo
    
    Pour plus d'informations, reportez-vous à Clés et OCID requis.
DBeaver crée une connexion pour la lecture des métadonnées et une connexion pour toutes les autres opérations. Si les connexions sont limitées, vous pouvez désactiver la seconde pour que DBeaver utilise une seule connexion pour toutes les opérations.
1. Cliquez sur Préférences.
2. Cliquez sur Common.
3. Cliquez sur Métadonnées.
4. Désélectionnez Ouvrir une connexion distincte pour les lectures de métadonnées.

Télécharger le pilote ODBC

Vous pouvez télécharger le pilote ODBC à partir de l'onglet Détails de connexion et le configurer pour différents outils BI.

Accédez à votre espace de travail et cliquez sur Compute.
Cliquez sur le cluster auquel vous voulez vous connecter à un outil BI compatible ODBC, puis sur Connexions.
Cliquez sur Télécharger le pilotes ODBC.
Sélectionnez le système d'exploitation approprié dans la liste.

API d'exécution d'instructions SQL

Vous pouvez utiliser l'API d'exécution d'instructions SQL pour exécuter une instruction SQL en lecture seule sur un cluster de calcul à partir d'une application, d'une automatisation ou d'un agent externe.

L'API renvoie le résultat directement pour les petits ensembles de résultats ou fournit un lien temporaire pour les résultats plus importants. L'API d'exécution d'instruction SQL utilise la signature de demande Oracle Cloud Infrastructure. Les instructions sont exécutées à l'aide de l'identité et des droits d'accès de l'appelant authentifié. Vous pouvez soumettre une instruction, en extraire le statut et les résultats et annuler une instruction en cours d'exécution.

Assurez-vous de disposer des éléments suivants avant de commencer :

Cluster de calcul démarré avec le statut Actif
Clé de cluster de calcul (ID). Vous pouvez le trouver dans l'onglet Détails de votre cluster, sous Informations générales.
Nom d'hôte de passerelle pour votre cluster. Vous pouvez trouver le nom d'hôte dans l'onglet de détails Connexion de votre cluster, sous le pilote JDBC ou ODBC.
Profil de jeton de sécurité de l'interface de ligne de commande OCI dans le terminal ou l'application de l'interface de ligne de commande que vous utilisez. Vous pouvez vous connecter en exécutant oci session authenticate --profile-name <profile-name> et en suivant les invites.

Définition des valeurs de connexion

Assurez-vous que vous avez défini les valeurs de connexion pour votre environnement dans le terminal ou l'application dans lequel l'interface de ligne de commande OCI est configurée.

Vous pouvez définir les valeurs de connexion pour votre environnement à l'aide des commandes suivantes :

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)"

Exemple :

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"

Actions d'API d'instruction SQL

Pour exécuter des actions pour l'API d'exécution d'instruction SQL, vous devez appeler l'adresse à partir de l'interface de ligne de commande Oracle Cloud Infrastructure.

Vous exécutez les actions suivantes à partir d'un terminal ou d'une application configuré avec l'interface de ligne de commande OCI.

Options de demande d'API d'exécution d'instruction SQL

Les champs de demande suivants sont utilisés lors de la création d'une demande d'API d'exécution d'instruction SQL.

Champ	Description
`statement`	Requis. Instruction SQL en lecture seule.
`wait_timeout`	Facultatif. Durée maximale pendant laquelle l'API attend que l'instruction se termine avant de renvoyer une réponse.
`disposition`	Indiquez INLINE ou EXTERNAL_LINKS.
`row_limit`	Nombre maximum de lignes conservées pour l'instruction.
`byte_limit`	Nombre maximal d'octets conservés pour l'instruction.
`catalog`	Facultatif. Catalogue à utiliser lors de l'exécution de l'instruction.
`schema`	Facultatif. Schéma à utiliser pour exécuter l'instruction.
`parameters`	Facultatif. Tableau de valeurs de paramètre nommées pour l'instruction SQL.
`query_tags`	Facultatif. Balises clé-valeur permettant d'identifier et de suivre une instruction. Ne spécifiez pas plus de 20 entrées.
`request_id`	Facultatif. Identificateur de corrélation ou d'idempotence fourni par l'appelant. Réutilisez la valeur uniquement pour la même demande logique.
`opc-request-id`	Facultatif. En-tête de demande permettant de suivre la demande. Utilisez uniquement des lettres, des chiffres, des traits de soulignement et des traits d'union.

Soumettre une instruction SQL

Les instructions SQL sont soumises à cette adresse d'API :

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

L'exemple suivant inclut une valeur wait_timeout facultative de 10 secondes pour un résultat :

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 réponse attendue à l'exemple ci-dessus se présente comme suit :

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

Le champ wait_timeout indique la durée pendant laquelle l'API attend que l'instruction se termine avant de renvoyer une réponse. Si l'instruction se termine dans le délai d'attente indiqué, l'API renvoie 200 OK et inclut le résultat de l'instruction. Si l'instruction ne se termine pas dans ce délai, l'API renvoie 202 Accepted et continue à l'exécuter.

Vous pouvez modifier le filtre jq pour afficher les champs de réponse requis par l'application. La commande enregistre la réponse complète de l'API dans le fichier temporaire /tmp/sql-submit.json, qui peut être vérifié pour obtenir des détails de réponse supplémentaires.

Soumettre un relevé avec des liens externes

Vous pouvez soumettre des instructions via la même adresse POST qui inclut des liens externes, comme dans l'exemple suivant :

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 réponse attendue à cet exemple est la suivante :

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

Dans cet exemple, le lien de résultat externe temporaire est enregistré dans /tmp/sql-external-submit.json et n'est pas affiché dans la réponse de commande.

Remarques :

Ne partagez pas de liens de résultats externes et ne les stockez pas dans du code source, des journaux, des tickets ou d'autres emplacements largement accessibles. Toute personne disposant d'un lien valide peut accéder aux données de résultat associées jusqu'à ce que le lien expire.

Si truncated a la valeur true, le résultat renvoyé a atteint la limite de lignes ou d'octets indiquée.

Définissez statement_id.

statement_id est nécessaire pour extraire des informations sur l'instruction, telles que le statut ou les résultats, et pour annuler une instruction. Vous pouvez définir statement_id lorsque l'instruction est soumise comme suit :

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

Si la réponse de soumission a été enregistrée dans /tmp/sql-submit.json, vous pouvez définir statement_id comme suit :

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

Statut de l'instruction SQL de la demande

Vous pouvez extraire le statut d'une instruction soumise à l'aide de son statement_id à partir de cette adresse :

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

L'exemple suivant extrait le statut d'une instruction à l'aide de son 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 réponse attendue à cette demande est :

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

Une instruction peut présenter les états suivants :

PENDING
RUNNING
SUCCEEDED
FAILED
CANCELLED

Pour une instruction qui renvoie 202 Accepted, extrayez le statut jusqu'à ce qu'elle atteigne un état de terminal : SUCCEEDED, FAILED ou CANCELLED.

Résultats de la demande de relevé

Une fois l'instruction terminée, vous pouvez extraire son résultat à l'aide de statement_id et du résultat chunk-index à l'aide de l'adresse suivante :

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

Définissez chunk-index pour déterminer les résultats extraits lors de l'appel de l'adresse. Une valeur chunk-index sur 0 extrait le premier résultat. Vous pouvez déterminer l'élément chunk-index du résultat suivant en vérifiant l'élément next_chunk_index dans la réponse. Si next_chunk_index est null, cela indique qu'il n'y a pas de bloc de résultat supplémentaire.

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

Vous pouvez utiliser row_limit et byte_limit pour contrôler la quantité de données de résultat que le service conserve et renvoie. Lorsque l'une des limites est atteinte, la réponse peut indiquer que le résultat est tronqué. Une instruction réussie n'implique pas que toutes les lignes source ont été conservées dans le résultat.

Cet exemple illustre une demande de résultats d'instruction :

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 réponse aux exemples ci-dessus se présente comme suit :

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

Lorsqu'une instruction se termine, la réponse inclut le statut de l'instruction et les métadonnées de résultat. Si vous indiquez INLINE pour disposition, le service renvoie les données de résultat dans la réponse. Utilisez INLINE pour obtenir de petits résultats qu'une application peut traiter immédiatement. Si vous indiquez EXTERNAL_LINKS, le service stocke le résultat et renvoie un lien temporaire au lieu d'inclure les données de résultat dans la réponse. Utilisez EXTERNAL_LINKS pour obtenir des résultats volumineux.

La réponse peut inclure les informations de résultat suivantes :

data_array : données de résultat lorsque le résultat est renvoyé en ligne. Cette valeur est NULL lorsque vous utilisez EXTERNAL_LINKS.
external_links : liens temporaires vers les données de résultat lorsque vous utilisez EXTERNAL_LINKS.
row_count et byte_count : nombre de lignes et d'octets dans le bloc de résultats renvoyé.
next_chunk_index : index du bloc de résultats suivant, lorsque davantage de données de résultat sont disponibles.
truncated : indique si le service n'a conservé qu'une partie du résultat car la limite de lignes ou d'octets demandée a été atteinte.
expires_at : date d'expiration des données de résultat conservées et des liens externes temporaires.

Annuler une déclaration soumise

Vous pouvez annuler une instruction en cours d'exécution. Vous avez besoin de statement_id pour l'instruction que vous essayez d'annuler.

Pour annuler une instruction, envoyez une demande POST à l'adresse suivante :

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

Cet exemple illustre une demande d'annulation d'une instruction :

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 réponse aux exemples ci-dessus se présente comme suit :

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

Une fois l'annulation terminée, l'API renvoie 200 OK. La réponse inclut l'ID d'instruction et le statut CANCELED.

Vous pouvez confirmer l'annulation en extrayant le statut du relevé à l'aide du même 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 réponse de vérification se présente comme suit :

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

Indiquer un catalogue ou un schéma

Vous pouvez indiquer un catalogue, un schéma ou les deux lorsque vous soumettez une instruction SQL. Les valeurs que vous indiquez dans la demande remplacent le contexte de session en cours. Indiquez le catalogue et le schéma pour exécuter l'instruction dans un catalogue et un schéma spécifiques.

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

Vous pouvez indiquer uniquement catalog pour sélectionner un catalogue. Pour vous assurer qu'une instruction utilise un schéma spécifique, indiquez catalog et schema.

Vous pouvez indiquer uniquement schema pour sélectionner un schéma dans le catalogue en cours. Vous pouvez également indiquer un nom de schéma qualifié, tel que sales_catalog.reporting, lorsque vous omettez catalog.

Si vous n'indiquez pas catalog ou schema, l'instruction utilise le schéma et le catalogue de session en cours. Si le catalogue ou le schéma indiqué n'existe pas ou si l'appelant n'y a pas accès, l'instruction peut se terminer avec le statut FAILED. Vérifiez status.state et status.error dans chaque réponse d'instruction terminée. La syntaxe de champ de catalogue ou de schéma non valide renvoie 400 Bad Request.

Paramatres nommés

Vous pouvez utiliser des paramètres nommés dans une instruction SQL. Indiquez un paramètre dans l'instruction en utilisant le signe deux-points suivi du nom du paramètre, tel que :id. Les paramètres positionnels, tels que ?, ne sont pas pris en charge. Indiquez des valeurs de paramètre dans le tableau parameters. Chaque paramètre contient les champs suivants :

Champ	Description
`name`	Requis. Nom du paramètre sans le préfixe deux-points ( :).
`value`	Requis. Valeur du paramètre. Indiquez la valeur sous forme de chaîne.
`type`	Facultatif. Conseil de type pour la valeur du paramètre.

Par exemple, la demande suivante fournit des valeurs pour :id et :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 prend en charge le conseil de type de paramètre suivant :

Booléen : BOOLEAN
Entier : BYTE, TINYINT, SHORT, SMALLINT, INTEGER, LONG, BIGINT
Numérique : FLOAT, DOUBLE, DECIMAL, NUMERIC
DATE et heure : DATE, TIMESTAMP, TIMESTAMP_NTZ
Caractère : STRING, CHAR, VARCHAR

La valeur de type est un conseil de type. Ne vous y fiez pas pour conserver une précision et une échelle décimales ou une variante d'horodatage fournies. Validez les valeurs et les types renvoyés dans votre application.

Résoudre les problèmes liés aux réponses d'API d'exécution d'instructions SQL

Utilisez le tableau suivant pour résoudre les problèmes liés aux solutions possibles aux réponses d'API courantes :

Réponse	Solution
`400 Bad Request`	Vérifiez que la demande inclut une instruction en lecture seule prise en charge et des valeurs de demande valides.
`401` ou `403`	Vérifiez l'authentification OCI et vos droits d'accès pour le cluster de calcul et les données interrogées.
`404 Not Found`	Vérifiez la région, la clé de cluster de calcul, l'identité de l'appelant et l'ID d'instruction.
`503 Service Unavailable`	Attendez que le cluster de calcul soit actif, puis réessayez.

Connexion à des applications externes avec Spark Connect

Vous pouvez utiliser Spark Connect pour exécuter du code Spark sur un cluster de calcul Oracle AI Data Platform à partir d'une application Python ou Java prise en charge.

Vous pouvez travailler à partir d'un IDE local ou d'une application externe pendant que le cluster exécute vos opérations DataFrame et vos requêtes SQL Spark. Par exemple, vous pouvez développer une transformation de données localement, l'exécuter sur les données disponibles pour votre cluster et extraire les résultats dans votre application.

Pour utiliser Spark Connect, assurez-vous que vous disposez des éléments suivants :

Cluster de calcul avec le statut Actif.
Utilisez les droits d'accès USE ou supérieurs pour le cluster et les données que vous utilisez.
Accès réseau au nom d'hôte du cluster Spark Connect sur le port 443.
Clé de cluster de calcul (ID). Vous pouvez le trouver dans l'onglet Détails de votre cluster, sous Informations générales.
Nom d'hôte de passerelle pour votre cluster. Vous pouvez trouver le nom d'hôte dans l'onglet de détails Connexion de votre cluster, sous le pilote JDBC ou ODBC.
Profil d'authentification OCI et client Spark Connect compatible.

AI Data Platform prend en charge les clients Python et Java et présente les exigences suivantes pour chacun d'entre eux :

Client	Exigences
Python	Python 3.9–3.11, PySpark Connect 3.5.1
Java	JDK 17, Maven 3.8 ou version ultérieure, client JVM Spark Connect 3.5.1

Connexion à Spark Connect avec un client Python

Cet exemple Python inclut la configuration de connexion nécessaire pour l'authentification auprès d'OCI et la création d'une session Spark distante.

Cet exemple nécessite les éléments spark_connect_example.py et requirements.txt fournis dans ce groupe : Exemples Spark Connect.

Ouvrez un terminal dans l'exemple de répertoire extrait. Créez un environnement virtuel et installez les dépendances :
```
python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install -r requirements.txt
```
Utilisez le fichier de dépendance fourni pour installer des versions compatibles des bibliothèques client.

Dans votre terminal, définissez le nom d'hôte, la clé de cluster et le profil 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>"

Remplacez les valeurs entre crochets par les détails de la connexion. Le profil OCI sélectionné doit contenir des informations d'identification de clé d'API ou de jeton de sécurité valides. Exemple :

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"

Vérification de la connexion :

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

Sélectionnez la méthode d'authentification qui correspond à votre profil :

Type d'authentification	Paramétrage
Clé d'API	`SPARK_CONNECT_OCI_AUTH_MODE=api_key`
Jeton de sécurité	`SPARK_CONNECT_OCI_AUTH_MODE=security_token`

L'exemple exécute une opération DataFrame et une requête SQL Spark. Les deux renvoient les ID 0 à 4 avec leurs valeurs au carré. Le terminal affiche les résultats sous forme de lignes collectées. Si les deux opérations sont terminées, l'application s'est authentifiée, s'est connectée au cluster et a exécuté du code Spark.

Utilisez la session Spark authentifiée créée par l'exemple pour exécuter vos propres opérations. Ouvrez spark_connect_example.py et remplacez les exemples d'opération du bloc try par votre code d'application. Conservez le code existant qui crée la session Spark authentifiée.
Par exemple, pour utiliser un élément DataFrame, vous pouvez utiliser les éléments suivants :
```
frame = spark.range(5)

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

result.show()
```
Pour exécuter Spark SQL, vous pouvez utiliser les éléments suivants :
```
spark.sql(
    "SELECT id, id * id AS squared FROM range(5)"
).show()
```
Lorsque vous interrogez vos propres tables, utilisez le catalogue et le schéma appropriés. Votre identité doit disposer des droits d'accès nécessaires pour accéder à ces tables.
Une fois l'application terminée, fermez la session Spark :
```
spark.stop()
```

Remarques :

L'exemple fourni désactive l'exécution accessible de nouveau pour le client Spark 3.5.1 documenté :

spark.client.disable_reattachable_execute()

Conservez ce paramètre lorsque vous adaptez l'exemple.

Connexion à Spark Connect avec un client Java

Cet exemple Java inclut la configuration de connexion nécessaire pour l'authentification auprès d'OCI et la création d'une session Spark distante.

Cet exemple nécessite les éléments SparkConnectExample.java et pom.xml fournis dans ce groupe : Exemples Spark Connect.

Extrayez le lot et ouvrez filename. Suivez les instructions fournies dans l'installation du contenu du bundle.

Ouvrez un terminal dans l'exemple de répertoire extrait. Définissez les mêmes nom d'hôte, clé de cluster, chemin de fichier de configuration et profil :

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

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

Vérifiez les connexions :

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

Sélectionnez la méthode d'authentification qui correspond à votre profil :

Type d'authentification	Paramétrage
Clé d'API	`SPARK_CONNECT_OCI_AUTH_MODE=api_key`
Jeton de sécurité	`SPARK_CONNECT_OCI_AUTH_MODE=security_token`

Utilisez la session Spark authentifiée créée par l'exemple pour exécuter vos propres opérations.
Par exemple, pour utiliser un élément DataFrame, vous pouvez utiliser les éléments suivants :
```
frame = spark.range(5)

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

result.show()
```
Pour exécuter Spark SQL, vous pouvez utiliser les éléments suivants :
```
spark.sql(
    "SELECT id, id * id AS squared FROM range(5)"
).show()
```
Lorsque vous interrogez vos propres tables, utilisez le catalogue et le schéma appropriés. Votre identité doit disposer des droits d'accès nécessaires pour accéder à ces tables.
Une fois l'application terminée, fermez la session Spark :
```
spark.stop()
```

Dépannage de Spark Connect

Le tableau fourni répertorie les problèmes courants que vous pouvez rencontrer lors de la configuration de connexions Spark Connect à Oracle AI Data Platform et en indique les causes potentielles.

Problème	A vérifier
L'application ne peut pas se connecter	Vérifiez que le cluster est actif et que votre environnement peut atteindre le nom d'hôte de la passerelle sur le port 443.
Echec d'authentification	Vérifiez le chemin du fichier de configuration OCI, le nom du profil et les informations d'identification. Actualisez les informations d'identification de session expirées.
Echec de l'autorisation ou ressource introuvable	Vérifiez le nom d'hôte et la clé de cluster. Confirmez l'activation de la location et les droits d'accès permettant d'utiliser le cluster.
Une requête ne peut pas accéder à une table	Vérifiez le nom du catalogue, du schéma et de la table et vérifiez que l'identité authentifiée a accès aux données.
Python signale un module `pyspark` ou `oci` manquant	Installez les dépendances fournies et exécutez l'exemple à l'aide de `.venv/bin/python`.
Python charge une version Spark inattendue	Utilisez la commande documentée avec PYTHONPATH et SPARK_HOME supprimés.
Java signale une dépendance manquante ou une bibliothèque incompatible	Suivez les instructions de configuration fournies avec le groupe Java et utilisez les versions de dépendance spécifiées.