HTTP-szolgáltatások

A Durable Functions számos olyan funkcióval rendelkezik, amelyek megkönnyítik a tartós vezénylések és entitások HTTP-munkafolyamatokba való beépítését. Ez a cikk részletesen ismerteti ezen funkciók némelyikét.

HTTP API-k felfedve

A vezénylések és entitások HTTP-kérésekkel hívhatók meg és kezelhetők. A Durable Functions bővítmény beépített HTTP API-kat tesz elérhetővé. Emellett API-kat biztosít a VEzénylések és entitások HTTP által aktivált függvényekből való kezeléséhez.

Beépített HTTP API-k

A Durable Functions bővítmény automatikusan hozzáad egy SOR HTTP API-t az Azure Functions-gazdagéphez. Ezekkel az API-kkal kódírás nélkül kezelheti a vezényléseket és entitásokat.

A következő beépített HTTP API-k támogatottak.

• Új vezénylés indítása
• Lekérdezés-vezénylési példány
• Vezénylési példány leállása
• Külső esemény küldése vezénylésre
• Vezénylési előzmények törlése
• Műveletesemény küldése egy entitásnak
• Entitás állapotának lekérése
• Entitások listájának lekérdezése

A Durable Functions bővítmény által közzétett beépített HTTP API-k teljes leírását a HTTP API-król szóló cikkben találja.

HTTP API URL-felderítés

A vezénylési ügyfélkötés olyan API-kat tesz elérhetővé, amelyek kényelmes HTTP-válasz hasznos adatokat hozhatnak létre. Létrehozhat például egy választ, amely egy adott vezénylési példány felügyeleti API-ira mutató hivatkozásokat tartalmaz. Az alábbi példák egy HTTP-trigger függvényt mutatnak be, amely bemutatja, hogyan használhatja ezt az API-t egy új vezénylési példányhoz:

C#

// Copyright (c) .NET Foundation. All rights reserved.
// Licensed under the MIT License. See LICENSE in the project root for license information.

using System.Net.Http;
using System.Threading.Tasks;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.DurableTask;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Extensions.Logging;

namespace VSSample
{
    public static class HttpStart
    {
        [FunctionName("HttpStart")]
        public static async Task<HttpResponseMessage> Run(
            [HttpTrigger(AuthorizationLevel.Function, methods: "post", Route = "orchestrators/{functionName}")] HttpRequestMessage req,
            [DurableClient] IDurableClient starter,
            string functionName,
            ILogger log)
        {
            // Function input comes from the request content.
            object eventData = await req.Content.ReadAsAsync<object>();
            string instanceId = await starter.StartNewAsync(functionName, eventData);

            log.LogInformation($"Started orchestration with ID = '{instanceId}'.");

            return starter.CreateCheckStatusResponse(req, instanceId);
        }
    }
}

JavaScript

index.js

const df = require("durable-functions");

module.exports = async function (context, req) {
    const client = df.getClient(context);
    const instanceId = await client.startNew(req.params.functionName, undefined, req.body);

    context.log(`Started orchestration with ID = '${instanceId}'.`);

    return client.createCheckStatusResponse(context.bindingData.req, instanceId);
};

function.json

{
    "bindings": [
      {
        "authLevel": "anonymous",
        "name": "req",
        "type": "httpTrigger",
        "direction": "in",
        "route": "orchestrators/{functionName}",
        "methods": ["post"]
      },
      {
        "name": "$return",
        "type": "http",
        "direction": "out"
      },
      {
        "name": "starter",
        "type": "orchestrationClient",
        "direction": "in"
      }
    ],
    "disabled": false
  }

Python

init.py

import logging
import azure.functions as func
import azure.durable_functions as df

async def main(req: func.HttpRequest, starter: str) -> func.HttpResponse:
    client = df.DurableOrchestrationClient(starter)
    function_name = req.route_params['functionName']
    event_data = req.get_body()

    instance_id = await client.start_new(function_name, instance_id, event_data)
    
    logging.info(f"Started orchestration with ID = '{instance_id}'.")
    return client.create_check_status_response(req, instance_id)

function.json

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

PowerShell

run.ps1

$FunctionName = $Request.Params.FunctionName
$InstanceId = Start-NewOrchestration -FunctionName $FunctionName
Write-Host "Started orchestration with ID = '$InstanceId'"

$Response = New-OrchestrationCheckStatusResponse -Request $Request -InstanceId $InstanceId
Push-OutputBinding -Name Response -Value $Response

function.json

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "name": "Request",
      "type": "httpTrigger",
      "direction": "in",
      "route": "orchestrators/{FunctionName}",
      "methods": [
        "post",
        "get"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "Response"
    },
    {
      "name": "starter",
      "type": "orchestrationClient",
      "direction": "in"
    }
  ]
}

Java

@FunctionName("HttpStart")
public HttpResponseMessage httpStart(
        @HttpTrigger(name = "req", route = "orchestrators/{functionName}") HttpRequestMessage<?> req,
        @DurableClientInput(name = "durableContext") DurableClientContext durableContext,
        @BindingName("functionName") String functionName,
        final ExecutionContext context) {

    DurableTaskClient client = durableContext.getClient();
    String instanceId = client.scheduleNewOrchestrationInstance(functionName);
    context.getLogger().info("Created new Java orchestration with instance ID = " + instanceId);
    return durableContext.createCheckStatusResponse(req, instanceId);
}

A vezénylőfüggvények indítása a korábban bemutatott HTTP-trigger függvények használatával bármely HTTP-ügyfél használatával elvégezhető. A következő cURL-parancs elindít egy vezénylő függvényt DoWork:

curl -X POST https://localhost:7071/orchestrators/DoWork -H "Content-Length: 0" -i

A következő példa egy olyan vezénylésre adott válasz, amely azonosítóként szolgál abc123 . Néhány részlet el lett távolítva az egyértelműség kedvéért.

HTTP/1.1 202 Accepted
Content-Type: application/json; charset=utf-8
Location: http://localhost:7071/runtime/webhooks/durabletask/instances/abc123?code=XXX
Retry-After: 10

{
    "id": "abc123",
    "purgeHistoryDeleteUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123?code=XXX",
    "sendEventPostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123/raiseEvent/{eventName}?code=XXX",
    "statusQueryGetUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123?code=XXX",
    "terminatePostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123/terminate?reason={text}&code=XXX"
}

Az előző példában Uri a végződő mezők mindegyike egy beépített HTTP API-nak felel meg. Ezekkel az API-kkal kezelheti a cél vezénylési példányt.

Megjegyzés:

A webhook URL-címeinek formátuma attól függ, hogy az Azure Functions-gazdagép melyik verzióját futtatja. Az előző példa az Azure Functions 2.0-gazdagépre mutat.

Az összes beépített HTTP API leírását a HTTP API-referencia ismerteti.

Aszinkron műveletek nyomon követése

A korábban említett HTTP-válasz úgy lett kialakítva, hogy segítsen a hosszan futó HTTP aszinkron API-k megvalósításában a Durable Functions használatával. Ezt a mintát néha lekérdezési fogyasztói mintának is nevezik. Az ügyfél-kiszolgáló folyamat a következőképpen működik:

1. Az ügyfél HTTP-kérést ad ki egy hosszú ideig futó folyamat, például egy vezénylőfüggvény elindításához.
2. A cél HTTP-eseményindító egy HTTP 202-választ ad vissza egy hely fejlécével, amelynek értéke "statusQueryGetUri".
3. Az ügyfél lekérdezi az URL-címet a Hely fejlécben. Az ügyfél továbbra is a HTTP 202-válaszokat látja egy Hely fejléccel.
4. Ha a példány befejeződik vagy meghiúsul, a Hely fejléc végpontja HTTP 200-et ad vissza.

Ez a protokoll lehetővé teszi a hosszú ideig futó folyamatok összehangolását olyan külső ügyfelekkel vagy szolgáltatásokkal, amelyek LEkérdezhetnek egy HTTP-végpontot, és követhetik a Hely fejlécet. A minta ügyfél- és kiszolgálói implementációi is a Durable Functions HTTP API-kba vannak beépítve.

Megjegyzés:

Alapértelmezés szerint az Azure Logic Apps által biztosított ÖSSZES HTTP-alapú művelet támogatja a szabványos aszinkron műveleti mintát. Ez a funkció lehetővé teszi egy hosszú ideig futó tartós függvény beágyazását egy Logic Apps-munkafolyamat részeként. Az aszinkron HTTP-minták Logic Apps-támogatásáról az Azure Logic Apps munkafolyamat-műveleteinek és eseményindítóinak dokumentációjában talál további részleteket.

Megjegyzés:

A vezénylésekkel való interakciók bármilyen függvénytípusból elvégezhetők, nem csak a HTTP által aktivált függvényekből.

A vezénylések és entitások ügyfél API-k használatával történő kezelésével kapcsolatos további információkért tekintse meg a Példánykezelési cikket.

HTTP API-k használata

A vezénylőfüggvények kódkorlátozásaiban leírtak szerint a vezénylő függvények nem tudják közvetlenül elvégezni az I/O-t. Ehelyett általában olyan tevékenységfüggvényeket neveznek, amelyek I/O-műveleteket végeznek.

A Durable Functions 2.0-tól kezdve a vezénylések natív módon használhatják a HTTP API-kat a vezénylési trigger kötésével.

Az alábbi példakód egy kimenő HTTP-kérést készítő vezénylő függvényt mutat be:

C#

[FunctionName("CheckSiteAvailable")]
public static async Task CheckSiteAvailable(
    [OrchestrationTrigger] IDurableOrchestrationContext context)
{
    Uri url = context.GetInput<Uri>();

    // Makes an HTTP GET request to the specified endpoint
    DurableHttpResponse response = 
        await context.CallHttpAsync(HttpMethod.Get, url);

    if (response.StatusCode >= 400)
    {
        // handling of error codes goes here
    }
}

JavaScript

const df = require("durable-functions");

module.exports = df.orchestrator(function*(context){
    const url = context.df.getInput();
    const response = yield context.df.callHttp("GET", url)

    if (response.statusCode >= 400) {
        // handling of error codes goes here
    }
});

Python

import azure.functions as func
import azure.durable_functions as df
from datetime import datetime, timedelta

def orchestrator_function(context: df.DurableOrchestrationContext):
    url = context.get_input()
    response = yield context.call_http('GET', url)
    
    if response["statusCode"] >= 400:
        # handling of error codes goes here

main = df.Orchestrator.create(orchestrator_function)

PowerShell

Ez a funkció nem érhető el a PowerShellben.

Java

Ez a funkció a Java-ban nem érhető el.

A "http meghívása" művelet használatával a következő műveleteket hajthatja végre a vezénylő függvényekben:

• A HTTP API-kat közvetlenül a vezénylési függvényekből hívhatja meg, néhány, később említett korlátozással.
• Automatikusan támogatja az ügyféloldali HTTP 202 állapot-lekérdezési mintákat.
• Az Azure Managed Identityes használatával engedélyezett HTTP-hívásokat indíthat más Azure-végpontokra.

A HTTP API-k közvetlenül a vezénylő függvényekből való felhasználásának lehetősége bizonyos gyakori forgatókönyvek kényelmét szolgálja. Ezeket a funkciókat saját maga is megvalósíthatja tevékenységfüggvények használatával. A tevékenységfüggvények sok esetben nagyobb rugalmasságot biztosíthatnak.

HTTP 202 kezelés

A "call HTTP" API automatikusan implementálhatja a lekérdezési fogyasztói minta ügyféloldalát. Ha egy úgynevezett API egy HTTP 202-választ ad vissza egy Hely fejléccel, a vezénylő függvény automatikusan lekérdezi a Hely erőforrást, amíg nem kap 202-től eltérő választ. Ez a válasz lesz a vezénylő függvény kódjának visszaadott válasza.

Megjegyzés:

1. Az Orchestrator-függvények natív módon támogatják a kiszolgálóoldali lekérdezési fogyasztói mintát is, az Async-műveletkövetésben leírtak szerint. Ez a támogatás azt jelenti, hogy az egyik függvényalkalmazás vezénylései egyszerűen összehangolhatják a vezénylő függvényeket más függvényalkalmazásokban. Ez hasonló az alvezénylési koncepcióhoz, de támogatja az alkalmazásközi kommunikációt. Ez a támogatás különösen hasznos mikroszolgáltatás-stílusú alkalmazások fejlesztéséhez.
2. Ideiglenes korlátozás miatt a beépített HTTP-lekérdezési minta jelenleg nem érhető el a JavaScriptben/TypeScriptben és a Pythonban.

Managed identities

A Durable Functions natív módon támogatja a Microsoft Entra-jogkivonatokat engedélyező API-k hívásait. Ez a támogatás azure-beli felügyelt identitásokkal szerzi be ezeket a jogkivonatokat.

Az alábbi kód egy vezénylő függvény példája. A függvény hitelesített hívásokat indít egy virtuális gép újraindításához az Azure Resource Manager virtuális gépek REST API-jának használatával.

C#

[FunctionName("RestartVm")]
public static async Task RunOrchestrator(
    [OrchestrationTrigger] IDurableOrchestrationContext context)
{
    string subscriptionId = "mySubId";
    string resourceGroup = "myRG";
    string vmName = "myVM";
    string apiVersion = "2019-03-01";
    
    // Automatically fetches an Azure AD token for resource = https://management.core.windows.net/.default
    // and attaches it to the outgoing Azure Resource Manager API call.
    var restartRequest = new DurableHttpRequest(
        HttpMethod.Post, 
        new Uri($"https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/Microsoft.Compute/virtualMachines/{vmName}/restart?api-version={apiVersion}"),
        tokenSource: new ManagedIdentityTokenSource("https://management.core.windows.net/.default"));
    DurableHttpResponse restartResponse = await context.CallHttpAsync(restartRequest);
    if (restartResponse.StatusCode != HttpStatusCode.OK)
    {
        throw new ArgumentException($"Failed to restart VM: {restartResponse.StatusCode}: {restartResponse.Content}");
    }
}

JavaScript

const df = require("durable-functions");

module.exports = df.orchestrator(function*(context) {
    const subscriptionId = "mySubId";
    const resourceGroup = "myRG";
    const vmName = "myVM";
    const apiVersion = "2019-03-01";
    const tokenSource = new df.ManagedIdentityTokenSource("https://management.core.windows.net/.default");

    // get a list of the Azure subscriptions that I have access to
    const restartResponse = yield context.df.callHttp(
        "POST",
        `https://management.azure.com/subscriptions/${subscriptionId}/resourceGroups/${resourceGroup}/providers/Microsoft.Compute/virtualMachines/${vmName}/restart?api-version=${apiVersion}`,
        undefined, // no request content
        undefined, // no request headers (besides auth which is handled by the token source)
        tokenSource);

    return restartResponse;
});

Python

import azure.functions as func
import azure.durable_functions as df

def orchestrator_function(context: df.DurableOrchestrationContext):
    subscription_id = "mySubId"
    resource_group = "myRg"
    vm_name = "myVM"
    api_version = "2019-03-01"
    token_source = df.ManagedIdentityTokenSource("https://management.core.windows.net/.default")

    # get a list of the Azure subscriptions that I have access to
    restart_response = yield context.call_http("POST", 
        f"https://management.azure.com/subscriptions/{subscription_id}/resourceGroups/{resource_group}/providers/Microsoft.Compute/virtualMachines/{vm_name}/restart?api-version={api_version}",
        None,
        None,
        token_source)
    return restart_response

main = df.Orchestrator.create(orchestrator_function)

PowerShell

Ez a funkció nem érhető el a PowerShellben.

Java

Ez a funkció a Java-ban nem érhető el.

Az előző példában a paraméter úgy tokenSource van konfigurálva, hogy Microsoft Entra-jogkivonatokat szerezzen be az Azure Resource Managerhez. A jogkivonatokat az erőforrás URI-ja https://management.core.windows.net/.defaultazonosítja. A példa feltételezi, hogy az aktuális függvényalkalmazás helyileg fut, vagy felügyelt identitással rendelkező függvényalkalmazásként lett üzembe helyezve. A rendszer feltételezi, hogy a helyi identitás vagy a felügyelt identitás rendelkezik engedéllyel a megadott erőforráscsoportban myRGlévő virtuális gépek kezeléséhez.

Futásidőben a konfigurált jogkivonat-forrás automatikusan egy OAuth 2.0 hozzáférési jogkivonatot ad vissza. A forrás ezután tulajdonosi jogkivonatként hozzáadja a jogkivonatot a kimenő kérés engedélyezési fejlécéhez. Ez a modell az engedélyezési fejlécek HTTP-kérelmekhez való manuális hozzáadásának továbbfejlesztése az alábbi okokból:

• A jogkivonatok frissítése automatikusan történik. Nem kell aggódnia a lejárt jogkivonatok miatt.
• A jogkivonatok soha nem tartós vezénylési állapotban vannak tárolva.
• A jogkivonatok beszerzésének kezeléséhez nem kell kódot írnia.

Az előre összeállított C# RestartVMs-mintában talál egy teljesebb példát.

A felügyelt identitások nem korlátozódnak az Azure-erőforrás-kezelésre. Felügyelt identitások használatával hozzáférhet minden olyan API-hoz, amely elfogadja a Microsoft Entra tulajdonosi jogkivonatait, beleértve a Microsoft Azure-szolgáltatásait és a partnerek webalkalmazásait. A partner webalkalmazása akár egy másik függvényalkalmazás is lehet. A Microsoft Entra-azonosítóval való hitelesítést támogató Azure-szolgáltatások listáját a Microsoft Entra-hitelesítést támogató Azure-szolgáltatásokban találja.

Korlátozások

A HTTP API-k meghívásának beépített támogatása kényelmi funkció. Ez nem minden esetben megfelelő.

A vezénylő függvények által küldött HTTP-kérések és válaszaik szerializálva vannak , és üzenetekként maradnak meg a Durable Functions storage-szolgáltatóban. Ez az állandó üzenetsor-kezelés biztosítja, hogy a HTTP-hívások megbízhatóak és biztonságosak legyenek a vezénylési visszajátszáshoz. Az állandó üzenetsor-kezelési viselkedés azonban korlátozásokkal is rendelkezik:

• Minden HTTP-kérés további késést jelent a natív HTTP-ügyfélhez képest.
• A konfigurált tárolószolgáltatótól függően a nagy kérés- vagy válaszüzenetek jelentősen csökkenthetik a vezénylés teljesítményét. Az Azure Storage használatakor például a HTTP-hasznos adatok, amelyek túl nagyok ahhoz, hogy elférjenek az Azure Queue-üzenetekben, tömörítve és tárolva lesznek az Azure Blob Storage-ban.
• A streamelés, az adattömbök és a bináris hasznos adatok nem támogatottak.
• A HTTP-ügyfél viselkedésének testreszabása korlátozott.

Ha ezek közül a korlátozások közül bármelyik hatással lehet a használati esetre, érdemes inkább tevékenységfüggvényeket és nyelvspecifikus HTTP-ügyfélkódtárakat használni kimenő HTTP-hívások indításához.

Megjegyzés:

Ha Ön .NET-fejlesztő, felmerülhet a kérdés, hogy ez a funkció miért használja a DurableHttpRequest és a DurableHttpResponse típust a beépített .NET HttpRequestMessage és HttpResponseMessage típusok helyett.

Ez a kialakítási döntés szándékos. Az elsődleges ok az, hogy az egyéni típusok segítenek biztosítani, hogy a felhasználók ne tegyenek helytelen feltételezéseket a belső HTTP-ügyfél támogatott viselkedésével kapcsolatban. A Durable Functionsre jellemző típusok lehetővé teszik az API-tervezés egyszerűsítését is. Emellett egyszerűbben elérhetővé tehetnek olyan speciális funkciókat, mint a felügyelt identitásintegráció és a lekérdezési fogyasztói minta.

Bővíthetőség (csak.NET)

A vezénylés belső HTTP-ügyfél viselkedésének testreszabása az Azure Functions .NET függőséginjektálásával lehetséges. Ez a képesség hasznos lehet kis viselkedési módosítások elvégzéséhez. A HTTP-ügyfél egységteszteléséhez is hasznos lehet a modellobjektumok injektálásával.

Az alábbi példa a külső HTTP-végpontokat meghívó vezénylő függvények TLS/SSL-tanúsítványérvényesítésének letiltására szolgáló függőséginjektálás használatát mutatja be.

public class Startup : FunctionsStartup
{
    public override void Configure(IFunctionsHostBuilder builder)
    {
        // Register own factory
        builder.Services.AddSingleton<
            IDurableHttpMessageHandlerFactory,
            MyDurableHttpMessageHandlerFactory>();
    }
}

public class MyDurableHttpMessageHandlerFactory : IDurableHttpMessageHandlerFactory
{
    public HttpMessageHandler CreateHttpMessageHandler()
    {
        // Disable TLS/SSL certificate validation (not recommended in production!)
        return new HttpClientHandler
        {
            ServerCertificateCustomValidationCallback =
                HttpClientHandler.DangerousAcceptAnyServerCertificateValidator,
        };
    }
}

Következő lépések

Tudnivalók a tartós entitásokról