外部プロシージャをSQL関数として起動

データベース内でPL/SQLを使用して外部プロシージャを起動するステップを示します。

外部プロシージャの概要

外部プロシージャは、第3世代言語で記述されたファンクションであり、PL/SQLルーチンまたはファンクションと同様に、PL/SQLまたはSQL内からコールできます。

外部プロシージャは、再利用性、効率性およびモジュール性を促進します。他の言語で記述された既存の動的リンク・ライブラリ(DLL)は、PL/SQLプログラムからコールできます。DLLは必要な場合にのみロードされ、呼び出しプログラムに影響を与えずに拡張できます。

また、外部プロシージャを使用すると、SQLトランザクション処理に適したPL/SQLよりも、第3世代の言語によって特定のタスクがより効率的に実行されるため、パフォーマンスが向上します。

外部プロシージャは、次の場合に役立ちます。

• 科学的問題や工学的問題の解決

• データの分析中

• デバイスやプロセスのリアルタイム制御

詳細は、外部プロシージャとはを参照してください。

Autonomous AI Databaseでの外部プロシージャの使用について

ユーザー定義関数を使用して、Autonomous AI Databaseで外部プロシージャを起動して使用できます。

Autonomous AI Databaseインスタンスには外部プロシージャをインストールしません。外部プロシージャを使用するには、プロシージャがOracle Cloud Infrastructure Virtual Cloud Network (VCN)で実行されているVMでリモートでホストされます。

外部プロシージャは、Autonomous AI Databaseがプライベート・エンドポイント上にある場合にのみサポートされます。EXTPROCエージェント・インスタンスはプライベート・サブネットでホストされ、Autonomous AI Databaseはリバース接続エンドポイント(RCE)を介してEXTPROCエージェントにアクセスします。

ノート

ノート: Autonomous AI Databaseでは、C言語の外部プロシージャのみがサポートされます。

外部プロシージャは次のものを使用してデプロイされます。

• Oracle Cloud Infrastructure (OCI)マーケットプレイス・スタックの一部としてインストールおよび構成されたEXTPROCエージェントを含むOracle提供のコンテナ・イメージ。

  EXTPROCエージェント・インスタンスは、Oracle Cloud Infrastructure Virtual Cloud Network (VCN)で実行されているVMでリモートにホストされます。Autonomous AI DatabaseとEXTPROCエージェント・インスタンス間のセキュアな通信は、プライベート・エンドポイントで実行されているAutonomous AI DatabaseインスタンスからEXTPROCエージェント・インスタンスへのトラフィックが許可されるようにネットワーク・セキュリティ・グループ(NSG)ルールを設定することで保証されます。

  EXTPROCエージェント・イメージは、ポート16000で外部プロシージャをホストおよび実行するように事前構成されています。

• ライブラリを作成し、外部ファンクションおよびプロシージャを登録および起動するためのPL/SQLプロシージャ。

  詳細は、DBMS_CLOUD_FUNCTIONパッケージを参照してください。

Autonomous AI Databaseで外部プロシージャを起動するには、次のステップに従います:

• Cプロシージャを定義します。「Cプロシージャの定義」を参照してください。

• 共有オブジェクト(.soファイル)ライブラリを作成します。Create a Shared Library (.so) Fileを参照してください。

• Autonomous AI DatabaseのEXTPROCスタック・アプリケーションを起動します。OCI Marketplace EXTPROC Stackアプリケーションの取得を参照してください。

• Oracle Autonomous AI Database EXTPROCエージェントをプロビジョニングおよび構成します。詳細は、「EXTPROCエージェント・アプリケーションのスタックの作成」を参照してください。

• EXTPROCエージェント・インスタンスに接続するようにAutonomous AI Databaseを構成します。詳細は、「EXTPROCエージェント・インスタンスへのセキュアな接続を作成するためのWalletのアップロード」を参照してください。

• DBMS_CLOUD_FUNCTION.CREATE_CATALOGを使用してリモート・ライブラリを作成します。詳細は、「SQLファンクションとして外部プロシージャを起動するステップ」を参照してください。

• 前のステップで作成したユーザー定義関数を使用します。詳細は、「SQLファンクションとして外部プロシージャを起動するステップ」を参照してください。

Cプロシージャの定義

これらのプロトタイプのいずれかを使用してCプロシージャを定義します。

• Kernighan & Ritchieスタイル・プロトタイプ。たとえば:

  void UpdateSalary(x)
   float x;
  ...

• 全角ではない数値データ型(float、short、charなど)以外のISO/ANSIプロトタイプ。次に例を示します。

  void UpdateSalary(double x)
  ...

• デフォルトの引数格上げによってサイズの変わらないその他のデータ型。

  デフォルトの引数格上げによってサイズが変わる定義の例は次のとおりです。

  void UpdateSalary(float x)
  ...

共有ライブラリ(.so)ファイルの作成

共有オブジェクト(.soファイル)ライブラリを作成します。共有オブジェクトライブラリには、前の手順で定義したCプロシージャー(外部手順)が含まれています。

次のコマンドを使用して、共有オブジェクト・ライブラリを生成します。

gcc -I/u01/app/oracle/extproc_libs/ -shared -fPIC -o extproc.so UpdateSalary.c

これにより、共有オブジェクト(.so)、extproc.soライブラリが作成されます。前のステップで定義したUpdateSalaryプロシージャは、extproc.soライブラリに含まれています。共有オブジェクト(.so)ライブラリは、実行時に動的にロードされます。

OCI Marketplace EXTPROC Stackアプリケーションの入手

OCI MarketplaceのEXTPROCスタック・アプリケーションを取得するステップを示します。

次のステップを実行します:

1. OCIコンソール(http://cloud.oracle.com)にサインインします。詳細は、Oracle Cloud Infrastructure Consoleへのサインインを参照してください。

2. Oracle Cloud Infrastructureの左側のナビゲーション・メニューから「Marketplace」をクリックし、「Marketplace」で「すべてのアプリケーション」をクリックします。これにより、「Marketplace All Applications」ダッシュボードに移動します。

3. 検索フィールドにEXTPROCと入力し、「検索」をクリックします。

4. 「タイプ: スタック」のEXTPROCウィジェットをクリックします。

   

   図adbs_extproc_application.pngの説明

これにより、Oracle Autonomous AI Database EXTPROC Agentの詳細ページが表示されます。

EXTPROCスタック・アプリケーションの起動

EXTPROCアプリケーションの詳細ページからEXTPROCスタック・アプリケーションを起動します。

1. Oracle Autonomous AI DatabaseのEXTPROCエージェント・ページの「タイプ・スタック」で、次を実行します:

   • 「バージョン」ドロップダウン・リストから、スタックのパッケージのバージョンを選択します。デフォルトでは、メニューには最新バージョンが表示されます。

   • 「コンパートメント」ドロップダウン・リストから、インスタンスを起動するコンパートメントの名前を選択します。

     ノート
     
     ノート:選択したコンパートメントでインスタンスを起動する権限がない場合、インスタンスはルート・コンパートメントで起動されます。

   • 「Oracle標準条件および制約事項を確認した上でこれに同意」チェックボックスを選択します。

2. 「スタックの起動」をクリックします。

   

   図adb_launch_stack.pngの説明

これにより、EXTPROCエージェントのスタックを作成できる「スタックの作成」ページが表示されます。

EXTPROCエージェント・アプリケーションのスタックの作成

EXTPROCインスタンスのスタックを作成するステップを示します。

スタックの作成ウィザードで、次のステップを実行します。

1. 「スタック情報」ページで、必要に応じて次の情報を確認および編集します。

   • スタック情報

   • カスタム・プロバイダ

   • 名前(オプション): デフォルトのスタック名を編集できます。機密情報を入力しないでください。

   • 説明(オプション): デフォルトのスタックの説明を編集できます。機密情報を入力しないでください。

   • コンパートメントに作成

   • Terraformのバージョン

   • タグ: タグをスタックに割り当てるには、次を指定します。

     • タグ・ネームスペース: 定義済のタグを追加するには、既存のネームスペースを選択します。free-fromタグを追加するには、値を空白のままにします。

     • タグ・キー: 定義済のタグを追加するには、既存のタグ・キーを選択します。フリーフォーム・タグを追加するには、必要なキー名を入力します。

     • タグ値: 必要なタグ値を入力します。

     タグの追加: 別のタグを追加する場合にクリックします。

     タグ付けの詳細は、リソース・タグを参照してください。

     

     図adbs_extproc_createstack_updated.pngの説明

2. 「次へ」をクリックします。

   これにより、「変数の構成」ページに移動し、この実行プランの適用ジョブの実行時にスタックが作成するインフラストラクチャ・リソースの変数を構成できます。

3. 「変数の構成」ページで、EXTPROCエージェントの構成、ネットワーク構成およびコンピュート構成の各領域に情報を入力します。

   1. 「EXTPROCエージェントの構成」領域に情報を指定します。

      • 外部ライブラリ: Autonomous AI Databaseから起動できるようにするライブラリのリストをカンマ(、)で区切って指定します。たとえば、extproc.so、extproc1.soです。

        スタックを作成した後、ライブラリをEXTPROCエージェントVMの/u01/app/oracle/extproc_libsディレクトリにコピーする必要があります。

      • Walletパスワード:ウォレット・パスワードを指定します。

        Autonomous AI DatabaseとEXTPROCエージェントVMの間の相互TLS認証のために、ウォレットおよび自己署名証明書が生成されます。ウォレットは/u01/app/oracle/extproc_walletディレクトリに作成されます。

        ノート
        
        ノート:ウォレットの作成後は、ウォレット・パスワードを変更できません。

      

      図adbs_configure_var_extproc_agent.pngの説明

   2. 「Network Configuration」領域に情報を指定します。

      • コンパートメント: ドロップダウン・リストから、構成を配置するコンパートメントを選択します。

      • ネットワーク戦略: ドロップダウン・リストから、「新規VCNおよびサブネットの作成」または「既存のVCNおよびサブネットの使用」のいずれかのオプションを選択します。

        • 新規VCNおよびサブネットの作成: プライベート・エンドポイントがAutonomous AIデータベースに対して構成されていない場合は、このオプションを選択します。これにより、セキュリティ・ルールが事前構成されたパブリックおよびプライベート・サブネットを持つ新しいVCNが作成されます。

          このオプションを選択すると、「構成戦略」ドロップダウン・リストもページに表示されます。

          「構成戦略」ドロップダウン・リストから「推奨構成の使用」を選択します。

          

          図adb_extproc_network_config.pngの説明

        • 既存のVCNおよびサブネットの使用: 既存のVCNを使用してEXTPROCエージェントを作成するには、このオプションを選択します。これにより、指定されたサブネットにEXTPROCエージェント・インスタンスが作成されます。

          このオプションを選択する場合は、既存のVCNおよびサブネットに次の情報を指定します:

          • 「Virtual Cloud Network」で、次の手順を実行します。

            「既存のVCN」ドロップダウン・リストから、既存のVCNを選択します。指定されたVCNが存在しない場合は、新しいVCNが作成されます。

          • 「EXTPROC Subnet」で、次の手順を実行します。

            「既存のサブネット」ドロップダウン・リストから、既存のサブネットを選択します。

            既存のVCNおよびサブネットの使用を選択する場合は、EXTPROCエージェント・インスタンスのポート16000のイングレス・ルールを追加します。また、パブリック・サブネットにエグレス・ルールを追加します。

            詳細は、プライベート・エンドポイントを使用したネットワーク・アクセスの構成を参照してください。

          

          図adbs_extproc_network_configuration_existing_vcn.pngの説明

      • EXTPROCエージェント・アクセス・タイプ: ドロップダウン・リストから次のいずれかのオプションを選択します。

        • VCN内の特定のADB-Sプライベート・エンドポイント・データベースからのセキュア・アクセス: Virtual Cloud Network (VCN)内の指定されたプライベート・エンドポイントIPのみをEXTPROCエージェントに接続できるようにするには、このオプションを選択します。

          このオプションを選択した場合、次のステップで許可されるプライベート・エンドポイントIPアドレスのリストを指定します。

        • VCN内のすべてのADB-Sプライベート・エンドポイント・データベースからのセキュアなアクセス: Virtual Cloud Network (VCN)内のプライベート・エンドポイントがEXTPROCエージェントに接続できるようにするには、このオプションを選択します。

      • プライベート・Endpoint IPアドレス

        プライベート・エンドポイントIPアドレス変数に、カンマ(、)で区切られたプライベート・エンドポイントIPアドレスのリストを指定します。たとえば、10.0.0.0、10.0.0.1です。

        ノート
        
        ノート:このフィールドは、「EXTPROCエージェント・アクセス・タイプ」で「VCN内の特定のADB-Sプライベート・エンドポイント・データベースからのセキュア・アクセス」を選択した場合にのみ表示されます。

   3. コンピュート構成情報を指定します。

      • コンパートメント: スタックを作成するコンパートメントを選択します。

      • シェイプ: EXTPROCエージェント・インスタンスのワークロード要件に基づいてシェイプを選択します。シェイプによって、EXTPROCエージェント・インスタンスに割り当てられるリソースが決まります。

      • OCPU数: EXTPROCエージェント・インスタンスに割り当てるOCPU数を選択します。

      • メモリー・サイズ(GB): EXTPROCエージェント・インスタンスに割り当てるメモリー量をギガバイト(GB)で選択します。

      • SSHキーの追加: SSH公開キーをアップロードするか、公開キーを貼り付けます。次のいずれかのオプションを選択します:

        • SSHキー・ファイルを選択: キー・ペアの公開キー部分をアップロードします。アップロードするキー・ファイルを参照して選択するか、ボックスにファイルをドラッグ・アンド・ドロップします。

        • SSHキーの貼付け: ボックスにキー・ペアの秘密キー部分を貼り付けます。

        

        図adbs_extproc_compute_config.pngの説明

4. 「次へ」をクリックします。

   これにより、「確認」ページが表示されます。

5. 「確認」ページで、次のステップを実行します。

   1. 構成変数の検証。

   2. 「作成されたスタックで適用を実行しますか。」の下の「適用の実行」チェック・ボックスを選択します。

   3. 「作成」をクリックします。

   ノート
   
   ノート:この領域には、デフォルト値または変更されていない変数は表示されません。

   

   図adbs_extproc_review.pngの説明

   リソース・マネージャは、適用ジョブを実行して、それに応じてスタック・リソースを作成します。これにより、「ジョブ詳細」ページに移動し、ジョブの状態が「受入れ済」になります。適用ジョブが開始されると、ステータスは「進行中」に更新されます。

   

   図adbs_extproc_job_details.pngの説明

ノート

ノート:スタックの一部として作成されたインスタンスに接続するために必要な情報は、「アプリケーション情報」タブにあります。

WalletのアップロードによるEXTPROCエージェント・インスタンスへのセキュアな接続の作成

自己署名ウォレットは、EXTPROCエージェント・アプリケーションの作成の一部として作成されます。このウォレットを使用すると、Extrpocエージェント・インスタンスにアクセスできます。

EXTPROCエージェント・インスタンスでリモート・プロシージャを実行するには、Autonomous AI DatabaseとEXTPROCエージェントが相互Transport Layer Security (mTLS)を使用して接続します。相互Transport Layer Security (mTLS)を使用する場合、クライアントは、標準のTLS 1.2を信頼できるクライアント認証局(CA)証明書とともに使用して、TCPS (セキュアTCP)データベース接続を介して接続します。詳細は、Autonomous AIデータベース・インスタンスへの接続についてを参照してください。

ノート

ノート:認証局(CA)によって発行された公開証明書を取得して使用することもできます。

前提条件として、EXTPROCが実行されているVMの/u01/app/oracle/extproc_walletディレクトリからウォレットをオブジェクト・ストレージにエクスポートする必要があります。

次のステップに従って、Autonomous AI Databaseにウォレットをアップロードします:

1. Autonomous AI Databaseのオブジェクト・ストレージから、EXTPROCエージェント・インスタンスの証明書を含むウォレットcwallet.ssoをインポートします。ウォレット・ファイルについては、次の点に注意してください。

   • ウォレット・ファイルは、データベース・ユーザーIDおよびパスワードとともに、EXTPROCエージェント・インスタンスへのアクセスを提供します。ウォレット・ファイルを安全な場所に格納し、認可されたユーザーのみと共有します。

   • ウォレット・ファイルの名前を変更しないでください。オブジェクト・ストレージのウォレット・ファイルには、cwallet.ssoという名前を付ける必要があります。

2. ウォレット・ファイルcwallet.ssoを格納するオブジェクト・ストレージにアクセスするための資格証明を作成します。様々なオブジェクト・ストレージ・サービスのusernameおよびpasswordパラメータの詳細は、「CREATE_CREDENTIALプロシージャ」を参照してください。

   リソース・プリンシパル資格証明を有効にする場合、Oracle Cloud Infrastructureオブジェクト・ストアにアクセスするための資格証明の作成は必要ありません。詳細は、「リソース・プリンシパルを使用したOracle Cloud Infrastructureリソースへのアクセスについて」を参照してください。

3. ウォレット・ファイルcwallet.ssoのディレクトリをAutonomous AI Databaseに作成します。

   CREATE DIRECTORY WALLET_DIR AS 'directory_location';

   ディレクトリの作成の詳細は、Autonomous AI Databaseでのディレクトリの作成を参照してください。

4. ウォレットのアップロードには、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 Object Storageネームスペースで、bucketnameはバケット名です。詳細は、「オブジェクト・ストレージ・ネームスペース」を参照してください。

   ウォレットは、前のステップのWALLET_DIRで作成したディレクトリにコピーされます。EXTPROCエージェント・インスタンスに接続できるウォレットが、Autonomous AI Databaseインスタンスで使用できるようになりました。

SQLファンクションとして外部プロシージャを起動するステップ

SQLファンクションとして外部プロシージャを起動するステップを示します。

OCI MarketplaceのEXTPROCスタック・アプリケーションを起動し、外部プロシージャを実行するように構成した後、それぞれの外部プロシージャを参照してコールするSQLラッパー関数のライブラリを作成します。

前提条件として、ホワイトリスト・ライブラリをEXTPROC VMの/u01/app/oracle/extproc_libsディレクトリにコピーする必要があります。

Autonomous AI Databaseでライブラリを作成し、Cルーチンをライブラリの外部プロシージャとして登録するには、次のステップに従います:

1. ライブラリを作成します。

   外部プロシージャは、ライブラリに格納されているC言語ルーチンです。Autonomous AI Databaseを使用して外部プロシージャを起動するには、ライブラリを作成します。

   DBMS_CLOUD_FUNCTION.CREATE_CATALOGを実行してライブラリを作成します。次に例を示します。

   BEGIN
       DBMS_CLOUD_FUNCTION.CREATE_CATALOG (
           library_name               => 'demolib',
           library_listener_url       => '*remote_extproc_hostname*:16000',
           library_wallet_dir_name    => 'wallet_dir',
           library_ssl_server_cert_dn => 'CN=*VM Hostname*',
           library_remote_path        => '/u01/app/oracle/extproc_libs/*library name*'
   );
   END;
   /

   これにより、Autonomous AI Databaseにdemolibライブラリが作成され、データベースに動的リンク・ライブラリが登録されます。EXTPROCエージェント・インスタンスは、ポート16000で外部プロシージャをホストするように事前構成されています。

   詳細は、CREATE_CATALOGプロシージャを参照してください。

   DBA_CLOUD_FUNCTION_CATALOGビュー・ビューおよびUSER_CLOUD_FUNCTION_CATALOGビュー・ビューを問い合せて、データベース内のすべてのカタログおよびライブラリのリストを取得します。

   USER_CLOUD_FUNCTION_ERRORSビュー・ビューを問い合せて、リモート・ライブラリの場所への接続検証中に生成されたエラーをリストします。

2. 関数を作成します。

   たとえば:

   CREATE OR REPLACE FUNCTION ftest(
         x VARCHAR2,
         y VARCHAR2)
   RETURN VARCHAR2 AS LANGUAGE C
         LIBRARY demolib
         NAME "demolibfunction"
         PARAMETERS(
             x STRING,
             y STRING);
   /

3. DROP_CATALOGプロシージャを使用して、既存のライブラリを削除できます。次に例を示します。

   BEGIN
       DBMS_CLOUD_FUNCTION.DROP_CATALOG (
         LIBRARY_NAME  => 'demolib'
     );
   END;
   /

   これにより、DEMOLIBライブラリが削除されます。

   詳細は、DROP_CATALOGプロシージャを参照してください。