Oracle Cloud Infrastructure関数のデータ・フローへの登録および使用

Oracle Cloud Infrastructure (OCI)関数をOracle Analyticsに登録し、それらをデータ・フローで使用してデータを変換できるようにします。

Oracle AnalyticsでのOCI関数の使用について

OCIで作成された関数を使用してOracle Analytics内のデータを変換できます。たとえば、言語変換関数を使用して、英語のテキストをスペイン語またはドイツ語に変換できます。

まず、Oracle AnalyticsでOCI関数を登録すると、BIサービス管理者またはDVコンテンツ作成者権限を持つすべてのOracle Analyticsユーザーがデータ・フローでそれらを使用できるようになります。

Oracle Analyticsで使用するOCI関数の構成について

OCIコンソールで関数を作成し、それらを使用して、Oracle Analyticsデータ・フローのデータを変換できるようにします。

Oracle AnalyticsでのOCI関数の登録について

OCI関数をOracle Analyticsに登録する際、「関数の選択」ダイアログでグレー表示されている場合、それがoac-compatibleタグで構成済であり、正しいfuncMode値で起動されていることを確認してください。

図oci-functions-select-function-register.pngの説明

Oracle Analyticsで使用するOCI関数の構成について

Oracle Analyticsで使用するOCI関数にはoac-compatibleタグがあり、関数コードにはfuncMode変数を含める必要があります。OCIコンソールでこれらの設定を構成します:

oac-compatible - 名前oac-compatibleを使用してフリー・フォーム・タグを関数に追加して、値trueに設定します。
図oci-function-tags.pngの説明
funcMode - funcMode変数を関数コードに含めます。Oracle Analyticsは、funcMode=describeFunctionでOCI関数を登録するリクエスト、およびfuncMode=executeFunctionでOCI関数を起動するリクエストを送信します。func.py内のハンドラ関数は、describeFunctionモードまたはexecuteFunctionモードで操作する必要があります。次に示すリクエストの入力変数funcModeの値に基づいて、これを実行できます。

図oci-function-mode.pngの説明

pythonでの語数の例におけるOCI関数のリクエストおよびレスポンス形式を次に示します。

funcMode = describeFunction
```
{ "funcMode": "describeFunction"}
```
リクエストのfuncModeが'describeFunction'の場合、関数はステータス(returnCodeおよびerrorMessage)、出力(出力列の名前、データ型)、パラメータ(入力パラメータの名前、説明、タイプなど)、bucketNameなどを含む関数定義を、次の形式のJSONオブジェクトとして返します(語数の例):
```
funcDefinition = {
    "status": {
        "returnCode": 0,
        "errorMessage": ""
    },
    "funcDescription": {
        "outputs": [
            {"name": "word_count", "dataType": "integer"}
        ],
        "parameters": [
            {"name": "textColumn", "displayName": "Text Column",
             "description": "Choose column to count words", "required": True,
             "value": {"type": "column"}}
        ],
        "bucketName": "bucket-OCI-FAAS",
        "isOutputJoinableWithInput": True
    }
}
```
リクエスト内のfuncModeが'describeFunction'である場合、次のコードをfunc.pyに追加して、funcDefinitionを返します。
```
def handler(ctx, data: io.BytesIO = None):
    response_data = ""
    try:
        body = json.loads(data.getvalue())
        funcMode = body.get("funcMode")
        if funcMode == 'describeFunction':
           response_data = json.dumps(funcDefinition)
    except (Exception, ValueError) as ex:
        response_data = json.dumps(
            {"error": "{0}".format(str(ex))})
    return response.Response(
        ctx, response_data,
        headers={"Content-Type": "application/json"}
    )
```
funcMode = executeFunction - funcModeが'executeFunction'の場合、実際の関数ロジックを実行し、レスポンスを出力とともにOracle Analyticsに返信する必要があります。登録されている関数がOracle Analyticsのデータフローから起動される場合、リクエスト・オブジェクトは、argsの列名、input(bucketName、fileName、fileExtension、fileName、method、rowID)およびoutput(bucketName、fileName、fileExtension)を含む次のような形式になります。
```
{
    "args":
    {
        "textColumn": "REVIEW"
    },
    "funcMode": "executeFunction",
    "input":
    {
        "bucketName": "bucket-OCI-FAAS",
        "fileExtension": ".csv",
        "fileName": "oac-fn-e99cd4fddb3844be89c7af6ea4bbeb76-input",
        "method": "csv",
        "rowID": "row_id"
    },
    "output":
    {
        "bucketName": "bucket-OCI-FAAS",
        "fileExtension": ".csv",
        "fileName": "oac-fn-e99cd4fddb3844be89c7af6ea4bbeb76-output"
    }
}
```

OCIでの関数の作成について

OCIコンソール、コマンド・ライン(Fn Project CLI)またはAPIを使用して、関数を作成できます。たとえば、OCIコンソールで、「開発者サービス」、「ファンクション」を順にクリックし、画面上の指示に従って、アプリケーションおよび1つ以上の関数を作成します。詳細は、OCIドキュメントでのファンクションの作成を参照してください。初めて関数を作成している場合、エンド・ツー・エンドのステップHelloworldファンクションの作成、デプロイおよび起動に従います。Oracle Analyticsで使用するすべての関数には、フリー・フォーム・タグoac-compatible=trueを含める必要があります(前述のOracle Analyticsで使用するOCI関数の構成についてを参照)。

OCIコンソールでの関数の作成のヒント

ログの有効化 - デフォルトでは、関数のログは無効化されています。関数のログを有効にするには、アプリケーション・ページで、「ログ」をクリックし、「ログ名」に提供されているログを有効にします。「リソース」で、「ログの探索」を選択し、ログ・エントリにドリルして、関数の問題をデバック、診断できます。
依存関係を含める - 関数のrequirements.txtファイル内の依存パッケージを含めます。
インデント・ルールに従う- Python関数をコーディングする際に、Pythonのインデント・ルールに従います。
関数レスポンス・エラーの使用 - データフロー・ページにリストされているエラー詳細を使用して、問題を診断します。
関数を先にローカルでテスト - OCIで関数を作成する前に、開発環境において関数をローカルでテストし、関数が構文的かつ論理的に正しいことを確認してください。
OCIでの関数のテスト - 関数をOracle Analyticsと統合する前に、それらをOCI内の標準関数として正常にデプロイおよび起動できることを確認してください。
タイムアウトの増加- デフォルトでは、関数のタイムアウト値は30秒です。必要に応じて、OCIコンソールの「ファンクションの編集」ページでタイムアウト設定を増加します(たとえば、300秒に変更します)。
メモリーの増加- デフォルトでは、関数のメモリー制限は1024MBです。必要に応じて、OCIコンソールの「ファンクションの編集」ページでメモリー制限を増加します。
領域の最適化 - 未使用のファイルは、使用後にただちに削除してください。
ネットワーク・レイテンシに注意 - ネットワーク・レイテンシにより処理全体でわずかな遅延が発生する可能性があることに注意してください。

OCI関数を使用したデータの変換のための一般的なワークフロー

次にリストされた順序でこれらの高レベルのタスクに従い、OCI関数を使用してデータを変換します。

タスク	説明	詳細情報
OCIでの関数の作成(関数の開発者権限が必要)	OCIテナンシで関数を作成し、それらが、Oracle Analyticsで使用するために指定された前提条件に準拠していることを確認してください。	Oracle Analyticsで使用するOCI関数の構成について
OCIテナンシへのOracle Analyticsの接続(管理者またはDV作成者権限が必要)	Oracle Analyticsで、OCIテナンシへの接続を作成します。	OCIテナンシへの接続の作成
Oracle AnalyticsでのOCI関数の登録(管理者またはDV作成者権限が必要)	Oracle Analyticsで、OCI関数をデータ・フローから呼び出せるように登録します。	Oracle AnalyticsでのOCI関数の登録
OCI関数を使用したデータの変換(管理者またはDV作成者権限が必要)	データ・フローを作成し、「カスタム・スクリプトの適用」ステップを使用して、OCI関数を起動します。	OCI関数を使用したデータの変換

OCIテナンシへの接続の作成

OCIテナンシへの接続を作成して、Oracle AnalyticsをOCI関数、OCI Vision、OCI Data ScienceまたはOCI Languageと統合できるようにします。たとえば、OCIにホストされている言語変換関数を登録して、Oracle Analyticsデータ・フローを使用して英語のテキストをスペイン語またはドイツ語に変換できるようにします。

APIキーを使用してOCIテナンシに接続します。

OCIコンソールで、OCIテナンシ・プロファイルに移動し、リージョン、テナンシOCIDおよびユーザーOCIDをコピーします。
- リージョンについては、プロファイルの上部に表示されている地理的リージョンを確認してください。
- テナンシOCIDについては、「テナンシ」の名前をクリックし、OCIDをコピーします。
- ユーザーOCIDについては、「ユーザー設定」をクリックし、OCIDをコピーします。
図vision_tenancy_ids.pngの説明

テナンシのOCIDおよびユーザーのOCIDの取得場所を参照してください。
Oracle Analyticsのホーム・ページで、「作成」をクリックし、「接続」をクリックします。
「接続タイプを選択してください」ダイアログで、OCIリソースをクリックします。
「接続名」には、Oracle Analytics内でこの接続を識別するためのわかりやすい名前を指定します。
APIキーを使用して接続するには:
- 「次を使用して接続」で、「APIキー」を選択します。
- 「テナンシOCID」で、ステップ1でコピーしたテナンシOCIDを貼り付けます。
- 「デフォルト・リージョン」では、OCIリソースが配置されているリージョンを選択します。
- 「ユーザーOCID」で、ステップ1でコピーしたユーザーOCIDを貼り付けます。
- 「公開APIキー」で、「生成」、「コピー」の順にクリックします。
- OCIテナンシで、APIキーを「ユーザー設定」の「APIキー」ページに貼り付け、「追加」をクリックします。
リソース・プリンシパルを使用して接続するには:
- 「次を使用して接続」で、「リソース・プリンシパル」を選択します。
- 「デフォルト・リージョン」では、OCIリソースが配置されているリージョンを選択します。
- 「コンパートメント」で、「選択」をクリックし、接続先のOCIコンパートメントを選択します。
- 「サービス」では、接続が使用されるOCIサービスを選択します。サービスを選択するには、BIサービス管理者の権限を持つユーザーとしてOracle Analyticsにログインします。
Oracle Analyticsの「接続の作成」ダイアログで、「保存」をクリックします。
APIキーを使用して接続している場合は、接続を保存する前に数秒待って、次のエラーを回避します: "Failed to save the connection. Invalid connection parameters specified"。

Oracle AnalyticsでのOCI関数の登録

OCI関数をOracle Analyticsに登録し、それらをデータ・フローで使用してデータを変換できるようにします。たとえば、言語変換関数を登録して、データ・アナリストが英語のテキストをスペイン語またはドイツ語に変換できるようにします。

Oracle Analyticsのホーム・ページで、「ページ・メニュー」、「モデル/関数の登録」、「OCI関数」の順にクリックします。
「カスタム関数の登録」ダイアログで、関数があるOCIテナンシへの接続を選択します。
「アプリケーションの選択」ダイアログで、OCI関数を含むアプリケーションを選択します。
不明な場合、OCIで関数を作成した個人に問い合せてください。
「関数の選択」ダイアログで、関数を選択し、「登録」をクリックします。
使用する関数がグレー表示されている場合、それがOracle Analytics用に構成されていることを管理者に確認してください。Oracle Analyticsで使用するOCI関数の構成についてを参照してください。

データ・フロー内の登録されたOCI関数を使用して、データを変換できます。どの関数が登録されているかを確認するには、機械学習ページの「スクリプト」タブで登録済関数を表示できます(ホーム・ページから「ナビゲータ」、「機械学習」、「スクリプト」の順にクリックします)。