HTTP Özellikleri

Makale
10/18/2023

Dayanıklı İşlevler, dayanıklı düzenlemelerin ve varlıkların HTTP iş akışlarına dahil olmasını kolaylaştıran çeşitli özelliklere sahiptir. Bu makalede bu özelliklerden bazıları hakkında ayrıntılı bilgi verilmektedir.

HTTP API'lerini açığa çıkarma

Düzenleme ve varlıklar HTTP istekleri kullanılarak çağrılabilir ve yönetilebilir. Dayanıklı İşlevler uzantısı yerleşik HTTP API'lerini kullanıma sunar. Ayrıca, HTTP ile tetiklenen işlevlerin içinden düzenlemelerle ve varlıklarla etkileşime yönelik API'ler sağlar.

Yerleşik HTTP API'leri

Dayanıklı İşlevler uzantısı, Azure İşlevleri konağına otomatik olarak bir HTTP API'leri kümesi ekler. Bu API'lerle, herhangi bir kod yazmadan düzenlemelerle ve varlıklarla etkileşimde bulunabilir ve bunları yönetebilirsiniz.

Aşağıdaki yerleşik HTTP API'leri desteklenir.

Dayanıklı İşlevler uzantısı tarafından kullanıma sunulan tüm yerleşik HTTP API'lerinin tam açıklaması için HTTP API'leri makalesine bakın.

HTTP API URL'si bulma

Düzenleme istemci bağlaması, uygun HTTP yanıt yükleri oluşturabilen API'leri kullanıma sunar. Örneğin, belirli bir düzenleme örneği için yönetim API'lerine bağlantılar içeren bir yanıt oluşturabilir. Aşağıdaki örneklerde, yeni bir düzenleme örneği için bu API'nin nasıl kullanılacağını gösteren bir HTTP tetikleyici işlevi gösterilmektedir:

// 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);
        }
    }
}

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
  }

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"
    }
  ]
}

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"
    }
  ]
}

@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);
}

Daha önce gösterilen HTTP tetikleyici işlevlerini kullanarak bir orchestrator işlevi başlatmak herhangi bir HTTP istemcisi kullanılarak yapılabilir. Aşağıdaki cURL komutu adlı DoWorkbir orchestrator işlevi başlatır:

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

Ardından, kimliği olarak sahip bir düzenleme abc123 için örnek bir yanıt verilmiştir. Netlik sağlamak için bazı ayrıntılar kaldırıldı.

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"
}

Önceki örnekte, ile biten Uri alanların her biri yerleşik bir HTTP API'sine karşılık gelir. Hedef düzenleme örneğini yönetmek için bu API'leri kullanabilirsiniz.

Dekont

Web kancası URL'lerinin biçimi, Azure İşlevleri konağın hangi sürümünü çalıştırdığınıza bağlıdır. Önceki örnek, Azure İşlevleri 2.0 konağı içindir.

Tüm yerleşik HTTP API'lerinin açıklaması için bkz . HTTP API başvurusu.

Zaman uyumsuz işlem izleme

Daha önce bahsedilen HTTP yanıtı, Dayanıklı İşlevler ile uzun süre çalışan HTTP zaman uyumsuz API'lerinin uygulanmasına yardımcı olmak için tasarlanmıştır. Bu desen bazen yoklama tüketici deseni olarak adlandırılır. İstemci/sunucu akışı aşağıdaki gibi çalışır:

İstemci, orchestrator işlevi gibi uzun süre çalışan bir işlem başlatmak için bir HTTP isteğinde bulunur.
Hedef HTTP tetikleyicisi, "statusQueryGetUri" değerine sahip bir Konum üst bilgisine sahip bir HTTP 202 yanıtı döndürür.
İstemci, Konum üst bilgisindeki URL'yi yoklar. İstemci, Konum üst bilgisi olan HTTP 202 yanıtlarını görmeye devam eder.
Örnek tamamlandığında veya başarısız olduğunda, Konum üst bilgisindeki uç nokta HTTP 200 döndürür.

Bu protokol, bir HTTP uç noktasını yoklayıp Konum üst bilgisini takip eden dış istemciler veya hizmetlerle uzun süre çalışan işlemlerin koordinasyonunu sağlar. Bu desenin hem istemci hem de sunucu uygulamaları Dayanıklı İşlevler HTTP API'lerinde yerleşiktir.

Dekont

Varsayılan olarak, Azure Logic Apps tarafından sağlanan tüm HTTP tabanlı eylemler standart zaman uyumsuz işlem desenini destekler. Bu özellik, Logic Apps iş akışının parçası olarak uzun süre çalışan bir dayanıklı işlev eklemeyi mümkün kılar. Zaman uyumsuz HTTP desenleri için Logic Apps desteği hakkında daha fazla ayrıntıyı Azure Logic Apps iş akışı eylemleri ve tetikleyicileri belgelerinde bulabilirsiniz.

Dekont

Düzenlemelerle etkileşimler yalnızca HTTP ile tetiklenen işlevlerle değil, herhangi bir işlev türünden gerçekleştirilebilir.

İstemci API'lerini kullanarak düzenleme ve varlıkları yönetme hakkında daha fazla bilgi için Örnek yönetimi makalesine bakın.

HTTP API'lerini kullanma

Orchestrator işlev kodu kısıtlamalarında açıklandığı gibi, orchestrator işlevleri doğrudan G/Ç yapamaz. Bunun yerine genellikle G/Ç işlemlerine sahip etkinlik işlevlerini çağırırlar.

Dayanıklı İşlevler 2.0'dan başlayarak, düzenleme işlemleri düzenleme tetikleyici bağlamasını kullanarak HTTP API'lerini yerel olarak kullanabilir.

Aşağıdaki örnek kod, giden HTTP isteğinde bulunan bir orchestrator işlevini gösterir:

[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
    }
}

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
    }
});

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)

"HTTP'yi çağır" eylemini kullanarak düzenleyici işlevlerinizde aşağıdaki eylemleri gerçekleştirebilirsiniz:

HTTP API'lerini daha sonra bahsedilen bazı sınırlamalarla doğrudan düzenleme işlevlerinden çağırabilirsiniz.
İstemci tarafı HTTP 202 durum yoklama desenlerini otomatik olarak destekler.
Diğer Azure uç noktalarına yetkili HTTP çağrıları yapmak için Azure Yönetilen Kimlikleri'ni kullanın.

HTTP API'lerini doğrudan orchestrator işlevlerinden kullanma özelliği, belirli bir ortak senaryo kümesi için kolaylık sağlamak amacıyla tasarlanmıştır. Etkinlik işlevlerini kullanarak bu özelliklerin tümünü kendiniz uygulayabilirsiniz. Çoğu durumda etkinlik işlevleri size daha fazla esneklik verebilir.

HTTP 202 işleme

"HTTP çağrısı" API'si, yoklama tüketici deseninin istemci tarafını otomatik olarak uygulayabilir. Çağrılan API, Konum üst bilgisi olan bir HTTP 202 yanıtı döndürürse, orchestrator işlevi 202 dışında bir yanıt alıncaya kadar Konum kaynağını otomatik olarak yoklar. Bu yanıt, orchestrator işlev koduna döndürülen yanıt olacaktır.

Dekont

Orchestrator işlevleri, Zaman uyumsuz işlem izleme bölümünde açıklandığı gibi sunucu tarafı yoklama tüketici desenini de yerel olarak destekler. Bu destek, bir işlev uygulamasındaki düzenlemelerin diğer işlev uygulamalarında orchestrator işlevlerini kolayca koordine olabileceği anlamına gelir. Bu, alt düzenleme kavramına benzer, ancak uygulamalar arası iletişimi destekler. Bu destek özellikle mikro hizmet stili uygulama geliştirme için kullanışlıdır.
Geçici bir sınırlama nedeniyle, yerleşik HTTP yoklama düzeni şu anda JavaScript/TypeScript ve Python'da kullanılamaz.

Yönetilen kimlikler

Dayanıklı İşlevler yetkilendirme için Microsoft Entra belirteçlerini kabul eden API'lere çağrıları yerel olarak destekler. Bu destek, bu belirteçleri almak için Azure yönetilen kimliklerini kullanır.

Aşağıdaki kod bir orchestrator işlevi örneğidir. İşlev, Azure Resource Manager sanal makineleri REST API'sini kullanarak bir sanal makineyi yeniden başlatmak için kimliği doğrulanmış çağrılar yapar.

[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}");
    }
}

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;
});

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)

Önceki örnekte parametresi, tokenSource Azure Resource Manager için Microsoft Entra belirteçlerini almak üzere yapılandırılmıştır. Belirteçler kaynak URI'sine https://management.core.windows.net/.defaultgöre tanımlanır. Örnekte, geçerli işlev uygulamasının yerel olarak çalıştığı veya yönetilen kimliğe sahip bir işlev uygulaması olarak dağıtıldığı varsayılır. Yerel kimliğin veya yönetilen kimliğin, belirtilen kaynak grubundaki myRGVM'leri yönetme iznine sahip olduğu varsayılır.

Çalışma zamanında, yapılandırılan belirteç kaynağı otomatik olarak bir OAuth 2.0 erişim belirteci döndürür. Ardından kaynak, giden isteğin Yetkilendirme üst bilgisine taşıyıcı belirteç olarak belirteci ekler. Bu model, aşağıdaki nedenlerle HTTP isteklerine el ile yetkilendirme üst bilgileri eklemeye göre bir geliştirmedir:

Belirteç yenilemesi otomatik olarak işlenir. Süresi dolan belirteçler konusunda endişelenmeniz gerekmez.
Belirteçler hiçbir zaman dayanıklı düzenleme durumunda depolanmaz.
Belirteç alımını yönetmek için herhangi bir kod yazmanız gerekmez.

Önceden derlenmiş C# RestartVMs örneğinde daha eksiksiz bir örnek bulabilirsiniz.

Yönetilen kimlikler Azure kaynak yönetimiyle sınırlı değildir. Microsoft'un Azure hizmetleri ve iş ortaklarının web uygulamaları dahil olmak üzere Microsoft Entra taşıyıcı belirteçlerini kabul eden herhangi bir API'ye erişmek için yönetilen kimlikleri kullanabilirsiniz. İş ortağının web uygulaması başka bir işlev uygulaması bile olabilir. Microsoft Entra Id ile kimlik doğrulamasını destekleyen Microsoft azure hizmetlerinin listesi için bkz . Microsoft Entra kimlik doğrulamasını destekleyen Azure hizmetleri.

Sınırlamalar

HTTP API'lerini çağırmaya yönelik yerleşik destek kolaylık bir özelliktir. Tüm senaryolar için uygun değildir.

Orchestrator işlevleri ve yanıtları tarafından gönderilen HTTP istekleri, Dayanıklı İşlevler depolama sağlayıcısında ileti olarak serileştirilir ve kalıcı hale getirilir. Bu kalıcı kuyruğa alma davranışı, HTTP çağrılarının düzenleme yeniden yürütmesi için güvenilir ve güvenli olmasını sağlar. Ancak, kalıcı kuyruğa alma davranışının da sınırlamaları vardır:

Her HTTP isteği, yerel bir HTTP istemcisiyle karşılaştırıldığında ek gecikme süresi içerir.
Yapılandırılan depolama sağlayıcısına bağlı olarak, büyük istek veya yanıt iletileri düzenleme performansını önemli ölçüde düşürebilir. Örneğin, Azure Depolama kullanılırken, Azure Kuyruk iletilerine sığamayacak kadar büyük http yükleri sıkıştırılır ve Azure Blob depolamada depolanır.
Akış, öbeklenmiş ve ikili yükleri desteklenmez.
HTTP istemcisinin davranışını özelleştirme özelliği sınırlıdır.

Bu sınırlamalardan herhangi biri kullanım örneğinizi etkileyebilirse, bunun yerine giden HTTP çağrıları yapmak için etkinlik işlevlerini ve dile özgü HTTP istemci kitaplıklarını kullanmayı göz önünde bulundurun.

Dekont

.NET geliştiricisiyseniz, bu özelliğin neden yerleşik .NET HttpRequestMessage ve HttpResponseMessage türleri yerine DayanıklıHttpRequest ve DayanıklıHttpResponse türlerini kullandığını merak edebilirsiniz.

Bu tasarım seçimi kasıtlıdır. Bunun birincil nedeni, özel türlerin kullanıcıların iç HTTP istemcisinin desteklenen davranışları hakkında yanlış varsayımlarda bulunmamasını sağlamaya yardımcı olmasıdır. Dayanıklı İşlevler özgü türler, API tasarımını basitleştirmeyi de mümkün hale getirir. Ayrıca yönetilen kimlik tümleştirmesi ve yoklama tüketici düzeni gibi özel özellikleri daha kolay kullanılabilir hale getirir.

Genişletilebilirlik (yalnızca.NET)

.NET bağımlılık ekleme Azure İşlevleri kullanarak düzenlemenin iç HTTP istemcisinin davranışını özelleştirmek mümkündür. Bu özellik, küçük davranış değişiklikleri yapmak için yararlı olabilir. Sahte nesneler ekleyerek HTTP istemcisini birim testi için de yararlı olabilir.

Aşağıdaki örnekte, dış HTTP uç noktalarını çağıran düzenleyici işlevleri için TLS/SSL sertifika doğrulamasını devre dışı bırakmak için bağımlılık eklemenin kullanılması gösterilmektedir.

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,
        };
    }
}

Sonraki adımlar

Dayanıklı varlıklar hakkında bilgi edinin

Aracılığıyla paylaş

HTTP Özellikleri

HTTP API'lerini açığa çıkarma

Yerleşik HTTP API'leri

HTTP API URL'si bulma

Zaman uyumsuz işlem izleme

HTTP API'lerini kullanma

HTTP 202 işleme

Yönetilen kimlikler

Sınırlamalar

Genişletilebilirlik (yalnızca.NET)

Sonraki adımlar

Geri Bildirim

Geri Bildirim

Ek kaynaklar