Verbindung zu Compute herstellen

10 Verbindung zu Compute herstellen

In diesem Abschnitt wird beschrieben, wie Sie Compute in Ihrer Oracle AI Data Platform mit anderen Business-Intelligence-Tools verbinden.

Themen:

Verbindungen

Sie können Ihre Oracle AI Data Platform mit Oracle Analytics Cloud oder anderen Business-Intelligence-Tools verbinden.

Sie können über verschiedene Business-Intelligence-Tools eine Verbindung zu AI Data Platform herstellen, indem Sie ein benutzerdefiniertes JDBC oder ODBC verwenden, das von AI Data Platform bereitgestellt wird. AI Data Platform unterstützt auch Verbindungen von kommerziellen BI-Tools von Drittanbietern (Tableau, Power BI) oder Open-Source-BI-Tools wie DBeaver. Um über diese Tools eine Verbindung herzustellen, benötigen Sie die Verbindungsdetails des Compute-Clusters in Ihrer AI Data Platform, die Sie auf der Registerkarte "Verbindungsdetails" finden. Die erforderlichen Informationen variieren je nach Produkt, mit dem Sie eine Verbindung herstellen.

Registerkarte "Verbindungsdetails" für das Compute-Cluster Dev_cluster_1

Oracle Analytics mit Oracle AI Data Platform verbinden

Sie können über eine Oracle Analytics Cloud-Instanz eine Verbindung zu dem Katalog oder den Tabellen herstellen, die von Ihrer Oracle AI Data Platform-Instanz verwaltet werden.

Um eine Verbindung von Oracle Analytics zu AI Data Platform herzustellen, benötigen Sie eine Verbindungsdatei von AI Data Platform und einen API-Schlüssel von Analytics Cloud.

Konfigurationsdatei für Oracle Analytics-Verbindung abrufen

Sie müssen eine config.json-Datei von Ihrer Oracle AI Data Platform-Instanz herunterladen, um eine Verbindung zu Oracle Analytics herzustellen.

Sie benötigen ein Compute Cluster mit mindestens 2 OCPUs, 32 GB Arbeitsspeicher für Treiber- und Worker-Knoten und mindestens 2 Worker.

Navigieren Sie zu Ihrem Workspace, und klicken Sie auf Compute.
Klicken Sie auf das Cluster, mit dem Sie eine Verbindung zu Oracle Analytics herstellen möchten.
Klicken Sie auf der Registerkarte Verbindungsdetails unter dem Oracle Analytics Cloud-Logo auf das Symbol Herunterladen. Eine config.json-Datei wird auf Ihren Rechner heruntergeladen.

Verbindung zu Oracle Analytics herstellen

Sie können über eine Oracle Analytics-Instanz eine Verbindung zu dem Katalog oder den Tabellen herstellen, die von Ihrer Oracle AI Data Platform-Instanz verwaltet werden.

Stellen Sie sicher, dass eine Verbindungskonfigurationsdatei von AI Data Platform vorhanden ist, bevor Sie Ihre Verbindung in Oracle Analytics erstellen. Siehe Oracle Analytics-Verbindungskonfigurationsdatei abrufen.

Oracle Analytics-Verbindungen zu AI Data Platform-Instanzen unterstützen nur einen Katalog pro Verbindung. Sie müssen zusätzliche Verbindungen erstellen, um mehrere Kataloge zu verwenden.

Klicken Sie auf der Homepage von Oracle Analytics auf Erstellen und dann auf Verbindung.
Klicken Sie auf Oracle AI Data Platform.
Geben Sie einen Namen und die Beschreibung für die Verbindung ein.
Geben Sie unter Speicherort an, wo die Verbindung gespeichert werden soll. Um die Verbindung für andere Benutzer freizugeben, speichern Sie sie in /Gemeinsam genutzten Ordnern.
Klicken Sie unter "Verbindungsdetails" in Oracle Analytics Cloud auf Auswählen, navigieren Sie zur Datei config.json, und klicken Sie auf Öffnen.
Wählen Sie API-Schlüssel als Authentifizierungstyp aus.
Klicken Sie unter Öffentlicher API-Schlüssel auf Generieren, Kopieren.
Fügen Sie in OCI einen API-Schlüssel hinzu.
1. Klicken Sie in OCI auf das Benutzersymbol, und klicken Sie dann auf Benutzereinstellungen.
2. Klicken Sie in "Mein Profil" auf Token und Schlüssel und dann auf API-Schlüssel hinzufügen.
3. Wählen Sie Public Key einfügen aus, und kopieren Sie den in Schritt 7 generierten Schlüssel, und klicken Sie dann auf Hinzufügen.
Warten Sie zwei bis drei Minuten, bis der API-Schlüssel synchronisiert ist.
Geben Sie unter Katalog den Katalognamen an, der in Ihren Datensets verwendet werden soll.
Wenn die Liste Katalog nicht geladen wird und die Alertmeldung "Benutzer hat keine ausreichenden Berechtigungen zum Ausführen des Vorgangs" angezeigt wird, warten Sie etwas länger, bis der API-Schlüssel synchronisiert wird.
Klicken Sie auf Speichern.
Testen Sie die neue Verbindung, indem Sie ein Dataset erstellen.

Wenn Sie die Anweisungen befolgt haben und weiterhin Probleme beim Speichern der Verbindung oder beim Auflisten der Schemas haben, ist möglicherweise ein Clusterneustart erforderlich.

JDBC-Treiber herunterladen

Sie können den JDBC-Treiber auf der Registerkarte "Verbindungsdetails" herunterladen und für verschiedene BI-Tools konfigurieren.

Navigieren Sie zu Ihrem Workspace, und klicken Sie auf Compute.
Klicken Sie auf das Cluster, das Sie mit einem JDBC-kompatiblen BI-Tool verbinden möchten, und klicken Sie auf Verbindungen.
Klicken Sie auf JDBC-Treiber herunterladen.

DBeaver konfigurieren

Sie müssen DBeaver installieren und Dateien vorbereiten, die von Oracle AI Data Platform heruntergeladen wurden, bevor Sie es mit einem Compute-Cluster in AI Data Platform verbinden können.

Herunterladen und DBeaver-Client installieren Sie können Community- oder Enterprise-Versionen verwenden, müssen jedoch mindestens 22.x sein. DBeaver ist nur für Windows, Mac OS X, Eclipse-Plug-in und Linux verfügbar.
Dekomprimieren Sie die Datei aus JDBC-Treiber herunterladen.
Entpacken Sie die Treiberdatei simbaSpark.zip aus den entpackten Dateien.

DBeaver mit dem Spark Simba JDBC-Treiber konfigurieren

Sie können DBeaver so konfigurieren, dass eine Verbindung zu einem Compute-Cluster in Oracle AI Data Platform hergestellt wird.

Sie müssen DBeaver installiert und die von AI Data Platform heruntergeladenen simbaSpark.zip-Dateien extrahiert haben.

Öffnen Sie DBeaver.
Klicken Sie auf Database Navigator.
Klicken Sie auf Treibermanager.
Klicken Sie auf Neu.
Geben Sie AI Data Platform als Treibernamen ein.
Klicken Sie auf Librarys.
Klicken Sie auf Ordner hinzufügen.
Navigieren Sie zum Speicherort des sparkSimba.zip-Extrakts.
Klicken Sie auf Klasse suchen.
Wählen Sie OK aus.
Setzen Sie Treiberklasse auf com.simba.spark.jdbc.Driver.
Klicken Sie auf Einstellungen.
Setzen Sie Klassenname auf com.simba.spark.jdbc.Driver.
Klicken Sie auf OK.

Datenbankverbindung in DBeaver erstellen

Um DBeaver mit einem Compute-Cluster in Oracle AI Data Platform zu verbinden, müssen Sie zunächst eine Datenbankverbindung in DBeaver erstellen.

Sie müssen DBeaver mit dem Spark Simba JDBC-Treiber konfiguriert haben, der von AI Data Platform heruntergeladen wurde. Weitere Informationen finden Sie unter DBeaver mit dem Spark Simba JDBC-Treiber konfigurieren.

Öffnen Sie DBeaver.
Klicken Sie auf Datenbank.
Klicken Sie auf Neue Datenbankverbindung.
Klicken Sie auf Alle.
Wählen Sie AI Data Platform aus.
Klicken Sie auf Weiter.
Geben Sie die URL des JDBC-Treibers ein. Die JDBC-URL finden Sie auf der Registerkarte Verbindungsdetails des Compute-Clusters in AI Data Platform.
Klicken Sie auf Fertig stellen.

DBeaver über JDBC mit Oracle AI Data Platform verbinden

Nachdem DBeaver konfiguriert wurde und eine Datenbankverbindung zu Oracle AI Data Platform besteht, können Sie die Verbindung zwischen DBeaver und AI Data Platform abschließen.

Öffnen Sie DBeaver.
Klicken Sie auf Verbinden.
Wählen Sie aus, ob eine Verbindung mit einem Autorisierungstoken oder einem API-Schlüssel hergestellt werden soll.
- Verbindung mit Autorisierungstoken herstellen
  - Verwenden Sie ein Token, indem Sie kein Profil in der URL angeben, wenn Sie kein DEFAULT-Profil haben. Beispiel: jdbc:spark://gateway.aidp.me-riyadh-1.oci.oraclecloud.com/default;SparkServerType=AIDP;httpPath=cliservice/cf18b4ef-b83e-41dd-82b6-8d391584f6c5
    Die URL öffnet ein Browserfenster.
    
    Melden Sie sich bei dem Mandanten an, in dem die AI Data Platform-Instanz erstellt wird.
    
    Weitere Informationen finden Sie unter Tokenbasierte Authentifizierung für die CLI.
- Verbinden Sie sich mit einem API-Schlüssel, indem Sie das OCI-Profil mit ociProfile=<profile_name> in der Verbindungs-URL angeben.
  - Verwenden Sie die API-Schlüsselauthentifizierung, um eine Verbindung zu einer AI Data Platform-Instanz herzustellen.
    Verwenden Sie den API-Schlüssel, indem Sie das OCI-Profil mit ociProfile=<profile_name> in der Verbindungs-URL angeben. Beispiel: So verwenden Sie die Demo des OCI-Profilnamens: jdbc:spark://gateway.aidp.me-riyadh-1.oci.oraclecloud.com/default;SparkServerType=AIDP;httpPath=cliservice/cf18b4ef-b83e-41dd-82b6-8d391584f6c5 ;ociProfile=Demo
    
    Weitere Informationen finden Sie unter Erforderliche Schlüssel und OCIDs.
DBeaver erstellt eine Verbindung zum Lesen von Metadaten und eine Verbindung für alle anderen Vorgänge. Wenn Sie auf Verbindungen beschränkt sind, können Sie die zweite Verbindung deaktivieren, sodass DBeaver eine Verbindung für alle Vorgänge verwendet.
1. Klicken Sie auf Voreinstellungen.
2. Klicken Sie auf Allgemein.
3. Klicken Sie auf Metadaten.
4. Deaktivieren Sie die Option Separate Verbindung für Metadatenlesevorgänge öffnen.

ODBC-Treiber herunterladen

Sie können den ODBC-Treiber auf der Registerkarte "Verbindungsdetails" herunterladen und für verschiedene BI-Tools konfigurieren.

Navigieren Sie zu Ihrem Workspace, und klicken Sie auf Compute.
Klicken Sie auf das Cluster, das Sie mit einem ODBC-kompatiblen BI-Tool verbinden möchten, und klicken Sie auf Verbindungen.
Klicken Sie auf ODBC-Treiber herunterladen.
Wählen Sie das entsprechende Betriebssystem aus der Liste aus.

API zur Ausführung von SQL-Anweisungen

Mit der API zur Ausführung von SQL-Anweisungen können Sie eine schreibgeschützte SQL-Anweisung in einem Compute-Cluster von einer externen Anwendung, Automatisierung oder einem Agent ausführen.

Die API gibt das Ergebnis direkt für kleine Ergebnismengen zurück oder stellt einen temporären Link für größere Ergebnisse bereit. Die SQL-Ausführungs-API verwendet die Oracle Cloud Infrastructure-Anforderungssignatur. Anweisungen werden mit der Identität und den Berechtigungen des authentifizierten Aufrufers ausgeführt. Sie können eine Anweisung weiterleiten, ihren Status und ihre Ergebnisse abrufen und eine laufende Anweisung abbrechen.

Stellen Sie sicher, dass Sie Folgendes haben, bevor Sie beginnen:

Ein gestartetes Compute-Cluster mit dem Status "Aktiv"
Der Compute-Clusterschlüssel (ID). Sie finden dies auf der Registerkarte Details des Clusters unter "Allgemeine Informationen".
Der Gatewayhostname für das Cluster. Sie finden den Hostnamen auf der Registerkarte Verbindungsdetails des Clusters unter JDBC-Treiber oder ODBC-Treiber.
Ein OCI-CLI-Sicherheitstokenprofil im verwendeten CLI-Terminal oder der verwendeten Anwendung. Sie können sich anmelden, indem Sie oci session authenticate --profile-name <profile-name> ausführen und die Prompts befolgen.

So legen Sie Verbindungswerte fest

Stellen Sie sicher, dass Sie die Verbindungswerte für Ihre Umgebung im Terminal oder in der Anwendung festgelegt haben, in dem die OCI-CLI konfiguriert ist.

Mit den folgenden Befehlen können Sie die Verbindungswerte für Ihre Umgebung festlegen:

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

Beispiel:

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"

SQL-Anweisung - API-Aktionen

Um Aktionen für die API zur Ausführung von SQL-Anweisungen auszuführen, müssen Sie den Endpunkt über die Oracle Cloud Infrastructure-CLI aufrufen.

Sie führen die folgenden Aktionen von einem Terminal oder einer Anwendung aus, das/die mit Ihrer OCI-CLI konfiguriert ist.

Anforderungsoptionen der API zur Ausführung von SQL-Anweisungen

Die folgenden Anforderungsfelder werden beim Erstellen einer API-Anforderung für die Ausführung von SQL-Anweisungen verwendet.

Feld	Beschreibung
`statement`	Eingabe erforderlich. Schreibgeschützte SQL-Anweisung.
`wait_timeout`	Optional. Die maximale Zeit, die die API wartet, bis die Anweisung abgeschlossen ist, bevor eine Antwort zurückgegeben wird.
`disposition`	Geben Sie INLINE oder EXTERNAL_LINKS an.
`row_limit`	Die maximale Anzahl von Zeilen, die für die Anweisung beibehalten werden.
`byte_limit`	Die maximale Anzahl von Byte, die für die Anweisung beibehalten werden.
`catalog`	Optional. Der Katalog, der beim Ausführen der Anweisung verwendet werden soll.
`schema`	Optional. Das Schema, das beim Ausführen der Anweisung verwendet werden soll.
`parameters`	Optional. Ein Array mit benannten Parameterwerten für die SQL-Anweisung.
`query_tags`	Optional. Schlüsselwert-Tags zur Identifizierung und Verfolgung einer Anweisung. Geben Sie maximal 20 Einträge an.
`request_id`	Optional. Eine vom Aufrufer bereitgestellte Korrelations- oder Idempotenzkennung. Verwenden Sie den Wert nur für dieselbe logische Anforderung erneut.
`opc-request-id`	Optional. Ein Anforderungsheader zum Verfolgen der Anforderung. Verwenden Sie nur Buchstaben, Zahlen, Unterstriche und Bindestriche.

SQL-Anweisung weiterleiten

SQL-Anweisungen werden an diesen API-Endpunkt weitergeleitet:

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

Das folgende Beispiel enthält einen optionalen wait_timeout-Wert von 10 Sekunden für ein Ergebnis:

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

Die erwartete Antwort auf das obige Beispiel sieht folgendermaßen aus:

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

Das Feld wait_timeout gibt an, wie lange die API auf den Abschluss der Anweisung wartet, bevor eine Antwort zurückgegeben wird. Wenn die Anweisung innerhalb der angegebenen Wartezeit abgeschlossen wird, gibt die API 200 OK zurück und schließt das Anweisungsergebnis ein. Wenn die Anweisung nicht innerhalb dieser Zeit abgeschlossen wird, gibt die API 202 Accepted zurück und fährt mit der Ausführung der Anweisung fort.

Sie können den Filter jq ändern, um die für die Anwendung erforderlichen Antwortfelder anzuzeigen. Der Befehl speichert die vollständige API-Antwort in der temporären Datei /tmp/sql-submit.json, die auf weitere Antwortdetails geprüft werden kann.

Anweisung mit externen Links weiterleiten

Sie können Anweisungen über denselben POST-Endpunkt weiterleiten, der externe Links enthält, wie im folgenden Beispiel:

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

Die erwartete Antwort auf das obige Beispiel lautet wie folgt:

{
  "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 diesem Beispiel wird der temporäre externe Ergebnislink in /tmp/sql-external-submit.json gespeichert und nicht in der Befehlsantwort angezeigt.

Hinweis:

Freigeben Sie keine externen Ergebnislinks, oder speichern Sie sie nicht in Quellcode, Protokollen, Tickets oder anderen allgemein zugänglichen Orten. Jeder, der über einen gültigen Link verfügt, kann auf die zugehörigen Ergebnisdaten zugreifen, bis der Link abläuft.

Wenn truncated true ist, hat das zurückgegebene Ergebnis den angegebenen Zeilengrenzwert oder Bytegrenzwert erreicht.

statement_id festlegen

Die statement_id wird benötigt, um Informationen über die Anweisung abzurufen, wie Status oder Ergebnisse, und um eine Anweisung abzubrechen. Sie können die statement_id festlegen, wenn die Anweisung wie folgt weitergeleitet wird:

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

Wenn die Weiterleitungsantwort in /tmp/sql-submit.json gespeichert wurde, können Sie die statement_id wie folgt festlegen:

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

SQL-Anweisungsstatus anfordern

Sie können den Status einer weitergeleiteten Anweisung mit dem zugehörigen statement_id von diesem Endpunkt abrufen:

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

Im folgenden Beispiel wird der Status einer Anweisung mithilfe der statement_id abgerufen:

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

Die erwartete Antwort für diese Anforderung lautet wie folgt:

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

Eine Anweisung kann die folgenden Status aufweisen:

PENDING
RUNNING
SUCCEEDED
FAILED
CANCELLED

Rufen Sie für eine Anweisung, die 202 Accepted zurückgibt, den Status ab, bis die Anweisung einen Terminalstatus erreicht: SUCCEEDED, FAILED oder CANCELLED.

Anweisungsergebnisse anfordern

Wenn eine Anweisung abgeschlossen ist, können Sie ihr Ergebnis mit statement_id und Ergebnis chunk-index mit dem folgenden Endpunkt abrufen:

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

Legen Sie chunk-index fest, um zu bestimmen, welche Ergebnisse beim Aufrufen des Endpunkts abgerufen werden. chunk-index von 0 ruft das erste Ergebnis ab. Sie können die chunk-index des nächsten Ergebnisses bestimmen, indem Sie die next_chunk_index in der Antwort prüfen. Wenn next_chunk_index null ist, gibt dies an, dass keine zusätzlichen Ergebnis-Chunks vorhanden sind.

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

Mit row_limit und byte_limit können Sie steuern, wie viele Ergebnisdaten der Service speichert und zurückgibt. Wenn eine der beiden Grenzwerte erreicht ist, kann die Antwort darauf hinweisen, dass das Ergebnis abgeschnitten wurde. Eine erfolgreiche Anweisung bedeutet nicht, dass alle Quellzeilen im Ergebnis beibehalten wurden.

In diesem Beispiel wird eine Anforderung für Anweisungsergebnisse gezeigt:

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

Die Antwort auf die oben genannten Beispiele sieht folgendermaßen aus:

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

Wenn eine Anweisung abgeschlossen ist, enthält die Antwort den Anweisungsstatus und die Ergebnismetadaten. Wenn Sie INLINE für disposition angeben, gibt der Service Ergebnisdaten in der Antwort zurück. Verwenden Sie INLINE für kleine Ergebnisse, die eine Anwendung sofort verarbeiten kann. Wenn Sie EXTERNAL_LINKS angeben, speichert der Service das Ergebnis und gibt einen temporären Link zurück, anstatt die Ergebnisdaten in die Antwort aufzunehmen. Verwenden Sie EXTERNAL_LINKS für große Ergebnisse.

Die Antwort kann die folgenden Ergebnisinformationen enthalten:

data_array: Ergebnisdaten, wenn das Ergebnis inline zurückgegeben wird. Dieser Wert ist Null, wenn Sie EXTERNAL_LINKS verwenden.
external_links: Temporäre Links zu Ergebnisdaten, wenn Sie EXTERNAL_LINKS verwenden.
row_count und byte_count: Die Anzahl der Zeilen und Byte im zurückgegebenen Ergebnis-Chunk.
next_chunk_index: Der Index des nächsten Ergebnis-Chunk, wenn mehr Ergebnisdaten verfügbar sind.
truncated: Gibt an, ob der Service nur einen Teil des Ergebnisses beibehalten hat, weil der angeforderte Zeilen- oder Bytegrenzwert erreicht wurde.
expires_at: Die Zeit, zu der beibehaltene Ergebnisdaten und temporäre externe Links ablaufen.

Weitergeleitete Auszüge stornieren

Sie können eine ausgeführte Anweisung abbrechen. Sie benötigen die statement_id für die Anweisung, die Sie abbrechen möchten.

Um eine Anweisung abzubrechen, senden Sie eine POST-Anforderung an den folgenden Endpunkt:

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

In diesem Beispiel wird eine Anforderung zum Abbrechen einer Anweisung gezeigt:

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

Die Antwort auf die oben genannten Beispiele sieht folgendermaßen aus:

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

Wenn der Abbruch abgeschlossen ist, gibt die API 200 OK zurück. Die Antwort enthält die Anweisungs-ID und den Status CANCELED.

Sie können den Abbruch bestätigen, indem Sie den Auszugsstatus mit demselben statement_id abrufen:

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

Die Verifizierungsantwort sieht folgendermaßen aus:

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

Katalog oder Schema angeben

Sie können einen Katalog, ein Schema oder beides angeben, wenn Sie eine SQL-Anweisung weiterleiten. Werte, die Sie in der Anforderung angeben, überschreiben den aktuellen Sessionkontext. Geben Sie Katalog und Schema an, um die Anweisung in einem bestimmten Katalog und Schema auszuführen.

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

Sie können nur catalog angeben, um einen Katalog auszuwählen. Um sicherzustellen, dass eine Anweisung ein bestimmtes Schema verwendet, geben Sie sowohl catalog als auch schema an.

Sie können nur schema angeben, um ein Schema im aktuellen Katalog auszuwählen. Sie können auch einen qualifizierten Schemanamen angeben, wie sales_catalog.reporting, wenn Sie catalog weglassen.

Wenn Sie catalog oder schema nicht angeben, verwendet die Anweisung den aktuellen Sessionkatalog und das aktuelle Schema. Wenn der angegebene Katalog oder das angegebene Schema nicht vorhanden ist oder der Aufrufer keinen Zugriff hat, kann die Anweisung mit dem Status FAILED abgeschlossen werden. Prüfen Sie status.state und status.error in jeder Antwort auf eine abgeschlossene Anweisung. Ungültige Syntax für Katalog- oder Schemafeld gibt 400 Bad Request zurück.

Benannte Paramater

Sie können benannte Parameter in einer SQL-Anweisung verwenden. Geben Sie einen Parameter in der Anweisung an, indem Sie einen Doppelpunkt gefolgt vom Parameternamen verwenden, wie :id. Positionsparameter, wie ?, werden nicht unterstützt. Geben Sie Parameterwerte im Array parameters an. Jeder Parameter enthält die folgenden Felder:

Feld	Beschreibung
`name`	Eingabe erforderlich. Der Parametername ohne Doppelpunkt (:)-Präfix.
`value`	Eingabe erforderlich. Der Parameterwert. Geben Sie den Wert als Zeichenfolge an.
`type`	Optional. Ein Typhinweis für den Parameterwert.

Beispiel: Die folgende Anforderung stellt Werte für :id und :name bereit:

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

Die API unterstützt den folgenden Parametertyphinweis:

Boolescher Wert: BOOLEAN
Ganzzahl: BYTE, TINYINT, SHORT, SMALLINT, INT, INTEGER, LONG, BIGINT
Numerisch: FLOAT, DOUBLE, DECIMAL, NUMERIC
Datum und Uhrzeit: DATE, TIMESTAMP, TIMESTAMP_NTZ
Zeichen: STRING, CHAR, VARCHAR

Der Typwert ist ein Typhinweis. Verlassen Sie sich nicht darauf, eine mitgelieferte Dezimalgenauigkeit und Skalierung oder eine Zeitstempelvariante beizubehalten. Validieren Sie zurückgegebene Werte und Typen in Ihrer Anwendung.

Fehlerbehebung bei API-Antworten für SQL-Anweisungen

Verwenden Sie die folgende Tabelle, um mögliche Lösungen für häufige API-Antworten zu beheben:

Antwort	Lösung
`400 Bad Request`	Stellen Sie sicher, dass die Anforderung eine unterstützte schreibgeschützte Anweisung und gültige Anforderungswerte enthält.
`401` oder `403`	Prüfen Sie die OCI-Authentifizierung und Ihre Berechtigungen für das Compute-Cluster und die abgefragten Daten.
`404 Not Found`	Prüfen Sie die Region, den Compute-Clusterschlüssel, die Aufruferidentität und die Anweisungs-ID.
`503 Service Unavailable`	Warten Sie, bis das Compute-Cluster aktiv ist, und wiederholen Sie den Vorgang.

Verbindung zu externen Anwendungen mit Spark Connect herstellen

Mit Spark Connect können Sie Spark-Code in einem Oracle AI Data Platform-Compute-Cluster aus einer unterstützten Python- oder Java-Anwendung ausführen.

Sie können von einer lokalen IDE oder einer externen Anwendung aus arbeiten, während das Cluster Ihre DataFrame-Vorgänge und Spark-SQL-Abfragen ausführt. Beispiel: Sie können eine Datentransformation lokal entwickeln, sie für Daten ausführen, die für das Cluster verfügbar sind, und die Ergebnisse in der Anwendung abrufen.

Um Spark Connect zu verwenden, stellen Sie Folgendes sicher:

Ein Compute-Cluster mit dem Status "Aktiv".
Benutzen Sie Berechtigungen oder höher für das Cluster und die Daten, die Sie verwenden.
Netzwerkzugriff auf den Hostnamen des Spark Connect-Clusters auf Port 443.
Der Compute-Clusterschlüssel (ID). Sie finden dies auf der Registerkarte Details des Clusters unter "Allgemeine Informationen".
Der Gatewayhostname für das Cluster. Sie finden den Hostnamen auf der Registerkarte Verbindungsdetails des Clusters unter JDBC-Treiber oder ODBC-Treiber.
Ein OCI-Authentifizierungsprofil und ein kompatibler Spark Connect-Client.

AI Data Platform unterstützt Python- und Java-Clients und hat für jeden die folgenden Anforderungen:

Client	Anforderungen
Python	Python 3.9-3.11, PySpark Connect 3.5.1
Java	JDK 17, Maven 3.8 oder höher, Spark Connect JVM-Client 3.5.1

Verbindung zu Spark Connect mit einem Python-Client herstellen

Dieses Python-Beispiel enthält das Verbindungssetup, das zur Authentifizierung mit OCI und zum Erstellen einer Remote-Spark-Session erforderlich ist.

Für dieses Beispiel sind spark_connect_example.py und requirements.txt erforderlich, die in diesem Bundle angegeben sind: Spark-Connect-Beispiele.

Öffnen Sie ein Terminal im extrahierten Beispielverzeichnis. Virtuelle Umgebung erstellen und Abhängigkeiten installieren:
```
python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install -r requirements.txt
```
Verwenden Sie die angegebene Abhängigkeitsdatei, um kompatible Versionen der Clientbibliotheken zu installieren.

Legen Sie in Ihrem Terminal den Hostnamen, den Cluster-Schlüssel und das OCI-Profil fest:

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

Ersetzen Sie die Werte in eckigen Klammern durch Ihre Verbindungsdetails. Das ausgewählte OCI-Profil muss gültige API-Schlüssel- oder Sicherheitstoken-Zugangsdaten enthalten. Beispiel:

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"

Prüfen Sie die Verbindung:

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

Wählen Sie die Authentifizierungsmethode aus, die Ihrem Profil entspricht:

Authentifizierungstyp	Einstellung
API-Schlüssel	`SPARK_CONNECT_OCI_AUTH_MODE=api_key`
Sicherheitstoken	`SPARK_CONNECT_OCI_AUTH_MODE=security_token`

Im Beispiel werden ein DataFrame-Vorgang und eine Spark-SQL-Abfrage ausgeführt. Beide geben die IDs 0 bis 4 mit ihren quadratischen Werten zurück. Das Terminal zeigt die Ergebnisse als erfasste Zeilen an. Wenn beide Vorgänge abgeschlossen sind, hat die Anwendung authentifiziert, mit dem Cluster verbunden und Spark-Code ausgeführt.

Verwenden Sie die im Beispiel erstellte authentifizierte Spark-Session, um Ihre eigenen Vorgänge auszuführen. Öffnen Sie spark_connect_example.py, und ersetzen Sie die Beispielvorgänge innerhalb des Versuchsblocks durch Ihren Anwendungscode. Behalten Sie den vorhandenen Code bei, der die authentifizierte Spark-Session erstellt.
Beispiel: Um mit einer DataFrame zu arbeiten, können Sie Folgendes verwenden:
```
frame = spark.range(5)

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

result.show()
```
Um Spark SQL auszuführen, können Sie Folgendes verwenden:
```
spark.sql(
    "SELECT id, id * id AS squared FROM range(5)"
).show()
```
Verwenden Sie beim Abfragen eigener Tabellen den entsprechenden Katalog und das entsprechende Schema. Ihre Identität muss über Berechtigungen für den Zugriff auf diese Tabellen verfügen.
Wenn die Anwendung beendet ist, schließen Sie die Spark-Session:
```
spark.stop()
```

Hinweis:

Im angegebenen Beispiel wird die anschließbare Ausführung für den dokumentierten Spark 3.5.1-Client deaktiviert:

spark.client.disable_reattachable_execute()

Behalten Sie diese Einstellung bei, wenn Sie das Beispiel anpassen.

Verbindung zu Spark Connect mit einem Java-Client herstellen

Dieses Java-Beispiel enthält das Verbindungssetup, das zur Authentifizierung mit OCI und zum Erstellen einer Remote-Spark-Session erforderlich ist.

Für dieses Beispiel sind SparkConnectExample.java und pom.xml erforderlich, die in diesem Bundle angegeben sind: Spark-Connect-Beispiele.

Extrahieren Sie das Bundle, und öffnen Sie filename. Befolgen Sie die Anweisungen, wie Sie den Bundle-Inhalt installieren.

Öffnen Sie ein Terminal im extrahierten Beispielverzeichnis. Legen Sie denselben Hostnamen, denselben Cluster-Schlüssel, denselben Pfad und dasselbe Profil für die Konfigurationsdatei fest:

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

Ersetzen Sie die Werte in eckigen Klammern durch Ihre Verbindungsdetails. Das ausgewählte OCI-Profil muss gültige API-Schlüssel- oder Sicherheitstoken-Zugangsdaten enthalten. Beispiel:

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

Prüfen Sie die Verbindungen:

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

Wählen Sie die Authentifizierungsmethode aus, die Ihrem Profil entspricht:

Authentifizierungstyp	Einstellung
API-Schlüssel	`SPARK_CONNECT_OCI_AUTH_MODE=api_key`
Sicherheitstoken	`SPARK_CONNECT_OCI_AUTH_MODE=security_token`

Verwenden Sie die im Beispiel erstellte authentifizierte Spark-Session, um Ihre eigenen Vorgänge auszuführen.
Beispiel: Um mit einer DataFrame zu arbeiten, können Sie Folgendes verwenden:
```
frame = spark.range(5)

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

result.show()
```
Um Spark SQL auszuführen, können Sie Folgendes verwenden:
```
spark.sql(
    "SELECT id, id * id AS squared FROM range(5)"
).show()
```
Verwenden Sie beim Abfragen eigener Tabellen den entsprechenden Katalog und das entsprechende Schema. Ihre Identität muss über Berechtigungen für den Zugriff auf diese Tabellen verfügen.
Wenn die Anwendung beendet ist, schließen Sie die Spark-Session:
```
spark.stop()
```

Fehlerbehebung bei Spark Connect

In der bereitgestellten Tabelle werden allgemeine Probleme aufgeführt, die beim Konfigurieren von Spark Connect-Verbindungen zu Oracle AI Data Platform auftreten können, und es werden potenzielle Ursachen angegeben.

Problem	Was zu überprüfen ist
Die Anwendung kann keine Verbindung herstellen	Vergewissern Sie sich, dass das Cluster aktiv ist und Ihre Umgebung den Gateway-Hostnamen auf Port 443 erreichen kann.
Authentifizierung fehlgeschlagen	Prüfen Sie den Pfad, den Profilnamen und die Zugangsdaten der OCI-Konfigurationsdatei. Zugangsdaten für abgelaufene Session aktualisieren.
Autorisierung nicht erfolgreich, oder die Ressource kann nicht gefunden werden	Prüfen Sie Hostname und Cluster-Schlüssel. Bestätigen Sie die Aktivierung des Mandanten und die Berechtigung zur Verwendung des Clusters.
Eine Abfrage kann nicht auf eine Tabelle zugreifen	Prüfen Sie den Katalog-, Schema- und Tabellennamen, und prüfen Sie, ob die authentifizierte Identität Zugriff auf die Daten hat.
Python meldet ein fehlendes `pyspark`- oder `oci`-Modul	Installieren Sie die angegebenen Abhängigkeiten, und führen Sie das Beispiel mit `.venv/bin/python` aus.
Python lädt eine unerwartete Spark-Version	Verwenden Sie den dokumentierten Befehl, während PYTHONPATH und SPARK_HOME entfernt werden.
Java meldet fehlende Abhängigkeit oder inkompatible Library	Befolgen Sie die Setupanweisungen, die mit dem Java-Bundle bereitgestellt werden, und verwenden Sie die angegebenen Abhängigkeitsversionen.