Fitur HTTP

Artikel
06/01/2023

Durable Functions memiliki beberapa fitur yang memudahkan untuk memasukkan orkestrasi dan entitas yang tahan lama ke dalam alur kerja HTTP. Artikel ini menjelaskan rinci tentang beberapa fitur tersebut.

Mengekspos API HTTP

Orkestrasi dan entitas dapat dipanggil dan dikelola menggunakan permintaan HTTP. Ekstensi Durable Functions memaparkan API HTTP bawaan. Ekstensi ini juga menyediakan API untuk berinteraksi dengan orkestrasi dan entitas dari dalam fungsi yang dipicu HTTP.

API HTTP Bawaan

Ekstensi Durable Functions secara otomatis menambahkan sekumpulan API HTTP ke host Microsoft Azure Functions. Dengan API ini, Anda dapat berinteraksi dengan serta mengelola orkestrasi dan entitas tanpa menulis kode.

API HTTP bawaan berikut didukung.

Lihat artikel API HTTP untuk deskripsi lengkap semua API HTTP bawaan yang dipaparkan oleh ekstensi Durable Functions.

Penemuan URL API HTTP

Pengikatan data klien orkestrasi memaparkan API yang dapat menghasilkan payload respons HTTP yang nyaman. Contohnya, ini dapat membuat respons yang memuat tautan ke API manajemen untuk instans orkestrasi tertentu. Contoh berikut menunjukkan fungsi pemicu HTTP yang menunjukkan cara menggunakan API untuk instans orkestrasi baru:

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

Memulai fungsi orkestrator dengan menggunakan fungsi pemicu HTTP yang ditunjukkan sebelumnya dapat dilakukan menggunakan klien HTTP. Perintah cURL berikut memulai fungsi orkestrator bernama DoWork :

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

Berikutnya adalah contoh respons untuk orkestrasi yang memiliki abc123 sebagai ID. Beberapa detail telah dihapus karena kejelasan.

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

Dalam contoh sebelumnya, setiap bidang yang berakhiran Uri sesuai dengan API HTTP bawaan. Anda dapat menggunakan API ini untuk mengelola instans orkestrasi target.

Catatan

Format URL webhook dapat berbeda bergantung pada versi hosting Microsoft Azure Functions yang sedang dijalankan. Contoh sebelumnya adalah untuk hosting Microsoft Azure Functions 2.0.

Untuk deskripsi semua API HTTP bawaan, lihat referensi API HTTP.

Penelusuran operasi asinkron

Respons HTTP yang disebutkan sebelumnya dirancang untuk membantu menerapkan API HTTP asinkron yang sudah berjalan lama dengan Durable Functions. Pola ini terkadang disebut sebagai pola konsumen polling. Alur klien/server berfungsi sebagai berikut:

Klien mengeluarkan permintaan HTTP untuk memulai proses yang berjalan lama seperti fungsi orkestrator.
Pemicu HTTP target mengembalikan respons HTTP 202 dengan header Lokasi yang memiliki nilai "statusQueryGetUri".
Klien membuat polling URL di header Lokasi. Klien terus melihat respons HTTP 202 dengan header Lokasi.
Ketika instans selesai atau gagal, titik akhir di header Lokasi mengembalikan HTTP 200.

Protokol ini memungkinkan koordinasi proses yang berjalan lama dengan klien eksternal atau layanan yang dapat melakukan polling titik akhir HTTP dan mengikuti header Lokasi. Baik penerapan klien dan server dari pola ini dibangun ke dalam API HTTP Durable Functions.

Catatan

Secara default, semua tindakan berbasis HTTP yang disediakan oleh Microsoft Azure Logic Apps mendukung pola operasi asinkron standar. Kemampuan ini memungkinkan untuk menyematkan fungsi tahan lama sebagai bagian dari alur kerja Azure Logic Apps. Anda dapat menemukan detail selengkapnya tentang dukungan Microsoft Azure Logic Apps untuk pola HTTP asinkron dalam tindakan alur kerja Microsoft Azure Logic Apps dan memicu dokumentasi.

Catatan

Interaksi dengan orkestrasi dapat dilakukan dari jenis fungsi apa pun, bukan hanya fungsi yang dipicu HTTP.

Untuk informasi selengkapnya tentang cara mengelola orkestrasi dan entitas menggunakan API klien, lihat Artikel manajemen instans.

Menggunakan API HTTP

Seperti dijelaskan dalam batasan kode fungsi orkestrator, fungsi orkestrator tidak dapat melakukan I/O langsung. Sebaliknya, biasanya disebut fungsi aktivitas yang melakukan operasi I/O.

Dimulai dengan Durable Functions 2.0, orkestrasi dapat secara asli menggunakan API HTTP dengan menggunakan pengikatan pemicu orkestrasi.

Contoh kode berikut menunjukkan fungsi orkestrator membuat permintaan HTTP keluar:

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

Dengan menggunakan tindakan “panggil HTTP”, Anda dapat melakukan tindakan berikut dalam fungsi orkestrator:

Panggil API HTTP langsung dari fungsi orkestrasi, dengan beberapa batasan yang disebutkan kemudian.
Secara otomatis mendukung pola polling status HTTP 202 sisi klien.
Gunakan Identitas Terkelola Azure untuk melakukan panggilan HTTP resmi ke titik akhir Azure lainnya.

Kemampuan untuk menggunakan API HTTP langsung dari fungsi orkestrator dimaksudkan sebagai kenyamanan untuk serangkaian skenario umum tertentu. Anda dapat menerapkan semua fitur ini sendiri menggunakan fungsi aktivitas. Dalam banyak kasus, fungsi aktivitas dapat memberikan lebih banyak fleksibilitas kepada Anda.

Penanganan HTTP 202

API “panggil HTTP” dapat secara otomatis menerapkan sisi klien dari pola konsumen melakukan polling. Jika API yang disebut mengembalikan respons HTTP 202 dengan header Lokasi, fungsi orkestrator secara otomatis melakukan polling sumber daya Lokasi hingga menerima respons selain 202. Respons ini akan menjadi respons yang dikembalikan ke kode fungsi orkestrator.

Catatan

Fungsi orkestrator juga secara asli mendukung pola konsumen melakukan polling sisi server, seperti dijelaskan dalam pelacakan operasi Asinkron. Dukungan ini berarti bahwa orkestrasi dalam satu aplikasi fungsi dapat mudah mengoordinasikan fungsi orkestrator di aplikasi fungsi lain. Fungsi ini mirip konsep sub-orkestrasi, tetapi dengan dukungan untuk komunikasi lintas aplikasi. Dukungan ini sangat berguna untuk pengembangan aplikasi bergaya microservice.
Karena keterbatasan sementara, pola polling HTTP bawaan saat ini tidak tersedia di JavaScript/TypeScript dan Python.

Identitas Terkelola

Durable Functions secara asli mendukung panggilan ke API yang menerima token Microsoft Entra untuk otorisasi. Dukungan ini menggunakan identitas yang dikelola Azure untuk memperoleh token ini.

Kode berikut adalah contoh fungsi orkestrator. Fungsi ini melakukan panggilan terautentikasi untuk memulai ulang komputer virtual dengan menggunakan REST API komputer virtual Microsoft Azure Resource Manager.

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

Dalam contoh sebelumnya, parameter dikonfigurasi tokenSource untuk memperoleh token Microsoft Entra untuk Azure Resource Manager. Token diidentifikasi oleh URI sumber daya https://management.core.windows.net/.default. Contohnya mengasumsikan bahwa aplikasi fungsi saat ini berjalan secara lokal atau disebarkan sebagai aplikasi fungsi dengan identitas terkelola. Identitas lokal atau identitas terkelola diasumsikan memiliki izin untuk mengelola VM dalam grup sumber daya myRG yang ditentukan.

Pada runtime, sumber token yang dikonfigurasi secara otomatis mengembalikan token akses OAuth 2.0. Lalu, sumber menambahkan token sebagai token pembawa ke header Otorisasi permintaan keluar. Model ini adalah peningkatan untuk menambahkan header otorisasi secara manual ke permintaan HTTP karena alasan berikut:

Refresh token ditangani secara otomatis. Anda tidak perlu khawatir tentang token yang kedaluwarsa.
Token tidak pernah disimpan dalam keadaan orkestrasi yang tahan lama.
Anda tidak perlu menulis kode untuk mengelola akuisisi token.

Anda dapat menemukan contoh yang lebih lengkap dalam sampel C# RestartVMs yang telah diolah sebelumnya.

Identitas terkelola tidak terbatas pada manajemen sumber daya Microsoft Azure. Anda dapat menggunakan identitas terkelola untuk mengakses API apa pun yang menerima token pembawa Microsoft Entra, termasuk layanan Azure dari Microsoft dan aplikasi web dari mitra. Aplikasi web mitra bahkan dapat menjadi aplikasi fungsi lain. Untuk daftar layanan Azure dari Microsoft yang mendukung autentikasi dengan ID Microsoft Entra, lihat Layanan Azure yang mendukung autentikasi Microsoft Entra.

Batasan

Dukungan bawaan untuk memanggil API HTTP adalah fitur yang nyaman. Dukungan ini tidak sesuai untuk semua skenario.

Permintaan HTTP yang dikirim oleh fungsi orkestrator dan responsnya diserialisasikan dan dipertahankan sebagai pesan di penyedia penyimpanan Durable Functions. Perilaku mengantrekan persisten ini memastikan panggilan HTTP dapat diandalkan dan aman untuk pemutaran ulang orkestrasi. Namun, perilaku mengantrekan persisten juga memiliki keterbatasan:

Setiap permintaan HTTP melibatkan latensi tambahan jika dibandingkan dengan klien HTTP asli.
Bergantung pada penyedia penyimpanan terkonfigurasi, pesan permintaan atau respons yang besar dapat secara signifikan menurunkan performa orkestrasi. Misalnya, saat menggunakan Azure Storage, muatan HTTP yang terlalu besar untuk masuk ke dalam pesan Azure Queue dikompresi dan disimpan dalam penyimpanan Azure Blob.
Payload streaming, gugusan, dan biner tidak didukung.
Kemampuan untuk menyesuaikan perilaku klien HTTP terbatas.

Jika salah satu batasan ini dapat memengaruhi kasus penggunaan Anda, pertimbangkan untuk menggunakan fungsi aktivitas dan pustaka klien HTTP khusus bahasa untuk melakukan panggilan HTTP keluar.

Catatan

Jika Anda adalah pengembang .NET, Anda dapat bertanya-tanya alasan fitur ini menggunakan jenis DurableHttpRequest dan DurableHttpResponse bukan jenis .NET HttpRequestMessage dan HttpResponseMessage bawaan.

Pilihan desain ini disengaja. Alasan utamanya adalah bahwa jenis kustom membantu memastikan pengguna tidak membuat asumsi salah tentang perilaku yang didukung dari klien HTTP internal. Jenis khusus untuk Durable Functions juga memungkinkan untuk menyederhanakan desain API. Mereka juga dapat lebih mudah menyediakan fitur khusus seperti integrasi identitas terkelola dan pola konsumen polling.

Ekstensibilitas (hanya.NET)

Menyesuaikan perilaku klien HTTP internal orkestrasi dimungkinkan menggunakan injeksi dependensi Microsoft Azure Functions .NET. Kemampuan ini dapat berguna untuk membuat perubahan perilaku kecil. Hal ini juga dapat berguna untuk pengujian unit klien HTTP dengan menyuntikkan objek tiruan.

Contoh berikut menunjukkan menggunakan injeksi dependensi untuk menonaktifkan validasi sertifikat TLS/SSL untuk fungsi orkestrator yang memanggil titik akhir HTTP eksternal.

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

Langkah berikutnya

Pelajari tentang entitas yang tahan lama

Fitur HTTP

Mengekspos API HTTP

API HTTP Bawaan

Penemuan URL API HTTP

Penelusuran operasi asinkron

Menggunakan API HTTP

Penanganan HTTP 202

Identitas Terkelola

Batasan

Ekstensibilitas (hanya.NET)

Langkah berikutnya

Sumber Daya Tambahan: