Oracle AnalyticsのOCI関数との統合

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関数とOracle Analyticsの統合に必要なポリシー

Oracle AnalyticsをOCI関数と統合するには、必要なセキュリティ・ポリシーがあることを確認します。

Oracle Analytics CloudとOCIテナンシ間の接続で指定するOCIユーザーには、使用するOCIリソースを含むコンパートメントに対する読取り、書込みおよび削除権限が必要です。OCIユーザーが次の最小限のOCIセキュリティ・ポリシーを持つユーザー・グループに属していることを確認してくださいOCIテナンシにOracle Analyticsから接続する場合は、OCI APIキーまたはリソース・プリンシパルを使用できます。

ノート: リソース・プリンシパルの場合、コンパートメント下のすべての分析インスタンスを含めるには、{request.principal.id='<analytics_instance_ocid>'}のかわりに{request.principal.type='analyticsinstance', request.principal.compartment.id='<compartmentA_ocid>'}を指定します。

表25-1 OCI関数統合に必要なセキュリティ・ポリシー

APIキー・ポリシー	リソース・プリンシパル・ポリシー
`Allow group <group_name> to use functions-family in compartment <compartment_name>`	`Allow any-user to use functions-family in compartment <compartment_name> where all {request.principal.id='<analytics_instance_ocid>'}`
`Allow group <group_name> to read buckets in compartment <compartment_name>`	`Allow any-user to read buckets in compartment <compartment_name> where all {request.principal.id='<analytics_instance_ocid>'}`
`Allow group <group_name> to manage objects in compartment <compartment_name> where target.bucket.name='<staging_bucket_name>'`	`Allow any-user to manage objects in compartment <compartment_name> where all {request.principal.id='<analytics_instance_ocid>', target.bucket.name='<staging_bucket_name>'}`
`Allow group <group_name> to read objectstorage-namespaces in tenancy`	`Allow any-user to read objectstorage-namespaces in tenancy where all {request.principal.id='<analytics_instance_ocid>'}`

表25-2 OCI関数 - 動的グループ・ポリシー

ポリシー	説明
`Allow dynamic-group <dynamic_group> to manage objects in compartment <compartment_name> where target.bucket.name='<staging_bucket_name>'`	動的グループのステージング・バケットへのアクセスを提供します。

<dynamic_group>.{resource.type = 'fnfunc', resource.compartment.id = '<compartment_ocid>'}のサンプル一致ルール

ノート: <compartment_id>は、関数を含むコンパートメントのOCIDです。

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

下にリストされた順序で、次に示す大まかなタスクに従い、OCI関数を使用してOracle Analyticsのデータを変換します。

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

Oracle AnalyticsでのOCI関数の登録

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

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

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