Udostępnij za pośrednictwem

Przewodnik dokumentacji dla deweloperów Azure Functions dla aplikacji Python

Azure Functions to bezserwerowa usługa obliczeniowa, która umożliwia uruchamianie kodu opartego na zdarzeniach bez aprowizowania infrastruktury ani zarządzania nią. Wykonania funkcji są wyzwalane przez zdarzenia, takie jak żądania HTTP, komunikaty w kolejce, czasomierze lub zmiany w magazynie — i są skalowane automatycznie na podstawie zapotrzebowania.

Ten przewodnik koncentruje się specjalnie na tworzeniu Azure Functions opartych na Python i ułatwia:

  • Tworzenie i uruchamianie lokalnie aplikacji funkcjonalnych
  • Omówienie modelu programowania Python
  • Organizowanie i konfigurowanie aplikacji
  • Wdrażanie i monitorowanie aplikacji w Azure
  • Stosowanie najlepszych rozwiązań dotyczących skalowania i wydajności

Szukasz przeglądu pojęć? Zobacz dokumentację dla deweloperów Azure Functions.

Zainteresowany/a rzeczywistymi przypadkami użycia? Zapoznaj się ze stroną Scenariusze i przykłady .

Wprowadzenie

Wybierz środowisko pasujące do przepływu pracy i przejdź do Azure Functions dla Python:

Budowanie aplikacji funkcji

W tej sekcji opisano podstawowe składniki tworzenia i strukturyzowania aplikacji funkcji Python. Tematy obejmują model programowania, strukturę projektu, wyzwalacze i powiązania oraz zarządzanie zależnościami.

Model programowania

Funkcje obsługują dwie wersje modelu programowania Python:

wersja opis
2.x Użyj podejścia opartego na dekoratorze, aby zdefiniować wyzwalacze i powiązania bezpośrednio w pliku kodu Python. Każda funkcja jest implementowana jako globalna, bezstanowa metoda w function_app.py pliku lub w pliku planu, do którego się odwołujesz. Ta wersja modelu jest zalecana dla nowych aplikacji Python.
1.x Wyzwalacze i powiązania są definiowane dla każdej funkcji w osobnym function.json pliku. Każda funkcja jest implementowana jako globalna, bezstanowa funkcja w pliku kodu Pythona. Ta wersja modelu obsługuje starsze aplikacje.

Artykuł ten dotyczy określonej wersji modelu Python. Wybierz żądaną wersję w górnej części artykułu.

Ważne

Użyj modelu programowania w wersji 2 dla podejścia opartego na dekoratorze , aby zdefiniować wyzwalacze i powiązania bezpośrednio w kodzie.

W modelu programowania Python w wersji 1 każda funkcja jest definiowana jako globalna, bezstanowa metoda main() wewnątrz pliku o nazwie __init__.py. Wyzwalacze i powiązania funkcji są konfigurowane oddzielnie w function.json pliku, a wartości powiązań name są używane jako parametry w metodzie main() .

Przykład

Oto prosta funkcja, która odpowiada na żądanie HTTP:

# __init__.py
def main(req):
    user = req.params.get('user')
    return f'Hello, {user}!'

Oto odpowiedni function.json plik:

{
    "scriptFile": "__init__.py",
    "bindings": [
        {
            "authLevel": "function",
            "type": "httpTrigger",
            "direction": "in",
            "name": "req",
            "methods": [
                "get",
                "post"
            ]
        },
        {
            "type": "http",
            "direction": "out",
            "name": "$return"
        }
    ]
}

Najważniejsze pojęcia

  • Funkcja ma jeden wyzwalacz HTTP.
  • Obiekt HttpRequest zawiera nagłówki żądań, parametry zapytania, parametry trasy i treść komunikatu. Ta funkcja pobiera wartość parametru name zapytania z params parametru obiektu HttpRequest .
  • Aby wysłać nazwę w tym przykładzie, dołącz ?name={name} do udostępnionego adresu URL funkcji. Jeśli na przykład działa lokalnie, pełny adres URL może wyglądać następująco: http://localhost:7071/api/http_trigger?name=Test. Przykłady użycia powiązań można znaleźć w temacie Triggers and Bindings (Wyzwalacze i powiązania).

Użyj zestawu azure-functions SDK i zastosuj adnotacje typów dla ulepszenia obsługi funkcji IntelliSense i edytora:

# __init__.py
import azure.functions as func

def http_trigger(req: func.HttpRequest) -> str:

# requirements.txt
azure-functions

Biblioteka azure-functions

Biblioteka azure-functions Python udostępnia podstawowe typy używane do interakcji ze środowiskiem uruchomieniowym Azure Functions. Aby wyświetlić wszystkie dostępne typy i metody, odwiedź APIazure-functions. Możesz używać w kodzie funkcji azure-functions do:

  • Dostęp do danych wejściowych wyzwalacza (na przykład HttpRequest, TimerRequest)
  • Tworzenie wartości wyjściowych (takich jak HttpResponse)
  • Interakcja z danymi kontekstu i danymi powiązań udostępnionymi w czasie wykonywania

Jeśli używasz azure-functions w aplikacji, musi ona być uwzględniona w zależnościach projektu.

Uwaga

Biblioteka azure-functions definiuje powierzchnię programowania dla Python Azure Functions, ale nie jest to zestaw SDK ogólnego przeznaczenia. Używaj jej specjalnie do tworzenia i uruchamiania funkcji w środowisku uruchomieniowym Azure Functions.

Alternatywny punkt wejścia

Domyślne zachowanie funkcji można zmienić, określając właściwości scriptFile i entryPoint w pliku function.json. Na przykład poniższy plik function.json kieruje środowisko uruchomieniowe do użycia metody custom_entry() w pliku main.py jako punktu wejścia dla funkcji Azure.

{
  "scriptFile": "main.py",
  "entryPoint": "custom_entry",
  "bindings": [
      ...
  ]
}

Struktura folderów

Użyj następującej struktury dla projektu Python Azure Functions:

<project_root>/
│
├── .venv/                   # (Optional) Local Python virtual environment
├── .vscode/                 # (Optional) VS Code workspace settings
│
├── my_first_function/       # Function directory
│   └── __init__.py          # Function code file
│   └── function.json        # Function binding configuration file
│
├── my_second_function/
│   └── __init__.py  
│   └── function.json 
│
├── shared/                  # (Optional) Pure helper code with no triggers/bindings
│   └── utils.py
│
├── additional_functions/    # (Optional) Contains blueprints for organizing related Functions
│   └── blueprint_1.py  
│
├── tests/                   # (Optional) Unit tests for your functions
│   └── test_my_function.py
│
├── .funcignore              # Excludes files from being published
├── host.json                # Global function app configuration
├── local.settings.json      # Local-only app settings (not published)
├── requirements.txt         # (Optional) Defines Python dependencies for remote build
├── Dockerfile               # (Optional) For custom container deployment

Kluczowe pliki i foldery

Plik / Folder opis Aplikacja wymagana do uruchomienia w Azure
my_first_function/ Katalog dla pojedynczej funkcji. ✅
__init__.py/ Skrypt główny, w my_first_function którym zdefiniowano kod funkcji. ✅
function.json/ Zawiera konfigurację powiązania dla my_first_function funkcji. ✅
host.json Konfiguracja globalna dla wszystkich funkcji w aplikacji. ✅
requirements.txt Zależności Python są instalowane podczas publikowania przy użyciu kompilacji zdalnej remote build. ❌ (zalecane w przypadku zarządzania pakietami)
local.settings.json Ustawienia aplikacji i tajne informacje przeznaczone tylko dla lokalnego użytku (nigdy nie są udostępniane). ❌ (wymagane do rozwoju lokalnego)
.funcignore Określa pliki i foldery do wykluczenia z wdrożenia (na przykład .venv/, , tests/local.settings.json). ❌ (zalecane)
.venv/ Lokalne środowisko wirtualne dla Python (wykluczone z wdrożenia). ❌
.vscode/ Konfiguracja edytora dla Visual Studio Code. Nie wymaga wdrożenia. ❌
shared/ Przechowuje kod pomocniczy współdzielony w projekcie aplikacji funkcji ❌
additional_functions/ Służy do modularnej organizacji kodu — zwykle ze szkicami. ❌
tests/ Testy jednostkowe dla Twojej aplikacji funkcji. Nie opublikowano w Azure. ❌
Dockerfile Definiuje kontener niestandardowy do wdrożenia. ❌

W modelu programowania Python w wersji 2 Azure Functions używa podejścia opartego na decorator do definiowania wyzwalaczy i powiązań bezpośrednio w kodzie. Każda funkcja jest implementowana jako globalna, bezstanowa metoda w function_app.py pliku.

Przykład

Oto prosta funkcja, która odpowiada na żądanie HTTP:

import azure.functions as func

app = func.FunctionApp()

@app.route("hello")
def http_trigger(req):
    user = req.params.get("user")
    return f"Hello, {user}!"

# requirements.txt
azure-functions

Najważniejsze pojęcia

  • Kod importuje pakiet azure-functions i używa dekoratorów oraz typów do zdefiniowania funkcji aplikacji.
  • Funkcja ma jeden wyzwalacz HTTP.
  • Obiekt HttpRequest zawiera nagłówki żądań, parametry zapytania, parametry trasy i treść komunikatu. Ta funkcja pobiera wartość parametru name zapytania z params parametru obiektu HttpRequest .
  • Aby wysłać nazwę w tym przykładzie, dołącz ?name={name} do udostępnionego adresu URL funkcji. Jeśli na przykład działa lokalnie, pełny adres URL może wyglądać następująco: http://localhost:7071/api/http_trigger?name=Test. Przykłady użycia powiązań można znaleźć w temacie Triggers and Bindings (Wyzwalacze i powiązania).

Biblioteka azure-functions

Biblioteka azure-functions Python jest główną częścią modelu programowania Azure Functions. Udostępnia on dekoratory, wyzwalacze i typy powiązań oraz obiekty żądań/odpowiedzi używane do definiowania i interakcji z funkcjami w czasie wykonywania. Aby wyświetlić wszystkie dostępne typy i dekoratory, odwiedź azure-functions API. Kod twojej aplikacji funkcji zależy od tej biblioteki, aby:

  • Definiowanie wszystkich funkcji przy użyciu FunctionApp obiektu
  • Deklarowanie wyzwalaczy i powiązań (na przykład @app.route, @app.timer_trigger)
  • Dostęp do typiowanych danych wejściowych i wyjściowych (takich jak HttpRequest i HttpResponse, i Out')

Element azure-functions musi być uwzględniony w zależnościach projektu. Aby dowiedzieć się więcej, zobacz Zarządzanie pakietami.

Uwaga

Biblioteka azure-functions definiuje powierzchnię programowania dla Python Azure Functions, ale nie jest to zestaw SDK ogólnego przeznaczenia. Używaj jej specjalnie do tworzenia i uruchamiania funkcji w środowisku uruchomieniowym Azure Functions.

Użyj adnotacji typu, aby ulepszyć obsługę funkcji IntelliSense i edytora:

def http_trigger(req: func.HttpRequest) -> str:

Organizowanie przy użyciu strategii

W przypadku większych lub modułowych aplikacji użyj blueprints aby zdefiniować funkcje w osobnych plikach Python i zarejestrować je w głównej aplikacji. Ta separacja zapewnia uporządkowanie kodu i możliwość ponownego wykorzystania.

Aby zdefiniować i zarejestrować strategię:

  1. Zdefiniuj strategię w innym pliku Python, takim jak http_blueprint.py:

    import azure.functions as func

bp = func.Blueprint()

@bp.route(route="default_template")
def default_template(req: func.HttpRequest) -> func.HttpResponse:
    return func.HttpResponse("Hello World!")

  2. Zarejestruj strategię w pliku głównym function_app.py :

    import azure.functions as func
from http_blueprint import bp

app = func.FunctionApp()
app.register_functions(bp)

Za pomocą strategii można wykonywać następujące czynności:

  • Podział aplikacji na moduły wielokrotnego użytku
  • Zachowaj powiązane funkcje pogrupowane według pliku lub funkcji
  • Rozszerzanie lub dzielenie się szkicami między projektami

Uwaga

Durable Functions obsługuje również blueprinty przy użyciu azure-functions-durable. Zobacz przykład →

Struktura folderów

Użyj następującej struktury dla projektu Python Azure Functions:

<project_root>/
│
├── .venv/                   # (Optional) Local Python virtual environment
├── .vscode/                 # (Optional) VS Code workspace settings
│
├── function_app.py          # Main function entry point (decorator model)
├── shared/                  # (Optional) Pure helper code with no triggers/bindings
│   └── utils.py
│
├── additional_functions/    # (Optional) Contains blueprints for organizing related Functions
│   └── blueprint_1.py  
│
├── tests/                   # (Optional) Unit tests for your functions
│   └── test_my_function.py
│
├── .funcignore              # Excludes files from being published
├── host.json                # Global function app configuration
├── local.settings.json      # Local-only app settings (not published)
├── requirements.txt         # (Optional) Defines Python dependencies for remote build
├── Dockerfile               # (Optional) For custom container deployment

Kluczowe pliki i foldery

Plik / Folder opis Aplikacja wymagana do uruchomienia w Azure
function_app.py Główny skrypt, w którym Azure Functions i wyzwalacze są definiowane przy użyciu dekoratorów. ✅
host.json Konfiguracja globalna dla wszystkich funkcji w aplikacji. ✅
requirements.txt Zależności Python są instalowane podczas publikowania przy użyciu kompilacji zdalnej remote build. ❌ (zalecane w przypadku zarządzania pakietami)
local.settings.json Ustawienia aplikacji i tajne informacje przeznaczone tylko dla lokalnego użytku (nigdy nie są udostępniane). ❌ (wymagane do rozwoju lokalnego)
.funcignore Określa pliki i foldery do wykluczenia z wdrożenia (na przykład .venv/, , tests/local.settings.json). ❌ (zalecane)
.venv/ Lokalne środowisko wirtualne dla Python (wykluczone z wdrożenia). ❌
.vscode/ Konfiguracja edytora dla Visual Studio Code. Nie wymaga wdrożenia. ❌
shared/ Przechowuje kod pomocniczy współdzielony w projekcie aplikacji funkcji ❌
additional_functions/ Służy do modularnej organizacji kodu — zwykle ze szkicami. ❌
tests/ Testy jednostkowe dla Twojej aplikacji funkcji. Nie opublikowano w Azure. ❌
Dockerfile Definiuje kontener niestandardowy do wdrożenia. ❌

[UWAGA!] requirements.txt Dołącz plik podczas wdrażania za pomocą kompilacji zdalnej. Jeśli nie używasz kompilacji zdalnej lub chcesz użyć innego pliku do definiowania zależności aplikacji, możesz wykonać lokalną kompilację i wdrożyć aplikację ze wstępnie utworzonymi zależnościami.

Aby uzyskać wskazówki dotyczące testowania jednostkowego, zobacz Testowanie jednostkowe. Aby zapoznać się z wdrożeniami kontenerów, zobacz Wdrażanie za pomocą kontenerów niestandardowych.

Wyzwalacze i powiązania

Azure Functions używa triggers do uruchamiania wykonywania funkcji i bindings w celu połączenia kodu z innymi usługami, takimi jak magazyn, kolejki i bazy danych. W modelu programowania Python w wersji 2 deklaruj powiązania przy użyciu dekoratorów.

Istnieją dwa główne typy powiązań:

  • Wyzwalacze (dane wejściowe uruchamiające funkcję)
  • Dane wejściowe i wyjściowe (dodatkowe źródła danych lub miejsca docelowe)

Aby uzyskać więcej informacji na temat dostępnych wyzwalaczy i powiązań, zobacz Triggers and Bindings in Azure Functions (Wyzwalacze i powiązania).

Przykład: Wyzwalacz czasomierza z danymi wejściowymi obiektu blob

Ta funkcja:

  • Wyzwalacze co 10 minut
  • Odczyty z Blob przy użyciu powiązań typowych SDK
  • Buforuje wyniki i zapisuje w pliku tymczasowym
import azure.functions as func
import azurefunctions.extensions.bindings.blob as blob
import logging
import tempfile

CACHED_BLOB_DATA = None

app = func.FunctionApp()

@app.function_name(name="TimerTriggerWithBlob")
@app.schedule(schedule="0 */10 * * * *", arg_name="mytimer")
@app.blob_input(arg_name="client",
                path="PATH/TO/BLOB",
                connection="BLOB_CONNECTION_SETTING")
def timer_trigger_with_blob(mytimer: func.TimerRequest,
                            client: blob.BlobClient,
                            context: func.Context) -> None:
    global CACHED_BLOB_DATA
    if CACHED_BLOB_DATA is None:
        # Download blob and save as a global variable
        CACHED_BLOB_DATA = client.download_blob().readall()

        # Create temp file prefix
        my_prefix = context.invocation_id
        temp_file = tempfile.NamedTemporaryFile(prefix=my_prefix)
        temp_file.write(CACHED_BLOB_DATA)
        logging.info(f"Cached data written to {temp_file.name}")

Najważniejsze pojęcia

  • Używanie powiązań typu zestawu SDK do pracy z bogatymi typami. Aby uzyskać więcej informacji, zobacz Powiązania typu zestawu SDK.
  • Zmienne globalne umożliwiają buforowanie kosztownych obliczeń, ale ich stan nie jest gwarantowany w przypadku wykonywania funkcji.
  • Pliki tymczasowe są przechowywane w tmp/ i nie są gwarantowane jako trwałe między wywołaniami ani instancjami skalowalnymi w poziomie.
  • Dostęp do kontekstu wywołania funkcji można uzyskać za pomocą klasy Context.

Przykład: wyzwalacz HTTP z danymi wejściowymi usługi Cosmos DB i danymi wyjściowymi centrum zdarzeń

Ta funkcja:

  • Wyzwalacze w żądaniu HTTP
  • Odczytywanie z bazy danych Cosmos DB
  • Zapisuje do wyjścia Event Hub
  • Zwraca odpowiedź HTTP
# __init__.py
import azure.functions as func

def main(req: func.HttpRequest,
         documents: func.DocumentList,
         event: func.Out[str]) -> func.HttpResponse:

    # Content from HttpRequest and Cosmos DB input
    http_content = req.params.get("body")
    doc_id = documents[0]["id"] if documents else "No documents found"

    event.set(f"HttpRequest content: {http_content} | CosmosDB ID: {doc_id}")

    return func.HttpResponse(
        "Function executed successfully.",
        status_code=200
    )

// function.json
{
  "scriptFile": "__init__.py",
  "entryPoint": "main",
  "bindings": [
    {
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": ["get", "post"],
      "route": "file"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    },
    {
      "type": "cosmosDB",
      "direction": "in",
      "name": "documents",
      "databaseName": "test",
      "containerName": "items",
      "id": "cosmosdb-input-test",
      "connection": "COSMOSDB_CONNECTION_SETTING"
    },
    {
      "type": "eventHub",
      "direction": "out",
      "name": "event",
      "eventHubName": "my-test-eventhub",
      "connection": "EVENTHUB_CONNECTION_SETTING"
    }
  ]
}

Kluczowe pojęcia

  • Każda funkcja ma jeden wyzwalacz, ale może mieć wiele powiązań.
  • Dodaj dane wejściowe, określając direction jako "in" w function.json. Dane wyjściowe mają direction o wartości out.
  • Możesz uzyskać dostęp do szczegółów żądania za pośrednictwem HttpRequest obiektu i utworzyć niestandardowy HttpResponse z nagłówkami, kodem stanu i treścią.
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="HttpTriggerWithCosmosDB")
@app.route(route="file")
@app.cosmos_db_input(arg_name="documents",
                     database_name="test",
                     container_name="items",
                     connection="COSMOSDB_CONNECTION_SETTING")
@app.event_hub_output(arg_name="event",
                      event_hub_name="my-test-eventhub",
                      connection="EVENTHUB_CONNECTION_SETTING")
def http_trigger_with_cosmosdb(req: func.HttpRequest,
                               documents: func.DocumentList,
                               event: func.Out[str]) -> func.HttpResponse:
    # Content from HttpRequest and Cosmos DB input
    http_content = req.params.get('body')
    doc_id = documents[0]['id']

    event.set("HttpRequest content: " + http_content
              + " | CosmosDB ID: " + doc_id)

    return func.HttpResponse(
        f"Function executed successfully.",
        status_code=200
    )

Najważniejsze pojęcia

  • Użyj dekoratora @route() lub dekoratorów specyficznych dla wyzwalacza (@timer_trigger, @queue_trigger i innych), aby zdefiniować sposób, w jaki wywoływana jest twoja funkcja.
  • Dodaj dane wejściowe przy użyciu dekoratorów, takich jak @blob_input, @queue_inputi innych.
  • Dane wyjściowe mogą być następujące:
    • Zwracane bezpośrednio (jeśli tylko jedno dane wyjściowe)
    • Przypisane przy użyciu powiązań Out i metody .set() dla wielu wyników.
  • Możesz uzyskać dostęp do szczegółów żądania za pośrednictwem HttpRequest obiektu i utworzyć niestandardowy HttpResponse z nagłówkami, kodem stanu i treścią.

Wiązania typu SDK

W przypadku wybranych wyzwalaczy i powiązań można pracować z typami danych zaimplementowanymi przez podstawowe Azure SDKs i struktury. Korzystając z tych powiązań typu zestawu SDK, możesz wchodzić w interakcje z danymi powiązania, tak jak w przypadku korzystania z bazowego zestawu SDK usługi. Aby uzyskać więcej informacji, zobacz obsługiwane powiązania typu zestawu SDK.

Ważne

Obsługa powiązań typów zestawu SDK dla Python jest dostępna tylko w modelu programowania Python w wersji 2.

Zmienne środowiskowe

Zmienne środowiskowe w usłudze Azure Functions umożliwiają bezpieczne zarządzanie wartościami konfiguracji, parametrami połączenia i tajnymi danymi aplikacji bez twardego kodowania ich w kodzie funkcji.

Zmienne środowiskowe można zdefiniować:

Uzyskaj dostęp do zmiennych bezpośrednio w kodzie przy użyciu polecenia os.environ lub os.getenv.

setting_value = os.getenv("myAppSetting", "default_value")

Uwaga

Azure Functions rozpoznaje również zmienne środowiskowe systemu, które konfigurują środowisko uruchomieniowe funkcji i działanie procesów roboczych w Pythonie. Te zmienne nie są jawnie używane w kodzie funkcji, ale wpływają na sposób działania aplikacji. Aby uzyskać pełną listę zmiennych środowiskowych systemowych, zobacz Dokumentacja ustawień aplikacji.

Zarządzanie pakietami

Aby użyć innych pakietów Python w aplikacji Azure Functions, wyświetl je w pliku requirements.txt w katalogu głównym projektu. Te pakiety są importowane przez system importu Python, a następnie można odwoływać się do tych pakietów w zwykły sposób. Aby dowiedzieć się więcej na temat tworzenia i wdrażania opcji z zależnościami zewnętrznymi, zobacz Opcje kompilacji dla aplikacji funkcji Python.

Na przykład, poniższa próbka pokazuje, jak moduł requests jest uwzględniony i używany w aplikacji funkcji.

<requirements.txt>
requests==2.31.0

Zainstaluj pakiet lokalnie za pomocą polecenia pip install -r requirements.txt.

Po zainstalowaniu pakietu można go zaimportować i użyć w kodzie funkcji:

import azure.functions as func
import requests

def main(req: func.HttpRequest) -> func.HttpResponse:
    r = requests.get("https://api.github.com")
    return func.HttpResponse(f"Status: {r.status_code}")

import azure.functions as func
import requests

app = func.FunctionApp()

@app.function_name(name="HttpExample")
@app.route(route="call_api")
def main(req: func.HttpRequest) -> func.HttpResponse:
    r = requests.get("https://api.github.com")
    return func.HttpResponse(f"Status: {r.status_code}")

Rozważania

  • Konflikty z wbudowanymi modułami:
    • Unikaj nazewnictwa folderów projektu od standardowych bibliotek Pythona (na przykład email/, json/).
    • Nie dołączaj bibliotek natywnych Python (takich jak logging, asyncio lub uuid) w requirements.txt.
  • Wdrażania:
    • Aby zapobiec błędomModuleNotFound, upewnij się, że wszystkie wymagane zależności są wymienione w pliku requirements.txt.
    • Jeśli zaktualizujesz Python wersję aplikacji, skompilujesz i ponownie wdrożysz aplikację w nowej wersji Python, aby uniknąć konfliktów zależności z wcześniej utworzonymi pakietami.
  • Zależności inne niż PyPI:
  • Azure Functions zależności modułów roboczych Python:
    • Jeśli pakiet zawiera pewne biblioteki, które mogą zderzać się z zależnościami procesu roboczego (na przykład protobuf lub grpcio), skonfiguruj PYTHON_ISOLATE_WORKER_DEPENDENCIES na 1 w ustawieniach aplikacji, aby uniemożliwić aplikacji odwoływania się do zależności procesu roboczego. W przypadku Python 3.13 i nowszych funkcja this jest domyślnie włączona.

Uruchamianie i wdrażanie

Ta sekcja zawiera informacje o lokalnym uruchamianiu funkcji, obsłudze wersji Python, opcjach budowania i wdrażania oraz konfiguracji środowiska wykonawczego. Użyj tych informacji, aby pomyślnie uruchomić aplikację funkcji w środowiskach lokalnych i Azure.

Uruchamianie lokalnie

Możesz uruchomić i przetestować aplikację funkcji Python na komputerze lokalnym przed wdrożeniem w Azure.

Korzystanie z narzędzi Azure Functions Core Tools

Zainstaluj Azure Functions Core Tools i uruchom lokalne środowisko uruchomieniowe, uruchamiając polecenie func start z katalogu głównego projektu:

func start

Po lokalnym uruchomieniu aplikacji funkcyjnej narzędzie Core Tools wyświetla wszystkie funkcje, które znajdzie dla Twojej aplikacji.

Functions:
        http_trigger:  http://localhost:7071/api/http_trigger

Aby dowiedzieć się więcej na temat korzystania z narzędzi Core Tools, zobacz Develop Azure Functions lokalnie przy użyciu narzędzi Core Tools.

Bezpośrednie wywoływanie funkcji

Używając azure-functions >= 1.21.0, można również wywoływać funkcje bezpośrednio przy użyciu interpretera Python bez uruchamiania narzędzi Core Tools. Takie podejście jest przydatne w przypadku szybkich testów jednostkowych:

# function_app.py
import azure.functions as func

app = func.FunctionApp(http_auth_level=func.AuthLevel.ANONYMOUS)

@app.route(route="http_trigger")
def http_trigger(req: func.HttpRequest) -> func.HttpResponse:
    return "Hello, World!"

# Test the function directly
print(http_trigger(None))

Aby wyświetlić dane wyjściowe, uruchom plik bezpośrednio przy użyciu Python:

> python function_app.py

Hello, World!

# __init__.py
import azure.functions as func

def main(req: func.HttpRequest) -> func.HttpResponse:
    return func.HttpResponse("Hello, World!")

# Test the function directly
print(main(None))

Aby wyświetlić dane wyjściowe, uruchom plik bezpośrednio przy użyciu Python:

> python __init__.py

Hello, World!

Takie podejście nie wymaga żadnych dodatkowych pakietów ani konfiguracji i jest idealne do szybkiej weryfikacji podczas programowania. Aby uzyskać więcej szczegółowych informacji na temat testowania, zobacz Testowanie jednostkowe

Obsługiwane wersje Python

Azure Functions obsługuje wersje Python wymienione w Obsługiwane języki w Azure Functions. Aby uzyskać więcej ogólnych informacji, zobacz zasady obsługi środowiska uruchomieniowego Azure Functions.

Ważne

Jeśli zmienisz wersję Python dla aplikacji funkcji, musisz ponownie skompilować i wdrożyć aplikację przy użyciu nowej wersji. Istniejące artefakty wdrożenia i zależności nie są automatycznie odbudowywane po zmianie wersji Python.

Kompilowanie i wdrażanie

Aby dowiedzieć się więcej na temat zalecanego mechanizmu kompilacji dla danego scenariusza, zobacz Opcje kompilacji. Aby zapoznać się z ogólnym omówieniem technologii wdrażania, zobacz Deployment w Azure Functions.

Szybkie porównanie mechanizmów wdrażania

Narzędzie/platforma Polecenie/akcja Najlepszy przypadek użycia
Azure Functions Core Tools func azure functionapp publish <APP_NAME> Idealne dla operacji ciągłej integracji, automatyzacji lokalnej lub działań między platformami.
AZ CLI (Interfejs wiersza polecenia dla Azure) az functionapp deployment source config-zip Przydatne podczas wykonywania skryptów wdrożeń poza narzędziami Core Tools. Działa dobrze w zautomatyzowanych potokach lub terminalach opartych na chmurze (Azure Cloud Shell).
Visual Studio Code (rozszerzenie Azure Functions) Paleta Poleceń → "Azure Functions: Deploy to Azure..." Najlepsze dla początkujących lub interaktywnych wdrożeń. Automatycznie obsługuje pakowanie i kompilowanie.
GitHub Actions Azure/functions-action@v1 Idealne dla GitHub, oparte na ciągłej integracji i ciągłym wdrażaniu. Umożliwia automatyczne wdrożenia w scalaniu wypychanych lub żądań ściągnięcia.
Azure Pipelines AzureFunctionApp@2 Zadanie CI/CD w przedsiębiorstwie przy użyciu Azure DevOps. Najlepszy dla przepływów pracy z kontrolowanym wydaniem, kompilacji z kontrolowanym dostępem oraz potoków wieloetapowych.
Wdrożenie niestandardowego kontenera Pchnij kontener az functionapp create --image <container> Wymagane, jeśli potrzebujesz pakietów na poziomie systemu operacyjnego, niestandardowych kompilacji Python, przypiętych środowisk uruchomieniowych lub nieobsługiwanych zależności (na przykład bibliotek systemowych, lokalnych plików binarnych).
Tworzenie funkcji opartej na portalu Utwórz funkcję w portalu Azure → poprzez edytor inline Używaj tylko dla prostych, wolnych od zależności funkcji. Doskonale sprawdza się w przypadku pokazów lub szkoleń, ale nie jest to zalecane w przypadku aplikacji wymagających pakietów innych firm.

Uwaga

Tworzenie funkcji oparte na portalu nie obsługuje zależności innych firm i nie jest zalecane do tworzenia aplikacji produkcyjnych. Nie można zainstalować ani odwołać się do pakietów poza azure-functions i wbudowaną bibliotekę standardową Pythona.

Ważne

Po 30 września 2028 r. opcja hostowania aplikacji funkcyjnej w systemie Linux w planie konsumpcyjnym zostanie wycofana. Aby uniknąć zakłóceń, zmigruj istniejące aplikacje planu zużycia działające na Linuxie do planu Flex Consumption przed tą datą. Ta zmiana nie ma wpływu na aplikacje działające na Windows w planie Zużycie.

Po 30 września 2025 r. do planu Zużycie systemu Linux nie będą dodawane żadne nowe funkcje ani wsparcie dla nowych stosów językowych. Ostatnie obsługiwane wersje językowe użycia systemu Linux to: .NET 9, Python 3.12, Node.js 22, PowerShell 7.4 i Java 21. Nowsze wersje językowe nie są obsługiwane w przypadku użycia systemu Linux.

Aby uzyskać więcej informacji, zobacz Migrowanie aplikacji z planu zużycia na plan Flex Consumption.

Aktualizacje Python dla wersji 3.13 i nowsze

Począwszy od wersji Python 3.13, Azure Functions wprowadza kilka głównych ulepszeń środowiska uruchomieniowego i wydajności, które wpływają na sposób tworzenia i uruchamiania aplikacji. Kluczowe zmiany obejmują:

  • Kontrola wersji środowiska uruchomieniowego: Możesz teraz opcjonalnie przypisać lub zaktualizować swoją aplikację do określonych wersji worker Python, odwołując się do pakietu azure-functions-runtime w requirements.txt.

    • Bez włączonej kontroli wersji aplikacja jest uruchamiana w domyślnej wersji środowiska uruchomieniowego Python, którym zarządza usługa Functions. Musisz zmodyfikować plik requirements.txt, aby zażądać najnowszej wersji, wersji wstępnie wydanej lub przypiąć aplikację do określonej wersji środowiska uruchomieniowego Python.

    • Możesz włączyć kontrolę wersji środowiska uruchomieniowego, dodając odwołanie do pakietu środowiska uruchomieniowego Python do pliku requirements.txt, gdzie wartość przypisana do pakietu określa używaną wersję środowiska uruchomieniowego.

    • Unikaj przypinania dowolnej aplikacji produkcyjnej do wersji wstępnych (alfa, beta lub deweloperskich).

    • Aby być świadomym zmian, regularnie przeglądaj notatki o wydaniu środowiska uruchomieniowego Python.

    • W poniższej tabeli przedstawiono zachowanie przechowywania wersji na podstawie wartości wersji tego ustawienia w pliku requirements.txt :

      wersja Przykład Zachowanie
      Brak ustawionej wartości azure-functions-runtime Aplikacja Python w wersji 3.13 lub nowszej jest uruchamiana w najnowszej dostępnej wersji środowiska uruchomieniowego usługi Functions Python. Ta opcja jest najlepsza do utrzymania aktualności dzięki ulepszeniom i funkcjom platformy, ponieważ aplikacja automatycznie otrzymuje najnowsze stabilne aktualizacje środowiska uruchomieniowego.
      Przypięte do określonej wersji azure-functions-runtime==1.2.0 Aplikacja Python w wersji 3.13 lub nowszej pozostaje w przypiętej wersji środowiska uruchomieniowego i nie otrzymuje aktualizacji automatycznych. Zamiast tego należy ręcznie zaktualizować przypiętą wersję, aby korzystać z nowych funkcji, poprawek i ulepszeń środowiska uruchomieniowego. Przypinanie jest zalecane w przypadku krytycznych obciążeń produkcyjnych, w których niezbędna jest stabilność i przewidywalność. Przypinanie umożliwia również testowanie aplikacji na przedpremierowych wersjach środowiska uruchomieniowego w trakcie rozwoju.
      Brak odwołania do pakietu n/a Nie ustawiając azure-functions-runtime, aplikacja Python w wersji 3.13 lub nowszej jest uruchamiana w domyślnej wersji środowiska uruchomieniowego Python, które znajduje się za najnowszą wydaną wersją. Aktualizacje są okresowo wprowadzane przez usługę Functions. Ta opcja zapewnia stabilność i szeroką zgodność. Jednak dostęp do najnowszych funkcji i poprawek jest opóźniony do momentu zaktualizowania wersji domyślnej.

  • Izolacja zależności: zależności aplikacji (na przykład grpcio lub protobuf) są w pełni odizolowane od zależności modułu roboczego, co zapobiega konfliktom wersji. Ustawienie aplikacji PYTHON_ISOLATE_WORKER_DEPENDENCIES nie będzie miało wpływu na aplikacje działające w Python 3.13 lub nowszym.

  • Uproszczona konfiguracja przesyłania strumieniowego HTTP — nie są wymagane żadne specjalne ustawienia aplikacji.

  • Usunięto obsługę rozszerzeń procesów roboczych i funkcji pamięci udostępnionej.

  • Kontrola wersji środowiska uruchomieniowego: Możesz teraz opcjonalnie przypisać lub zaktualizować swoją aplikację do określonych wersji worker Python, odwołując się do pakietu azure-functions-runtime-v1 w requirements.txt.

    • Bez włączonej kontroli wersji aplikacja jest uruchamiana w domyślnej wersji środowiska uruchomieniowego Python, którym zarządza usługa Functions. Musisz zmodyfikować plik requirements.txt, aby zażądać najnowszej wersji, wersji wstępnie wydanej lub przypiąć aplikację do określonej wersji środowiska uruchomieniowego Python.

    • Możesz włączyć kontrolę wersji środowiska uruchomieniowego, dodając odwołanie do pakietu środowiska uruchomieniowego Python do pliku requirements.txt, gdzie wartość przypisana do pakietu określa używaną wersję środowiska uruchomieniowego.

    • Unikaj przypinania dowolnej aplikacji produkcyjnej do wersji wstępnych (alfa, beta lub deweloperskich).

    • Aby być świadomym zmian, regularnie przeglądaj notatki o wydaniu środowiska uruchomieniowego Python.

    • W poniższej tabeli przedstawiono zachowanie przechowywania wersji na podstawie wartości wersji tego ustawienia w pliku requirements.txt :

      wersja Przykład Zachowanie
      Brak ustawionej wartości azure-functions-runtime-v1 Aplikacja Python w wersji 3.13 lub nowszej jest uruchamiana w najnowszej dostępnej wersji środowiska uruchomieniowego usługi Functions Python. Ta opcja jest najlepsza do utrzymania aktualności dzięki ulepszeniom i funkcjom platformy, ponieważ aplikacja automatycznie otrzymuje najnowsze stabilne aktualizacje środowiska uruchomieniowego.
      Przypięte do określonej wersji azure-functions-runtime-v1==1.2.0 Aplikacja Python w wersji 3.13 lub nowszej pozostaje w przypiętej wersji środowiska uruchomieniowego i nie otrzymuje aktualizacji automatycznych. Zamiast tego należy ręcznie zaktualizować przypiętą wersję, aby korzystać z nowych funkcji, poprawek i ulepszeń środowiska uruchomieniowego. Przypinanie jest zalecane w przypadku krytycznych obciążeń produkcyjnych, w których niezbędna jest stabilność i przewidywalność. Przypinanie umożliwia również testowanie aplikacji na przedpremierowych wersjach środowiska uruchomieniowego w trakcie rozwoju.
      Brak odwołania do pakietu n/a Nie ustawiając azure-functions-runtime-v1, aplikacja Python w wersji 3.13 lub nowszej jest uruchamiana w domyślnej wersji środowiska uruchomieniowego Python, które znajduje się za najnowszą wydaną wersją. Aktualizacje są okresowo wprowadzane przez usługę Functions. Ta opcja zapewnia stabilność i szeroką zgodność. Jednak dostęp do najnowszych funkcji i poprawek jest opóźniony do momentu zaktualizowania wersji domyślnej.

  • Izolacja zależności: zależności aplikacji (na przykład grpcio lub protobuf) są w pełni odizolowane od zależności modułu roboczego, co zapobiega konfliktom wersji. Ustawienie aplikacji PYTHON_ISOLATE_WORKER_DEPENDENCIES nie będzie miało wpływu na aplikacje działające w Python 3.13 lub nowszym.

  • Usunięto obsługę rozszerzeń procesów roboczych i funkcji pamięci udostępnionej.

Obserwowanie i testowanie

W tej sekcji opisano logging, monitoring oraz testing capabilities w celu ułatwienia debugowania problemów, śledzenia wydajności i zapewnienia niezawodności aplikacji funkcji Python.

Rejestrowanie i monitorowanie

Azure Functions udostępnia rejestrator root, którego można używać bezpośrednio z wbudowanym modułem języka Python logging. Wszystkie komunikaty zapisywane przy użyciu tego rejestratora są automatycznie wysyłane do Application Insights gdy aplikacja jest uruchomiona w Azure.

Rejestrowanie umożliwia przechwytywanie informacji o środowisku uruchomieniowym i diagnozowanie problemów bez konieczności dodatkowej konfiguracji.

Przykład rejestrowania za pomocą wyzwalacza HTTP

import logging
import azure.functions as func

def main(req: func.HttpRequest) -> func.HttpResponse:
    logging.debug("Example debug log")
    logging.info("Example info log")
    logging.warning("Example warning")
    logging.error("Example error log")
    return func.HttpResponse("OK")

import logging
import azure.functions as func

app = func.FunctionApp()

@app.route(route="http_trigger")
def http_trigger(req) -> func.HttpResponse:
    logging.debug("Example debug log")
    logging.info("Example info log")
    logging.warning("Example warning")
    logging.error("Example error log")
    return func.HttpResponse("OK")

Możesz użyć pełnego zestawu poziomów rejestrowania (debug, info, warning, error, critical) i są one wyświetlane w portalu Azure w obszarze Dzienniki lub Application Insights.

Aby dowiedzieć się więcej na temat monitorowania Azure Functions w portalu, zobacz Monitorowanie Azure Functions.

Uwaga

Aby wyświetlić dzienniki debugowania w usłudze Application Insights, wymagana jest większa konfiguracja. Tę funkcję można włączyć, ustawiając PYTHON_ENABLE_DEBUG_LOGGING na 1 i ustawiając wartość logLeveltrace lub debug w plikuhost.json. Domyślnie dzienniki debugowania nie są widoczne w usłudze Application Insights.

Logowanie z wątków w tle

Jeśli funkcja uruchamia nowy wątek i musi zalogować się z tego wątku, pamiętaj o przekazaniu argumentu context do wątku. Zawiera context magazyn lokalny wątku oraz element invocation_id, który obecnie musi być ustawiony na wątku roboczym, aby dzienniki były prawidłowo skojarzone z wykonywaniem funkcji.

import logging
import threading
import azure.functions as func

def main(req: func.HttpRequest, context) -> func.HttpResponse:
    logging.info("Function started")
    t = threading.Thread(target=log_from_thread, args=(context,))
    t.start()
    return "okay"

def log_from_thread(context):
    # Associate the thread with the current invocation
    context.thread_local_storage.invocation_id = context.invocation_id  
    logging.info("Logging from a background thread")

import azure.functions as func
import logging
import threading

app = func.FunctionApp()

@app.route(route="http_trigger")
def http_trigger(req, context) -> func.HttpResponse:
    logging.info("Function started")
    t = threading.Thread(target=log_from_thread, args=(context,))
    t.start()
    return "okay"

def log_from_thread(context):
    # Associate the thread with the current invocation
    context.thread_local_storage.invocation_id = context.invocation_id  
    logging.info("Logging from a background thread")

Konfigurowanie niestandardowych rejestratorów

Niestandardowe rejestratory można skonfigurować w języku Python, gdy potrzebujesz większej kontroli nad zachowaniem logowania, takim jak niestandardowe formatowanie, filtrowanie dzienników lub integracje z firmami trzecimi. Aby skonfigurować niestandardowy rejestrator, użyj Python logging.getLogger() z niestandardową nazwą i dodaj programy obsługi lub formatatory zgodnie z potrzebami.

import logging

custom_logger = logging.getLogger('my_custom_logger')

Obsługa funkcji OpenTelemetry

Azure Functions dla Python obsługuje również OpenTelemetry co umożliwia emitowanie śladów, metryk i dzienników w standardowym formacie. Korzystanie z technologii OpenTelemetry jest szczególnie przydatne w przypadku aplikacji rozproszonych lub scenariuszy, w których chcesz wyeksportować dane telemetryczne do narzędzi spoza usługi Application Insights (takich jak Grafana lub Jaeger).

Aby uzyskać instrukcje konfiguracji i przykładowy kod, zobacz przewodnik szybkiego startu OpenTelemetry dla Azure Functions (Python).

Testowanie jednostek

Napisz i uruchom testy jednostkowe dla swoich funkcji przy użyciu pytest. Funkcje Python, takie jak inny kod Python, można przetestować przy użyciu standardowych struktur testowania. W przypadku większości powiązań można utworzyć pozorny obiekt wejściowy, tworząc wystąpienie odpowiedniej klasy z azure.functions pakietu.

Na przykładzie my_function, poniższy przykład to test próbny funkcji wyzwalanej przez HTTP.

Najpierw utwórz <plik project_root>/function_app.py i zaimplementuj my_function funkcję jako wyzwalacz HTTP.

# <project_root>/function_app.py
import azure.functions as func
import logging

app = func.FunctionApp()

# Define the HTTP trigger that accepts the ?value=<int> query parameter
# Double the value and return the result in HttpResponse
@app.function_name(name="my_function")
@app.route(route="hello")
def my_function(req: func.HttpRequest) -> func.HttpResponse:
    logging.info('Executing myfunction.')

    initial_value: int = int(req.params.get('value'))
    doubled_value: int = initial_value * 2

    return func.HttpResponse(
        body=f"{initial_value} * 2 = {doubled_value}",
        status_code=200
    )

Możesz rozpocząć pisanie przypadków testowych dla wyzwalacza HTTP.

# <project_root>/test_my_function.py
import unittest
import azure.functions as func

from function_app import my_function

class TestFunction(unittest.TestCase):
  def test_my_function(self):
    # Construct a mock HTTP request.
    req = func.HttpRequest(method='GET',
                           body=None,
                           url='/api/my_function',
                           params={'value': '21'})
    # Call the function.
    func_call = main.build().get_user_function()
    resp = func_call(req)
    # Check the output.
    self.assertEqual(
        resp.get_body(),
        b'21 * 2 = 42',
    )

W folderze środowiska wirtualnego Python możesz uruchomić następujące polecenia, aby przetestować aplikację:

pip install pytest
pytest test_my_function.py

W terminalu widać wyniki pytest tak jak poniżej:

============================================================================================================ test session starts ============================================================================================================
collected 1 item                                                                                                                                                                                                                             

test_my_function.py .                                                                                                                                                                                                                  [100%] 
============================================================================================================= 1 passed in 0.24s =============================================================================================================

Optymalizacja i tematy zaawansowane

Aby dowiedzieć się więcej na temat optymalizowania aplikacji funkcji Python, zobacz następujące artykuły:

Aby uzyskać więcej informacji na temat funkcji, zobacz następujące artykuły:

Masz problemy z używaniem Python? Daj nam znać i zgłoś problem.

  • Last updated on