Veebiteenuste ja hajussüsteemide arendus - Kursused

Ü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 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 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.
- Valige kindlasti Consumption plaan, mitte Flex Consumption plaan
- Seadke selle nimeks enda poolt valitud nimi.
- Valige Runtime stack väärtuseks: Python
- Version väärtuseks: 3.9
- Regioon: North Europe
- Resource Grupp: looge uus resource group
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 funktsiooni HTTP lõppunkti.
  - 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äljastatavat 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, ja loome Azure pilve funktsiooni käsurealt.

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/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 konverteerida 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 praktikumi esimeses ülesandes.
  - Seadistage ka File Storage Account samaks, mis loodi esimeses ülesande Funktsiooni jaoks.
  - NB! On hästi tähtis meelde jätta või kontrollida, millist File Storage Account kasutatakse funktsiooni poolt. Kuna funktsioon hakkab seda kuulama, ning selle teenuse sisse peab raamatu failid looma. Hoolitsege, et te hiljem ei testi vale File Storage Account teenusega!
- Seadke funktsiooni rakenduse 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 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.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 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.

Ülesanne 11.5: 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. 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 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:

Küsimuse vastus ülesandest 11.1
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
Ekraanivaated ülesandest 11.5

Lahenduste esitamiseks peate olema sisse loginud ja kursusele registreerunud.

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

Veebiteenuste ja hajussüsteemide arendus 2024/25 kevad