Autonomous AI DatabaseでのWITH_CONTEXTを使用したPythonスクリプトの起動

Autonomous AI Databaseでの`WITH_CONTEXT`を使用したPythonスクリプトの起動

データベースでWITH_CONTEXTを使用してPythonスクリプトを起動するステップを示します。

トピック

Autonomous AI DatabaseでのWITH_CONTEXTを使用したPythonスクリプトの起動について
WITH_CONTEXT属性を持つOracle Schedulerジョブを使用して、Autonomous AI DatabaseインスタンスでPythonスクリプトを実行できます。
Pythonスクリプトの作成
Pythonスクリプトの作成の例を示します
Oracle Autonomous AI Database EXTPROCコンテナ・イメージの構成
Oracle Autonomous AI Database EXTPROCコンテナ・イメージを取得および構成するステップについて説明します。
WalletのアップロードによるEXTPROCエージェント・インスタンスへのセキュアな接続の作成
自己署名ウォレットは、Autonomous AI Database EXTPROCエージェント・アプリケーションの作成の一部として作成されます。このウォレットを使用すると、Extrpocエージェント・インスタンスにアクセスできます。
Pythonスクリプトを起動するステップ
Autonomous AI DatabaseでPythonスクリプトを起動するステップを示します。

Autonomous AI DatabaseでのWITH_CONTEXTを使用したPythonスクリプトの起動について

WITH_CONTEXT属性を持つOracle Schedulerジョブを使用して、Autonomous AI DatabaseインスタンスでPythonスクリプトを実行できます。

Autonomous AI DatabaseでWITH_CONTEXTを使用してPythonスクリプトを起動すると、スクリプトがデータベースにコールバックできるようにするコンテキスト・ポインタがスクリプトに渡されます。コンテキストは、データベース・セッション、接続、およびスクリプトがアクセスまたは操作する必要がある関連する状態またはデータを指します。

Autonomous AI DatabaseインスタンスでPythonスクリプトを直接実行することはできません。かわりに、Oracle Cloud Infrastructure Virtual Cloud Network (VCN)で実行されているOracle <span>Autonomous AI Database</span>Extprocコンテナ・イメージでスクリプトをリモートでホストします。コンテナ・イメージは、EXTPROCエージェントで事前構成され、スクリプトを実行するために必要なすべてのライブラリ(utils、onnx、python-oracledbなど)が含まれます。

Oracle Schedulerジョブを使用して、Autonomous AI DatabaseからPythonスクリプトを起動します。作成するスケジューラ・ジョブは、実行可能ジョブである必要があり、WITH_CONTEXT属性で実行されます。実行可能ジョブは、シェル・スクリプトまたはその他の実行可能ファイルを実行でき、WITH_CONTEXT Oracle Scheduler属性を使用すると、外部プロシージャ、プログラムまたはスクリプトをコールするときに、スクリプトが現在のセッション権限を継承できます。 WITH_CONTEXT属性を使用すると、外部ルーチンは、スキーマ、権限、その他のコンテキスト変数などのセッション固有の情報にアクセスできます。

Autonomous AI DatabaseからのPythonスクリプトは、データベースがプライベート・エンドポイントにある場合にのみサポートされます。 Pythonスクリプトを実行するには、EXTPROCエージェントがインストールされたOracle Autonomous AI Database EXTPROCコンテナ・イメージを取得、インストールおよび構成する必要があります。 Autonomous AI DatabaseのEXTPROCコンテナ・イメージを使用すると、BASH、CまたはPythonで記述された外部プロシージャおよびスクリプトをAutonomous AI Databaseからコールできます。 EXTPROCエージェント・インスタンスはプライベート・サブネットでホストされ、Autonomous AI Databaseはリバース接続エンドポイント(RCE)を介してEXTPROCエージェントにアクセスします。

ノート:

この機能は、Oracleデータベース・リリース19cでのみサポートされています。

次のものを使用して、Pythonスクリプトをデプロイします。

Oracleは、EXTPROCエージェントがインストールされたAutonomous AI Databaseコンテナ・イメージを提供しました。 Oracleは、GitHubパッケージにコンテナ・イメージを提供します。

EXTPROCコンテナ・イメージを取得および構成する手順は、GitHub READMEを参照してください:

EXTPROCエージェント・インスタンスは、Oracle Cloud Infrastructure Virtual Cloud Network (VCN)で実行されているコンテナ・イメージでリモートでホストされます。 Autonomous AI DatabaseとEXTPROCエージェント・インスタンス間のセキュアな通信は、プライベート・エンドポイントで実行されているAutonomous AI DatabaseインスタンスからEXTPROCエージェント・インスタンスへのトラフィックが許可されるように、ネットワーク・セキュリティ・グループ(NSG)ルールを設定することで保護されます。 EXTPROCエージェント・イメージは、ポート16000で外部プロシージャをホストおよび実行するように事前構成されています。
エンドポイント環境を登録し、登録されたエンドポイントに対する権限を管理するPL/SQLプロシージャ。詳細については、「DBMS_CLOUD_FUNCTION_ADMINパッケージ」を参照してください。
Pythonスクリプトを起動するスケジューラ・ジョブおよびプログラムを作成および管理するためのPL/SQLプロシージャ。

詳細については、DBMS_SCHEDULERを参照してください。

Autonomous AI DatabaseインスタンスでWITH_CONTEXTを使用してPythonスクリプトを実行するには、次のステップに従います:

Pythonスクリプトを作成します。詳細は、Pythonスクリプトの作成を参照してください。
EXTPROCコンテナ・イメージを取得および構成します。詳細については、GitHub READMEを参照してください。
EXTPROCエージェント・インスタンスに接続するようにAutonomous AI Databaseを構成します。詳細については、「WalletのアップロードによるEXTPROCエージェント・インスタンスへのセキュアな接続の作成」を参照してください。
Autonomous AI DatabaseでPythonスクリプトを起動します。詳細は、Pythonスクリプトを起動するステップを参照してください。

親トピック: Autonomous AI DatabaseでのWITH_CONTEXTを使用したPythonスクリプトの起動

Pythonスクリプトの作成

Pythonスクリプトの作成例を示します

例: データベースに表を作成するPythonスクリプト。

#!/usr/bin/env python1

import oracledb
import utils
 def gsf_main(argc, argv):
    table_name = argv[0]
    table_pk = argv[1]
    print(f"Total number of args: {argc}")
    print(f"Arg1: {table_name}")
    print(f"Arg2: {table_pk}")
    print(f"Arg3: {argv[2]}")
    print(f"Arg4: {argv[3]}")
    print(f"Arg5: {argv[4]}")
     
    # Step 1: Get connection object
    con = utils.getconnection()
    if con is None:
        print("Failed to establish database connection.")
        return -1
      try:
        # Step 2: Create a table
        cur = con.cursor()
        create_table_query = f"""
            CREATE TABLE {table_name} (
                employee_id NUMBER GENERATED ALWAYS AS IDENTITY (START WITH 1 INCREMENT BY 1),
                employee_name VARCHAR2(4000),
                employee_age NUMBER,
                CONSTRAINT {table_pk} PRIMARY KEY (employee_id)
            )
            """
        cur.execute(create_table_query)
    except Exception as e:
        print(f"Error performing operations: {e}")
        return -1
    finally:
        if cur:
            cur.close()

この例では、python1.pyスクリプトを作成します。このスクリプトは、スケジューラ・ジョブからの引数を受け入れるPython関数gsf_main(argc, argv)を定義し、指定された属性を使用してデータベースに表を作成し、例外を処理します。

oracledbドライバを使用すると、スクリプトをデータベースに接続できます。

utilsパッケージは、データベース接続を取得するためのヘルパー関数getconnection()を提供します。

詳細は、Pythonのドキュメントを参照してください。

親トピック: Autonomous AI DatabaseでのWITH_CONTEXTを使用したPythonスクリプトの起動

Oracle Autonomous AI Database EXTPROCコンテナ・イメージの構成

Oracle Autonomous AI Database EXTPROCコンテナ・イメージを取得および構成するステップについて説明します。

EXTPROCエージェントがインストールされたOracle提供のAutonomous AI Databaseコンテナ・イメージは、GitHubパッケージでホストされます。 EXTPROCコンテナ・イメージを取得および構成する手順は、GitHub READMEを参照してください。

親トピック: Autonomous AI DatabaseでのWITH_CONTEXTを使用したPythonスクリプトの起動

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

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

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

ノート:

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

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

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

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

親トピック: Autonomous AI DatabaseでのWITH_CONTEXTを使用したPythonスクリプトの起動

Pythonスクリプトを起動するステップ

Autonomous AI DatabaseでPythonスクリプトを起動するステップを示します。

Pythonスクリプトを実行するようにEXTPROCエージェント・インスタンスを構成した後、リモート・エンドポイントを登録し、スクリプトをコールするためのスケジューラ・ジョブを作成します。

Autonomous AI DatabaseでPythonスクリプトを起動するための前提条件を次に示します:

Pythonスクリプトは、EXTPROCエージェント・インスタンスにコピーする必要があります。
スケジューラ・ジョブを作成して管理し、ADMIN以外のユーザーでPythonスクリプトを起動するには、次の権限が必要です:
- MANAGE SCHEDULER
- CREATE JOB
- 登録済リモート・エンドポイントの権限

トピック

Autonomous AI Databaseでのリモート・エンドポイントの登録および管理
ADMINユーザーとして、次のステップを実行して、Autonomous AI Databaseにリモート・エンドポイントを登録および管理します。
Pythonスクリプトを起動するスケジューラ・ジョブの作成と管理
Autonomous AI DatabaseからPythonスクリプトを起動するスケジューラ・ジョブを作成および管理するステップを示します。

親トピック: Autonomous AI DatabaseでのWITH_CONTEXTを使用したPythonスクリプトの起動

Autonomous AI Databaseでのリモート・エンドポイントの登録および管理

ADMINユーザーとして、次のステップを実行して、Autonomous AI Databaseのリモート・エンドポイントを登録および管理します。

リモート・エンドポイントの登録

DBMS_CLOUD_FUNCTION_ADMIN.REGISTER_REMOTE_EXECUTION_ENVを使用して、リモート・エンドポイントを登録します。

例:

BEGIN
 DBMS_CLOUD_FUNCTION_ADMIN.REGISTER_REMOTE_EXECUTION_ENV (
        remote_endpoint_name => 'rem_executable',
        remote_endpoint_url  => 'remote_extproc_hostname:16000',
        wallet_dir           => 'WALLET_DIR',
        remote_cert_dn       => 'CN=MACHINENAME'
);
END;
/

この例では、rem_executableライブラリを作成し、Autonomous AI Databaseのremote_endpoint_urlパラメータで指定されたEXTPROCエージェント・インスタンスを登録します。 EXTPROCエージェント・インスタンスは、ポート16000でPythonスクリプトをホストするように事前構成されています。

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

登録済エンドポイントの権限の管理

このステップはオプションであり、ADMIN以外のユーザーがAutonomous AI DatabaseからPythonスクリプトを起動する必要がある場合にのみ必要です。

DBMS_CLOUD_FUNCTION_ADMIN.GRANT_REMOTE_EXECUTION_ENVを使用して、登録済エンドポイントに対する権限をADMIN以外のユーザーに付与します。

例:

BEGIN
 DBMS_CLOUD_FUNCTION_ADMIN.GRANT_REMOTE_EXECUTION_ENV (   
    remote_endpoint_name => 'REM_EXECUTABLE',
    user_name            => 'username');
END;
/

この例では、REM_EXECUTABLEに対する権限を指定されたユーザーに付与します。詳細については、「GRANT_REMOTE_EXECUTION_ENVプロシージャ」を参照してください。

登録済エンドポイントに対する権限を付与した後、DBMS_CLOUD_FUNCTION_ADMIN.REVOKE_REMOTE_EXECUTION_ENVを使用して、登録済エンドポイントに対する権限をユーザーから取り消すことができます。

例:

BEGIN
 DBMS_CLOUD_FUNCTION_ADMIN.REVOKE_REMOTE_EXECUTION_ENV (   
    remote_endpoint_name => 'REM_EXECUTABLE',
    user_name            => 'username');
END;
/

この例では、指定したユーザーからREM_EXECUTABLEに対する権限を取り消します。詳細については、「REVOKE_REMOTE_EXECUTION_ENVプロシージャ」を参照してください。

DBA_CLOUD_FUNCTION_REMOTE_EXECUTION_GRANTを問い合せて、すべてのリモート・エンドポイントに付与されている権限をリストできます。詳細については、「DBA_CLOUD_FUNCTION_REMOTE_EXECUTION_GRANTビュー」を参照してください。

登録済エンドポイントの削除

DBMS_CLOUD_FUNCTION_ADMIN.DEREGISTER_REMOTE_EXECUTION_ENVを使用して、登録済リモート・エンドポイントを削除します。

例:

BEGIN
 DBMS_CLOUD_FUNCTION_ADMIN.DEREGISTER_REMOTE_EXECUTION_ENV (   
    remote_endpoint_name => 'REM_EXECUTABLE');
END;
/

これにより、Autonomous AI Databaseからrem_executableリモート・エンドポイントが削除されます。詳細については、「DEREGISTER_REMOTE_EXECUTION_ENVプロシージャ」を参照してください。

親トピック: Pythonスクリプトを起動するステップ

Pythonスクリプトを起動するスケジューラ・ジョブの作成と管理

Autonomous AI DatabaseからPythonスクリプトを起動するスケジューラ・ジョブを作成および管理するステップを示します。

ADMIN以外のユーザーとして次のステップを実行するには、必要な権限が必要です。詳細は、Pythonスクリプトを起動するステップを参照してください。

DBMS_SCHEDULER.CREATE_JOBを使用して、ジョブ・タイプがexecutableのスケジューラ・ジョブを作成します。たとえば:
```
BEGIN
 DBMS_SCHEDULER.CREATE_JOB (
    job_name             => 'rem_exec_job',
    job_type             => 'executable',
    job_action           => '/script_location_on_extproc_agent_image/python1.py',
    number_of_arguments  => 1,
    enabled              => false,
    auto_drop            => true);
 END;
/
```
この例では、実行可能タイプのrem_exec_jobスケジューラ・ジョブを作成します。

job_nameパラメータは、ジョブの名前を指定します。

job_typeパラメータは、ジョブ・アクション・タイプを指定します。 Autonomous AI DatabaseでPythonスクリプトを起動するには、実行可能ファイルとしてjob_typeを指定する必要があります。

job_actionパラメータは、ジョブのインライン・アクションを指定します。これは、呼び出す必要があるリモート・エンドポイント上のスクリプトのロケーションです。この例では、前のステップで作成したpython1.pyスクリプトを呼び出します。

number_of_argumentsパラメータは、ジョブ引数の数を指定します。

enabledパラメータは、ジョブの作成直後にジョブを有効にするかどうかを示します。作成時にPythonスクリプトを起動するOracle Schedulerジョブは有効にできません。DBMS_SCHEDULER.ENABLEを使用して、ジョブの作成後にジョブを有効にします。

auto_dropパラメータは、完了後にジョブを削除するかどうかを示します。
DBMS_SCHEDULER.SET_JOB_ARGUMENT_VALUEを使用して、ジョブ引数の値を設定します。
例:
```
BEGIN
 DBMS_SCHEDULER.SET_JOB_ARGUMENT_VALUE (
    job_name          => 'rem_exec_job',
    argument_position => 1,
    argument_value    => 'job_param');
 END;
/
```
この例では、rem_exec_jobジョブの最初の引数をString値job_paramに設定します。ジョブを実行すると、最初のパラメータの値としてjob_paramが渡されます。
DBMS_SCHEDULER.SET_ATTRIBUTEを使用して、rem_exec_jobジョブのdestination属性を変更します。 destination属性は、リモート・エンドポイントの宛先を指定します。
例:
```
BEGIN
 DBMS_SCHEDULER.SET_ATTRIBUTE (
      name       => 'rem_exec_job',
      attribute  => 'destination',
      value      => 'REMOTE_EXTPROC:remote_endpoint_name:WITH_CONTEXT');
 END;
/
```
この例では、rem_exec_jobジョブのdestination属性を変更して、リモート・ライブラリ・パスを指定します。

job_nameパラメータは、ジョブの名前を指定します。

attributeパラメータは、変更する属性を指定します。

valueパラメータは、リモート・エンドポイント宛先を指定するためにdestination属性を変更します。

このパラメータは、REMOTE_EXTPROC:remote_endpoint_name:WITH_CONTEXT形式の文字列値を受け入れます。remote_endpoint_nameは、登録されたリモート・エンドポイントの名前です。 WITH_CONTEXT句を使用すると、外部プロシージャ、プログラムまたはスクリプトをコールするときに、スクリプトで現在のセッション権限を継承できます。

指定したエンドポイントに対する権限がない場合、エラーが発生します。
詳細については、「DBMS_SCHEDULERサブプログラム」を参照してください。
DBMS_SCHEDULER.ENABLEを実行して、スケジューラ・ジョブを有効にします。
例:
```
BEGIN
 DBMS_SCHEDULER.ENABLE (
    name => 'rem_exec_job');
 END; 
/
```
この例では、rem_exec_jobジョブを有効にします。詳細については、DBMS_SCHEDULERを参照してください。

ジョブを有効にすると、スケジューラはジョブの実行を開始します。

「USER_CLOUD_FUNCTION_RUN_DETAILSビュー」および「DBA_CLOUD_FUNCTION_RUN_DETAILSビュー」を問い合せて、スケジューラ・ジョブのステータスを表示します。

親トピック: Pythonスクリプトを起動するステップ