Интеграция Oracle Analytics с функциями OCI

Интегрируйте функции Oracle Cloud Infrastructure (OCI) с Oracle Analytics, чтобы использовать их в потоках данных для преобразования данных.

Использование функций OCI в Oracle Analytics

Можно преобразовать данные в Oracle Analytics с помощью функций, созданных в OCI. Например, можно использовать функцию преобразования языка для преобразования английского текста в испанский или немецкий.

Сначала вы регистрируете функции OCI в Oracle Analytics, а затем любой пользователь Oracle Analytics с полномочиями администратора сервиса BI или автором контента DV может использовать их в потоках данных.

Настройка функций OCI для использования в Oracle Analytics

Создайте функции в консоли OCI, чтобы их можно было использовать для преобразования данных в потоки данных Oracle Analytics.

Регистрация функций OCI в Oracle Analytics

Если при регистрации функции OCI в Oracle Analytics она затеняется серым цветом в диалоговом окне "Выбор функции", с помощью тега oac-compatible убедитесь, что она настроена и вызывается с правильным значением funcMode.
Описание GUID-6FE05B2C-5352-4953-998F-D967B6BA1891-default.png ниже
.png

Настройка функций OCI для использования в Oracle Analytics

Функции OCI, которые необходимо использовать в Oracle Analytics, должны иметь тег oac-compatible, а код функции должен включать переменную funcMode. Настройте следующие параметры в консоли OCI.

oac-compatible: добавьте к функции произвольный тег с именем oac-compatible и установите значение true.
.png
funcMode : включите переменную funcMode в код функции. Oracle Analytics отправляет запрос на регистрацию функции OCI с кодом funcMode=describeFunction и запрос на вызов функции OCI с кодом funcMode=executeFunction. Функция обработчика в func.py должна работать в режиме describeFunction или executeFunction. Это можно сделать на основе значения входной переменной funcMode из запроса, как показано ниже.

.png

Ниже представлен формат запроса и ответа на примере функций OCI для подсчета слов в Python.

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
    }
}
```
Добавьте следующий код в func.py, чтобы возвращать funcDefinition, когда funcMode в запросе имеет значение "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: если funcMode имеет значение "executeFunction", необходимо выполнить фактическую логику функции, а ответ должен быть отправлен назад в Oracle Analytics вместе с выходными данными. Когда зарегистрированная функция вызывается из потока данных в Oracle Analytics, объект запроса будет иметь следующий формат с именем столбца в аргументах: 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. При первом создании функций следуйте инструкциям, приведенным в подробном примере Создание, развертывание и вызов функций HelloWorld. Любые функции, которые необходимо использовать в Oracle Analytics, должны иметь произвольный тег oac-compatible=true (см. раздел Настройка функций OCI для использования в Oracle Analytics выше).

Советы по созданию функций в консоли OCI

Включите журналы. По умолчанию журналы для функций отключены. Чтобы включить журналы для функций, на странице Приложения нажмите Журналы и включите журнал, указанный в поле Имя журнала. В разделе Ресурсы теперь можно выбрать Просмотр журнала и получить доступ к записям журнала для отладки и диагностики неполадок функций.
Включите зависимости. Включите зависимые пакеты в файл requirements.txt для функции.
Следуйте правилам отступов. Следуйте правилам отступов Python при написании программного кода функций Python.
Используйте ошибки ответа функции. Для диагностики неполадок используйте сведения об ошибке, указанные на странице "Поток данных".
Сначала проверьте функции локально. Прежде чем создавать функцию в OCI, проверьте ее локально в среде разработки, чтобы убедиться, что функция синтаксически и логически верна.
Проверьте функции в OCI. Перед интеграцией функций с Oracle Analytics убедитесь, что удастся развернуть и вызвать их в качестве автономных функций в OCI.
Увеличьте время ожидания. По умолчанию время ожидания функций — 30 секунд. При необходимости увеличьте значение времени ожидания (например до 300 секунд) на странице редактирования функции в консоли OCI.
Увеличьте объем памяти. По умолчанию для функций установлено ограничение памяти — 1024 МБ. При необходимости увеличьте объем памяти на странице редактирования функции в консоли OCI.
Оптимизируйте пространство. Удаляйте неиспользуемые файлы сразу после использования.
Учитывайте задержку сети. Помните, что задержка сети может вызвать небольшую задержку общей обработки.

Политики, необходимые для интеграции функций OCI с Oracle Analytics

Для интеграции Oracle Analytics с функциями OCI убедитесь в наличии необходимых политик безопасности.

Пользователь OCI, указанный в подключении между Oracle Analytics Cloud и арендой OCI, должен иметь разрешения на чтение, запись и удаление в пространстве, содержащем необходимые ресурсы OCI. Убедитесь, что пользователь OCI принадлежит к группе пользователей со следующими минимальными политиками безопасности OCI. При подключении к аренде OCI из Oracle Analytics можно использовать API-ключ OCI или субъект ресурсов.

Примечание. Для субъекта ресурсов: чтобы включить все экземпляры Analytics в пространстве, укажите {request.principal.type='analyticsinstance', request.principal.compartment.id='<compartmentA_ocid>'} вместо {request.principal.id='<analytics_instance_ocid>'}.

Таблица 31-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>'}`

Таблица 31-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.

Задача	Описание	Дополнительная информация
Создание функций в OCI (требуются полномочия разработчика функций)	В аренде OCI создайте функции и убедитесь, что они соответствуют предварительным условиям, указанным для использования с Oracle Analytics.	Настройка функций OCI для использования в Oracle Analytics
Назначение политик OCI	Убедитесь в наличии политик OCI, необходимых для подключения с помощью ключа API или субъекта ресурсов.	Политики, необходимые для интеграции функций OCI с Oracle Analytics
Подключение Oracle Analytics к аренде OCI (требуются полномочия администратора или автора DV)	В Oracle Analytics создайте подключение к аренде OCI.	Создание подключения к аренде OCI
Регистрация функций OCI в Oracle Analytics (требуются полномочия администратора или автора DV)	В Oracle Analytics зарегистрируйте функции OCI, чтобы их можно было вызывать из потоков данных.	Регистрация функций OCI в Oracle Analytics
Преобразование данных с помощью функций OCI (требуются полномочия администратора или автора DV)	Создайте поток данных и используйте шаг Применить нестандартный сценарий, чтобы вызвать функцию OCI.	Преобразование данных с помощью функций OCI

Регистрация функций OCI в Oracle Analytics

Зарегистрируйте функции OCI в Oracle Analytics, чтобы использовать их в потоках данных для преобразования данных. Например, можно зарегистрировать функцию преобразования языка, чтобы аналитики данных могли преобразовать английский текст в испанский или немецкий.

На главной странице Oracle Analytics нажмите Меню страницы, выберите Регистрация модели/функции, а затем нажмите Функции OCI.
В диалоговом окне "Регистрация нестандартной функции" выберите подключение к аренде OCI, в которой расположены функции.
В диалоговом окне "Выбор приложения" выберите приложение, содержащее функции OCI.
Если вы не уверены, спросите человека, создавшего функции в OCI.
В диалоговом окне "Выбор функции" выберите функцию, затем нажмите Зарегистрировать.
Если функция, которую необходимо использовать, затенена серым цветом, попросите администратора проверить, что она настроена для Oracle Analytics. См. раздел "Настройка функций OCI для использования в Oracle Analytics".

Можно использовать зарегистрированные функции OCI в потоках данных для преобразования данных. Чтобы проверить, какие функции зарегистрированы, можно использовать вкладку "Сценарии" страницы "Машинное обучение" (на главной странице нажмите Навигатор, затем Машинное обучение и Сценарии).