SQLファンクションとしての外部プロシージャの起動

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

外部プロシージャの概要
外部プロシージャは、第3世代の言語で記述されたファンクションで、PL/SQLまたはSQL内からPL/SQLルーチンまたはファンクションであるかのようにコールできます。
Autonomous Databaseでの外部プロシージャの使用について
ユーザー定義関数を使用して、Autonomous Databaseの外部プロシージャを起動して使用できます。
Cプロシージャの定義
これらのプロトタイプのいずれかを使用して、Cプロシージャを定義します。
共有ライブラリ(.so)ファイルの作成
共有オブジェクト(.soファイル)ライブラリを作成します。共有オブジェクト・ライブラリには、前のステップで定義したCプロシージャ(外部プロシージャ)が含まれています。
OCI Marketplace EXTPROCスタック・アプリケーションの入手
OCI MarketplaceのEXTPROCスタック・アプリケーションを取得するステップを示します。
EXTPROCスタック・アプリケーションの起動
「EXTPROCアプリケーション詳細」ページからEXTPROCスタック・アプリケーションを起動します。
EXTPROCエージェント・アプリケーションのスタックの作成
EXTPROCインスタンスのスタックを作成するステップを示します。
WalletのアップロードによるEXTPROCエージェント・インスタンスへのセキュアな接続の作成
自己署名ウォレットは、EXTPROCエージェント・アプリケーションの作成の一部として作成されます。このウォレットを使用すると、Extrpocエージェント・インスタンスにアクセスできます。
外部プロシージャをSQLファンクションとして起動するステップ
外部プロシージャをSQLファンクションとして起動するステップを示します。

外部プロシージャの概要

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

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

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

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

科学的問題や工学的問題の解決
データの分析
デバイスやプロセスのリアルタイム制御

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

親トピック: SQLファンクションとしての外部プロシージャの起動

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

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

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

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

ノート:

Autonomous Databaseは、C言語の外部プロシージャのみをサポートします。

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

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

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

EXTPROCエージェント・イメージは、ポート16000で外部プロシージャをホストおよび実行するように事前構成されています。
ライブラリを作成し、外部ファンクションおよびプロシージャを登録および起動するためのPL/SQLプロシージャ。

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

次のステップに従って、Autonomous Databaseで外部プロシージャを起動します:

Cプロシージャを定義します。「Cプロシージャの定義」を参照してください。
共有オブジェクト(.soファイル)ライブラリを作成します。「共有ライブラリ(.so)ファイルの作成」を参照してください。
Autonomous Database EXTPROCスタック・アプリケーションを起動します。「OCI Marketplace EXTPROCスタック・アプリケーションの入手」を参照してください。
Oracle Autonomous Database EXTPROCエージェントをプロビジョニングおよび構成します。詳細については、「EXTPROCエージェント・アプリケーションのスタックの作成」を参照してください。
EXTPROCエージェント・インスタンスに接続するようにAutonomous Databaseを構成します。詳細については、「WalletのアップロードによるEXTPROCエージェント・インスタンスへのセキュアな接続の作成」を参照してください。
DBMS_CLOUD_FUNCTION.CREATE_CATALOGを使用してリモート・ライブラリを作成します。詳細については、「外部プロシージャをSQLファンクションとして起動するステップ」を参照してください。
前のステップで作成したユーザー定義関数を使用します。詳細については、「外部プロシージャをSQLファンクションとして起動するステップ」を参照してください。

親トピック: SQLファンクションとしての外部プロシージャの起動

Cプロシージャの定義

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

Kernighan & Ritchieスタイルのプロトタイプ。たとえば:
```
void UpdateSalary(x)
 float x;
...
```
全幅より小さい数値データ型以外のISO/ANSIプロトタイプ(float, short, charなど)。たとえば:
```
void UpdateSalary(double x)
...
```
デフォルトの引数格上げによってサイズの変わらないその他のデータ型。

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

親トピック: SQLファンクションとしての外部プロシージャの起動

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

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

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

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

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

親トピック: SQLファンクションとしての外部プロシージャの起動

OCI Marketplace EXTPROCスタック・アプリケーションの入手

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

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

OCIコンソール(http://cloud.oracle.com)にサインインします。詳細については、「Oracle Cloud Infrastructureコンソールにサインイン」を参照してください。
Oracle Cloud Infrastructure左側のナビゲーション・メニューから、「マーケットプレイス」をクリックし、「マーケットプレイス」の下の「すべてのアプリケーション」をクリックします。これにより、Marketplaceの「すべてのアプリケーション」ダッシュボードに移動します。
検索フィールドにEXTPROCと入力し、searchをクリックします。
「タイプ: スタック」のEXTPROCウィジェットをクリックします。

図adbs_extproc_application.pngの説明

これにより、「Oracle Autonomous Database EXTPROCエージェント」の詳細ページが表示されます。

親トピック: SQLファンクションとしての外部プロシージャの起動

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

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

「Oracle Autonomous Database EXTPROC Agent」ページの「タイプ・スタック」で、次の手順を実行します:
- 「バージョン」ドロップダウン・リストから、スタックのパッケージ・バージョンを選択します。デフォルトでは、メニューには最新バージョンが表示されます。
- 「コンパートメント」ドロップダウン・リストから、インスタンスを起動するコンパートメントの名前を選択します。
  
  ノート:
  選択したコンパートメントでインスタンスを起動する権限がない場合、インスタンスはルート・コンパートメントで起動されます。
- 「Oracle Standard Terms and Restrictionsを確認して同意」チェックボックスを選択します。
「スタックを起動」をクリックします。

図adb_launch_stack.pngの説明

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

親トピック: SQLファンクションとしての外部プロシージャの起動

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

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

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

スタック情報ページで、必要に応じて次の情報を確認および編集します:
- スタック情報
- カスタム・プロバイダ
- 名前(オプション): デフォルトのスタック名を編集できます。機密情報の入力は避けてください。
- 説明(オプション): デフォルトのスタック記述を編集できます。機密情報の入力は避けてください。
- コンパートメントに作成
- Terraformのバージョン
- タグ: タグをスタックに割り当てるには、次を指定します。
  - タグ・ネームスペース: 定義済タグを追加するには、既存のネームスペースを選択します。フリー・ソース・タグを追加するには、値を空白のままにします。
  - タグ・キー: 定義済タグを追加するには、既存のタグ・キーを選択します。フリーフォーム・タグを追加するには、必要なキー名を入力します。
  - タグ値: 必要なタグ値を入力します。
  タグを追加: 別のタグを追加する場合にクリックします。
  
  タグ付けの詳細は、「リソース・タグ」を参照してください。
図adbs_extproc_createstack_updated.pngの説明
「次へ」をクリックします。
これにより、「変数の構成」ページに移動します。このページでは、この実行計画の適用ジョブの実行時にスタックによって作成されるインフラストラクチャ・リソースの変数を構成できます。
「変数の構成」ページで、領域に情報を入力: EXTPROCエージェントの構成、ネットワーク構成、およびコンピュート構成です。
1. 「EXTPROCエージェントの構成」領域に情報を指定します。
  - 外部ライブラリ: Autonomous Databaseから起動できるようにするライブラリのリストをカンマ(、)で区切って指定します。たとえば、extproc.so、extproc1.soなどです。
    
    スタックを作成した後、ライブラリをEXTPROCエージェントVMの/u01/app/oracle/extproc_libsディレクトリにコピーする必要があります。
  - Walletパスワード: ウォレット・パスワードを指定します。
    
    ウォレットと自己署名証明書は、Autonomous DatabaseとEXTPROCエージェントVMの間の相互TLS認証用に生成されます。ウォレットは、/u01/app/oracle/extproc_walletディレクトリに作成されます。
    
    ノート:
    ウォレットの作成後は、ウォレット・パスワードを変更できません。
  図adbs_configure_var_extproc_agent.pngの説明
2. 「ネットワーク構成」領域に情報を指定します。
  - コンパートメント: ドロップダウン・リストから、構成を配置するコンパートメントを選択します。
  - ネットワーク戦略: ドロップダウン・リストから、新規VCNおよびサブネットの作成または既存のVCNおよびサブネットの使用のいずれかのオプションを選択します。
    - 新規VCNおよびサブネットの作成: プライベート・エンドポイントがAutonomous Databaseに対して構成されていない場合は、このオプションを選択します。これにより、セキュリティ・ルールが事前構成されたパブリック・サブネットとプライベート・サブネットを持つ新しいVCNが作成されます。
      
      このオプションを選択すると、ページには「構成戦略」ドロップダウン・リストも表示されます:
      
      「構成戦略」ドロップダウン・リストから「推奨構成の使用」を選択します。
      
      図adb_extproc_network_config.pngの説明
    - 既存のVCNおよびサブネットの使用: 既存のVCNを使用してEXTPROCエージェントを作成するには、このオプションを選択します。これにより、指定されたサブネットにEXTPROCエージェント・インスタンスが作成されます。
      
      このオプションを選択する場合は、既存のVCNおよびサブネットについて次の情報を指定します:
      
      仮想クラウド・ネットワークの下で:
      
      「既存のVCN」ドロップダウン・リストから、既存のVCNを選択します。指定されたVCNが存在しない場合は、新しいVCNが作成されます。
      
      EXTPROCサブネットの下で:
      
      「既存のサブネット」ドロップダウン・リストから、既存のサブネットを選択します。
      
      既存の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エージェントに接続できるようにするには、このオプションを選択します。
  - プライベート・エンドポイント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の説明
「次へ」をクリックします。

これにより、「確認」ページに移動します。
確認ページで、次のステップを実行します:
1. 構成変数を確認します。
2. 「作成されたスタックで適用を実行しますか。」の下の「適用の実行」チェック・ボックスを選択
3. 「作成」をクリックします。
ノート:
この領域には、デフォルト値または変更していない変数は表示されません。

図adbs_extproc_review.pngの説明

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

図adbs_extproc_job_details.pngの説明

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

親トピック: SQLファンクションとしての外部プロシージャの起動

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

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

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

ノート:

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

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

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

Autonomous Databaseのオブジェクト・ストレージから、EXTPROCエージェント・インスタンスの証明書を含むウォレットcwallet.ssoをインポートします。ウォレット・ファイルの次の点に注意してください:
- ウォレット・ファイルは、データベース・ユーザーIDおよびパスワードとともに、EXTPROCエージェント・インスタンスへのアクセスを提供します。ウォレット・ファイルを安全なロケーションに格納し、認可されたユーザーのみと共有します。
- ウォレット・ファイルの名前を変更しないでください。オブジェクト・ストレージのウォレット・ファイルの名前は、cwallet.ssoである必要があります。
ウォレット・ファイルcwallet.ssoを格納するオブジェクト・ストレージにアクセスするための資格証明を作成します。様々なオブジェクト・ストレージ・サービスのusernameおよびpasswordパラメータの詳細は、「CREATE_CREDENTIALプロシージャ」を参照してください。
リソース・プリンシパル資格証明を有効にする場合、Oracle Cloud Infrastructureオブジェクト・ストアにアクセスするための資格証明を作成する必要はありません。詳細については、「リソース・プリンシパルを使用したOracle Cloud Infrastructureリソースへのアクセスについて」を参照してください。
ウォレット・ファイルcwallet.ssoのディレクトリをAutonomous Databaseに作成します。
```
CREATE DIRECTORY wallet_dir AS 'directory_location';
```
ディレクトリの作成の詳細は、「Autonomous Databaseでのディレクトリの作成」を参照してください。
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 Databaseインスタンスで使用できるようになりました。

親トピック: SQLファンクションとしての外部プロシージャの起動

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

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

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

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

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

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

外部プロシージャは、ライブラリに格納されているC言語ルーチンです。 Autonomous 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 Databaseにdemolibライブラリが作成され、データベースに動的リンク・ライブラリが登録されます。 EXTPROCエージェント・インスタンスは、ポート16000で外部プロシージャをホストするように事前構成されています。

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

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

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

関数を作成します。

たとえば:

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

DROP_CATALOGプロシージャを使用して、既存のライブラリを削除できます。たとえば:
```
BEGIN
    DBMS_CLOUD_FUNCTION.DROP_CATALOG (
      LIBRARY_NAME  => 'demolib'
  );
END;
/
```
これにより、DEMOLIBライブラリが削除されます。

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

親トピック: SQLファンクションとしての外部プロシージャの起動