고객 관리 전자 지갑을 사용하여 외부 호출 생성

자율운영 AI 데이터베이스가 HTTP/HTTPS를 통해 인터넷의 데이터에 액세스해야 하는 경우 UTL_HTTP 패키지를 사용할 수 있습니다. UTL_HTTP 패키지를 사용하면 SQL 및 PL/SQL에서 직접 HTTP 콜아웃을 만들 수 있습니다.

HTTPS 엔드포인트를 호출하는 경우 Oracle Wallet을 구성해야 합니다. 자율운영 AI 데이터베이스에는 데이터베이스가 접속할 HTTPS 끝점에 대한 신뢰할 수 있는 루트 및 중간 인증서가 포함된 전자 지갑이 필요합니다. UTL_HTTP 패키지는 이 전자 지갑을 사용하여 보안 SSL/TLS 연결을 설정합니다. orapki 유틸리티를 사용하여 전자 지갑을 생성하고 관리할 수 있습니다.

주: 일반 HTTP(비HTTPS) 요청에는 Oracle Wallet이 필요하지 않습니다.

아래 섹션에서는 고객 관리형 전자 지갑을 구성 및 사용하여 자율운영 AI 데이터베이스의 UTL_HTTP 패키지를 통해 아웃바운드 HTTPS 호출을 수행하는 방법에 대해 설명합니다.

외부 호출과 함께 고객 관리 전자 지갑을 사용하기 위한 전제 조건

시작하기 전에 다음이 있는지 확인하십시오.

• PL/SQL을 실행하고 UTL_HTTP를 구성할 수 있는 계정을 사용하여 자율운영 AI 데이터베이스에 액세스합니다.

• 대상 HTTPS 끝점 및 해당 전체 인증서 체인(루트 + 중간 인증서)에 액세스합니다.

• orapki를 실행하여 Oracle Wallet을 생성 및 검증할 수 있는 워크스테이션입니다. orapki 유틸리티를 사용하려면 Oracle Database를 설치해야 합니다. 자세한 내용은 Installing Oracle Database를 참조하십시오.

고객 관리 전자 지갑 준비

이 단계에서는 자율운영 AI 데이터베이스에 업로드하기 전에 워크스테이션에서 전자 지갑을 생성하고 검증합니다.

고객 관리 전자 지갑(wallet) 획득 또는 생성

orapki를 사용하는 예제:

-- Create an SSL Wallet and load the Root CERTs using orapki utility
$ORACLE_HOME/bin/orapki wallet create -wallet /u01/web/wallet -pwd ********
$ORACLE_HOME/bin/orapki wallet add -wallet /u01/web/wallet -trusted_cert -cert MyWebServer.cer -pwd ********
-- Store the credentials in the SSL Wallet using mkstore utility
$ORACLE_HOME/bin/mkstore -wrl /u01/web/wallet -createCredential secret-from-the-wallet '[e-mail]'
********Enter wallet password: ********

전자 지갑 검증

$ORACLE_HOME/bin/orapki wallet display -wallet /u01/web/wallet

열려있는 모든 인증서를 볼 수 있습니다.

전자 지갑 업로드

고객 관리형 전자 지갑이 준비되면(필요한 자체 서명/루트/중간 인증서 포함) 전자 지갑 파일을 OCI(Oracle Cloud Infrastructure) Object Storage의 위치로 업로드합니다.

UTL_HTTP로 고객 관리 전자 지갑(wallet) 사용

이 섹션에서는 오브젝트 스토리지에서 전자 지갑을 다운로드하고, HTTPS 엔드포인트에 대한 네트워크 액세스를 허용한 다음, UTL_HTTP 패키지를 사용하여 HTTPS 호출을 수행하는 방법을 보여줍니다.

1. 오브젝트 스토리지 액세스에 대한 인증서 생성:

    BEGIN
    DBMS_CLOUD.CREATE_CREDENTIAL(credential_name => 'DEF_CRED_NAME',
    username => '[e-mail]',
    password => 'password'
    );
    END;
    /
   

   username 및 password에 대해 제공하는 값은 사용 중인 클라우드 오브젝트 스토리지 서비스에 따라 달라집니다. 이렇게 하면 고객 관리 전자 지갑이 상주하는 클라우드 오브젝트 스토리지에 액세스하는 데 사용하는 인증서가 생성됩니다.

2. 전자 지갑(wallet)의 디렉토리 객체를 생성(또는 재사용)합니다.

   기존 디렉토리를 사용하거나 전자 지갑 파일의 새 디렉토리를 생성합니다. 예:

    CREATE DIRECTORY wallet_dir AS 'directory_path_of_your_choice';
   

   디렉토리 생성에 대한 자세한 내용은 자율운영 AI 데이터베이스에서 디렉토리 생성을 참조하십시오.

3. 절대 디렉토리 경로를 가져옵니다.

   UTL_HTTP.SET_WALLET를 호출할 때 절대 디렉토리 경로가 필요합니다.

    SELECT DIRECTORY_NAME, DIRECTORY_PATH FROM DBA_DIRECTORIES WHERE DIRECTORY_NAME = '<wallet_dir>';
   

4. Object Storage에서 다음 디렉토리로 전자 지갑 파일을 다운로드합니다.

   DBMS_CLOUD.GET_OBJECT를 사용하여 전자 지갑 파일을 디렉토리에 복사합니다. 예:

    BEGIN
    DBMS_CLOUD.GET_OBJECT(
    credential_name => 'DEF_CRED_NAME',
    object_uri => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/cwallet.sso',
    directory_name => 'WALLET_DIR');
    END;
    /
   

   이 예에서 namespace-string은 Oracle Cloud Infrastructure 오브젝트 스토리지 네임스페이스이고 bucketname은 버킷 이름입니다. 자세한 내용은 객체 스토리지 네임스페이스 이해를 참조하십시오.

5. HTTPS 엔드포인트에 대한 아웃바운드 네트워크 액세스(ACL) 허용:

   데이터베이스 유저/스키마가 네트워크를 통해 대상 호스트에 도달할 수 있도록 허용해야 합니다.

     BEGIN
      DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
          host => 'api.example.com',
          ace  => xs$ace_type(
          privilege_list => xs$name_list('CONNECT','HTTP','RESOLVE'),
          principal_name => 'ADMIN',
          principal_type => xs_acl.ptype_db
      )
    );
    END;
    /
   

   Exadata Cloud@Customer 배치에서도 아래와 같이 프록시를 설정해야 합니다.

    BEGIN
      UTL_HTTP.SET_PROXY('www-proxy.us.oracle.com:80', 'oracle.com');
    END;
    /
   

6. UTL_HTTP를 사용하여 HTTPS 호출:

   간단한 GET 요청:

    DECLARE
    l_http_req UTL_HTTP.req;
    l_http_resp UTL_HTTP.resp;
    l_response VARCHAR2(32767);
   
    BEGIN
       utl_http.set_wallet('file:<absolute_directory_path_from_step_3>');
       l_http_req := UTL_HTTP.BEGIN_REQUEST('https://api.example.com/status');
       l_http_resp := UTL_HTTP.GET_RESPONSE(l_http_req);
       LOOP UTL_HTTP.READ_LINE(l_http_resp, l_response, TRUE);
           DBMS_OUTPUT.PUT_LINE(l_response);
       END LOOP;
       UTL_HTTP.END_RESPONSE(l_http_resp);
    END;
    /
   

   JSON 페이로드가 있는 POST 요청:

    DECLARE
      l_req UTL_HTTP.req;
      l_resp UTL_HTTP.resp;
      l_line VARCHAR2(32767);
    BEGIN
      utl_http.set_wallet('file:<absolute_directory_path_from_step_3>');
      l_req := UTL_HTTP.BEGIN_REQUEST( url => 'https://api.example.com/data', method => 'POST' );
      UTL_HTTP.SET_HEADER(l_req, 'Content-Type', 'application/json');
      UTL_HTTP.WRITE_TEXT(l_req, '{"key":"value"}');
      l_resp := UTL_HTTP.GET_RESPONSE(l_req);
      LOOP UTL_HTTP.READ_LINE(l_resp, l_line, TRUE);
        DBMS_OUTPUT.PUT_LINE(l_line);
      END LOOP;
      UTL_HTTP.END_RESPONSE(l_resp);
     END;
     /
   

일반적인 오류 해결:

인증서 체인 오류

오류: ORA-29024: Certificate validation failure

• 루트 및 중간 인증서가 누락될 수 있습니다.

• 대상 끝점이 새 CA를 사용하고 있을 수 있습니다. 전체 인증서 체인을 다시 다운로드하고 전자 지갑을 재생성하십시오.

전자 지갑 경로 오류

ORA-28759: Failure to open file

• SET_WALLET에 잘못된 전자 지갑 경로가 있습니다.

• file: 접두어가 누락되었습니다.

• 업로드된 전자 지갑 파일이 디렉토리에 없습니다.

핸드쉐이크 Failure

ORA-24263 / ORA-29005

• TLS 프로토콜이 일치하지 않습니다.

• 인증서가 잘못되었거나 만료되었습니다.

• 끝점이 TLS > 1.2를 강제 적용합니다.

SMTP(스케줄러 전자 메일 통지)에 고객 관리 전자 지갑 사용

이 절에서는 고객 관리 전자 지갑과 함께 TLS(STARTTLS)를 통한 SMTP 서버를 사용하도록 스케줄러 전자 메일 통지를 구성하는 방법을 보여줍니다.

시작하기 전에 이미 고객 관리 전자 지갑(로컬로 생성, 검증 및 오브젝트 스토리지에 업로드)을 준비했는지 확인하십시오. 자세한 내용은 고객 관리 전자 지갑 준비를 참조하십시오.

스케줄러 전자 메일 서버에서 고객 관리 전자 지갑을 사용하려면 다음과 같이 하십시오.

1. 오브젝트 스토리지 액세스에 대한 인증서 생성:

   DBMS_CLOUD.CREATE_CREDENTIAL를 사용하여 Cloud Object Storage에 액세스할 수 있는 인증서를 생성할 수 있습니다.

    BEGIN
      DBMS_CLOUD.CREATE_CREDENTIAL(
        credential_name => 'DEF_CRED_NAME',
        username => '[e-mail]',
        password => 'password'
    );
    END;
    /
   

   username 및 password에 대해 제공하는 값은 사용 중인 클라우드 오브젝트 스토리지 서비스에 따라 달라집니다. 이렇게 하면 고객 관리 전자 지갑이 상주하는 클라우드 오브젝트 스토리지에 액세스하는 데 사용하는 인증서가 생성됩니다.

2. 전자 지갑(wallet)의 디렉토리 객체를 생성(또는 재사용)합니다.

   기존 디렉토리를 사용하거나 전자 지갑 파일의 새 디렉토리를 생성합니다. 예:

    CREATE DIRECTORY wallet_dir AS 'directory_path_of_your_choice';
   

   디렉토리 생성에 대한 자세한 내용은 자율운영 AI 데이터베이스에서 디렉토리 생성을 참조하십시오.

3. 절대 디렉토리 경로를 가져옵니다.

   UTL_HTTP.SET_WALLET를 호출할 때 절대 디렉토리 경로가 필요합니다.

    SELECT DIRECTORY_NAME, DIRECTORY_PATH FROM DBA_DIRECTORIES WHERE DIRECTORY_NAME = '<wallet_dir>';
   

4. Object Storage에서 다음 디렉토리로 전자 지갑 파일을 다운로드합니다.

   DBMS_CLOUD.GET_OBJECT를 사용하여 전자 지갑 파일을 디렉토리에 복사합니다. 예:

    BEGIN
      DBMS_CLOUD.GET_OBJECT(
        credential_name => 'DEF_CRED_NAME',
        object_uri => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/cwallet.sso',
        directory_name => 'WALLET_DIR');
    END;
    /
   

   이 예에서 namespace-string은 Oracle Cloud Infrastructure 오브젝트 스토리지 네임스페이스이고 bucketname은 버킷 이름입니다. 자세한 내용은 객체 스토리지 네임스페이스 이해를 참조하십시오.

5. 스케줄러 전자 메일 구성(SMTP + STARTTLS):

   스케줄러 작업 통지를 위해 SMTP 전자메일을 전송하도록 스케줄러를 설정하는 명령을 실행합니다.

    EXEC DBMS_CLOUD.CREATE_CREDENTIAL('EMAIL_CRED', '<user_ocid>', '<password>');
    GRANT EXECUTE ON admin.EMAIL_CRED TO sys;
    EXEC DBMS_SCHEDULER.SET_SCHEDULER_ATTRIBUTE(
          'EMAIL_SERVER',
          'smtp.email.us-ashburn-1.oci.oraclecloud.com:587'
    );
    EXEC DBMS_SCHEDULER.SET_SCHEDULER_ATTRIBUTE(
            'EMAIL_SERVER_CREDENTIAL',
            'EMAIL_CRED'
    );
    EXEC DBMS_SCHEDULER.SET_SCHEDULER_ATTRIBUTE(
            'EMAIL_SERVER_ENCRYPTION',
            'STARTTLS'
    );
   

   이 명령은 다음을 수행합니다.

   • 스케줄러 SMTP 끝점 설정(EMAIL_SERVER)

   • EMAIL_CRED에 SMTP 로그인 세부 정보를 저장하고 스케줄러를 가리킵니다.

   • STARTTLS를 사용하여 TLS 암호화를 사용으로 설정합니다.

   자세한 내용은 SET_SCHEDULER_ATTRIBUTE 프로시저를 참조하십시오.

6. 전자 지갑 암호에 대한 인증서를 생성합니다.

   고객 관리 전자 지갑의 비밀번호를 저장할 인증서를 생성합니다.

    BEGIN
      DBMS_CLOUD.CREATE_CREDENTIAL(
        credential_name => 'WALLET_CRED',
        username        => 'any_user',
        password        => 'password'
      );
    END;
    /
   

   그러면 다음 단계에서 고객 관리 전자 지갑(Wallet)의 암호를 제공하는 데 사용할 인증서가 생성됩니다.

7. Scheduler에게 전자 지갑의 위치 및 잠금 해제 방법을 알려 줍니다.

   스케줄러 전자 지갑 디렉토리 및 전자 지갑 인증서를 설정합니다.

    BEGIN
      DBMS_SCHEDULER.SET_SCHEDULER_ATTRIBUTE(
        'EMAIL_SERVER_WALLET_DIRECTORY',
        'WALLET_DIR'
      );
   
      DBMS_SCHEDULER.SET_SCHEDULER_ATTRIBUTE(
        'EMAIL_SERVER_WALLET_CREDENTIAL',
        'ADMIN.WALLET_CRED'
      );
    END;
    /
   

8. Scheduler 전자 메일 구성을 확인합니다.

   DBA_SCHEDULER_GLOBAL_ATTRIBUTE 뷰를 질의하여 이전 단계에서 설정한 값을 확인합니다.

    SELECT attribute_name, value
    FROM DBA_SCHEDULER_GLOBAL_ATTRIBUTE
    WHERE attribute_name LIKE 'EMAIL_SERVER%' ORDER BY 1, 2;
   

    ATTRIBUTE_NAME                 VALUE
   
    ------------------------------ -----------------------------------------------
    EMAIL_SERVER                   smtp.email.us-ashburn-1.oci.oraclecloud.com:587
    EMAIL_SERVER_CREDENTIAL        "ADMIN"."EMAIL_CRED"
    EMAIL_SERVER_ENCRYPTION        STARTTLS
    EMAIL_SERVER_WALLET_CREDENTIAL "ADMIN"."WALLET_CRED"
    EMAIL_SERVER_WALLET_DIRECTORY  "WALLET_DIR"
   

참조

유용한 orapki 명령:

orapki wallet display -wallet <path> orapki wallet add -wallet <path>
-trusted_cert -cert <cert-file> orapki wallet create -wallet <path> -auto_login

예제 전자 지갑 디렉토리 구조:

cmw_wallet/
- ewallet.p12
- cwallet.sso