Oracle Functions : Valider une clé d'API à l'aide de la passerelle d'API

• Un compte Oracle Cloud Infrastructure payant. Voir Inscription à Oracle Cloud Infrastructure.
• Un compte OCI configuré pour prendre en charge le développement avec Oracle Functions. Voir Démarrage rapide avec Oracle Functions sur Cloud Shell.
• Vous devez avoir suivi l'un des deux tutoriels d'introduction à Oracle Functions.
  • Oracle Functions : Démarrer avec Cloud Shell
  • Oracle Functions : Démarrer à l'aide de la CLI
• Voici les résultats obtenus après l'exécution de ces deux tutoriels :
  • Oracle Functions est configuré pour créer des applications et déployer des fonctions.
  • Oracle Registry est configuré pour stocker des images de fonction.
  • Docker est connecté à Oracle Registry.
  • Vous disposez du VCN requis et des ressources requises pour Oracle Functions.
  • Vous disposez d'une paire de clés d'API et d'un jeton d'authentification.

Interface de ligne de commande Oracle

• Python 3.6+ et pip3.
• Moteur Docker : Ordinateur Linux ou machine virtuelle Linux. Voir les exigences en matière de moteur Docker pour connaître les versions et les distributions prises en charge.
• Docker Desktop : Disponible pour MacOS ou Windows 10.
  • Windows 10 : Mise à jour Windows 10 2004 avec WSL 2 et Ubuntu ou toute autre distribution installée.
    • Consultez le guide d'installation du sous-système Windows pour Linux sous Windows 10.
    • Installez Docker Desktop pour Windows 10.
    Note
    
    Docker inclut une prise en charge spéciale de Linux pour WSL 2 sous la mise à jour Windows 10 2004.
  • MacOS : Consultez la page relative à l'installation de Docker Desktop pour MacOS.

Oracle Cloud Shell

• Si vous utilisez Cloud Shell, les logiciels répertoriés dans la liste précédente sont déjà installés.

Pour créer un compartiment, voir Créer un compartiment. Une fois votre compartiment créé, enregistrez son OCID et son nom.

Pour obtenir l'OCID du compartiment à partir d'un compartiment existant :

1. Ouvrez le menu de navigation et cliquez sur Identité et sécurité. Sous Identité, cliquez sur Compartiments.
2. Sélectionnez votre compartiment.
3. Cliquez sur le lien Copier pour le champ OCID.

Enregistrez l'OCID et le nom du compartiment.

Notez les informations suivantes pour le tutoriel.

• Nom du compartiment : <your-compartment-name>

  Exemple : mon compartiment

• ID compartiment : <your-compartment-OCID>

  Exemple : ocid1.compartment.oc1.aaaaaaa...

• Nom du VCN : <your-vcn-name>

  Exemple : mon VCN

  Ouvrez le menu de navigation et cliquez successivement sur Service de réseau et Réseaux en nuage virtuels.

• Nom du sous-réseau public du réseau VCN : <Public-Subnet-your-vcn-name>

  Exemple : Public-Subnet-my-vcn

  Ouvrez le menu de navigation et cliquez successivement sur Service de réseau et Réseaux en nuage virtuels. Cliquez sur le VCN que vous avez créé.

Pour créer une application, procédez de la façon suivante.

1. Ouvrez le menu de navigation et cliquez sur Services de développement. Sous Fonctions, cliquez sur Applications.
2. Sélectionnez votre compartiment dans la liste déroulante Compartiments.
3. Cliquez sur Créer une application.
4. Complétez le formulaire.
   • Nom : <your-app-name>
   • VCN : <your-vcn-name>
   • Sous-réseaux : <Public-Subnet-your-vcn-name>
5. Cliquez sur Créer.

Votre application est créée.

1. Ouvrez le menu de navigation et cliquez successivement sur Service de réseau et Réseaux en nuage virtuels.
2. Cliquez sur le nom du VCN que vous avez utilisé pour votre application Oracle Functions.
3. Maintenant que votre nouveau VCN est affiché, cliquez sur le lien de sous-réseau Public.

   Les informations sur le sous-réseau public s'affichent avec les listes de sécurité au bas de la page.

4. Cliquez sur le lien Liste de sécurité par défaut ou sur le lien de liste de sécurité approprié.

   Les règles de trafic entrant par défaut pour votre VCN s'affichent.

5. Cliquez sur Ajouter des règles de trafic entrant.

   Une boîte de dialogue Ajouter des règles de trafic entrant s'affiche.

6. Entrez les informations suivantes pour la règle de trafic entrant. Une fois toutes les données entrées, cliquez sur Ajouter des règles de trafic entrant

   Définissez la règle de trafic entrant comme suit :

   • Sans état : Coché
   • Type de source : CIDR
   • CIDR source : 0.0.0.0/0
   • Protocole IP : TCP
   • Intervalle de ports sources : (Laissez vide)
   • Intervalle de ports de destination : 443
   • Description : VCN pour les applications

   Après que vous avez cliqué sur Ajouter une règle de trafic entrant, les connexions HTTPS à votre sous-réseau public sont autorisées.

À présent, configurez une politique qui permet à la passerelle d'API d'appeler des fonctions.

Commencez par créer un groupe dynamique pour la passerelle d'API.

1. Ouvrez le menu de navigation et cliquez sur Identité et sécurité. Sous Identité, cliquez sur Groupes dynamiques.
2. Cliquez sur Créer un groupe dynamique.
3. Indiquez les informations suivantes pour définir votre groupe dynamique.
   • Nom : <name-for-your-dynamic-group>
   • Sous Règles de correspondance, utilisez Règle 1 : <the-rule-text>

   Voici le nom d'exemple et la règle que vous devez entrer.

   • Nom : api-gtw-func-dynamic-group
   • Sous Règles de correspondance, utilisez Règle 1 : Tout {resource.type = 'ApiGateway', resource.compartment.id = 'ocid1.compartment.<your-compartment-OCID>'}
4. Cliquez sur Créer.

À présent, créez la politique pour la passerelle d'API.

1. Ouvrez le menu de navigation et cliquez sur Identité et sécurité. Sous Identité, cliquez sur Politiques.
2. Cliquez sur Créer une politique.
3. Pour définir votre politique, entrez les informations suivantes.
   • Nom : <name-for-your-policy>
   • Description : <description-for policy>
   • compartiment : <name-of-functions-compartment>

   Pour la section Générateur de politiques :

   • Cliquez sur Afficher l'éditeur manuel.
   • Entrez votre politique dans la zone de texte, par exemple :

     Allow dynamic-group  api-gtw-func-dynamic-group to use functions-family in compartment <your-compartment-name>

     Note
     
     Le dernier paramètre est le nom et non l'OCID du compartiment.
4. Cliquez sur Créer.

Vous avez créé une politique pour permettre à la passerelle d'API d'utiliser le service des fonctions.

1. Ouvrez une fenêtre de terminal.
2. Créez un répertoire dans lequel stocker vos fonctions et accédez à ce répertoire.

   mkdir my-dir-name
   cd my-dir-name                        
                        

3. Créez une fonction Python "Hello World" avec Fn.

   fn init --runtime python my-func-name

   Cette commande crée un répertoire nommé my-func-name contenant la fonction et des fichiers de configuration.

4. Accédez au répertoire.
5. Déployez la fonction.

   fn -v deploy --app your-app-name

   Divers messages s'affichent au fur et à mesure que les images Docker sont créées, poussées vers OCIR, puis déployées dans Oracle Functions.

6. Appelez la fonction.

   fn invoke your-app-name my-func-name

   Retourne : {"message": "Hello World"}

7. Appelez la fonction avec un paramètre.

   echo -n '{"name":"Bob"}' | fn invoke your-app-name my-func-name

   Retourne : {"message": "Hello Bob"}

Pour créer une passerelle d'API :

1. Ouvrez le menu de navigation et cliquez sur Services de développement. Sous Gestion d'API, cliquez sur Passerelles.
2. Sélectionnez votre compartiment dans la liste déroulante Compartiments.
3. Cliquez sur Créer une passerelle
4. Indiquez les informations suivantes pour définir votre passerelle d'API.
   • Nom : <your-gateway-name>
   • Type : <Public>
   • compartiment : <your-compartment-name>
   • Réseau en nuage virtuel dans <your-vcn-name>: <select-your-vcn>
   • Sous-réseau dans <your-compartment-name: <your-public-subnet-name>
5. Cliquez sur Créer. Attendez quelques minutes que votre passerelle d'API soit créée.

À présent, créez un déploiement pour votre passerelle d'API.

1. Cliquez sur Déploiements dans la section Ressources située dans la partie gauche de l'écran.
2. Cliquez sur Créer un déploiement.
3. Assurez-vous que À partir de zéro est sélectionné pour le type de déploiement.
4. Pour définir votre déploiement, renseignez la section Informations de base.
   • Nom : <your-deployment-name>
   • Préfixe de chemin (exemple) : /tokens
   • compartiment : <your-compartment-name>
   • Politiques de demande d'API : Utilisez les valeurs par défaut
   • Politiques de journalisation d'API : Utilisez la valeur par défaut Informations
5. Cliquez sur Suivant. La boîte de dialogue Routes s'affiche avec la valeur Route 1 sélectionnée.
6. Pour définir votre route, renseignez la section Route 1.
   • Chemin : <your-route-path>

     Exemple : /val-token

   • Modes : GET POST
   • Type : Oracle Functions
   • Application dans <your-compartment-name> : Sélectionnez l'application Oracle Functions que vous avez créée.
   • Nom de la fonction : Sélectionnez la fonction que vous avez créée à la section de configuration.
7. Cliquez sur Suivant. La boîte de dialogue Vérifier récapitulant les choix que vous avez faits s'affiche.
8. Cliquez sur Créer. Votre déploiement est créé.
9. Cliquez sur le lien Déploiements pour votre passerelle. Copiez le point d'extrémité de base pour le déploiement que vous avez créé.

   Par exemple : https://aaaaa.apigateway.us-ashburn-X.oci.customer-oic.com/tokens

Maintenant que votre passerelle d'API et votre déploiement sont créés, vous pouvez tester votre installation. Créez un script simple pour la commande curl. Pour créer l'URL de curl, ajoutez votre chemin de déploiement à votre point d'extrémité.

1. Créez le fichier de script : touch gtw01.sh && chmod 755 gtw01.sh
2. Ajoutez la commande curl au fichier de script :

   #!/bin/bash
   curl <your-api-gateway-endpoint>/val-token

3. La commande retourne : {"message":"Hello World"}

Vous avez connecté votre passerelle d'API à une fonction Python standard. À présent, vous allez mettre à jour votre fonction Python pour afficher les informations transmises dans une demande HTTP.

Si vous examinez la fonction Python standard, elle ressemble à ceci.

import io
import json
import logging

from fdk import response


def handler(ctx, data: io.BytesIO = None):
    name = "World"
    try:
        body = json.loads(data.getvalue())
        name = body.get("name")
    except (Exception, ValueError) as ex:
        logging.getLogger().info('error parsing json payload: ' + str(ex))
    
    logging.getLogger().info("Inside Python Hello World function")
    return response.Response(
       ctx, response_data=json.dumps(
           {"message": "Hello {0}".format(name)}),
       headers={"Content-Type": "application/json"}
    )

Avec ce code comme point de départ, les sections suivantes convertissent la fonction en une fonction Python qui valide une clé d'API et retourne un jeton.

Oracle Functions vous permet de stocker les données de configuration dans le contexte disponible dans votre demande. Il est possible de stocker les données de configuration dans une application ou une fonction. La commande suivante stocke la clé d'API dans la configuration de votre application.

• fn config app <your-app-name> FN_API_KEY ABCD

La chaîne "ABCD" est un exemple de valeur de clé.

Pour plus d'informations sur la définition des valeurs de configuration d'Oracle Functions, voir le tutoriel sur le contexte d'exécution FnProject.

Commencez par mettre à jour func.py avec les ensembles requis.

1. Mettez à jour les énoncés import dans func.py pour la validation des ensembles requis :

   import io
   import json
   import logging
   import datetime
   
   from datetime import timedelta
   from fdk import response
                   

   L'ensemble datetime sert à définir un délai d'expiration pour le jeton retourné.

2. Retirez le corps principal de la fonction. La méthode response et le code connexe seront ajoutés à nouveau au fur et à mesure.

   import io
   import json
   import logging
   import datetime
   
   from datetime import timedelta
   from fdk import response
                           
   
   def handler(ctx, data: io.BytesIO = None):                
   

À présent, vous pouvez mettre à jour la fonction avec le code de validation.

À présent, ajoutez du code pour valider la clé d'API et retourner un jeton dans la réponse. Voici le code avec des commentaires.

import io
import json
import logging
import datetime

from datetime import timedelta
from fdk import response

def handler(ctx, data: io.BytesIO = None):
    auth_token = "invalid"
    token = "invalid"
    apiKey = "invalid"
    expiresAt = (datetime.datetime.utcnow() + timedelta(seconds=60)).replace(tzinfo=datetime.timezone.utc).astimezone().replace(microsecond=0).isoformat()
    
    try:
        auth_token = json.loads(data.getvalue())
        token = auth_token.get("token")
        
        app_context = dict(ctx.Config())
        apiKey = app_context['FN_API_KEY']
        
        if token == apiKey:
            return response.Response(
                ctx, 
                status_code=200, 
                response_data=json.dumps({"active": True, "principal": "foo", "scope": "bar", "clientId": "1234", "expiresAt": expiresAt, "context": {"username": "wally"}})
            )
    
    except (Exception, ValueError) as ex:
        logging.getLogger().info('error parsing json payload: ' + str(ex))
        pass
    
    return response.Response(
        ctx, 
        status_code=401, 
        response_data=json.dumps({"active": False, "wwwAuthenticate": "API-key"})
    )

• La fonction handler reçoit des informations système sur la demande courante au moyen des paramètres ctx et data.
• La fonction suppose que FN_API_KEY est défini dans la configuration de l'application. Ensuite, la fonction compare la valeur de configuration à la valeur de jeton envoyée à partir de la demande POST curl : -d '{"token":"ABCD"}'.
• Si les valeurs correspondent, un message JSON de validation est retourné. Dans le cas contraire, un code 401 est retourné avec les données d'erreur JSON.

Le code de fonction est terminé. À présent, vous pouvez tester la fonction.

1. Redéployez la fonction mise à jour.
2. Appelez la fonction pour vous assurer qu'elle fonctionne.
3. Mettez à jour le script gtw01.sh pour transmettre les données POST au script.

   /bin/bash
   curl -X POST -d '{"token":"ABCD"}' https://aaaaa.apigateway.us-ashburn-X.oci.customer-oic.com/tokens/val-token

4. Exécutez le script : gtw01.sh | jq
5. Si les clés d'API correspondent, la sortie du script ressemble à ceci :

   {
       "active": true,
       "principal": "foo",
       "scope": "bar",
       "clientId": "1234",
       "expiresAt": "2020-12-16T22:48:50+00:00",
       "context": {
       "username": "wally"
       }
   }

   Si les clés d'API ne correspondent pas, un message d'erreur est retourné.

   {
       "active": false,
       "wwwAuthenticate": "API-key"
   }                        
                       

   Vous pouvez télécharger le code source complet de la fonction à partir du site des échantillons pour Oracle Functions.

Félicitations, vous avez converti la fonction Python standard en une nouvelle fonction qui valide une clé d'API. La fonction montre comment des données peuvent être transmises à la passerelle d'API et traitées dans une fonction.