ميزات HTTP

مقالة
06/01/2023

تتميز Durable Functions بالعديد من الميزات التي تسهل دمج التزامنات والكيانات الدائمة في سير عمل HTTP. تتناول هذه المقالة تفاصيل عن بعض هذه الميزات.

الكشف عن واجهات برمجة التطبيقات HTTP

يمكن استدعاء التزامنات والكيانات وإدارتها باستخدام طلبات HTTP. يكشف ملحق Durable Functions عن واجهات برمجة تطبيقات HTTP المضمنة. كما يوفر واجهات برمجة التطبيقات للتفاعل مع التزامن والكيانات من داخل الوظائف التي يتم تشغيلها بواسطة HTTP.

واجهات برمجة التطبيقات HTTP المضمنة

يضيف ملحق Durable Functions تلقائيًا مجموعة من واجهات برمجة التطبيقات لـHTT إلى مضيف وظائف Azure. بواجهات برمجة التطبيقات يمكنك التفاعل مع التزامن والكيانات وإدارتها دون كتابة أي رمز.

يتم دعم واجهات برمجة تطبيقات HTTP المضمنة التالية.

راجع مقالة واجهات برمجة التطبيقات HTTP للحصول على وصف كامل لكافة واجهات برمجة التطبيقات HTTP المضمنة التي يتم الكشف عنها من خلال ملحق Durable Functions.

اكتشاف عنوان URL لواجهة برمجة التطبيقات لـHTTP

ربط عميل التزامن يكشف واجهات برمجة التطبيقات التي يمكن أن تنشئ حمولات استجابة HTTP مريحة. على سبيل المثال، يمكن إنشاء استجابة تحتوي على ارتباطات إلى إدارة واجهات برمجة التطبيقات لمثيل تزامن معين. تظهر الأمثلة التالية وظيفة مشغل HTTP يوضح كيفية استخدام API هذا لمثيل تزامن جديد:

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

ابدأ تشغيل وظيفة تزامن باستخدام مشغل وظائف HTTP توضح سابقًا ما يمكن القيام به باستخدام أي عميل HTTP. يبدأ أمر cURL التالي وظيفة منسق مسماه DoWork:

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

المثال التالي هو استجابة لتزامن له abc123 معرف. تمت إزالة بعض التفاصيل للوضوح.

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

في المثال السابق، كل من الحقول التي تنتهي في Uri تتوافق مع واجهة برمجية التطبيقات HTTP المضمنة. يمكنك استخدام واجهات برمجة التطبيقات لإدارة نموذج هدف التزامن.

إشعار

يعتمد نموذج إخطار علي الويب عناوين URL للإخطار على الويب على إصدار مضيف Azure Functions الذي تقوم بتشغيله. المثال السابق هو مضيف Azure Functions 2. 0.

للحصول على وصف لكافة واجهات برمجة تطبيقات HTTP المضمنة، راجع مرجع واجهة برمجة التطبيقات HTTP.

تعقب عملية التزامن

تم تصميم استجابة HTTP المذكورة سابقًا للمساعدة في تنفيذ واجهات برمجة تطبيقات HTTP غير المتزامنة مع Durable Functions. يشار هذا النمط أحيانًا إلىتحقق نمط المستهلك يعمل تدفق العميل / الخادم على النحو التالي:

تتطلب مشاكل العميل بدء عملية HTTP طويلة الأجل مثل وظيفة منسق.
يعود الهدف من مشغل HTTP إرجاع استجابة202 HTTP بعنوان موقع يحتوي على القيمة "statusQueryGetUri".
يقوم العميل باستطلاعات محدد مواقع ويب في عنوان الموقع. يستمر العميل في مشاهدة استجابات HTTP 202 بعنوان موقع.
عند انتهاء المثيل أو فشله، ترجع نقطة النهاية في عنوان الموقع HTTP 200.

يسمح هذا البروتوكول بتنسيق العمليات طويلة الأمد مع العملاء أو الخدمات الخارجية التي يمكنها الاستقصاء عن نقطة نهاية HTTP واتباع عنوان الموقع. يتم تنفيذ تطبيقات كل من العميل والخادم في واجهات برمجة التطبيقات لـDurable Functions HTTP.

إشعار

بشكل افتراضي، تدعم جميع الإجراءات المستندة إلى HTTP التي توفرها Azure Logic Apps نمط التشغيل القياسي غير المتزامن. تتيح هذه الإمكانية تضمين وظيفة دائمة طويلة الأمد كجزء من سير عمل Logic Apps. يمكنك العثور على مزيد من التفاصيل حول دعم تطبيقات المنطق لأنماط HTTP غير المتزامنة في إجراءات سير عمل Azure Logic Apps وتشغل الوثائق.

إشعار

يمكن إجراء التفاعلات مع التزامنات من أي نوع وظيفة، وليس فقط تشغيل الوظائف لـHTTP.

للحصول على مزيدٍ من المعلومات حول كيفية إدارة التزامنات والكيانات باستخدام واجهات برمجة تطبيقات العميل، راجع مقالة إدارة المثيل.

استخدام واجهات برمجة التطبيقات لـHTTP

كما هو موضح في قيود رمز وظيفة التزامن، لا يمكن أن تقوم وظائف التزامن بالإدخال/الإخراج مباشرة. بدلًا من ذلك، تقوم عادة باستدعاء وظائف النشاط التي تقوم بعمليات الإدخال/إخراج.

بدءًا من Durable Functions 2.0، يمكن أن تستخدم التزامنات واجهات برمجة التطبيقات أصلية HTTP باستخدام ربط مشغل التزامن.

يوضح المثال التالي وظائف التعليمات البرمجية لإجراء طلب لـHTTP صادر

[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"، يمكن القيام بالإجراءات التالية في وظائف التزامن الخاصة بك:

يمكنك استدعاء واجهات برمجة التطبيقات لـ HTTP مباشرة من وظائف التزامن مع بعض القيود المذكورة لاحقًا.
دعم أنماط استقصاء حالة HTTP 202 من جانب العميل تلقائيًا.
استخدم الهويات المدارة لـAzure لإجراء مكالمات HTTP مصرح بها لنقاط نهاية Azure الأخرى.

تهدف القدرة على استهلاك واجهات برمجة تطبيقات HTTP مباشرة من وظائف المنسق إلى استخدام مجموعة معينة من السيناريوهات الشائعة بطريقة ملائمة. يمكنك تنفيذ كافة هذه الميزات بنفسك باستخدام وظائف النشاط. في كثير من الحالات، قد تمنحك وظائف النشاط مرونة أكبر.

معالجة HTTP 202

يمكن واجهة برمجة التطبيقات "استدعاء لـ HTTP" تنفيذ جانب العميل لنمط تحقق المستهلك إذا قامت واجهة برمجة التطبيقات التي تم استدعؤها بإرجاع استجابة HTT 202 بعنوان الوقع تقوم وظيفة المنسق تلقائيًا باستقصاء مورد الموقع حتى تلقي استجابة بخلاف ل 202. ستكون هذه الاستجابة هي الاستجابة التي يتم إرجاعها إلى رمز وظيفة المنسق.

إشعار

تدعم وظائف التزامن أيضًا بشكل أصلي تحقق نمط المستهلك الاستقصاء من جانب الخادم، كما هو موضح في تعقب عملية غير متزامن. يعني هذا الدعم أن التزامن في تطبيق وظيفة واحده يمكنه بسهولة تنسيق وظائف التزامن في تطبيقات الوظائف الأخرى. هذا يشبه مفهوم التزامن الفرعي، ولكن مع دعم الاتصالات عبر التطبيق. هذا الدعم مفيد بشكل خاص لتطوير التطبيقات على نمط الخدمات الصغيرة.
بسبب وجود قيود مؤقتة، لا يتوفر نمط تحقق لـ HTTP المضمن حاليًا في JavaScript/TypeScript و Python.

الهويات المُدارة

تدعم Durable Functions في الأصل استدعاءات واجهات برمجة التطبيقات التي تقبل رموز Microsoft Entra المميزة للتخويل. يستخدم هذا الدعم Azure الهويات المدارة للحصول على هذه الرموز المميزة.

التعليمات البرمجية التالية مثال على وظيفة التزامن. تقوم الوظيفة بإجراء مكالمات مصادق عليها لإعادة تشغيل جهاز ظاهري باستخدام AZURE Resource Managerأجهزه ظاهريه واجهة برمجة تطبيقات REST.

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

في المثال السابق، تم تكوين المعلمة tokenSource للحصول على رموز Microsoft Entra المميزة ل Azure Resource Manager. يتم تعريف الرموز المميزة بواسطة URI المورد https://management.core.windows.net/.default. يفترض المثال أن تطبيق الوظيفة الحالي إما يعمل محليًا أو تم نشره كدارة ذات هوية مدارة. يفترض أن يكون للهوية المحلية أو الهوية المدارة إذن لإدارة الأجهزة الظاهرية في مجموعة الموارد myRG المحددة.

في وقت التشغيل، مصدر الرمز المميز المكون تلقائيا بإرجاع رمز مميز للوصول OAuth 2.0. المصدر ثم يضيف الرمز المميز كرمز مميز للحامل إلى تحويل العنوان الطلب الصادر. هذا الطراز هو تحسين عبر إضافة عناوين التخويل يدويا إلى طلبات HTTP للأسباب التالية:

تتم معالجة تحديث الرمز المميز تلقائيا. لا داعي للقلق بشأن الرموز منتهية الصلاحية.
لا يتم تخزين الرموز المميزة في حالة التزامن الدائم.
لا تحتاج إلى كتابة أي تعليمة برمجية لإدارة اكتساب الرمز المميز.

يمكنك العثور على مثال أكثر اكتمالًا في نموذج C# RestartVMs المترجم مسبقًا.

لا تقتصر الهويات المدارة على إدارة موارد Azure. يمكنك استخدام الهويات المدارة للوصول إلى أي واجهة برمجة تطبيقات تقبل الرموز المميزة لحامل Microsoft Entra، بما في ذلك خدمات Azure من Microsoft وتطبيقات الويب من الشركاء. يمكن أن يكون تطبيق الويب الخاص بالشركاء تطبيقا آخر للوظيفة. للحصول على قائمة بخدمات Azure من Microsoft التي تدعم المصادقة باستخدام معرف Microsoft Entra، راجع خدمات Azure التي تدعم مصادقة Microsoft Entra.

القيود

يعد الدعم المدمج لاستدعاء واجهات برمجة تطبيقات HTTP ميزة ملائمة. إنها ليست مناسبة لجميع السيناريوهات.

يتم تسلسل طلبات HTTP المرسلة بواسطة وظائف التزامن والاستجابات الخاصة بها واستمرت كرسائل في موفر التخزين "Durable Functions ". يضمن هذا السلوك الانتظار المستمر مكالمات لـ HTTP موثوقة وآمنة لإعادة تشغيل التزامن. ومع ذلك، فإن سلوك الانتظار المستمر له أيضًا قيود:

يتضمن كل طلب ل HTTP زمن وصول إضافي عند مقارنته مع عميل HTTP أصلي.
استنادًا إلى موفر التخزين المكونة، يمكن أن تؤدي رسائل الطلب أو الاستجابة الكبيرة إلى انخفاض أداء التزامن بشكل كبير. على سبيل المثال، عند استخدام تخزين Azure، يتم ضغط حمولات HTTP الكبيرة جدًا بحيث لا يمكن احتواؤها في رسائل Azure قائمة الانتظار وتخزينها في مخزن البيانات الثنائية ل Azure .
لا تدعم تدفق مجموعة البيانات وثنائي البيانات الأساسية
القدرة على تخصيص سلوك عميل HTTP محدودة.

إذا كان أي من هذه القيود قد يؤثر على حالة الاستخدام، ففكر بدلًا من ذلك في استخدام وظائف النشاط ولغة محددة وعملاء ل HTTP لإجراء مكالمات HTTP صادرة.

إشعار

إذا كنت مطور .NET، قد تتساءل لماذا تستخدم هذه الميزة نوعي دائم HttpRequest و DurableHttpResponse بدلا من المضمنة .NET HttpRequestMessage و HttpResponseMessage أنواع.

التصميم المختار هذا مقصود. السبب الأساسي هو أن الأنواع المخصصة تساعد على التأكد من عدم قيام المستخدمين بإجراء افتراضات غير صحيحة حول السلوكيات مدعمة لعميل HTTP الداخلي. تتيح الأنواع الخاصة بـDurable Functions أيضًا تبسيط تصميم واجهة برمجة التطبيقات. كما يمكنها بسهولة أكبر توفير ميزات محددة مثل إدارة الهوية المتكاملة ونمط تحقق المستهلك.

القابلية للتوسعة (.NET فقط)

تخصيص سلوك عميل HTTP الداخلي للتزامن ممكن باستخدام حقن التبعية Azure الوظائف.NET. هذه القدرة يمكن أن تكون مفيدة لإجراء تغييرات سلوكية صغيرة. كما يمكن أن تكون مفيدة لاختبار وحدة عميل HTTP عن طريق إضافة عناصر وهمية.

يوضح المثال التالي استخدام حقن التبعية لتعطيل التحقق من صحة شهادة TLS/SSL لوظائف التزامن التي تستدعي نقاط نهاية HTTP الخارجية.

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

الخطوات التالية

تعرف على الكيانات الدائمة

مشاركة عبر

ميزات HTTP

الكشف عن واجهات برمجة التطبيقات HTTP

واجهات برمجة التطبيقات HTTP المضمنة

اكتشاف عنوان URL لواجهة برمجة التطبيقات لـHTTP

تعقب عملية التزامن

استخدام واجهات برمجة التطبيقات لـHTTP

معالجة HTTP 202

الهويات المُدارة

القيود

القابلية للتوسعة (.NET فقط)

الخطوات التالية

الملاحظات

الموارد الإضافية