10 컴퓨트에 연결

이 섹션에서는 Oracle AI Data Platform의 컴퓨트를 다른 비즈니스 인텔리전스 도구에 연결하는 방법을 다룹니다.

연결

Oracle AI Data Platform을 Oracle Analytics Cloud 또는 기타 비즈니스 인텔리전스 도구와 연결할 수 있습니다.

AI 데이터 플랫폼에서 제공하는 사용자정의 JDBC 또는 ODBC를 사용하여 다양한 비즈니스 인텔리전스 툴에서 AI 데이터 플랫폼에 연결할 수 있습니다. 또한 AI 데이터 플랫폼은 타사 상용 BI 도구(Tableau, Power BI) 또는 DBeaver와 같은 오픈 소스 BI 도구의 연결을 지원합니다. 이러한 툴에서 접속하려면 접속 세부정보 탭에서 찾을 수 있는 AI 데이터 플랫폼에서 컴퓨트 클러스터의 접속 세부정보가 필요합니다. 필요한 정보는 연결 중인 제품에 따라 다릅니다.


Dev_cluster_1 컴퓨트 클러스터에 대한 접속 세부정보 탭

Oracle Analytics를 Oracle AI Data Platform에 연결

Oracle Analytics Cloud 인스턴스에서 Oracle AI Data Platform 인스턴스로 관리되는 카탈로그 또는 테이블에 연결할 수 있습니다.

Oracle Analytics에서 AI Data Platform으로의 연결을 생성하려면 AI Data Platform의 연결 파일과 Analytics Cloud의 API 키가 필요합니다.

Oracle Analytics 접속 구성 파일 가져오기

Oracle Analytics에 접속하려면 Oracle AI Data Platform 인스턴스에서 config.json 파일을 다운로드해야 합니다.

OCPU가 2개 이상이고, 드라이버 및 작업자 노드 모두에 32GB 메모리가 있고, 작업자가 2명 이상인 컴퓨트 클러스터가 필요합니다.
  1. 작업영역으로 이동하고 컴퓨트를 누릅니다.

    Cluster_High 컴퓨트 클러스터가 강조 표시된 컴퓨트 페이지가 열립니다.

  2. Oracle Analytics에 접속할 클러스터를 누릅니다.
  3. 접속 세부정보 탭에서 Oracle Analytics Cloud 로고 아래의 다운로드 아이콘을 누릅니다. config.json 파일이 시스템에 다운로드됩니다.

    Cluster_High 클러스터에 대한 컴퓨트 페이지가 접속 세부정보 탭과 Oracle Analytics Cloud 다운로드가 강조 표시되어 있습니다.

Oracle Analytics에 연결합니다

Oracle Analytics 인스턴스에서 Oracle AI Data Platform 인스턴스로 관리되는 카탈로그 또는 테이블에 연결할 수 있습니다.

Oracle Analytics에서 연결을 생성하기 전에 AI Data Platform의 연결 구성 파일이 있는지 확인하십시오. Get an Oracle Analytics Connection Configuration File를 참조하십시오.
AI Data Platform 인스턴스에 대한 Oracle Analytics 연결은 연결당 하나의 카탈로그만 지원합니다. 두 개 이상의 카탈로그를 사용하려면 추가 연결을 생성해야 합니다.
  1. Oracle Analytics 홈 페이지에서 생성, 접속을 차례로 누릅니다.
  2. Oracle AI Data Platform을 누릅니다.
  3. 연결에 대한 이름 및 설명을 입력합니다.
  4. 위치에서 연결을 저장할 위치를 지정합니다. 다른 사용자와 연결을 공유하려면 /Shared Folders에 저장합니다.
  5. Oracle Analytics Cloud에서 접속 세부정보에 대해 선택을 누르고 config.json 파일로 이동한 다음 열기를 누릅니다.
  6. 인증 유형으로 API 키를 선택합니다.
  7. 공용 API 키에서 생성, 복사 순으로 누릅니다.
  8. OCI에서 API 키를 추가합니다.
    1. OCI에서 사용자 아이콘을 누른 다음 사용자 설정을 누릅니다.
    2. 내 프로파일에서 토큰 및 키를 누른 다음 API 키 추가를 누릅니다.
    3. 공개 키 붙여넣기를 선택하고 7단계에서 생성한 키를 복사한 다음 추가를 누릅니다.
    API 키가 동기화될 때까지 2~3분 정도 기다립니다.
  9. 카탈로그에서 데이터 세트에 사용할 카탈로그 이름을 지정합니다.
    Catalog 목록이 로드되지 않고 경보 메시지 "User does not have sufficient privileges to perform the operation"이 표시되는 경우 API 키가 동기화될 때까지 조금 더 기다립니다.
  10. 저장을 누릅니다.
  11. 데이터 집합을 생성하여 새 접속을 테스트합니다.

지침에 따라 연결을 저장하거나 스키마를 나열하는 데 문제가 있는 경우 클러스터를 다시 시작해야 할 수 있습니다.

JDBC 드라이버 다운로드

[접속 세부정보] 탭에서 JDBC 드라이버를 다운로드하고 다른 BI 툴에 맞게 구성할 수 있습니다.

  1. 작업영역으로 이동하고 컴퓨트를 누릅니다.
  2. JDBC 호환 BI 툴에 접속할 클러스터를 누르고 접속을 누릅니다.
  3. JDBC 드라이버 다운로드를 누릅니다.

DBeaver 구성

AI Data Platform의 컴퓨트 클러스터에 연결하려면 먼저 DBeaver를 설치하고 Oracle AI Data Platform에서 다운로드한 파일을 준비해야 합니다.

  1. 다운로드하고 DBeaver 클라이언트를 설치합니다. 커뮤니티 또는 엔터프라이즈 버전을 사용할 수 있지만 Windows, Mac OS X, Eclipse 플러그인 및 Linux에서만 22.x 이상이어야 합니다.
  2. JDBC 드라이버 다운로드에서 파일의 압축을 풉니다.
  3. 압축을 푼 파일에서 simbaSpark.zip 드라이버 파일의 압축을 풉니다.

Spark Simba JDBC 드라이버로 DBeaver 구성

Oracle AI Data Platform의 컴퓨트 클러스터에 연결하도록 DBeaver를 구성할 수 있습니다.

DBeaver를 설치하고 AI Data Platform에서 다운로드한 simbaSpark.zip 파일의 압축을 풀어야 합니다.
  1. DBeaver를 엽니다.
  2. 데이터베이스 네비게이터를 누릅니다.
  3. 드라이버 관리자를 누릅니다.
  4. 새로 만들기를 누릅니다.
  5. 드라이버 이름으로 AI 데이터 플랫폼을 입력합니다.
  6. 라이브러리를 누릅니다.
  7. 폴더 추가를 누릅니다.
  8. sparkSimba.zip 추출의 위치를 찾습니다.
  9. 클래스 찾기를 누릅니다.
  10. 확인을 선택합니다.
  11. 드라이버 클래스를 com.simba.spark.jdbc.Driver로 설정합니다.
  12. 설정을 누릅니다.
  13. Class Name을 com.simba.spark.jdbc.Driver로 설정합니다.
  14. 확인을 누릅니다.

DBeaver에서 데이터베이스 접속 생성

DBeaver를 Oracle AI Data Platform의 컴퓨트 클러스터에 연결하려면 먼저 DBeaver에서 데이터베이스 연결을 생성해야 합니다.

AI 데이터 플랫폼에서 다운로드한 Spark Simba JDBC 드라이버로 DBeaver를 구성해야 합니다. 자세한 내용은 Spark Simba JDBC 드라이버로 DBeaver 구성을 참조하십시오.
  1. DBeaver를 엽니다.
  2. Database를 누릅니다.
  3. 새 데이터베이스 접속을 누릅니다.
  4. 모두를 누릅니다.
  5. AI 데이터 플랫폼을 선택합니다.
  6. 다음을 누릅니다.
  7. JDBC 드라이버의 URL을 입력합니다. AI Data Platform에서 컴퓨트 클러스터의 접속 세부정보 탭에서 JDBC URL을 찾을 수 있습니다.
  8. 완료를 누릅니다.

JDBC를 사용하여 DBeaver를 Oracle AI Data Platform에 연결

DBeaver가 구성되고 Oracle AI Data Platform에 데이터베이스가 연결되어 있으면 DBeaver와 AI Data Platform 간의 연결을 완료할 수 있습니다.

  1. DBeaver를 엽니다.
  2. 연결을 누릅니다.
  3. 권한 부여 토큰 또는 API 키로 접속하도록 선택합니다.
    • 권한 부여 토큰을 사용하여 접속
      • DEFAULT 프로파일이 없는 경우 URL에 프로파일을 지정하지 않고 토큰을 사용합니다. 예: jdbc:spark://gateway.aidp.me-riyadh-1.oci.oraclecloud.com/default;SparkServerType=AIDP;httpPath=cliservice/cf18b4ef-b83e-41dd-82b6-8d391584f6c5

        URL이 브라우저 창을 엽니다.

        AI 데이터 플랫폼 인스턴스가 생성된 테넌시에 사인인합니다.

        자세한 내용은 CLI에 대한 토큰 기반 인증을 참조하십시오.

    • 연결 URL에 ociProfile=<profile_name>를 사용하여 OCI 프로파일을 지정하여 API 키를 사용하여 연결합니다.

      • API 키 인증을 사용하여 AI 데이터 플랫폼 인스턴스에 접속합니다.

        연결 URL에 ociProfile=<profile_name>를 사용하여 OCI 프로파일을 지정하여 API 키를 사용합니다. 예를 들어, OCI 프로파일 이름 데모를 사용하려면 다음과 같이 하십시오. jdbc:spark://gateway.aidp.me-riyadh-1.oci.oraclecloud.com/default;SparkServerType=AIDP;httpPath=cliservice/cf18b4ef-b83e-41dd-82b6-8d391584f6c5 ;ociProfile=Demo

        자세한 내용은 필수 키 및 OCID를 참조하십시오.

  4. DBeaver는 메타데이터를 읽기 위한 연결과 다른 모든 작업에 대한 연결을 생성합니다. 연결이 제한된 경우 DBeaver가 모든 작업에 대해 하나의 연결을 사용하도록 두번째 연결을 사용 안함으로 설정할 수 있습니다.
    1. 환경설정을 누릅니다.
    2. 공통을 누릅니다.
    3. 메타데이터를 누릅니다.
    4. 메타데이터 읽기에 대한 별도의 연결 열기를 선택 해제합니다.

ODBC 드라이버 다운로드

연결 세부정보 탭에서 ODBC 드라이버를 다운로드하여 다른 BI 도구에 맞게 구성할 수 있습니다.

  1. 작업영역으로 이동하고 컴퓨트를 누릅니다.
  2. ODBC 호환 BI 툴에 접속할 클러스터를 누르고 접속을 누릅니다.
  3. ODBC 드라이버 다운로드를 누릅니다.
  4. 목록에서 해당 OS를 선택합니다.

    Mac, Windows 및 Linx 옵션이 표시된 ODBC 드라이버 OS 드롭다운 열기

SQL 문 실행 API

SQL Statement Execution API를 사용하면 외부 응용 프로그램, 자동화 또는 에이전트에서 컴퓨트 클러스터의 읽기 전용 SQL 문을 실행할 수 있습니다.

API는 작은 결과 집합에 대해 직접 결과를 반환하거나 더 큰 결과를 위해 임시 링크를 제공합니다. SQL 문 실행 API는 Oracle Cloud Infrastructure 요청 서명을 사용합니다. 명령문은 인증된 호출자의 ID 및 권한을 사용하여 실행됩니다. 명령문을 실행하고, 해당 상태 및 결과를 검색하고, 실행 중인 명령문을 취소할 수 있습니다.

시작하기 전에 다음 사항이 있는지 확인합니다.
  • 활성 상태의 시작된 컴퓨트 클러스터
  • 컴퓨트 클러스터 키(ID)입니다. 일반 정보 아래에서 클러스터의 세부정보 탭에서 찾을 수 있습니다.
  • 클러스터의 게이트웨이 호스트 이름입니다. 클러스터의 접속 세부정보 탭에 있는 JDBC 드라이버 또는 ODBC 드라이버에서 호스트 이름을 찾을 수 있습니다.
  • 사용 중인 CLI 터미널 또는 애플리케이션의 OCI CLI 보안 토큰 프로파일입니다. oci session authenticate --profile-name <profile-name>를 실행하고 프롬프트에 따라 사인인할 수 있습니다.

연결 값을 설정하는 방법

OCI CLI가 구성된 터미널 또는 애플리케이션에서 환경에 대한 연결 값을 설정했는지 확인합니다.

다음 명령을 사용하여 환경에 대한 연결 값을 설정할 수 있습니다.
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)"
예:
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 문 API 작업

SQL 문 실행 API에 대한 작업을 실행하려면 Oracle Cloud Infrastructure CLI에서 끝점을 호출해야 합니다.

OCI CLI로 구성된 터미널 또는 응용 프로그램에서 다음 작업을 실행합니다.

SQL 문 실행 API 요청 옵션

다음 요청 필드는 SQL 문 실행 API 요청을 생성할 때 사용됩니다.

필드 설명
statement 필수입니다. 읽기 전용 SQL 문.
wait_timeout 선택 사항입니다. API가 명령문이 완료될 때까지 기다린 후 응답을 반환하는 최대 시간입니다.
disposition INLINE 또는 EXTERNAL_LINKS를 지정합니다.
row_limit 명령문에 대해 보존되는 최대 행 수입니다.
byte_limit 명령문에 대해 보유된 최대 바이트 수입니다.
catalog 선택 사항입니다. 명령문을 실행할 때 사용할 카탈로그입니다.
schema 선택 사항입니다. 명령문을 실행할 때 사용할 스키마입니다.
parameters 선택 사항입니다. SQL 문에 대한 명명된 매개변수 값의 배열입니다.
query_tags 선택 사항입니다. 명령문을 식별하고 추적하기 위한 키-값 태그입니다. 항목을 20개 이하로 지정합니다.
request_id 선택 사항입니다. 호출자가 제공한 상관 또는 멱등성 식별자입니다. 동일한 논리적 요청에 대해서만 값을 재사용합니다.
opc-request-id 선택 사항입니다. 요청 추적을 위한 요청 헤더입니다. 문자, 숫자, 밑줄 및 하이픈만 사용합니다.

SQL 문 제출

SQL 문이 이 API 끝점으로 제출됨:

POST /20200129/computeClusters/<compute-cluster-key>/workbench/sql/statements
다음 예에는 결과에 대한 선택적 wait_timeout 값 10초가 포함됩니다.
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"]}'
위 예에 대한 예상 응답은 다음과 같습니다.
{
  "http_status": "200 OK",
  "statement_id": "095865c4-27ce-41cc-99bb-67af1de760b2",
  "state": "SUCCEEDED",
  "result": [
    [
      "1"
    ]
  ],
  "opc_request_id": "sql-submit-20261022-214855/FBBFDCB770BDEFBC654EAE933E45E811/6CD8518A6A62E6411552DBFEF5ECEAD7"
}

wait_timeout 필드는 API가 명령문이 완료될 때까지 기다린 후 응답을 반환하는 기간을 지정합니다. 명령문이 지정된 대기 시간 내에 완료되면 API는 200 OK를 반환하고 명령문 결과를 포함합니다. 이 시간 내에 명령문이 완료되지 않으면 API는 202 Accepted를 반환하고 명령문 실행을 계속합니다.

애플리케이션에서 요구하는 응답 필드를 표시하도록 jq 필터를 수정할 수 있습니다. 이 명령은 추가 응답 세부 정보를 검토할 수 있는 전체 API 응답을 임시 파일 /tmp/sql-submit.json에 저장합니다.

외부 링크가 있는 명세서 제출

다음 예제와 같이 외부 링크를 포함하는 동일한 POST 끝점을 통해 명령문을 제출할 수 있습니다.
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"]
    }'
위 예에 대한 예상 응답은 다음과 같습니다.
{
  "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"
}

이 예에서는 임시 외부 결과 링크가 /tmp/sql-external-submit.json에 저장되고 명령 응답에 표시되지 않습니다.

주:

외부 결과 링크를 공유하거나 소스 코드, 로그, 티켓 또는 광범위하게 액세스할 수 있는 다른 위치에 저장하지 마십시오. 유효한 링크가 있는 사람은 링크가 만료될 때까지 연관된 결과 데이터에 액세스할 수 있습니다.

truncated가 true인 경우 반환된 결과가 지정된 행 제한 또는 바이트 제한에 도달했습니다.

statement_id 설정

상태 또는 결과와 같은 명령문에 대한 정보를 검색하고 명령문을 취소하려면 statement_id가 필요합니다. 다음과 같이 명령문이 제출될 때 statement_id를 설정할 수 있습니다.
export STATEMENT_ID="095865c4-27ce-41cc-99bb-67af1de760b2"
echo "${STATEMENT_ID}"
제출 응답이 /tmp/sql-submit.json에 저장된 경우 statement_id를 다음과 같이 설정할 수 있습니다.
export STATEMENT_ID="$(jq -r '.data.statement_id' /tmp/sql-submit.json)"

요청 SQL 문 상태

이 끝점에서 statement_id를 사용하여 제출된 명령문의 상태를 검색할 수 있습니다.
GET /20200129/computeClusters/<compute-cluster-key>/workbench/sql/statements/<statement-id>

다음 예제는 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"]}'
이 요청에 대한 예상 응답은 다음과 같습니다.
{
  "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"
}
명령문의 상태는 다음과 같습니다.
  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELLED
202 Accepted를 반환하는 명령문의 경우 명령문이 터미널 상태(SUCCEEDED, FAILED 또는 CANCELLED)에 도달할 때까지 상태를 검색합니다.

요청 명세서 결과

명령문이 완료되면 다음 끝점을 사용하여 statement_id 및 결과 chunk-index를 사용하여 해당 결과를 검색할 수 있습니다.

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

끝점을 호출할 때 검색되는 결과를 결정하려면 chunk-index를 설정합니다. chunk-index의 0은 첫번째 결과를 검색합니다. 응답에서 next_chunk_index를 확인하여 다음 결과의 chunk-index를 확인할 수 있습니다. next_chunk_index가 null인 경우 추가 결과 청크가 없음을 나타냅니다.

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

row_limit 및 byte_limit를 사용하여 서비스에서 유지하고 반환하는 결과 데이터의 양을 제어할 수 있습니다. 한도에 도달하면 응답이 결과가 잘렸음을 나타낼 수 있습니다. 성공한 명령문은 결과에서 모든 소스 행이 보존되었음을 의미하지는 않습니다.

다음 예제는 명령문 결과에 대한 요청을 보여줍니다.

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

위의 예제에 대한 응답은 다음과 같습니다.

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

명령문이 완료되면 응답에는 명령문 상태와 결과 메타 데이터가 포함됩니다. disposition에 대해 INLINE을 지정하면 서비스가 응답에 결과 데이터를 반환합니다. 응용 프로그램이 즉시 처리할 수 있는 작은 결과를 얻으려면 INLINE을 사용합니다. EXTERNAL_LINKS를 지정하면 서비스가 결과를 저장하고 응답에 결과 데이터를 포함하는 대신 임시 링크를 반환합니다. 큰 결과를 얻으려면 EXTERNAL_LINKS를 사용합니다.

응답에는 다음과 같은 결과 정보가 포함될 수 있습니다.
  • data_array – 결과가 인라인으로 반환될 때의 결과 데이터입니다. 이 값은 EXTERNAL_LINKS를 사용할 때 널입니다.
  • external_links – EXTERNAL_LINKS를 사용할 때 결과 데이터에 대한 임시 링크입니다.
  • row_count 및 byte_count – 반환된 결과 청크의 행 및 바이트 수입니다.
  • next_chunk_index – 더 많은 결과 데이터를 사용할 수 있는 경우 다음 결과 조각의 인덱스입니다.
  • truncated – 요청된 행 또는 바이트 제한에 도달하여 서비스가 결과의 일부만 보존했는지 여부를 나타냅니다.
  • expires_at – 보존된 결과 데이터 및 임시 외부 링크가 만료되는 시간입니다.

제출된 명령문 취소

실행 중인 명령문을 취소할 수 있습니다. 취소하려는 명령문에 대해 statement_id가 필요합니다.

명령문을 취소하려면 다음 끝점으로 POST 요청을 전송합니다.
POST /20200129/computeClusters/<compute-cluster-key>/workbench/sql/statements/<statement-id>/cancel
다음 예제는 명령문 취소 요청을 보여줍니다.
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"]}'
위의 예제에 대한 응답은 다음과 같습니다.
{
  "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"
}

취소가 완료되면 API는 200 OK를 반환합니다. 응답에는 명령문 ID와 CANCELED 상태가 포함됩니다.

동일한 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"]}'
확인 응답은 다음과 같습니다.
{
  "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"
}

카탈로그 또는 스키마 지정

SQL 문을 제출할 때 카탈로그, 스키마 또는 둘 다를 지정할 수 있습니다. 요청에서 지정한 값은 현재 세션 컨텍스트를 재정의합니다. 카탈로그와 스키마를 모두 지정하여 특정 카탈로그와 스키마에서 명령문을 실행합니다.

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

카탈로그를 선택하려면 catalog만 지정할 수 있습니다. 명령문이 특정 스키마를 사용하도록 하려면 catalog 및 schema를 모두 지정합니다.

현재 카탈로그에서 스키마를 선택하려면 schema만 지정할 수 있습니다. catalog를 생략할 때 sales_catalog.reporting와 같은 정규화된 스키마 이름을 지정할 수도 있습니다.

catalog 또는 schema를 지정하지 않으면 명령문은 현재 세션 카탈로그 및 스키마를 사용합니다. 지정된 카탈로그 또는 스키마가 존재하지 않거나 호출자에게 액세스 권한이 없는 경우 명령문이 FAILED 상태로 완료될 수 있습니다. 작성된 모든 명령문 응답에서 status.state 및 status.error를 확인합니다. 부적합한 카탈로그 또는 스키마 필드 구문이 400 Bad Request를 반환합니다.

명명된 매개변수

SQL 문에서 명명된 파라미터를 사용할 수 있습니다. :id와 같은 매개변수 이름 뒤에 콜론을 사용하여 명령문에서 매개변수를 지정합니다. ?와 같은 위치 매개변수는 지원되지 않습니다. parameters 배열에 매개변수 값을 지정합니다. 각 매개변수는 다음 필드를 포함합니다.

필드 설명
name 필수입니다. 콜론(:) 접두어가 없는 매개변수 이름입니다.
value 필수입니다. 매개변수 값입니다. 값을 문자열로 제공합니다.
type 선택 사항입니다. 매개변수 값에 대한 유형 힌트입니다.
예를 들어, 다음 요청은 :id 및 :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"
}
API는 다음 매개변수 유형 힌트를 지원합니다.
  • 부울: 부울
  • 정수: BYTE, TINYINT, SHORT, SMALLINT, INT, INTEGER, LONG, BIGINT
  • 숫자: 부동, 이중, 소수점, 숫자
  • 날짜 및 시간: DATE, TIMESTAMP, TIMESTAMP_NTZ
  • 문자: 문자열, 문자, VARCHAR
유형 값은 유형 힌트입니다. 제공된 소수점 이하 자릿수 및 소수점 이하 자릿수 또는 시간 기록 변형을 보존하는 데 의존하지 마십시오. 애플리케이션에서 반환된 값 및 유형을 검증합니다.

SQL 문 실행 API 응답 문제 해결

다음 표를 참조하여 일반적인 API 응답에 대한 가능한 해결 방법을 해결할 수 있습니다.
응답 솔루션
400 Bad Request 요청에 지원되는 읽기 전용 명령문과 적합한 요청 값이 포함되어 있는지 확인하십시오.
401 또는 403 컴퓨트 클러스터 및 질의된 데이터에 대한 OCI 인증 및 권한을 확인합니다.
404 Not Found 영역, 컴퓨트 클러스터 키, 호출자 ID 및 명령문 ID를 확인합니다.
503 Service Unavailable 컴퓨트 클러스터가 활성 상태가 될 때까지 기다린 후 재시도하십시오.

Spark Connect를 사용하여 외부 애플리케이션에 연결

Spark Connect를 사용하여 지원되는 Python 또는 Java 애플리케이션의 Oracle AI Data Platform 컴퓨트 클러스터에서 Spark 코드를 실행할 수 있습니다.

클러스터가 DataFrame 작업 및 Spark SQL 질의를 실행하는 동안 로컬 IDE 또는 외부 응용 프로그램에서 작업할 수 있습니다. 예를 들어, 로컬에서 데이터 변형을 개발하고, 클러스터에 사용 가능한 데이터에 대해 데이터 변형을 실행하고, 응용 프로그램에서 결과를 검색할 수 있습니다.

Spark Connect를 사용하려면 다음이 있는지 확인하십시오.
  • 상태가 활성인 컴퓨트 클러스터입니다.
  • 사용 중인 클러스터 및 데이터에 대해 권한 이상을 사용합니다.
  • 포트 443의 Spark Connect 클러스터 호스트 이름에 대한 네트워크 액세스
  • 컴퓨트 클러스터 키(ID)입니다. 일반 정보 아래에서 클러스터의 세부정보 탭에서 찾을 수 있습니다.
  • 클러스터의 게이트웨이 호스트 이름입니다. 클러스터의 접속 세부정보 탭에 있는 JDBC 드라이버 또는 ODBC 드라이버에서 호스트 이름을 찾을 수 있습니다.
  • OCI 인증 프로파일 및 호환되는 Spark Connect 클라이언트입니다.

AI 데이터 플랫폼은 Python 및 Java 클라이언트를 지원하며 각각에 대해 다음과 같은 요구 사항을 갖습니다.

클라이언트 요구 사항
Python Python 3.9–3.11, PySpark Connect 3.5.1
Java JDK 17, Maven 3.8 이상, Spark Connect JVM 클라이언트 3.5.1

Spark에 연결 Python 클라이언트로 연결

이 Python 예제에는 OCI로 인증하고 원격 Spark 세션을 생성하는 데 필요한 연결 설정이 포함되어 있습니다.

이 예에서는 Spark Connect 예제 번들에 제공된 spark_connect_example.py 및 requirements.txt가 필요합니다.
  1. 추출된 예제 디렉토리에서 터미널을 엽니다. 가상 환경을 만들고 종속성을 설치합니다.
    python3 -m venv .venv
    .venv/bin/python -m pip install --upgrade pip
    .venv/bin/python -m pip install -r requirements.txt

    제공된 종속성 파일을 사용하여 호환되는 클라이언트 라이브러리 버전을 설치합니다.

  2. 터미널에서 호스트 이름, 클러스터 키 및 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>"
    꺾쇠 괄호 안의 값을 연결 세부 정보로 바꿉니다. 선택한 OCI 프로파일에는 적합한 API 키 또는 보안 토큰 인증서가 포함되어야 합니다. 예:
    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. 다음 연결을 확인합니다.
    SPARK_CONNECT_OCI_AUTH_MODE=config \
    SPARK_CONNECT_EXAMPLE_TYPE=both \
    env -u PYTHONPATH -u SPARK_HOME \
    .venv/bin/python spark_connect_example.py

    프로파일과 일치하는 인증 방법을 선택합니다.

    인증 유형 설정
    API 키 SPARK_CONNECT_OCI_AUTH_MODE=api_key
    보안 토큰 SPARK_CONNECT_OCI_AUTH_MODE=security_token

    예제에서는 DataFrame 작업과 Spark SQL 질의를 실행합니다. 둘 다 ID가 0에서 4까지이고 제곱 값이 반환됩니다. 터미널은 결과를 수집된 행으로 표시합니다. 두 작업이 모두 완료되면 응용 프로그램이 인증되고 클러스터에 연결되며 Spark 코드를 실행합니다.

  4. 예제에서 생성한 인증된 Spark 세션을 사용하여 고유의 작업을 실행합니다. spark_connect_example.py를 열고 try 블록 안의 샘플 연산을 응용 프로그램 코드로 바꿉니다. 인증된 Spark 세션을 생성하는 기존 코드를 유지합니다.
    예를 들어, DataFrame로 작업하려면 다음을 사용할 수 있습니다.
    frame = spark.range(5)
    
    result = frame.withColumn(
        "squared",
        frame["id"] * frame["id"]
    )
    
    result.show()
    Spark SQL을 실행하려면 다음을 사용할 수 있습니다.
    spark.sql(
        "SELECT id, id * id AS squared FROM range(5)"
    ).show()

    고유 테이블을 query할 때는 해당 카탈로그와 스키마를 사용합니다. ID에 해당 테이블에 액세스할 수 있는 권한이 있어야 합니다.

  5. 응용 프로그램이 완료되면 Spark 세션을 닫습니다.
    spark.stop()

주:

제공된 예제는 문서화된 Spark 3.5.1 클라이언트에 대해 재연결 가능한 실행을 사용 안함으로 설정합니다.
spark.client.disable_reattachable_execute()
예제를 조정할 때 이 설정을 유지합니다.

Java 클라이언트로 Spark Connect에 접속

이 Java 예제에는 OCI로 인증하고 원격 Spark 세션을 생성하는 데 필요한 연결 설정이 포함되어 있습니다.

이 예에서는 Spark Connect 예제 번들에 제공된 SparkConnectExample.java 및 pom.xml가 필요합니다.
  1. 번들을 추출하고 filename를 엽니다. 제공된 지침에 따라 번들 콘텐츠를 설치합니다.
  2. 추출된 예제 디렉토리에서 터미널을 엽니다. 동일한 호스트 이름, 클러스터 키, 구성 파일 경로 및 프로파일을 설정합니다.
    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
    꺾쇠 괄호 안의 값을 연결 세부 정보로 바꿉니다. 선택한 OCI 프로파일에는 적합한 API 키 또는 보안 토큰 인증서가 포함되어야 합니다. 예:
    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. 다음 연결을 확인합니다.
    SPARK_CONNECT_OCI_AUTH_MODE=config \
    SPARK_CONNECT_EXAMPLE_TYPE=both \
    env -u PYTHONPATH -u SPARK_HOME \
    .venv/bin/python spark_connect_example.py"

    프로파일과 일치하는 인증 방법을 선택합니다.

    인증 유형 설정
    API 키 SPARK_CONNECT_OCI_AUTH_MODE=api_key
    보안 토큰 SPARK_CONNECT_OCI_AUTH_MODE=security_token

    예제에서는 DataFrame 작업과 Spark SQL 질의를 실행합니다. 둘 다 ID가 0에서 4까지이고 제곱 값이 반환됩니다. 터미널은 결과를 수집된 행으로 표시합니다. 두 작업이 모두 완료되면 응용 프로그램이 인증되고 클러스터에 연결되며 Spark 코드를 실행합니다.

  4. 예제에서 생성한 인증된 Spark 세션을 사용하여 고유의 작업을 실행합니다.
    예를 들어, DataFrame로 작업하려면 다음을 사용할 수 있습니다.
    frame = spark.range(5)
    
    result = frame.withColumn(
        "squared",
        frame["id"] * frame["id"]
    )
    
    result.show()
    Spark SQL을 실행하려면 다음을 사용할 수 있습니다.
    spark.sql(
        "SELECT id, id * id AS squared FROM range(5)"
    ).show()

    고유 테이블을 query할 때는 해당 카탈로그와 스키마를 사용합니다. ID에 해당 테이블에 액세스할 수 있는 권한이 있어야 합니다.

  5. 응용 프로그램이 완료되면 Spark 세션을 닫습니다.
    spark.stop()

Spark Connect 문제 해결

제공된 표는 Oracle AI Data Platform에 대한 Spark Connect 연결을 구성할 때 발생할 수 있는 일반적인 문제를 나열하고 잠재적 원인을 제공합니다.

문제 확인할 사항
애플리케이션이 접속할 수 없음 클러스터가 활성 상태이고 사용자 환경이 포트 443의 게이트웨이 호스트 이름에 도달할 수 있는지 확인합니다.
인증 실패 OCI 구성 파일 경로, 프로파일 이름 및 인증서를 확인합니다. 만료된 세션 인증서를 새로 고칩니다.
권한 부여를 실패하거나 리소스를 찾을 수 없습니다. 호스트 이름 및 클러스터 키를 확인합니다. 테넌시 사용으로 설정 및 클러스터 사용 권한을 확인합니다.
질의는 테이블에 액세스할 수 없습니다. 카탈로그, 스키마 및 테이블 이름을 확인하고 인증된 ID가 데이터에 액세스할 수 있는지 확인합니다.
Python에서 누락된 pyspark 또는 oci 모듈을 보고합니다. 제공된 종속성을 설치하고 .venv/bin/python를 사용하여 예제를 실행합니다.
Python이 예상치 못한 Spark 버전을 로드합니다. 문서화된 명령을 PYTHONPATH 및 SPARK_HOME 제거와 함께 사용합니다.
Java가 누락된 종속성 또는 호환되지 않는 라이브러리를 보고합니다. Java 번들과 함께 제공된 설정 지침에 따라 지정된 종속성 버전을 사용합니다.