Intégration d'Oracle Analytics à OCI Functions

Intégrez les fonctions Oracle Cloud Infrastructure (OCI) à Oracle Analytics de façon à pouvoir les utiliser dans des flux de données pour transformer des données.

A propos de l'utilisation des fonctions OCI dans Oracle Analytics

Dans Oracle Analytics, vous pouvez transformer des données à l'aide de fonctions créées dans OCI. Vous pouvez par exemple utiliser une fonction de conversion de langue pour remplacer un texte en anglais par de l'espagnol ou de l'allemand.

Commencez par inscrire des fonctions OCI dans Oracle Analytics. N'importe quel utilisateur Oracle Analytics doté de privilèges Administrateur de service BI ou Auteur de contenu DV peut ensuite s'en servir dans des flux de données.

A propos de la configuration de fonctions OCI à utiliser dans Oracle Analytics

Créez des fonctions dans la console OCI de façon à pouvoir les utiliser pour transformer des données dans des flux de données Oracle Analytics.

A propos de l'inscription de fonctions OCI dans Oracle Analytics

Lorsque vous inscrivez une fonction OCI dans Oracle Analytics, si elle est grisée dans la boîte de dialogue Sélectionner une fonction, vérifiez qu'elle est configurée avec la balise oac-compatible et appelée avec la valeur funcMode appropriée.
La description de GUID-6FE05B2C-5352-4953-998F-D967B6BA1891-default.png est la suivante
.png

A propos de la configuration de fonctions OCI à utiliser dans Oracle Analytics

Les fonctions OCI à utiliser dans Oracle Analytics doivent comporter une balise oac-compatible et le code de fonction doit inclure la variable funcMode. Configurez ces paramètres dans la console OCI :

oac-compatible : ajoutez à la fonction une balise de forme libre portant le nom oac-compatible et définissez la valeur sur true.
.png
funcMode : incluez la variable funcMode dans le code de fonction. Oracle Analytics envoie une demande d'inscription d'une fonction OCI avec funcMode=describeFunction et une demande d'appel d'une fonction OCI avec funcMode=executeFunction. La fonction de gestionnaire dans func.py doit être exécutée en mode describeFunction ou executeFunction. Comme illustré ci-après, la valeur de la variable d'entrée funcMode de la demande permet de l'indiquer.

.png

Voici le format de demande et de réponse des fonctions OCI pour un exemple de décompte de mots dans Python.

funcMode = describeFunction
```
{ "funcMode": "describeFunction"}
```
Lorsque funcMode est défini sur 'describeFunction' dans la demande, la fonction doit renvoyer la définition de fonction avec status (returnCode et errorMessage), outputs (name, dataType pour la colonne de sortie), parameters (name, description, type, etc. pour le paramètre d'entrée), bucketName, etc. en tant qu'objet JSON au format suivant (exemple du décompte de mots) :
```
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
    }
}
```
Ajoutez le code suivant dans func.py pour renvoyer funcDefinition quand funcMode est défini sur 'describeFunction' dans la demande.
```
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 : lorsque funcMode est défini sur 'executeFunction', la logique de fonction réelle doit être exécutée et la réponse renvoyée à Oracle Analytics avec la sortie. Lorsque la fonction inscrite est appelée à partir du flux de données dans Oracle Analytics, l'objet de demande est au format suivant avec le nom de colonne dans args, input (bucketName, fileName, fileExtension, fileName, method et rowID) et output (bucketName, fileName et 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"
    }
}
```

A propos de la création de fonctions dans OCI

Vous pouvez créer des fonctions à l'aide de la console OCI, de la ligne de commande (interface de ligne de commande du projet Fn) ou de l'API. Par exemple, dans la console OCI, cliquez sur Services de développement, puis sur Fonctions et suivez les instructions affichées à l'écran pour créer des applications et des fonctions. Pour plus d'informations, reportez-vous à Création de fonctions dans la documentation OCI. Si vous créez des fonctions pour la première fois, suivez les étapes de l'exemple complet Création, déploiement et appel d'une fonction HelloWorld. Les fonctions à utiliser dans Oracle Analytics doivent comporter la balise de forme libre oac-compatible=true (reportez-vous à A propos de la configuration de fonctions OCI à utiliser dans Oracle Analytics ci-avant).

Conseils pour la création de fonctions dans la console OCI

Activation des journaux : par défaut, les journaux sont désactivés pour les fonctions. Afin d'activer des journaux pour les fonctions, sur la page Applications, cliquez sur Journaux et activez le journal indiqué dans Nom de journal. Sous Ressources, vous pouvez maintenant sélectionner Explorer le journal et explorer les entrées de journal pour déboguer et diagnostiquer les problèmes de fonction.
Inclusion des dépendances : incluez des packages dépendants dans le fichier requirements.txt de la fonction.
Suivi des règles d'indentation : suivez les règles d'indentation Python lorsque vous codez des fonctions Python.
Utilisation des erreurs de réponse de fonction : utilisez les détails d'erreur répertoriés sur la page Flux de données pour diagnostiquer les problèmes.
Test des fonctions en local dans un premier temps : avant de créer une fonction dans OCI, testez-la localement dans l'environnement de développement afin de vérifier l'exactitude de sa syntaxe et de sa logique.
Test des fonctions dans OCI : avant d'intégrer des fonctions à Oracle Analytics, vérifiez que vous pouvez les déployer et les appeler en tant que fonctions autonomes dans OCI.
Augmentation du délai d'expiration : par défaut, les fonctions expirent après 30 secondes. Si besoin, augmentez le paramètre d'expiration (par exemple, remplacez-le par 300 secondes) sur la page Modifier la fonction dans la console OCI.
Augmentation de la mémoire : par défaut, les fonctions disposent d'une limite de mémoire de 1024 Mo. Si besoin, augmentez la limite de mémoire sur la page Modifier la fonction dans la console OCI.
Optimisation de l'espace : supprimez les fichiers inutiles immédiatement après utilisation.
Prise en compte de la latence réseau : gardez à l'esprit que la latence réseau peut entraîner un léger retard du traitement global.

Stratégies requises pour intégrer OCI Functions à Oracle Analytics

Pour intégrer Oracle Analytics à OCI Functions, assurez-vous que les stratégies de sécurité requises sont en place.

L'utilisateur OCI indiqué dans la connexion entre Oracle Analytics Cloud et votre location OCI doit disposer des droits d'accès en écriture, lecture et suppression sur le compartiment contenant les ressources OCI à utiliser. Assurez-vous que l'utilisateur OCI fait partie d'un groupe d'utilisateurs avec au moins les stratégies de sécurité OCI suivantes . Lorsque vous vous connectez à une location OCI à partir d'Oracle Analytics, vous pouvez utiliser une clé d'API OCI ou un principal de ressource.

Remarque : pour le principal de ressource, afin d'inclure toutes les instances Analytics dans un compartiment, spécifiez {request.principal.type='analyticsinstance', request.principal.compartment.id='<compartmentA_ocid>'} au lieu de {request.principal.id='<analytics_instance_ocid>'}.

Tableau 32-1 Stratégies de sécurité requises pour l'intégration d'OCI Functions

Stratégies avec clé d'API	Stratégies avec principal de ressource
`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>'}`

Tableau 32-2 OCI Functions - Stratégies de groupe dynamique

Stratégie	Description
`Allow dynamic-group <dynamic_group> to manage objects in compartment <compartment_name> where target.bucket.name='<staging_bucket_name>'`	Permet d'accéder au bucket intermédiaire pour le groupe dynamique.

Exemple de règle de correspondance pour <dynamic_group>.{resource.type = 'fnfunc', resource.compartment.id = '<compartment_ocid>'}

Remarque : <compartment_id> est l'OCID du compartiment contenant les fonctions.

Workflow standard pour la transformation de données à l'aide de fonctions OCI

Suivez ces tâches de haut niveau dans l'ordre ci-après pour transformer des données dans Oracle Analytics à l'aide de fonctions OCI.

Tâche	Description	Informations complémentaires
Créer des fonctions dans OCI (privilèges de développeur de fonctions requis)	Dans la location OCI, créez des fonctions et vérifiez qu'elles respectent les prérequis indiqués pour une utilisation avec Oracle Analytics.	A propos de la configuration de fonctions OCI à utiliser dans Oracle Analytics
Affecter des stratégies OCI	Assurez-vous que vous appliquez les stratégies OCI requises à des fins de connexion à l'aide de la clé d'API ou du principal de ressource.	Stratégies requises pour intégrer OCI Functions à Oracle Analytics
Connecter Oracle Analytics à la location OCI (privilèges d'administrateur ou d'auteur de contenu DV requis)	Dans Oracle Analytics, créez une connexion à la location OCI.	Création d'une connexion à la location OCI
Inscrire des fonctions OCI dans Oracle Analytics (privilèges d'administrateur ou d'auteur de contenu DV requis)	Dans Oracle Analytics, inscrivez les fonctions OCI de manière à pouvoir les appeler à partir de flux de données.	Inscription de fonctions OCI dans Oracle Analytics
Transformer les données à l'aide des fonctions OCI (privilèges d'administrateur ou d'auteur de contenu DV requis)	Créez un flux de données et utilisez l'étape Appliquer un script personnalisé pour appeler une fonction OCI.	Transformation des données à l'aide des fonctions OCI

Inscription de fonctions OCI dans Oracle Analytics

Inscrivez les fonctions OCI dans Oracle Analytics de façon à pouvoir les utiliser dans des flux de données pour transformer des données. Vous pouvez par exemple inscrire une fonction de conversion de langue afin que des analystes de données puissent remplacer un texte en anglais par de l'espagnol ou de l'allemand.

Dans Oracle Analytics, sur la page d'accueil, cliquez sur Menu de la page, sur Inscrire un modèle/une fonction, puis sur Fonctions OCI.
Dans la boîte de dialogue Inscrire une fonction personnalisée, sélectionnez une connexion à la location OCI dans laquelle se trouvent vos fonctions.
Dans la boîte de dialogue Sélectionner une application, sélectionnez l'application qui contient vos fonctions OCI.
En cas de doute, adressez-vous à la personne qui a créé les fonctions dans OCI.
Dans la boîte de dialogue Sélectionner une fonction, sélectionnez une fonction, puis cliquez sur Inscrire.
Si la fonction que vous voulez utiliser est grisée, vérifiez auprès de l'administrateur qu'elle est configurée pour Oracle Analytics. Reportez-vous à A propos de la configuration de fonctions OCI à utiliser dans Oracle Analytics.

Vous pouvez utiliser les fonctions OCI inscrites dans des flux de données pour transformer des données. Pour connaître les fonctions inscrites, vous pouvez consulter l'onglet Scripts de la page Apprentissage automatique (sur la page d'accueil, cliquez sur Navigateur, Apprentissage automatique, puis Scripts).