Template Flask pour Embedded Python

1. intersystems-iris-docker-rest-template

Il s'agit d'un modèle d'une application REST API intégrée en python dans InterSystems IRIS. Elle possède également une spécification OPEN API et peut être développée avec Docker et VSCode.

1. intersystems-iris-docker-rest-template

2. Conditions préalables

3. Installation

3.1. Installation pour le développement

3.2. Portail de gestion et et VSCode

3.3. Avoir le répertoire ouvert à l'intérieur du conteneur

4. Comment cela fonctionne

5. Comment l'utiliser

5.1. Requête POST

5.1.1. Test de la requête POST

5.1.2. Comment fonctionne la requête POST

5.2. Requête GET

5.2.1. Test de la requête GET

5.2.2. Comment fonctionne la requête GET

5.3. Requête PUT

5.3.1. Test de la requête PUT

5.3.2. Comment fonctionne la requête PUT

5.4. Requête DELETE

5.4.1. Test de la requête DELETE

5.4.2. Comment fonctionne la requête DELETE

6. Comment commencer le codage

7. Contenu du dépôt

7.1. Dockerfile

7.2. .vscode/settings.json

7.3. .vscode/launch.json

2. Conditions préalables

Assurez-vous que vous avez installé git et Docker desktop.

Il est à noter que le tableau Sample.Person a déjà été créé à l'avance pour la démo en utilisant le portail de gestion dans l'onglet sql :

CREATE TABLE Sample.Person (
      Société                               VARCHAR(50),
      DATE DE NAISSANCE                     DATE,
      Nom                                   VARCHAR(4096),
      Téléphone                              VARCHAR(4096),
      Position                               VARCHAR(50)
)

3. Installation

3.1. Installation pour le développement

Clone/git tire le repo dans n'importe quel répertoire local, par exemple comme indiqué ci-dessous :

$ git clone https://github.com/grongierisc/iris-python-flask-api-template.git

Ouvrez le terminal dans ce répertoire et exécutez :

 $ DOCKER_BUILDKIT=1 docker-compose up -d --build

3.2. Management Portal et VSCode

Ce dépôt est prêt pour VS Code.

Ouvrez le répertoire formation-template-python cloné localement dans VS Code.

Si vous êtes invité à le faire (dans le coin inférieur droit), installez les extensions recommandées.

3.3. Avoir le répertoire ouvert à l'intérieur du conteneur

Il est vraiment important de se rendre à l'intérieur du conteneur avant de coder.

Pour cela, il faut activer docker avant d'ouvrir VSCode.

Ensuite, dans VSCode, lorsque vous y êtes invité (dans le coin inférieur droit), rouvrez le répertoire à l'intérieur du conteneur afin de pouvoir utiliser les composants python qu'il contient.

La première fois que vous faites cela, il se peut que cela prenne plusieurs minutes, le temps que le conteneur soit préparé.

Plus d'informations ici

En ouvrant le répertoire à distance, vous permettez à VS Code et à tous les terminaux que vous ouvrez dans ce répertoire d'utiliser les composants python dans le conteneur. Configurer ceux-ci pour utiliser /usr/irissys/bin/irispython

4. Comment cela fonctionne

L' app.py, une fois lancé (à l'intérieur du conteneur) va recueillir les requêtes CRUD.

En fonction du type de demande, le message approprié sera créé pour être envoyé au service FlaskService, ce service appellera l'opération CrudPerson qui, en fonction du type de message envoyé par le service, distribuera les informations nécessaires pour effectuer l'action demandée..

Pour plus de détails, vous pouvez consulter la partie How it works (Comment ça marche) de cette démo entièrement documentée this fully documented demo.

5. Comment l’utiliser

Ce modèle crée une application web REST /crud sur IRIS qui met en œuvre 4 types de communication : GET, POST, PUT et DELETE, c'est-à-dire les opérations CRUD. Cette interface fonctionne avec un exemple de classe persistante Person trouvée dans src/python/person/obj.py.

Tout d'abord, il est nécessaire de démarrer l'application 'app.py' située dans src/python/person/app.py en utilisant flask.

Pour ce faire, allez dans le fichier app.py , ensuite dans la fenêtre run and debug  de VSCode et sélectionnez Python: Flask et et ensuite exécutez. Ceci lancera l'application.

5.1. Requête POST

5.1.1. Test de la requête POST

Créez une requête POST, par exemple dans Postman ou dans RESTer pour mozilla, avec des données brutes en JSON du type suivant :

En utilisant Content-Type en tant qu’ application/json

Ajustez l'autorisation si nécessaire - elle est basique pour le conteneur avec le login et le mot de passe par défaut pour le conteneur IRIS Community edition.

Envoyez la demande POST à localhost:4040/persons/

Cette opération créera un enregistrement dans le tableau Sample.Person d'IRIS et renverra l'identifiant id de la Person nouvellement ajoutée de la requête POST pour ajouter Elon Musk dans le tableau.

5.1.2. Comment fonctionne la requête POST

 

def create_person(self,request:CreatePersonRequest):
     """
        > Créer une nouvelle personne dans la base de données et renvoyer son identifiant
        :param request: L'objet de la requête qui a été transmise par le client
        :type request: CreatePersonRequest
        :return: L'identifiant de la personne nouvellement créée.
        """
     # sqlInsert = 'insert into Sample.Person values (?,?,?,?,?)'
     # iris.sql.exec(sqlInsert,request.person.company,dob,request.person.name,request.person.phone,request.person.title)
     # IRIS ORM
     person = iris.cls('Sample.Person')._New()
     if (v:=request.person.company) is not None: person.Company = v
     if (v:=request.person.name) is not None: person.Name = v
     if (v:=request.person.phone) is not None: person.Phone = v
     if (v:=request.person.title) is not None: person.Title = v
     if (v:=request.person.dob) is not None: person.DOB = v

        Utils.raise_on_error(person._Save())
     return CreatePersonResponse(person._Id())

En utilisant IRIS ORM , nous pouvons créer une nouvelle personne Person et le sauvegarder dans notre base de données.

5.2. Requête GET

5.2.1. Test de la requête GET

Pour tester GET, vous devez avoir des données. Vous pouvez les créer avec une requête requête POST.

Cette API REST expose deux requêtes GET : toutes les données et un enregistrement. Pour obtenir toutes les données en JSON, lancez :

Pour demander les données d'un enregistrement particulier, fournissez l'identifiant dans la requête GET comme 'localhost:5000/persons/id', voici un exemple :

Cela renverra des données JSON pour la personne avec ID=1, par exemple :

5.2.2. Comment fonctionne la requête GET

 

def get_person(self,request:GetPersonRequest):
     """
        > La fonction prend un objet `GetPersonRequest`, exécute une requête SQL, et renvoie
        Objet `GetPersonResponse`

        :param request: L'objet de la demande qui est passé dans
        :type request: GetPersonRequest
     :return: Objet GetPersonResponse
     """
     sql_select = """
         SELECT
             Société, date de naissance, nom, téléphone, position
            FROM Sample.Person
         where ID = ?
            """
     rs = iris.sql.exec(sql_select,request.id)
     response = GetPersonResponse()
     for person in rs:
            response.person= Person(company=person[0],dob=person[1],name=person[2],phone=person[3],title=person[4])
     return response

def get_all_person(self,request:GetAllPersonRequest):
     """
        > Cette fonction renvoie une liste de toutes les personnes figurant dans le tableau des personnes

        :param request: L'objet de la requête qui est passé au service
        :type request: GetAllPersonRequest
     :return: Une liste d'objets Person
     """
     sql_select = """
         SELECT
             Société, date de naissance, nom, téléphone, position
            FROM Sample.Person
            """
     rs = iris.sql.exec(sql_select)
     response = GetAllPersonResponse()
     response.persons = list()
        pour les personnes dans rs:
            response.persons.append(Person(company=person[0],dob=person[1],name=person[2],phone=person[3],title=person[4]))
     return response

Cette fois, à l'aide de la fonction iris python sql.exec , nous pouvons exécuter directement du code SQL dans la base de données IRIS, recueillir les informations nécessaires et les renvoyer à l'API et à l'utilisateur.

5.3. Requête PUT

5.3.1. Test de la requête PUT

La requête PUT peut être utilisée pour mettre à jour les enregistrements. Il faut envoyer le même JSON que dans la requête POST ci-dessus en fournissant l'identifiant de l'enregistrement mis à jour dans l'URL. Par exemple, nous voulons changer l'enregistrement avec id=5. Préparez le JSON en brut comme suit :

et envoyer la requête PUT à :

5.3.2. Comment fonctionne la requête PUT

 

def update_person(self,request:UpdatePersonRequest):
     """
        > Mettre à jour une personne dans la base de données

        :param request: L'objet de la requête qui est passé au service
        :type request: UpdatePersonRequest
     :return: UpdatePersonResponse()

     """
     # IRIS ORM
     if iris.cls('Sample.Person')._ExistsId(request.id):
         person = iris.cls('Sample.Person')._OpenId(request.id)
         if (v:=request.person.company) is not None: person.Company = v
         if (v:=request.person.name) is not None: person.Name = v
         if (v:=request.person.phone) is not None: person.Phone = v
         if (v:=request.person.title) is not None: person.Title = v
         if (v:=request.person.dob) is not None: person.DOB = v
            Utils.raise_on_error(person._Save())
     return UpdatePersonResponse()

En utilisant IRIS ORM, nous pouvons vérifier si l'identifiant mène à une personne, si c'est le cas, nous pouvons le mettre à jour en utilisant nos nouvelles informations et le sauvegarder dans notre base de données.

5.4. Requête DELETE

5.4.1. Test de la requête DELETE

Pour les demandes de suppression, cette API REST attend uniquement l'identifiant de l'enregistrement à supprimer. Par exemple, si l'id=5, l'appel DELETE suivant supprimera l'enregistrement :

5.4.2. Comment fonctionne la requête DELETE

 

def delete_person(self,request:DeletePersonRequest):
     """
        > Supprimer une personne de la base de données

        :param request: L'objet de la requête qui est passé au service
        :type request: DeletePersonRequest
        :return: La réponse est renvoyée.
        """
     sql_select = """
         DELETE FROM Sample.Person as Pers
         WHERE Pers.id = ?
            """
     rs = iris.sql.exec(sql_select,request.id)
     response = DeletePersonResponse()
     return response

Cette fois, en utilisant la fonction iris python sql.exec , nous pouvons directement exécuter un code SQL dans la base de données IRIS et supprimer la personne.

6. Comment commencer le codage

Ce référentiel est prêt à être codé en VSCode avec les plugins InterSystems. Ouvrez /src/python/person/app.py pour changer quoi que ce soit sur l'api. Ouvrez /src/python/person/bo.py pour pouvoir modifier les choses liées aux demandes internes, c'est ici que vous pouvez utiliser SQL - il sera compilé dans le conteneur docker IRIS en cours d'exécution.

7. Contenu du dépôt

7.1. Dockerfile

Le dockerfile le plus simple pour lancer IRIS. Utilisez le fichier docker-compose.yml associé pour configurer facilement des paramètres supplémentaires comme le numéro de port et l'endroit où vous mappez les clés et les dossiers d'hôte.

7.2. .vscode/settings.json

Fichier de configuration pour vous permettre de coder immédiatement en VSCode avec le plugin VSCode ObjectScript)

7.3. .vscode/launch.json

Fichier de configuration si vous voulez déboguer avec VSCode ObjectScript