DBMS_CLOUD REST API

필요 조건

개발자는 Oracle Public Cloud, 멀티클라우드 또는 Exadata Cloud@Customer에 배포된 Autonomous Database에서 DBMS_CLOUD 절차를 사용할 수 있습니다.

배포 선택에 따라 Amazon S3, Azure Blob Storage 및 Google Cloud Storage 서비스 제공업체와 함께 DBMS_CLOUD REST API를 사용하려면 다음 필수 조건이 충족되어야 합니다.

Oracle Public Cloud 또는 멀티클라우드
Exadata Cloud@Customer

플리트 관리자가 아래 설명된 대로 NAT 게이트웨이를 사용하여 아웃바운드 접속을 구성해야 합니다.

Oracle Cloud Infrastructure 문서의 NAT 게이트웨이 생성 지침에 따라 Autonomous Database 리소스가 상주하는 VCN(가상 클라우드 네트워크)에서 NAT 게이트웨이를 생성합니다.
NAT 게이트웨이를 생성한 후 각 서브넷(VCN 내)에 경로 규칙 및 송신 보안 규칙을 추가합니다. 여기서 Autonomous Database 리소스는 게이트웨이를 사용하여 Azure AD 인스턴스에서 퍼블릭 키를 얻을 수 있습니다.
1. 서브넷의 서브넷 세부 정보 페이지로 이동합니다.
2. 서브넷 정보 탭에서 서브넷의 경로 테이블 이름을 눌러 경로 테이블 세부정보 페이지를 표시합니다.
3. 기존 경로 규칙의 테이블에서 다음 특성을 가진 규칙이 이미 있는지 확인합니다.
  - 대상: 0.0.0.0/0
  - 대상 유형: NAT 게이트웨이
  - 대상: VCN에서 방금 생성한 NAT 게이트웨이의 이름입니다.
  해당 규칙이 없는 경우 경로 규칙 추가를 누르고 해당 특성을 가진 경로 규칙을 추가합니다.
4. 서브넷에 대한 서브넷 세부정보 페이지로 돌아갑니다.
5. 서브넷의 보안 목록 테이블에서 서브넷의 보안 목록 이름을 눌러 해당 보안 목록 세부정보 페이지를 표시합니다.
6. 사이드 메뉴의 리소스에서 송신 규칙을 누릅니다.
7. 기존 송신 규칙의 테이블에서 다음 특성을 가진 규칙이 이미 있는지 확인합니다.
  - 대상 유형: CIDR
  - 대상: 0.0.0.0/0
  - IP 프로토콜: TCP
  - 소스 포트 범위: 443
  - 대상 포트 범위: 모두
  해당 규칙이 없으면 Add Egress Rules를 누르고 이러한 특성을 가진 송신 규칙을 추가합니다.

환경의 HTTP 프록시 설정에서 데이터베이스가 클라우드 서비스 공급자에 액세스할 수 있도록 허용해야 합니다.

해당 설정은 콘솔을 사용하여 Cloud@Customer에서 Exadata Database Service 프로비전에 설명된 대로 Exadata Cloud@Customer 인프라를 생성하는 동안 플리트 관리자가 정의합니다.

주:

HTTP 프록시를 포함한 네트워크 구성은 Exadata 인프라가 활성화 필요 상태가 될 때까지만 편집할 수 있습니다. 활성화된 후에는 해당 설정을 편집할 수 없습니다.

이미 프로비전된 Exadata 인프라에 대해 HTTP 프록시를 설정하려면 My Oracle Support에서 SR(서비스 요청)이 필요합니다. 자세한 내용은 My Oracle Support에서 서비스 요청 생성을 참조하십시오.

DBMS_CLOUD REST API

이 섹션에서는 Autonomous Database와 함께 제공되는 DBMS_CLOUD REST API를 다룹니다.

REST API	설명
GET_RESPONSE_HEADERS 함수	이 함수는 Autonomous Database의 JSON 객체에서 HTTP 응답 헤더를 JSON 데이터로 반환합니다.
GET_RESPONSE_TEXT 함수	이 함수는 HTTP 응답을 Autonomous Database의 TEXT 형식(`VARCHAR2` 또는 `CLOB`)으로 반환합니다. 일반적으로 대부분의 클라우드 REST API는 JSON 응답을 텍스트 형식으로 반환합니다. 이 함수는 HTTP 응답이 텍스트 형식일 것으로 예상되는 경우에 유용합니다.
GET_API_RESULT_CACHE_SIZE 함수	이 함수는 구성된 결과 캐시 크기를 반환합니다.
SEND_REQUEST 함수 및 프로시저	이 함수는 HTTP 요청을 시작하고 응답을 가져오고 Autonomous Database에서 응답을 종료합니다. 이 함수는 인수와 반환 응답 코드 및 페이로드가 포함된 클라우드 REST API 요청을 전송하기 위한 워크플로우를 제공합니다.
SET_API_RESULT_CACHE_SIZE 프로시저	이 프로시저는 현재 세션의 최대 캐시 크기를 설정합니다.

DBMS_CLOUD REST API 개요

애플리케이션에서 PL/SQL을 사용하는 경우 Cloud REST API를 호출해야 하는 경우 DBMS_CLOUD.SEND_REQUEST을 사용하여 REST API 요청을 전송할 수 있습니다.

DBMS_CLOUD REST API 기능을 사용하면 DBMS_CLOUD.SEND_REQUEST를 사용하여 HTTP 요청을 생성하고 결과를 가져오고 저장할 수 있습니다. 이러한 기능은 지원되는 다음 클라우드 서비스를 통해 모든 REST API를 호출할 수 있는 일반 API를 제공합니다.

Oracle Cloud Infrastructure
Oracle Cloud Infrastructure REST API에 대한 자세한 내용은 API 참조 및 엔드포인트를 참조하십시오.
Azure Cloud ^{각주 1}
Azure REST API에 대한 자세한 내용은 Azure REST API Reference를 참조하십시오.

DBMS_CLOUD REST API 상수

DBMS_CLOUD.SEND_REQUEST를 사용하여 HTTP 요청을 만들기 위한 DBMS_CLOUD 상수를 설명합니다.

DBMS_CLOUD는 GET, PUT, POST, HEAD 및 DELETE HTTP 메소드를 지원합니다. HTTP 요청에 사용할 REST API 메소드는 일반적으로 Cloud REST API 설명서에 문서화되어 있습니다.

이름	유형	값
`METHOD_DELETE`	`VARCHAR2(6)`	`'DELETE'`
`METHOD_GET`	`VARCHAR2(3)`	`'GET'`
`METHOD_HEAD`	`VARCHAR2(4)`	`'HEAD'`
`METHOD_POST`	`VARCHAR2(4)`	`'POST'`
`METHOD_PUT`	`VARCHAR2(3)`	`'PUT'`

DBMS_CLOUD REST API 결과 캐시

DBMS_CLOUD.SEND_REQUEST를 사용하여 cache 매개변수를 true로 설정한 경우 DBMS_CLOUD REST API 결과를 저장할 수 있습니다. SESSION_CLOUD_API_RESULTS 뷰는 REST API 결과가 저장될 때 사용할 수 있는 열에 대해 설명합니다.

기본적으로 DBMS_CLOUD REST API 호출은 세션에 대한 결과를 저장하지 않습니다. 이 경우 DBMS_CLOUD.SEND_REQUEST 함수를 사용하여 결과를 반환합니다.

DBMS_CLOUD.SEND_REQUEST를 사용하고 cache 매개변수를 TRUE로 설정하면 결과가 저장되고 SESSION_CLOUD_API_RESULTS 뷰에서 이전 결과를 볼 수 있습니다. DBMS_CLOUD REST API 요청의 과거 결과를 저장 및 쿼리하면 애플리케이션에서 이전 결과를 작업해야 할 때 도움이 될 수 있습니다.

예를 들어, 최근 DBMS_CLOUD REST API 결과를 질의하려면 SESSION_CLOUD_API_RESULTS 뷰를 사용합니다.

SELECT timestamp FROM SESSION_CLOUD_API_RESULTS;

DBMS_CLOUD REST API 결과를 DBMS_CLOUD.SEND_REQUEST와 함께 저장하면 저장된 데이터는 동일한 세션(연결) 내에서만 사용할 수 있습니다. 세션이 종료되면 저장된 데이터를 더 이상 사용할 수 없습니다.

DBMS_CLOUD.GET_API_RESULT_CACHE_SIZE 및 DBMS_CLOUD.SET_API_RESULT_CACHE_SIZE을 사용하여 DBMS_CLOUD REST API 캐시 크기를 확인 및 설정하고 캐싱을 사용 안함으로 설정합니다.

DBMS_CLOUD REST API 결과 cache_scope 매개변수

DBMS_CLOUD REST API 결과를 DBMS_CLOUD.SEND_REQUEST와 함께 저장하면 cache_scope 값을 기반으로 SESSION_CLOUD_API_RESULTS의 결과에 대한 액세스가 제공됩니다.

기본적으로 cache_scope는 'PRIVATE'이며 세션의 현재 사용자만 결과에 액세스할 수 있습니다. cache_scope를 'PUBLIC'로 설정하면 모든 세션 사용자가 결과에 액세스할 수 있습니다. cache_scope의 기본값은 각 사용자가 호출자 권한으로 호출한 프로시저에 의해 생성된 DBMS_CLOUD.SEND_REQUEST REST API 결과만 볼 수 있도록 지정합니다. 세션에서 DBMS_CLOUD.SEND_REQUEST를 호출하면 cache_scope 값을 기반으로 현재 사용자가 캐시에서 결과를 볼 수 있는지 여부를 결정하는 세 가지 가능성이 있습니다.

DBMS_CLOUD.SEND_REQUEST를 최상위 명령문으로 직접 실행하고 DBMS_CLOUD.SEND_REQUEST에 대한 호출 및 REST API 결과는 동일한 사용자 이름으로 저장됩니다. 이 경우 cache_scope에 대해 설정된 기본값 'PRIVATE''을 사용하여 모든 결과에 액세스할 수 있습니다.
래퍼 호출자의 권한 프로시저를 작성하고 현재 사용자로 DBMS_CLOUD.SEND_REQUEST를 사용하여 호출하면 프로시저가 호출되고 REST API 결과가 동일한 사용자 이름으로 저장됩니다. 이 경우 cache_scope에 대해 설정된 기본값 'PRIVATE''을 사용하여 모든 결과에 액세스할 수 있습니다.
래퍼 정의자 권한 프로시저를 작성하면 프로시저는 다른 유저가 소유합니다. 프로시저 내에서 DBMS_CLOUD.SEND_REQUEST를 호출하면 결과가 프로시저 소유자의 사용자 이름과 함께 저장됩니다.

이 경우 다른 정의자의 권한 사용자가 DBMS_CLOUD.SEND_REQUEST를 호출하고 있으며 REST API 결과가 해당 정의자의 프로시저 소유자와 함께 저장됩니다. 이 경우 기본적으로 cache_scope가 PRIVATE'이면 호출자의 세션에서 결과를 볼 수 없습니다.

정의자의 프로시저 소유자가 호출 세션 사용자가 결과를 사용할 수 있도록 하려면 DBMS_CLOUD.SEND_REQUEST에서 cache_scope를 'PUBLIC'로 설정해야 합니다.

DBMS_CLOUD REST API SESSION_CLOUD_API_RESULTS 보기

DBMS_CLOUD.SEND_REQUEST를 사용하여 cache 매개변수를 true로 설정한 경우 DBMS_CLOUD REST API 결과를 저장할 수 있습니다. SESSION_CLOUD_API_RESULTS 뷰는 REST API 결과가 저장될 때 사용할 수 있는 열에 대해 설명합니다.

SESSION_CLOUD_API_RESULTS 뷰는 DBMS_CLOUD.SEND_REQUEST로 결과를 캐시할 경우 생성되는 뷰입니다. 유저 세션에 속하는 기록 결과를 query할 수 있습니다. 세션이 종료되면 SESSION_CLOUD_API_RESULTS의 데이터가 비워집니다.

열	설명
`URI`	`DBMS_CLOUD` REST API 요청 URL
`TIMESTAMP`	`DBMS_CLOUD` REST API 응답 시간 기록
`CLOUD_TYPE`	`DBMS_CLOUD` REST API 클라우드 유형(예: Oracle Cloud Infrastructure 및 AZURE_BLOB)
`REQUEST_METHOD`	`DBMS_CLOUD` REST API 요청 메소드(예: `GET`, `PUT`, `HEAD`)
`REQUEST_HEADERS`	`DBMS_CLOUD` REST API 요청 헤더
`REQUEST_BODY_TEXT`	`CLOB`의 `DBMS_CLOUD` REST API 요청 본문
`RESPONSE_STATUS_CODE`	`DBMS_CLOUD` REST API 응답 상태 코드(예: `200(OK)`, `404(Not Found)`)
`RESPONSE_HEADERS`	`DBMS_CLOUD` REST API 응답 헤더
`RESPONSE_BODY_TEXT`	`CLOB`의 `DBMS_CLOUD` REST API 응답 본문
`SCOPE`	`DBMS_CLOUD.SEND_REQUEST`로 설정된 `cache_scope`입니다. 적합한 값은 `PUBLIC` 또는 `PRIVATE`입니다.

GET_RESPONSE_HEADERS 함수

이 함수는 HTTP 응답 헤더를 JSON 객체의 JSON 데이터로 반환합니다.

구문

DBMS_CLOUD.GET_RESPONSE_HEADERS(
       resp          IN DBMS_CLOUD_TYPES.resp)
   RETURN JSON_OBJECT_T;

매개변수

매개변수	설명
`resp`	`DBMS_CLOUD.SEND_REQUEST`에서 반환된 HTTP 응답 유형입니다.

예외사항

예외사항	오류	설명
`invalid_response`	`ORA-20025`	`DBMS_CLOUD.GET_RESPONSE_HEADERS`에 잘못된 응답 유형 객체가 전달되었습니다.

GET_RESPONSE_TEXT 함수

이 함수는 HTTP 응답을 TEXT 형식(VARCHAR2 또는 CLOB)으로 반환합니다. 일반적으로 대부분의 클라우드 REST API는 JSON 응답을 텍스트 형식으로 반환합니다. 이 함수는 HTTP 응답이 텍스트 형식일 것으로 예상되는 경우에 유용합니다.

구문

DBMS_CLOUD.GET_RESPONSE_TEXT(
       resp          IN DBMS_CLOUD_TYPES.resp)
   RETURN CLOB;

매개변수

매개변수	설명
`resp`	`DBMS_CLOUD.SEND_REQUEST`에서 반환된 HTTP 응답 유형입니다.

예외사항

예외사항	오류	설명
`invalid_response`	`ORA-20025`	`DBMS_CLOUD.GET_RESPONSE_TEXT`에 잘못된 응답 유형 객체가 전달되었습니다.

GET_API_RESULT_CACHE_SIZE 함수

이 함수는 구성된 결과 캐시 크기를 반환합니다. 캐시 크기 값은 현재 세션에만 적용됩니다.

구문

DBMS_CLOUD.GET_API_RESULT_CACHE_SIZE()
   RETURN NUMBER;

SEND_REQUEST 함수 및 프로시저

이 함수와 프로시저는 HTTP 요청을 시작하고 응답을 가져오고 응답을 종료합니다. 이 함수는 인수와 함께 클라우드 REST API 요청을 전송하기 위한 워크플로우를 제공하며 함수는 응답 코드 및 페이로드를 반환합니다. 프로시저를 사용하는 경우 SESSION_CLOUD_API_RESULTS 뷰를 사용하여 저장된 결과에서 결과 및 응답 세부정보를 볼 수 있습니다.

구문

DBMS_CLOUD.SEND_REQUEST(
       credential_name    IN VARCHAR2,
       uri                IN VARCHAR2,
       method             IN VARCHAR2,
       headers            IN CLOB DEFAULT NULL,
       async_request_url  IN VARCHAR2 DEFAULT NULL,
       wait_for_states    IN DBMS_CLOUD_TYPES.wait_for_states_t DEFAULT NULL,
       timeout            IN NUMBER DEFAULT 0,
       cache              IN PL/SQL BOOLEAN DEFAULT FALSE,
       cache_scope        IN VARCHAR2 DEFAULT 'PRIVATE',
       body               IN BLOB DEFAULT NULL)
   RETURN DBMS_CLOUD_TYPES.resp;

DBMS_CLOUD.SEND_REQUEST(
       credential_name    IN VARCHAR2,
       uri                IN VARCHAR2,
       method             IN VARCHAR2,
       headers            IN CLOB DEFAULT NULL,
       async_request_url  IN VARCHAR2 DEFAULT NULL,
       wait_for_states    IN DBMS_CLOUD_TYPES.wait_for_states_t DEFAULT NULL,
       timeout            IN NUMBER DEFAULT 0,
       cache              IN PL/SQL BOOLEAN DEFAULT FALSE,
       cache_scope        IN VARCHAR2 DEFAULT 'PRIVATE',
       body               IN BLOB DEFAULT NULL);

매개변수

매개변수	설명
`credential_name`	해당 클라우드 네이티브 API로 인증하기 위한 인증서의 이름입니다.
`uri`	요청을 생성할 HTTP URI입니다.
`method`	HTTP 요청 메소드: `GET`, `PUT`, `POST`, `HEAD`, `DELETE`. `DBMS_CLOUD` 패키지 상수를 사용하여 메소드를 지정합니다. 자세한 내용은 DBMS_CLOUD REST API Constants를 참조하십시오.
`headers`	JSON 형식의 해당 클라우드 네이티브 API에 대한 HTTP 요청 헤더입니다. 인증 헤더는 자동으로 설정되며 사용자 정의 헤더만 전달합니다.
`async_request_url`	비동기 요청 URL입니다. URL을 얻으려면 API 목록에서 요청 API를 선택합니다(https://docs.cloud.oracle.com/en-us/iaas/api/ 참조). 그런 다음 왼쪽 창에서 요청에 대한 API를 찾습니다. Database Services API → Autonomous Database → StopAutonomousDatabase를 예로 들 수 있습니다. 이 페이지에는 API 홈이 표시되고 기본 끝점이 표시됩니다. 그런 다음 작업 요청 WorkRequest 링크에 대해 가져온 상대 경로와 함께 기본 끝점을 추가합니다.
`wait_for_states`	대기 상태는 `DBMS_CLOUD_TYPES.wait_for_states_t` 유형입니다. 예상 상태에 적합한 값은 다음과 같습니다. '`ACTIVE`', '`CANCELED`', '`COMPLETED`', '`DELETED`', '`FAILED`', '`SUCCEEDED`'. `wait_for_states`에는 여러 상태가 허용됩니다. `wait_for_states`의 기본값은 예상 상태 '`ACTIVE`', '`CANCELED`', '`COMPLETED`', '`DELETED`', '`FAILED`', '`SUCCEEDED`' 중 하나를 기다리는 것입니다.
`timeout`	매개변수가 `async_request_url` 및 `wait_for_states`인 비동기 요청에 대한 시간 초과(초)를 지정합니다. 기본값은 `0`입니다. 시간 초과 없이 요청이 완료될 때까지 기다립니다.
`cache`	`TRUE`가 요청을 REST 결과 API 캐시에 저장하도록 지정하는 경우 기본값은 `FALSE`입니다. 즉, REST API 요청이 캐시되지 않습니다.
`cache_scope`	모든 사용자가 이 요청 결과 캐시에 액세스할 수 있는지 여부를 지정합니다. 적합한 값은 `"PRIVATE"` 및 `"PUBLIC"`입니다. 기본값은 `"PRIVATE"`입니다.
`body`	`PUT` 및 `POST` 요청에 대한 HTTP 요청 본문입니다.

예외사항

예외사항	오류	설명
`invalid_req_method`	`ORA-20023`	`DBMS_CLOUD.SEND_REQUEST`에 전달된 요청 메소드가 부적합합니다.
`invalid_req_header`	`ORA-20024`	`DBMS_CLOUD.SEND_REQUEST`에 전달된 요청 헤더가 적합한 JSON 형식이 아닙니다.

사용법 참고

Oracle Cloud Infrastructure를 사용 중인 경우 credential_name에 대해 서명 키 기반 인증서 값을 사용해야 합니다. 자세한 내용은 CREATE_CREDENTIAL Procedure를 참조하십시오.
선택적 매개변수 async_request_url, wait_for_states 및 timeout를 사용하면 장기 실행 요청을 처리할 수 있습니다. 이 비동기 형식의 send_request를 사용하면 함수는 반환하기 전에 wait_for_states에 지정된 완료 상태를 기다립니다. send 요청에서 이러한 매개변수를 사용하여 wait_for_states 매개변수에 예상 반환 상태를 전달하고, async_request_url 매개변수를 사용하여 연관된 작업 요청을 지정하면 요청이 즉시 반환되지 않습니다. 대신 요청은 반환 상태가 예상 상태 중 하나이거나 timeout이 초과될 때까지 async_request_url를 프로브합니다(timeout는 선택 사항임). timeout를 지정하지 않으면 wait_for_states에서 발견된 상태가 발생할 때까지 요청이 대기합니다.

SET_API_RESULT_CACHE_SIZE 프로시저

이 프로시저는 현재 세션의 최대 캐시 크기를 설정합니다. 캐시 크기 값은 현재 세션에만 적용됩니다.

구문

DBMS_CLOUD.SET_API_RESULT_CACHE_SIZE(
       cache_size          IN NUMBER);

매개변수

매개변수 설명

매개변수	설명
`cache_size`	최대 캐시 크기를 지정된 값 `cache_size`로 설정합니다. 새 최대 캐시 크기가 현재 캐시 크기보다 작으면 행 수가 지정된 최대 캐시 크기와 같아질 때까지 이전 레코드가 삭제됩니다. 최대값은 `10000`입니다. 캐시 크기가 `0`로 설정된 경우 세션에서 캐싱이 사용 안함으로 설정됩니다. 기본 캐시 크기는 `10`입니다.

cache_size

최대 캐시 크기를 지정된 값 cache_size로 설정합니다. 새 최대 캐시 크기가 현재 캐시 크기보다 작으면 행 수가 지정된 최대 캐시 크기와 같아질 때까지 이전 레코드가 삭제됩니다. 최대값은 10000입니다.

캐시 크기가 0로 설정된 경우 세션에서 캐싱이 사용 안함으로 설정됩니다.

기본 캐시 크기는 10입니다.

예외사항

예외사항	오류	설명
`invalid API result cache size`	`ORA-20032`	최소값은 0이고 최대값은 10000입니다. 이 예외는 입력 값이 0보다 작거나 10000보다 큰 경우에 표시됩니다.

예

EXEC DBMS_CLOUD.SET_API_RESULT_CACHE_SIZE(101);