DBMS_CLOUD REST API
이 섹션에서는 Autonomous Database on Dedicated Exadata Infrastructure와 함께 제공되는 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 Cloud Infrastructure 문서의 NAT 게이트웨이 생성 지침에 따라 Autonomous Database 리소스가 상주하는 VCN(가상 클라우드 네트워크)에서 NAT 게이트웨이를 생성합니다.
- NAT 게이트웨이를 생성한 후 각 서브넷(VCN 내)에 경로 규칙 및 송신 보안 규칙을 추가합니다. 여기서 Autonomous Database 리소스는 게이트웨이를 사용하여 Azure AD 인스턴스에서 퍼블릭 키를 얻을 수 있습니다.
- 서브넷의 서브넷 세부 정보 페이지로 이동합니다.
- 서브넷 정보 탭에서 서브넷의 경로 테이블 이름을 눌러 경로 테이블 세부정보 페이지를 표시합니다.
- 기존 경로 규칙의 테이블에서 다음 특성을 가진 규칙이 이미 있는지 확인합니다.
- 대상: 0.0.0.0/0
- 대상 유형: NAT 게이트웨이
- 대상: VCN에서 방금 생성한 NAT 게이트웨이의 이름입니다.
해당 규칙이 없는 경우 경로 규칙 추가를 누르고 해당 특성을 가진 경로 규칙을 추가합니다.
- 서브넷에 대한 서브넷 세부정보 페이지로 돌아갑니다.
- 서브넷의 보안 목록 테이블에서 서브넷의 보안 목록 이름을 눌러 해당 보안 목록 세부정보 페이지를 표시합니다.
- 사이드 메뉴의 리소스에서 송신 규칙을 누릅니다.
- 기존 송신 규칙의 테이블에서 다음 특성을 가진 규칙이 이미 있는지 확인합니다.
- 대상 유형: CIDR
- 대상: 0.0.0.0/0
- IP 프로토콜: TCP
- 소스 포트 범위: 443
- 대상 포트 범위: 모두
해당 규칙이 없으면 Add Egress Rules를 누르고 이러한 특성을 가진 송신 규칙을 추가합니다.
환경의 HTTP 프록시 설정에서 데이터베이스가 클라우드 서비스 공급자에 액세스할 수 있도록 허용해야 합니다.
주:
HTTP 프록시를 포함한 네트워크 구성은 Exadata 인프라가 활성화 필요 상태가 될 때까지만 편집할 수 있습니다. 활성화된 후에는 해당 설정을 편집할 수 없습니다.이미 프로비전된 Exadata 인프라에 대해 HTTP 프록시를 설정하려면 My Oracle Support에서 SR(서비스 요청)이 필요합니다. 자세한 내용은 My Oracle Support에서 서비스 요청 생성을 참조하십시오.
DBMS_CLOUD REST API
이 섹션에서는 Autonomous Database와 함께 제공되는 DBMS_CLOUD
REST API를 다룹니다.
REST API | 설명 |
---|---|
이 함수는 Autonomous Database의 JSON 객체에서 HTTP 응답 헤더를 JSON 데이터로 반환합니다. | |
이 함수는 HTTP 응답을 Autonomous Database의 TEXT 형식(VARCHAR2 또는 CLOB )으로 반환합니다. 일반적으로 대부분의 클라우드 REST API는 JSON 응답을 텍스트 형식으로 반환합니다. 이 함수는 HTTP 응답이 텍스트 형식일 것으로 예상되는 경우에 유용합니다.
|
|
이 함수는 구성된 결과 캐시 크기를 반환합니다. |
|
이 함수는 HTTP 요청을 시작하고 응답을 가져오고 Autonomous Database에서 응답을 종료합니다. 이 함수는 인수와 반환 응답 코드 및 페이로드가 포함된 클라우드 REST API 요청을 전송하기 위한 워크플로우를 제공합니다. | |
이 프로시저는 현재 세션의 최대 캐시 크기를 설정합니다. |
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 |
|
GET_RESPONSE_HEADERS 함수
이 함수는 HTTP 응답 헤더를 JSON 객체의 JSON 데이터로 반환합니다.
구문
DBMS_CLOUD.GET_RESPONSE_HEADERS
(
resp IN DBMS_CLOUD_TYPES.resp)
RETURN JSON_OBJECT_T;
매개변수
매개변수 | 설명 |
---|---|
resp |
|
예외사항
예외사항 | 오류 | 설명 |
---|---|---|
invalid_response |
ORA-20025 |
|
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 |
|
예외사항
예외사항 | 오류 | 설명 |
---|---|---|
invalid_response |
ORA-20025 |
|
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);
매개변수
매개변수 | 설명 |
---|---|
|
해당 클라우드 네이티브 API로 인증하기 위한 인증서의 이름입니다. |
uri |
요청을 생성할 HTTP URI입니다. |
method |
HTTP 요청 메소드: 자세한 내용은 DBMS_CLOUD REST API Constants를 참조하십시오. |
headers |
JSON 형식의 해당 클라우드 네이티브 API에 대한 HTTP 요청 헤더입니다. 인증 헤더는 자동으로 설정되며 사용자 정의 헤더만 전달합니다. |
|
비동기 요청 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 |
대기 상태는
|
timeout |
매개변수가 기본값은 |
cache |
기본값은 |
cache_scope |
모든 사용자가 이 요청 결과 캐시에 액세스할 수 있는지 여부를 지정합니다. 적합한 값은 |
body |
|
예외사항
예외사항 | 오류 | 설명 |
---|---|---|
invalid_req_method |
ORA-20023 |
|
invalid_req_header |
ORA-20024 |
|
사용법 참고
-
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 |
최대 캐시 크기를 지정된 값 캐시 크기가 기본 캐시 크기는 |
예외사항
예외사항 | 오류 | 설명 |
---|---|---|
invalid API result cache size |
ORA-20032 |
최소값은 0이고 최대값은 10000입니다. 이 예외는 입력 값이 0보다 작거나 10000보다 큰 경우에 표시됩니다. |
예
EXEC DBMS_CLOUD.SET_API_RESULT_CACHE_SIZE
(101);