Wszystko co warto wiedzieć o Azure Functions

Wykorzystanie usługi Azure Functions (+ PowerShell), w pierwszych momentach wydaje się zawiłe i skomplikowane. Sporo plików, niekoniecznie wiadomo do czego.

Sprawa robi się dużo prostsza, gdy rozumiemy przeznaczenie i powiązania pomiędzy nimi. Dlatego poniżej chcę Ci przybliżyć najważniejsze pliki, które są odpowiedzialne między innymi za konfigurację usługi Azure Functions, obsługę modułów PowerShell i integrację w naszych funkcjach.

To drugi wpis na temat Azure Functions. W pierwszym znajdziesz co i jak zainstalować, aby móc lokalnie zacząć pisać funkcję Function App w języku PowerShell.

Struktura plików

Azure Functions wymaga przygotowania odpowiedniej struktury plików i folderów. Jeśli korzystasz z rozszerzenia do Visual Studio Code to przy tworzeniu nowej funkcji niezbędne pliki zostaną przygotowane automatycznie.

To co widzisz powyżej to takie minimum, jednak struktura może być bardziej rozbudowana. Zależy to głównie od ilości i złożoności naszych funkcji.

Nie przypadkowo na schemacie podzieliłem kolorystycznie pliki i foldery na dwie grupy. Grupa pierwsza to pliki odpowiedzialne za konfigurację usługi Azure Functions oraz lokalne środowisko.

Druga grupa to pliki odpowiedzialne za kształt naszych funkcji. Każdy folder w tej grupie to osoba funkcja, która współdzieli ustawienia z poziomu usługi.

Na początek zacznę od najważniejszych plików z grupy pierwszej.

Konfiguracja usługi Azure Functions

Plik host.json zawiera globalne opcje konfiguracji, które mają wpływ na wszystkie nasze funkcje. Dokładny opis każdej z opcji znajdziesz w dokumentacji.

Domyślnie wygląda jak poniżej i na razie nie ma potrzeby niczego zmieniać.

{
  "version": "2.0",
  "logging": {
    "applicationInsights": {
      "samplingSettings": {
        "isEnabled": true,
        "excludedTypes": "Request"
      }
    }
  },
  "extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle",
    "version": "[1.*, 2.0.0)"
  },
  "managedDependency": { 
    "enabled": true 
  }
}

Plik local.settings.json przechowuje ustawienia aplikacji, parametry połączenia i ustawienia używane, gdy uruchamiamy funkcję lokalnie.

To tutaj zostanie zapisany np. connectionString z kluczem przy integracji z Azure Storage.

Profile.ps1 pełni tą samo role, którą pełnią pliki profili w PowerShell. Zawartość pliku jest wykonywana raz w momencie uruchamiania któreś z funkcji. Tutaj możesz umieścić dodatkowe polecenia, zmienne lub aliasy PowerShell.

Ostatni, ale nie mniej ważny requirements.psd1 odpowiada za zarządzanie modułami PowerShell. Zdefiniowane moduły zostaną pobrane z PowerShell Gallery i będą dostępne do użycia w Azure Functions.

Maksymalnie możesz zdefiniować 10 modułów. Obsługiwana składnia to MajorNumber. * lub dokładna wersja modułu.

# example - requirements.psd1
@{
    'Az'      = '4.*'
    'platyPS' = '0.*'
}

Moduły z poza PowerShell Gallery

Plik requirements.psd1 sprawdzi się tylko w przypadku modułów dostępnych na PowerShell Gallery.

Jeśli moduł, który chcesz wykorzystać nie jest upubliczniony to wystarczy, że przygotujesz folder Modules (poziom usługi Azure Functions) i tam go przekopiujesz. Moduł zostanie automatycznie przeniesiony do Function App w momencie publikacji funkcji.

Pliki poziomu Function App

Przejdzmy teraz do poziomu samych funkcji. Po pierwsze nazwa katalogu stanowi nazwę funkcji. Domyślnie Azure Functions wykonuję zawartość pliku run.ps1 (można to zmienić, ale to temat na inny wpis) i to tutaj umieścisz swój kod PowerShell z logiką funkcji.

Drugi plik to function.json, który odpowiada za konfigurację zdarzenia, które wyzwoli naszą funkcję oraz za opcjonalne powiązania.

Wyzwalacze (trigger)

Funkcje Azure Functions są sterowane zdarzeniami (event-driven). Każda funkcja może mieć tylko jeden wyzwalacz, który może nie tylko ją uruchomić, ale przekazać dane do naszego kodu.

Jakie zdarzenie może byc wyzwalaczem?

• Przychodzące żądanie HTTP (httpTrigger)
• Utworzenie lub modyfikacja obiektu na Azure Storage (blobTrigger)
• Nowa wiadomość w kolejce (queueTrigger)
• Harmonogram (timerTrigger)

Przykład pliku function.json z triggerem blobTrigger:

{
  "bindings": [
    {
      "name": "InputBlob",
      "type": "blobTrigger",
      "direction": "in",
      "path": "photo/{name}",
      "connection": "storageaccountfunction"
    }
  ]
}

Wartość connection w pliku function.json to nazwa zmiennej, pod którą kryje się connectionString do Azure Storage. Lokalnie wartość tego ciągu musisz zapisać do pliku local.settings.json.

Warto zapamiętać, że domyślnie ustawienia z tego pliku nie są migrowane na platformę Azure podczas publikacji.

💡 Wykorzystaj poniższe polecenia do publikacji funkcji wraz ustawieniami z local.settings.json do Azure Functions. Możesz również przenieść same parametry wykorzystując --publish-settings-only

func azure functionapp publish [nazwa-uslugi-function-app] --publish-local-settings
# lub
func azure functionapp publish [nazwa-uslugi-function-app] --i
 
# tylko parametry
func azure functionapp publish [nazwa-uslugi-function-app] --publish-settings-only
# lub
func azure functionapp publish [nazwa-uslugi-function-app] -o

Powiązania (bindings)

Powiązania to genialny sposób na integrację w celu pobierania dodatkowych danych lub wypychania wyników działania z funkcji. Dlatego wyróżniamy powiązania wejściowe (in) i wyjściowe (out).

Poniżej przykład pliku wraz z dodatkowym powiązaniami wyjściowymi (direction: out)

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "Request",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "Response"
    }
  ]
}

Wykorzystanie integracji w pliku run.ps1

Oczywiście te dwa pliki są ze sobą ściśle powiązane. Przede wszystkim w pliku run.ps1 wykorzystywać będziemy zdefiniowane integracje.

Nazwę powiązania wejściowego z pliku function.json musimy umieścić jako zmienną w bloku param(). To pod tą zmienną w skrypcie PowerShell znajdziemy wartości przekazane przez wyzwalacz.

W bloku param(), warto dodać zmienną $TriggerMetadata, która dostarcza dodatkowe informacje o wyzwalaczu, które mogą się różnic w zależności od jego typu (blob, kolejka itd).

💡 Najprostszy sposób na podejrzenie wartości zmiennej $TriggerMetadata.

# wstaw do funkcji i sprawdź w logach
Write-Host ($TriggerMetadata | ConvertTo-Json)

Całkiem podobnie sytuacja wygląda w przypadku powiązań wyjściowych (out). Tutaj nazwy powiązań wykorzystamy, jako wartość parametru -Name dla dedykowanej funkcji PuSh-OutputBinding. Polecenie te przekaże dane z parametru -Value do określonego przez nas miejsca.

Podsumowanie

Wiedza na temat przeznaczenia oraz relacji pomiędzy plikami w Azure Functions pomaga w sprawniejszym pisaniu nowych funkcji. Najistotniejsze dla mnie było zrozumienie definiowania powiązań i wykorzystywania ich w kodzie funkcji zarówno w kwestii przyjmowania danych, jak i przekazywania dalej.

Mam nadzieję, że dla Ciebie też to okaże się pomocne.