Development of web services and distributed systems - Courses

Üheteistkümnes praktikum - Azure pilvefunktsioonid

Selles praktikumis uurime kuidas töötab Azure pivefunktsioonide platvorm ning loome Azure funktsioonide abil uue funktsionaalsuse enda praktikumi Python Flask teenusesse. Selleks funktsionaalsuseks on Raamatu failide automaatne konverteerimine PDF failideks peale raamatu tekstifaili üles laadimist Azure Blob andmehoidlasse.

Viited

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
Azure functions käsurea kliendi installeerimine ja kasutamine: https://docs.microsoft.com/en-us/azure/azure-functions/functions-run-local

Probleemide korral kontrollige:

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

Ülesanne 11.1: Azure keskkonna ette valmistamine

Selles ülesandes loome vajalikud teenused Azure funktsiooni rakenduse jaoks.

Logige Azure'i pilve sisse: https://portal.azure.com/#home
- Kasutage oma ülikooli e-posti aadressi ja parooli
Meil läheb vaja:
1. Azure Resource Group ühes Student Subscription toetatud regioonis:
  - polandcentral
  - germanywestcentral
  - francecentral
  - swedencentral
  - norwayeast
  - Otse link: https://portal.azure.com/#servicemenu/Microsoft_Azure_Resources/ResourceManager/resourcegroups
  - Azure Student Subscription kontos limiteeritud regioonid:
    - https://portal.azure.com/#view/Microsoft_Azure_Policy/PolicyMenuBlade.MenuView/~/Assignments
2. Storage Account teenust samas Resource group'is
  - https://portal.azure.com/#view/Microsoft_Azure_StorageHub/StorageHub.MenuView/~/StorageAccountsBrowse
Kasutage kas juba olemasolevaid ResourceGroup ja Storage Account teenuseid või looge uued.
- Parameetrid Storage Account loomisel:
  1. Performance: standard
  2. Reduncancy: Locally-redundant
  3. primary workload: Other

Järgnevad Function App loomise tegevused teeme käsurealt omast arvutist.

Ü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 ubuntu virtuaalmasinat või teha seda otse Windows'is.

Linuksis:

Uuendage Linuksi pakettide nimekiri:
- sudo apt update
Kontrollige, et teil on Python 3.11 või väiksem versioon.
Installeerime 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/22.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 rakenduse loomine.

Selles ülesandes loome uue Azure Python funktsiooni rakenduse, mille sisse saame hiljem luua uusi funktsioone.

NB! Selle peab looma käsurealt, kuna portaali kaudu ei ole enam võimalik luua Linux Consumption tüüpi funktsiooni rakendusi.

Loome Azure Function App teenuse käsurealt järgneva käsuga, aga enne muutes ära 4 väärtust selles käsus:
- az functionapp create --resource-group RECOURCE_GROUP_NAME --consumption-plan-location REGION_NAME --runtime python --runtime-version 3.12 --functions-version 4 --name FUNCTION_APP_NAME --storage-account STORAGE_ACCOUNT_NAME --os-type Linux

Resource Group (--resource-group) väärtus peab olema see varasem Resource Group, mille tegite praktikumi esimeses ülesandes.
Seadistage File Storage Account (--storage-account) nimeks sama, mille tegite esimeses ülesandes.
Seadke funktsiooni rakenduse nimeks (--name) enda poolt valitud nimi, aga seda läheb meil hiljem vaja (FUNCTION_APP_NAME)
Regiooniks (--consumption-plan-location) peab olema sama regioon, mida kasutasite Recource Group ja File storage account jaoks
Runtime stack väärtuseks: python
Version (--runtime-version) väärtuseks kasutage: 3.12

NB! Kui saate veateate, et selles regioonis ei ole vabu ressursse Linux keskkondade loomiseks, siis proovige teist toetatud regiooni. Võib vaja minna uue Recource Group ja Storage Account teenuste loomist uues regioonis.

Ülesanne 11.4: 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 konverteerida PDF faili sisuks. Failidest lugemise ja failidesse salvestamisega me tegelema ei pea. Sisendite ja väljundite suunamise eest hoolitseb Azure. Meie paneme paika mis sisend kausta kasutatakse raamatufailide leidmiseks ning millisesse kausta salvestatakse PDF failid.

Järgnevad tegevused teeme käsurealt.

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 skriptide 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.5: 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 unustage 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 konteksti 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, InputStream
- 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.

Vaadake Azure Functions App lehelt, et teie loodud funktsioon oleks nähtav Overview lehel:

Kui funktsioon ei ilmu nähtavale, siis võib see tähendada, et Python koodis või teistes failides (nt. requirements.txt) failis on vead, mis takistasid Azure's funktsiooni koodi ette valmistamist (build).

Ülesanne 11.6: Testime funktsiooni käivitust Azure pilves

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

Otsige üles File Storage Account mida see funktsioon "kuulab". See peab olema sama Resource Grupi sees.
Looge Storage Account teenuse sisse uus Blob container nimega raamatud
Looge Storage Account teenuse sisse uus Blob container nimega pdf
Laadige Azure Blob raamatud konteinerisse üles uus tekstifail.
- Vajadusel, kui teil ei õnnestu faile vaadata, siis määrake, et peaks muutma ligipääsu tüüp ümber (Switch to account key)
Kontrollige, et Funktsiooni poolt luuakse selle vastav PDF fail.
- See peaks enamvähem kohe tekkima. Kui ei teki, siis tõenäoliselt oli viga koodis, või te kasutasite vale Storage Account teenust.
- Uurige Funktsiooni käivitamise logisi Invocations alamlehel. Logide ilmumine võib mitu minutit aega võtta.

Azure funktsiooni väljakutseid ning veateateid saab vaadata Azure portaalis, funktsiooni lehel, Logs alamlehel.

Laadige PDF fail alla Azure Storage Account teenusest 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 Raamatu halduse API rakendusega. 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 tegemist 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:

Python koodi projekt/kaust ülesandest: 11.5
- 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
Ekraanivaated ülesandest 11.5

You must be logged in and registered to the course in order to submit solutions.

Võimalikud probleemid ja nende potentsiaalsed 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 ressursside 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äivitavat 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

Development of web services and distributed systems 2025/26 spring