将 Oracle Analytics 与 Oracle Cloud Infrastructure Functions 集成

可将 Oracle Analytics 与 Oracle Cloud Infrastructure (OCI) 函数集成，以便可以在数据流中使用它们转换数据。

关于在 Oracle Analytics 中使用 OCI 函数

您可以使用在 OCI 中创建的函数在 Oracle Analytics 中转换数据。例如，您可以使用语言转换函数将英语文本转换为西班牙语或德语。

您先在 Oracle Analytics 中注册 OCI 函数，然后具有 BI 服务管理员或 DV 内容作者权限的任何 Oracle Analytics 用户就可以在数据流中使用它们。

关于配置要在 Oracle Analytics 中使用的 OCI 函数

可在 OCI 控制台中创建函数，以便可以在 Oracle Analytics 数据流中使用它们转换数据。

关于在 Oracle Analytics 中注册 OCI 函数

在 Oracle Analytics 中注册 OCI 函数时，如果它在选择函数对话框中灰显，请检查是否为其配置了 oac-compatible 标记，以及是否使用正确的 funcMode 值调用它。
GUID-6FE05B2C-5352-4953-998F-D967B6BA1891-default.png 的说明如下
.png 的说明

关于配置要在 Oracle Analytics 中使用的 OCI 函数

要在 Oracle Analytics 中使用的 OCI 函数必须具有 oac-compatible 标记，并且函数代码必须包含 funcMode 变量。应在 OCI 控制台中配置以下设置：

  • oac-compatible — 向函数添加名称为 oac-compatible 的自由形式标记，并将值设置为 true。GUID-6DDD2A98-7F8D-45D7-9110-9643C2128A84-default.png 的说明如下
    .png 的说明
  • funcMode — 在函数代码中包含 funcMode 变量。Oracle Analytics 使用 funcMode=describeFunction 发送注册 OCI 函数的请求，使用 funcMode=executeFunction 发送调用 OCI 函数的请求。func.py 中的处理程序函数应以 describeFunction 模式或 executeFunction 模式运行。这可以根据来自请求的输入变量 funcMode 的值来完成，如下所示。

    GUID-0C335709-DEDC-4655-8A29-F544608DA8B3-default.png 的说明如下
    .png 的说明

    下面是采用 Python 编写的单词计数示例的 OCI 函数的请求和响应格式。

    funcMode = describeFunction

    { "funcMode": "describeFunction"}

    当请求中的 funcMode 为 'describeFunction' 时，函数应以 JSON 对象形式按以下格式返回包含以下内容的函数定义（单词计数示例）：status（returnCode 和 errorMessage）、outputs（输出列的 name 和 dataType）、parameters（输入参数的 name、description、type 等）、bucketName 等：

    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
    }
}

    在 func.py 中添加以下代码以在请求中的 funcMode 为 'describeFunction' 时返回 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 控制台中，依次单击开发人员服务和函数，然后按照屏幕上的说明来创建应用程序与一个或多个函数。有关详细信息，请参见有关在 OCI 中创建函数的文档。如果是第一次创建函数，请按照分步示例 Creating, Deploying, and Invoking a Helloworld Function（创建、部署和调用 Helloworld 函数）中的步骤操作。要在 Oracle Analytics 中使用的任何函数都必须包含自由形式标记 oac-compatible=true（请参见上文的关于配置要在 Oracle Analytics 中使用的 OCI 函数）。

有关在 OCI 控制台中创建函数的提示

  • 启用日志 — 默认情况下，对函数禁用日志。要对函数启用日志，请在应用程序页上，单击日志，并启用为日志名称提供的日志。现在可以在资源下选择浏览日志，然后钻探日志条目以对函数问题进行调试和诊断。
  • 包括相关性 — 在函数的 requirements.txt 文件中包括相关程序包。
  • 采用缩进规则 — 在对 Python 函数编码时采用 Python 缩进规则。
  • 使用函数响应错误 — 使用“数据流”页上列出的错误详细信息来诊断问题。
  • 首先在本地测试函数 — 在 OCI 中创建函数之前，在您的开发环境中本地测试函数，以确保函数在语法和逻辑上正确。
  • 在 OCI 中测试函数 — 在将函数与 Oracle Analytics 集成之前，确保可以在 OCI 中成功地以独立函数形式部署和调用它们。
  • 延长超时 — 默认情况下，函数的超时时间为 30 秒。如果需要，在 OCI 控制台中的编辑函数页中延长超时设置（例如，将其更改为 300 秒）。
  • 增加内存 — 默认情况下，函数的内存限制为 1024 MB。如果需要，在 OCI 控制台中的编辑函数页中提高内存限制。
  • 优化空间 — 在使用文件后立即删除未使用的文件。
  • 注意网络延迟 — 请注意，网络延迟可能会导致总体处理略有延迟。

将 OCI 函数与 Oracle Analytics 集成所需的策略

要将 Oracle Analytics 与 OCI 函数集成，请确保您具有所需的安全策略。

您在 Oracle Analytics Cloud 与 OCI 租户的连接中指定的 OCI 用户必须对您要使用的 OCI 资源所在的区间具有读取、写入和删除权限。确保该 OCI 用户所属的用户组至少具有以下 OCI 安全策略。从 Oracle Analytics 连接到 OCI 租户时，可以使用 OCI API 密钥或资源主体。

注：

对于资源主体，要将所有分析实例包含在一个区间下，请指定 {request.principal.type='analyticsinstance', request.principal.compartment.id='<compartmentA_ocid>'}，而非 {request.principal.id='<analytics_instance_ocid>'}。
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>'}
动态组策略 说明
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_ocid> 是包含函数的区间的 Oracle Cloud ID。

使用 OCI 函数转换数据的典型工作流

可按照下面所列顺序执行这些高级任务，以使用 OCI 函数转换 Oracle Analytics 中的数据。

任务 说明 详细信息

在 OCI 中创建函数（需要函数开发人员权限）

在 OCI 租户中，创建函数，并确保它们符合指定的先决条件以用于 Oracle Analytics。

关于配置要在 Oracle Analytics 中使用的 OCI 函数
分配 OCI 策略 确保您具有使用 API 密钥或资源主体进行连接所需的 OCI 策略。 将 OCI 函数与 Oracle Analytics 集成所需的策略
将 Oracle Analytics 连接到 OCI 租户（需要管理员或 DV 作者权限） 在 Oracle Analytics 中，创建与 OCI 租户的连接。

创建与 Oracle Cloud Infrastructure 租户的连接
在 Oracle Analytics 中注册 OCI 函数（需要管理员或 DV 作者权限） 在 Oracle Analytics 中，注册 OCI 函数，以便可以从数据流调用它们。

在 Oracle Analytics 中注册 OCI 函数
使用 OCI 函数转换数据（需要管理员或 DV 作者权限） 创建数据流，并使用应用定制脚本步骤调用 OCI 函数。

使用 OCI 函数转换数据

在 Oracle Analytics 中注册 OCI 函数

可在 Oracle Analytics 中注册 OCI 函数，以便可以在数据流中使用它们转换数据。例如，您可以注册语言转换函数，以便数据分析师可以将英语文本转换为西班牙语或德语。

  1. 在 Oracle Analytics 中的主页上，依次单击页菜单、注册模型/函数和 OCI 函数。
  2. 在注册定制函数对话框中，选择与您的函数所在 OCI 租户的连接。
  3. 在选择应用程序对话框中，选择包含您的 OCI 函数的应用程序。
    如果您不确定，请咨询在 OCI 中创建函数的人员。
  4. 在选择函数对话框中，选择函数，然后单击注册。
    如果要使用的函数灰显，请联系管理员以确保针对 Oracle Analytics 配置了该函数。请参见关于配置要在 Oracle Analytics 中使用的 OCI 函数。
可以在数据流中使用注册的 OCI 函数来转换数据。要确认注册了哪些函数，可以在机器学习页的脚本选项卡（在主页上，依次单击导航器 用于显示导航器的“导航器”图标、机器学习和脚本）上查看注册的函数。