Integración de Oracle Analytics con OCI Functions

Integre las funciones de Oracle Cloud Infrastructure (OCI) con Oracle Analytics para utilizarlas en flujos de datos para transformar datos.

Acerca del uso de funciones de OCI en Oracle Analytics

Puede transformar datos en Oracle Analytics mediante funciones creadas en OCI. Por ejemplo, puede utilizar una función de conversión de idioma para convertir texto en inglés en texto en español o alemán.

Primero puede registrar funciones de OCI en Oracle Analytics y, después, cualquier usuario de Oracle Analytics con privilegios de administrador de servicio de BI o de autor de contenido de DV podrá usarlas en flujos de datos.

Acerca de la configuración de las funciones de OCI para usarlas en Oracle Analytics

Cree funciones en la consola de OCI para poder utilizarlas para transformar datos en flujos de datos de Oracle Analytics.

Acerca del registro de funciones de OCI en Oracle Analytics

Cuando registra una función de OCI en Oracle Analytics, si aparece atenuada en el cuadro de diálogo Seleccionar una función, compruebe que se ha configurado con la etiqueta oac-compatible y que se ha llamado con el valor funcMode correcto.
A continuación se muestra la descripción de GUID-6FE05B2C-5352-4953-998F-D967B6BA1891-default.png
.png

Acerca de la configuración de las funciones de OCI para usarlas en Oracle Analytics

Las funciones de OCI que desee utilizar en Oracle Analytics deben tener una etiqueta oac-compatible y el código de la función debe incluir la variable funcMode. Configure estos valores en la consola de OCI:

oac-compatible: agregue una etiqueta de formato libre a la función con el nombre oac-compatible y establezca el valor en true.
.png
funcMode : incluya la variable funcMode en el código de la función. Oracle Analytics envía una solicitud para registrar una función de OCI con funcMode=describeFunction y una solicitud para llamar a una función de OCI con funcMode=executeFunction. La función de manejador en func.py debe funcionar en modo describeFunction o en modo executeFunction. Esto se puede realizar en función del valor de la variable de entrada funcMode de la solicitud como se muestra a continuación.

.png

Se muestra la solicitud y el formato de respuesta de las funciones de OCI para un ejemplo de recuento de palabras en Python.

funcMode = describeFunction
```
{ "funcMode": "describeFunction"}
```
Cuando funcMode en la solicitud sea "describeFunction", la función debe devolver la definición de la función con status (returnCode y errorMessage), outputs (name, dataType de la columna de salida), parameters (name, description, type, etc., del parámetro de entrada), bucketName, etc., como un objeto JSON en el siguiente formato (ejemplo de recuento de palabras):
```
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
    }
}
```
Agregue el siguiente código en func.py para devolver funcDefinition cuando funcMode en la solicitud sea "describeFunction".
```
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: cuando funcMode sea "executeFunction", la lógica de la función real debería ejecutarse y la respuesta debería enviarse de nuevo a Oracle Analytics con la salida. Cuando la función registrada se llama desde el flujo de datos en Oracle Analytics, el objeto de solicitud estará en el siguiente formato con el nombre de la columna en argumentos, input(bucketName, fileName, fileExtension, fileName, method y rowID) y output(bucketName, fileName y 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"
    }
}
```

Acerca de la creación de funciones en OCI

Puede crear funciones con la consola de OCI, la línea de comandos (CLI de Fn Project) o la API. Por ejemplo, en la consola de OCI, haga clic en Servicios para desarrolladores y, a continuación, en Funciones y siga las instrucciones de la pantalla para crear aplicaciones y una o más funciones. Para obtener más información, consulte Creación de funciones en Documentación de OCI. Si es la primera vez que crea funciones, siga los pasos del ejemplo completo de Creación, despliegue y llamada de una función Hola mundo. Cualquier función que desee utilizar en Oracle Analytics debe incluir la etiqueta de formato libre oac-compatible=true (consulte Acerca de la configuración de las funciones de OCI para usarlas en Oracle Analytics más arriba).

Consejos sobre la creación de funciones en la consola de OCI

Activar logs: los logs están desactivados por defecto para las funciones. Para activar los logs para las funciones, en la página Aplicaciones, haga clic en Logs y active el log proporcionado para Nombre de log. En Recursos, ahora puede seleccionar Explorar log y consultar las entradas de log para depurar y diagnosticar problemas de la función.
Incluir dependencias: incluya paquetes dependientes en el archivo requirements.txt para la función.
Seguir reglas de sangría: siga las reglas de sangría de Python mientras codifica funciones Python.
Usar errores de respuesta de función: utilice los detalles de error indicados en la página Flujo de datos para diagnosticar problemas.
Probar funciones localmente primero: antes de crear una función en OCI, pruébela localmente en su entorno de desarrollo para asegurarse de que la sintaxis y la lógica de la función sean correctas.
Probar funciones en OCI: antes de integrar funciones con Oracle Analytics, asegúrese de que puede desplegarlas y llamarlas correctamente como funciones autónomas en OCI.
Aumentar el timeout: las funciones tienen un timeout de 30 segundos por defecto. Si es necesario, aumente el valor de timeout (por ejemplo, cámbielo a 300 segundos) en la página Editar función de la consola de OCI.
Incrementar la memoria: las funciones tienen un límite de memoria de 1024 MB por defecto. Si es necesario, incremente el límite de memoria en la página Editar función de la consola de OCI.
Optimizar el espacio: elimine los archivos que no vaya a utilizar inmediatamente después de utilizarlos.
Cuidado con la latencia de red: tenga en cuenta que la latencia de red puede causar un ligero retraso en todo el procesamiento.

Políticas necesarias para integrar OCI Functions con Oracle Analytics

Para integrar Oracle Analytics con OCI Functions, asegúrese de que tiene las políticas de seguridad necesarias.

El usuario de OCI que especifique en la conexión entre Oracle Analytics Cloud y su arrendamiento de OCI debe tener permisos de lectura, escritura y supresión en el compartimento que contiene los recursos de OCI que desea utilizar. Asegúrese de que el usuario de OCI pertenece a un grupo de usuarios con las siguientes políticas de seguridad de OCI mínimas. Al conectarse a un arrendamiento de OCI desde Oracle Analytics, puede utilizar una clave de API o una entidad de recurso de OCI.

Nota: En el caso de la entidad de recurso, para incluir todas las instancias de Analytics de un compartimento, especifique {request.principal.type='analyticsinstance', request.principal.compartment.id='<compartmentA_ocid>'} en lugar de {request.principal.id='<analytics_instance_ocid>'}.

Tabla 32-1 Políticas de seguridad necesarias para la integración de OCI Functions

Políticas de clave de API	Políticas de entidad de recurso
`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>'}`

Tabla 32-2 OCI Functions - Políticas de grupo dinámico

Política	Descripción
`Allow dynamic-group <dynamic_group> to manage objects in compartment <compartment_name> where target.bucket.name='<staging_bucket_name>'`	Proporciona acceso al cubo temporal para el grupo dinámico.

Ejemplo de regla de coincidencia para <dynamic_group>.{resource.type = 'fnfunc', resource.compartment.id = '<compartment_ocid>'}

Nota: <compartment_id> es el OCID del compartimento que contiene las funciones.

Flujo de trabajo típico para transformar los datos mediante funciones de OCI

Siga estas tareas de alto nivel en el orden indicado a continuación para transformar los datos de Oracle Analytics mediante funciones de OCI.

Tarea	Descripción	Más información
Crear funciones en OCI (requiere privilegios de desarrollador de funciones)	En el arrendamiento de OCI, cree las funciones y asegúrese de que cumplen con los requisitos previos especificados para usarlas con Oracle Analytics.	Acerca de la configuración de las funciones de OCI para usarlas en Oracle Analytics
Asignar políticas de OCI	Asegúrese de que tiene las políticas de OCI necesarias para conectarse mediante la clave de API o el principal de recurso.	Políticas necesarias para integrar OCI Functions con Oracle Analytics
Conectar Oracle Analytics al arrendamiento de OCI (requiere privilegios de administrador o de autor de contenido de DV)	En Oracle Analytics, cree una conexión al arrendamiento de OCI.	Creación de una conexión al arrendamiento de OCI
Registrar funciones de OCI en Oracle Analytics (requiere privilegios de administrador o de autor de contenido de DV)	En Oracle Analytics, registre las funciones de OCI para que pueda llamarlas desde flujos de datos.	Registro de funciones de OCI en Oracle Analytics
Transformar datos mediante las funciones de OCI (requiere privilegios de administrador o de autor de contenido de DV)	Cree un flujo de datos y utilice el paso Aplicar script personalizado para llamar a una función de OCI.	Transformación de datos con las funciones de OCI

Registro de funciones de OCI en Oracle Analytics

Registre funciones de OCI en Oracle Analytics para utilizarlas en flujos de datos para transformar datos. Por ejemplo, puede registrar una función de conversión de idioma para que los analistas de datos puedan convertir texto en inglés en texto en español o alemán.

En Oracle Analytics, en la página de inicio, haga clic en Menú de página, en Registrar modelo/función y, a continuación, en Funciones de OCI.
En el cuadro de diálogo Registrar una función personalizada, seleccione una conexión al arrendamiento de OCI donde se encuentren las funciones.
En el cuadro de diálogo Seleccionar aplicación, seleccione la aplicación que contenga las funciones de OCI.
Si no está seguro, pregunte a la persona que ha creado las funciones en OCI.
En el cuadro de diálogo Seleccionar una función, seleccione una función y, a continuación, haga clic en Registrar.
Si la función que desea utilizar está atenuada, pida al administrador que se asegure de que está configurada para Oracle Analytics. Consulte Acerca de la configuración de las funciones de OCI para usarlas en Oracle Analytics.

Puede utilizar funciones de OCI registradas en flujos de datos para transformar datos. Para verificar las funciones que están registradas, puede verlas en el separador Scripts de la página Aprendizaje automático (en la página inicial, haga clic en Navegador, en Aprendizaje automático y, a continuación, en Scripts).