Development of web services and distributed systems 2023/24 spring

Üheteistkümnes praktikum - Azure pilvefunktsioonid

Selles praktikumis uurime kuidas töötab Azure pivefunktsioonide platvorm ning loome lihtsad näite funktsioonid. Kasutame neid teadmisi, et lisada Azure funktsioonide abil uue funktsionaalsuse enda praktikumi Python Flask teenusesse. Selleks funktsionaalsuseks on Raamatu failide automaatne konverteetimine PDF failideks peale raamatu tekstifaili üles laadimist Azure Blob andmehoidlasse.

Viited

1. Azure Functions App Python'i keskkonna dokumentatsioon: https://docs.microsoft.com/en-us/azure/azure-functions/functions-reference-python?tabs=asgi%2Cazurecli-linux%2Capplication-level
2. Azure functions käsurea kliendi installeerimine ja kasutamine: https://docs.microsoft.com/en-us/azure/azure-functions/functions-run-local

Probleemide korral kontrollige:

1. Võimalikud probleemid ja nende potentsiaalsed lahendused osa praktikumi juhendi lõpus.
2. Küsige otse #praktikum-11-nano Zulip teemas.
   • Ka siis kui soovite lihtsalt viheid.

Ülesanne 11.1: Azure funktsiooni loomine

Selles ülesandes loome lihtsa pilve näidis-funktsiooni Azure platvormil.

• Logige Azure'i pilve sisse: https://portal.azure.com/#home
  • Kasutage oma ülikooli e-posti aadressi ja parooli
• Otsige üles Azure function App teenus
• Looge uus Azure Function App rakendus. See töötab konteinerina Azure funktsiooni jaoks.
  • Seadistage Resource Group väärtuseks varasem Resource Group, mida kasutasite praktikumis 8 (Kus kasutasime Azure Blob teenust). Me soovime kasutada sama Azure Blob storage konteinerit, mida meie Flask Rakendus kasutab Raamatote hoidmiseks.
  • Seadke selle nimeks enda poolt valitud nimi.
  • Valige Runtime stack väärtuseks; Python
  • Version väärtuseks: 3.9
  • Regioon: North Europe
• Oodake kuni Functions App ressurss on valmis
• Looge uus (alam-)funktsioon Functions App sees
  • Programming model: v1 Programming Model
  • Valime malliks (template): HTTP trigger
    • See defineerib, et funktsiooni käivitamise päästik-sündmuseks on "sisse tulev" HTTP päring.
• Muutke funktsiooni nimi (New Function) enda poolt valitud väärtuseks
• Looge funktsioon.
• Funktsiooni vaates avage vasakul: Code+Test
  • Saate funktsiooni JavaScript koodi otse brauseri kaudu muuta.
  • Üleval paremal pool saate lingi Get Function URL kaudu kopeerida fuktsiooni HTTP lõpppunkti.
    • Kasutage seda link brauseris, ning kontrollige kas funktsioon töötab
    • Lisage funktsiooni urlile argument name kaudu oma nimi. Näiteks nii: &name=pelle
• Muutke funktsiooni poolt väljsastatavat väärtust (responseMessage).

Küsimus: Kui kiiresti muutub funktsiooni poolt väljastatav tulemus peale teie poolse muudatuse tegemist.

Azure funktsiooni väljakutseid ning veateateid saab vaadata Azure portaalis, funktsiooni lehel, Monitor alamlehel?

Ülesanne 11.2: Azure käsurea liidese installeerimine

Selles ülesandes installeerime Azure käsurea rakenduse.

Kui kasutate Windowsit oma arvutis, siis saate kasutada WSL kaudu üles seatud ubuntu2004 virtuaalmasinat või teha seda otse Windows'is.

Linuksis:

• Uuendage Linuksi pakettide nimekiri:
  • sudo apt update
• Kontrollige, et teil pon Python 3.11 või väiksem versioon.
• Instaleerime Python 3 virtuaalse keskkonna loomise käsu
  • sudo apt-get install python3-venv
• Seadistame ja installeerime Azure käsurea tööriistad:

  • wget -q https://packages.microsoft.com/config/ubuntu/19.04/packages-microsoft-prod.deb
    sudo dpkg -i packages-microsoft-prod.deb
    sudo apt-get update
    sudo apt-get install azure-functions-core-tools-4

• Installeerimine Azure käsurea käsud sisse logimiseks:
  • curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

Windowsis:

• Soovi korral võite proovida ka Windows versiooni nendest tööriistadest
• Installeerimine Azure käsurea käsud sisse logimiseks:
  • https://learn.microsoft.com/en-us/cli/azure/install-azure-cli-windows?tabs=azure-cli
• Seadistame ja installeerime Azure Functions käsurea tööriistad:
  • https://docs.microsoft.com/en-us/azure/azure-functions/functions-run-local?tabs=v4%2Cwindows%2Ccsharp%2Cportal%2Cbash

Peale käsurea tööriistade installeerimist:

• Kasutage käsurida, et sisse logida Azure platvormi:
  • az login
    • See käsk suunab teid edasi (või annab lingi mida tuleks kasutada) brauserisse, mille kaudu saate autentida enda (ülikooli) MS kontoga.
  • Kui tekib probleem sisse logimisega, korrake seda protsessi mitu korda. Kui ikka ei õnnestu, võtke ühendust õppejõuga.
  • Selle tulemusena seadistatakse juurdepääsu info lokaalselt.
• Selleks, et kontrollida kas kõik on üles seatud korrektselt, vaatame, millised Azure funktsioonide mallid on saadaval. Neid saab funktsioonide loomisel alusena kasutada:
  • func templates list -l python

Ülesanne 11.3: Azure Python funktsiooni loomine.

Selles ülesandes loome uue Azure Python funktsiooni, kasutades malli, mis seab selle funktsiooni päästik-sündmuseks uue faili tekkimise Azure blob storage teenuses. Samuti testime, et seda funktsiooni õnnestub Azure platvormi üles laadida.

Funktsiooni eesmärk on sisendina tulev tekst (Raamatu sisu) ümber konventeerida PDF faili sisuks (failidest lugemise ja failidesse salvestamisega me tegelema ei pea)

• Otsige üles Azure function App teenus Azure portaalis
• Looge uus Azure Function App rakendus. See töötab konteinerina Azure funktsiooni jaoks.
  • Seadistage Resource Group väärtuseks varasem Resource Group, mille kasutasite praktikumis esimeses ülesandes.
    • Seadistage ka File Storage account samaks, mida kasutasite eelmises praktikumid.
  • Seadke selle nimeks enda poolt valitud nimi, aga seda läheb meil hiljem vaja (FUNCTION_APP_NAME)
  • Valige Runtime stack väärtuseks: Python
  • Version väärtuseks: 3.9
  • Regioon: North Europe
• Loome uue kausta meie Azure Functions projekti jaoks.
  • Linuksis: mkdir azure
• Liigume kausta sisse:
  • Linuksis: cd azure
• Loome uue Python virtuaalse keskkonna
  • python3 -m venv venv
• Aktiveerime keskkonna:
  • Linuksis: . ./venv/bin/activate
  • Windows PowerShellis: /venv/Scripts/Activate.ps1
    • Windows Powershellis võib vaja minna scriptide jooksutamise lubamist, et virtuaalkeskkonna aktiveerimine õnnestuks.
• Linuksis uuendame Python pip versiooni:
  • Linuksis: sudo apt install python3-pip
  • Windowsis seda vaja minna ei tohiks.
• Loome uue lokaalse Azure Funktsioonide teenuse projekti, mis kasutab Python keskkonda:
  • func init localhsproj --worker-runtime python --model V1
• Liigume loodud kausta sisse:
  • cd localhsproj
• Genereerime funktsioonile koodi:
  • Meie valime funktsiooni alustüübiks: Azure Blob Storage trigger malli.
    • See tähendab seda, et see funktsioon on disainitud käivituma Azure Blob teenuse sündmuste korral (nt uue blob üles laadimise korral).
  • func new --name FUNCTION_NAME --template "Azure Blob Storage trigger"
    • NB! Asendage FUNCTION_NAME oma poolt valitud nimega.
    • Selle tulemusena luuakse FUNCTION_NAME nimeline kaust
• Muutke FUNCTION_NAME kaustas oleva function.json faili sisu.
  • Seame connection väärtuseks: AzureWebJobsStorage
    • AzureWebJobsStorage keskkonna muutuja kaudu saab meie funktsioon ligipääsu Azure blob storage ühenduse infole, mida saab kasutada uue ühenduse loomiseks (näiteks faili loomiseks või muutmiseks)
  • Seame path väärtuseks oma Azure Blob Storage' konteineri asukoha: raamatud/{blobname}
    • See seadistab integratsiooni raamatud blob konteineri ka meie poolt loodava funktsiooni vahel. Iga uue faili puhul käivitatakse see funktsioon.
• Publitseerime nüüd funktsiooni koodi Azure platvormi:
  • Käivitage järgmine meetod localhsproj kaustas (mitte alam-funktsiooni kaustas)
  • func azure functionapp publish FUNCTION_APP_NAME --build remote --python
  • Asendage selles käsus FUNCTION_APP_NAME oma funktsiooni rakenduse nimega, mille me varasemalt Azure portaalis tegime veebiliidese kaudu.

Ülesanne 11.4: Azure Python funktsiooni implementeerimine.

Selles ülesandes implementeerime genereeritud funktsiooni sisu.

• Muudame requirement.txt faili, et lisada PDF failide loomise Python teek:
  • lisage rida fpdf teegi jaoks
• Muudame function.json faili
  • See fail defineerib kust võtab funktsioon sisendid ning millised väljundid selle on.
  • Hetkel on failis defineeritud vaid sisend (myblob, mis on tüüpi blobTrigger).
    • Selle tulemusena otsitakse raamatud kaustast/konteinerist blob'e - selle funktsiooni sündmuste genereerimiseks
  • Lisake bindings listi üks plokk juurde väljundi jaoks:

    •     {
            "name": "blobout",
            "type": "blob",
            "direction": "out",
            "path": "pdf/{blobname}.pdf",
            "connection": "AzureWebJobsStorage"
      

      • Seadistame väljundiks samuti Azure blob teenuse.
      • Seadistame väljundi asukohaks pdf kausta/konteineri. Ning selle, et faili nimele peaks lõppu lisama .pdf.
      • NB! Ärge unustake koma panna nende kahe bloki vahele. Umbes nii:

        •       "connection": "AzureWebJobsStorage"
              },
              {
                "name": "blobout",

Implementeerime __init__.py faili sisu

• Importige vajalikud teegid:
  • from fpdf import FPDF
  • import os
• Lisage uus meetod tekst tüüpi sisendi (Raamatu sisu) genereerimiseks PDF väljundiks:

  • def text_to_pdf(text):
    
        pt_to_mm = 0.35
        fontsize_pt = 11
        fontsize_mm = fontsize_pt * pt_to_mm
        margin_bottom_mm = 20
    
        pdf = FPDF(orientation='P', unit='mm', format='A4')
        pdf.set_auto_page_break(True, margin=margin_bottom_mm)
        pdf.add_page()
        pdf.set_font(family='Courier', size=fontsize_pt)
    
        splitted = text.split('\n')
    
        for line in splitted:
            if len(line) == 0:
                pdf.ln()
            pdf.cell(0, fontsize_mm, line, ln=1)
    
        return(pdf.output(dest='S').encode('latin-1'))

  • Muudame main() meetodi kirje ära, lisades argumentidesse ka väljundi objekti viite ja conteksti objekti viite.
    • See peaks nüüd olema selline:
      • def main(myblob: InputStream, blobout: Out[bytes], context: Context):
  • Lisame Out ja Context classide importimise Azure function teegist:
    • from azure.functions import Out, Context
  • Muutame main() meetodi sisu:
    • Meetodi alguses loeme sisse sisendblobi sisu:
      • input = myblob.read()
    • Kodeerime selle ümber (väike häkkimine siin, et PDF teek saaks õiges vormingus sisu, ja et eemaldada karakterid millega see teek ei saa hakkama)
      • input_str = input.decode("UTF-8").encode('latin-1', 'ignore').decode('latin-1')
    • Kutsume välja pdf genereerimise funktsiooni:
      • sisu = text_to_pdf(input_str)
    • Seadistame main() meetodi välja kutse tulemusena väljund-pdf-faili sisu:
      • blobout.set(sisu)

Publitseerige funktsioon üles uuesti Azure pilve.

Ülesanne 11.5: Testime funktsiooni käivitust Azure pilves

Selles ülesandes testime, et meie poolt loodud muudatused töötavad.

• Looge Storage Account Blob teenuse sisse uus container nimega pdf
  • Vajadusel, määrake et peaks muutma ligipääsu tüüp ümber (Switch to account key)
• Laadige Azure Blob raamatud konteinerisse üles uus tekstifail.
• Kontrollige, et luuakse selle vastav PDF fail.
  • See peaks enamvähem kohe tekkima. Kui ei teki, siis tõenäoliselt oli viga koodis
  • Uurige Funktsiooni käivitamise logisi. Logide ilmumine võib mitu minutit aega võtta.
  • Azure funktsiooni väljakutseid ning veateateid saab vaadata Azure portaalis, funktsiooni lehel, Monitor alamlehel.
• Laadige PDF fail alla ning kontrollige, et selle sisu vastaks raamatu faili sisule.

Vaadake ka Võimalikud probleemid ja nende potentsiaalsed lahendused osa praktikumi juhendi lõpus, kuhu on lisatud infot selle kohta, kuidas lahendust debugida.

• Tehke sama protsess läbi. Aga seekord ärge looge raamatu faili käsitsi, vaid kasutage oma Azure Blob andmehoidla põhist Flask Raamatu halduse rakendust praktikumidest 9 (või 7).
  • NB! Hoolitsege, et Teie API kasutab sama Azure File Storage Blob teenuse kausta!!
  • Kuna tegite uue Blob teenuse, peate Azure Storage Connection String muutuja ära muutma.
• Kontrollige, et peale POST päringu tegemsist API /raamatud aadressile luuakse Azure Blob storage konteineris uus teksti fail ning taustal genereeritakse ka PDF fail.

Esitamiseks: Tehke ekraanivaated, mis näitavad Flask veebirakendusega sooritatud testimise protsessi samm-sammult.

Lahenduse esitamine

Praktikumi lahendusena tuleb esitada:

1. Küsimuse vastus ülesandest 11.1
2. Python koodi projekt/kaust ülesandest: 11.4
   • Faile saab kopeerida WSL ubuntu virtuaalmasina seest "väljaspoole"
   • WSL virtuaalmasina seest on välise arvuti failisüsteem tihti kätte saadab läbi /mnt kausta.
     • Näiteks minu sülearvuti kodu kaust on virtuaalmasina seest vaadates: /mnt/c/Users/pelle
     • Sinna faile kopeerides on need kätte saadavad väljaspool virtuaalmasinat
3. Ekraanivaated ülesandest 1.5

Võimalikud probleemid ja nende potentiaalsed lahendused.

• Kui saate funktsiooni loomisel vea Object reference not set to an instance of an object.
  • Hoolitsege, et funktsiooni koodi versioon on V1, mitte V2.
• Vältige Azure resursside nimedes suuri tähti, alakriipse ning muid spetsiaalseid tähti või karaktereid kui võimalik.
• Kui tekib probleem sellega, et meie PDF funktsioon kasutab erinevat Azure Storage kontot kui Flask rakendus, siis saab flask rakenduses ära muuta Storage Account connection string muutuja väärtus, et oleks sama, mis sellel kontol mida PDF funktsioon kasutab.
  • Selleks, et kontrollida täpselt millist Storage Account/kontot Azure Blob tüüpi päästikuga funktsioon kuulab:
    • Saab Function App - > Settings -> Configuration lehelt vaadata, mis on AzureWebJsonStorage muutuja sisemine (storage) AccountName väärtus. See määrab ära millise storage account'i sees selle Azure Function APP funktsioonid kuulavad.

• Kui funktsioon ei paista kävitavat peale seda kui laete üles uue teksti faili:
  • Kontrollige, et laete üles faili konteinerisse, mille nimi on raamatud
  • Kontrollige, ega teil ei ole mitut storage kontot, ning te kasutate teist kui see funktsioon kasutab.
  • Kontrollige, et funktsioni Trigger Tüüp on Blob