إدارة المثيلات في Durable Functions في Azure

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

بدء مثيلات

يبدأ أسلوب start-new (أو schedule-new) في ربط عميل التنسيق مثيل تزامن جديد. داخليا، يكتب هذا الأسلوب رسالة عبر موفر تخزين Durable Functions ثم يرجع. تؤدي هذه الرسالة بشكل غير متزامن إلى تشغيل بداية دالة تزامن بالاسم المحدد.

المعلمات لبدء مثيل تنسيق جديد هي كما يلي:

• الاسم: اسم دالة المنسق التي يجب جدولتها.
• الإدخال: أي بيانات JSON قابلة للتسلسل يجب تمريرها كمدخل إلى دالة المنسق.
• InstanceId: (اختياري) المعرف الفريد للمثيل. إذا لم تحدد هذه المعلمة، فإن الأسلوب يستخدم معرفا عشوائيا.

تلميح

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

التعليمات البرمجية التالية هي دالة مثال تبدأ مثيل تنسيق جديد:

C#‎

[FunctionName("HelloWorldQueueTrigger")]
public static async Task Run(
    [QueueTrigger("start-queue")] string input,
    [DurableClient] IDurableOrchestrationClient starter,
    ILogger log)
{
    string instanceId = await starter.StartNewAsync("HelloWorld", input);
    log.LogInformation($"Started orchestration with ID = '{instanceId}'.");
}

إشعار

التعليمة البرمجية C# السابقة هي ل Durable Functions 2.x. بالنسبة إلى Durable Functions 1.x، يجب استخدام OrchestrationClient السمة بدلا من السمة DurableClient ، ويجب استخدام نوع المعلمة DurableOrchestrationClient بدلا من IDurableOrchestrationClient. لمزيد من المعلومات حول الاختلافات بين الإصدارات، راجع مقالة إصدارات Durable Functions .

JavaScript

ما لم يتم تحديد خلاف ذلك، تستخدم الأمثلة الموجودة في هذه الصفحة مشغل HTTP مع function.jsonالتالية .

function.json

{
  "bindings": [
    {
      "name": "req",
      "type": "httpTrigger",
      "direction": "in",
      "methods": ["post"]
    },
    {
      "name": "$return",
      "type": "http",
      "direction": "out"
    },
    {
      "name": "starter",
      "type": "durableClient",
      "direction": "in"
    }
  ],
  "disabled": false
}

إشعار

يستهدف هذا المثال Durable Functions الإصدار 2.x. في الإصدار 1.x، استخدم orchestrationClient بدلا من durableClient.

index.js

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

module.exports = async function(context, input) {
    const client = df.getClient(context);

    const instanceId = await client.startNew("HelloWorld", undefined, input);
    context.log(`Started orchestration with ID = ${instanceId}.`);
};

بايثون

ما لم يتم تحديد خلاف ذلك، تستخدم الأمثلة الموجودة في هذه الصفحة مشغل HTTP مع function.jsonالتالية .

function.json

{
  "scriptFile": "__init__.py",
  "bindings": [    
    {
      "name": "req",
      "type": "httpTrigger",
      "direction": "in",
      "methods": ["post"]
    },
    {
      "name": "$return",
      "type": "http",
      "direction": "out"
    },
    {
      "name": "starter",
      "type": "durableClient",
      "direction": "in"
    }
  ],
  "disabled": false
}

إشعار

يستهدف هذا المثال Durable Functions الإصدار 2.x. في الإصدار 1.x، استخدم orchestrationClient بدلا من durableClient.

__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)
    
    instance_id = await client.start_new('HelloWorld', None, None)
    logging.log(f"Started orchestration with ID = ${instance_id}.")

ما لم يتم تحديد خلاف ذلك، تستخدم الأمثلة الموجودة في هذه الصفحة مشغل HTTP مع function.jsonالتالية .

function.json

{
  "bindings": [    
    {
      "name": "Request",
      "type": "httpTrigger",
      "direction": "in",
      "methods": ["post"]
    },
    {
      "name": "Response",
      "type": "http",
      "direction": "out"
    },
    {
      "name": "starter",
      "type": "durableClient",
      "direction": "in"
    }
  ],
  "disabled": false
}

إشعار

يستهدف هذا المثال Durable Functions الإصدار 2.x. في الإصدار 1.x، استخدم orchestrationClient بدلا من durableClient.

run.ps1

param($Request, $TriggerMetadata)

$InstanceId = Start-DurableOrchestration -FunctionName 'HelloWorld'
Write-Host "Started orchestration with ID = '$InstanceId'"

جاوة

@FunctionName("HelloWorldQueueTrigger")
public void helloWorldQueueTrigger(
        @QueueTrigger(name = "input", queueName = "start-queue", connection = "Storage") String input,
        @DurableClientInput(name = "durableContext") DurableClientContext durableContext,
        final ExecutionContext context) {
    DurableTaskClient client = durableContext.getClient();        
    String instanceID = client.scheduleNewOrchestrationInstance("HelloWorld");
    context.getLogger().info("Scheduled orchestration with ID = " + instanceID);
}

إذا كنت تريد الانتظار حتى يبدأ المنسق قبل العودة من الدالة waitForInstanceStart() الخاصة بك، يمكنك أيضا استخدام الأسلوب .

// wait up to 30 seconds for the scheduled orchestration to enter the "Running" state
client.waitForInstanceStart(instanceID, Duration.ofSeconds(30));

أدوات Azure Functions الأساسية

يمكنك أيضا بدء تشغيل مثيل مباشرة باستخدام func durable start-new الأمر في Core Tools، والذي يأخذ المعلمات التالية:

• function-name (مطلوب): اسم الدالة للبدء.
• input (اختياري): الإدخال إلى الدالة، إما مضمن أو من خلال ملف JSON. بالنسبة للملفات، أضف بادئة إلى المسار إلى الملف باستخدام @، مثل @path/to/file.json.
• id (اختياري): معرف مثيل التنسيق. إذا لم تحدد هذه المعلمة، يستخدم الأمر GUID عشوائيا.
• connection-string-setting (اختياري): اسم إعداد التطبيق الذي يحتوي على سلسلة اتصال التخزين المراد استخدامها. الافتراضي هو AzureWebJobsStorage.
• task-hub-name (اختياري): اسم مركز مهام Durable Functions المراد استخدامه. الافتراضي هو DurableFunctionsHub. يمكنك أيضا تعيين هذا في host.json باستخدام durableTask:HubName.

إشعار

تفترض أوامر Core Tools أنك تقوم بتشغيلها من الدليل الجذر لتطبيق الوظائف. إذا قمت بتوفير connection-string-setting المعلمتين و task-hub-name بشكل صريح، يمكنك تشغيل الأوامر من أي دليل. على الرغم من أنه يمكنك تشغيل هذه الأوامر دون تشغيل مضيف تطبيق دالة، فقد تجد أنه لا يمكنك مراقبة بعض التأثيرات ما لم يكن المضيف قيد التشغيل. على سبيل المثال، start-new يقوم الأمر بإدراج رسالة بدء في مركز المهام الهدف، ولكن لا يتم تشغيل التنسيق فعليا ما لم تكن هناك عملية مضيف تطبيق دالة قيد التشغيل يمكنها معالجة الرسالة.

إشعار

يتم دعم أوامر Core Tools حاليا فقط عند استخدام موفر Azure Storage الافتراضي لحالة وقت التشغيل المستمرة.

يبدأ الأمر التالي الدالة المسماة HelloWorld، ويمرر محتويات الملف counter-data.json إليها:

func durable start-new --function-name HelloWorld --input @counter-data.json --task-hub-name TestTaskHub

مثيلات الاستعلام

بعد بدء تشغيل مثيلات تزامن جديدة، ستحتاج على الأرجح إلى الاستعلام عن حالة وقت التشغيل لمعرفة ما إذا كانت قيد التشغيل أو اكتملت أو فشلت.

يستعلم أسلوب الحصول على الحالة في ربط عميل التزامن عن حالة مثيل التزامن.

يأخذ instanceId (مطلوب) و showHistory (اختياري) showHistoryOutput و(اختياري) و showInput (اختياري) كمعلمات.

• showHistory: إذا تم تعيينها إلى true، تحتوي الاستجابة على محفوظات التنفيذ.
• showHistoryOutput: إذا تم تعيينه إلى true، يحتوي سجل التنفيذ على مخرجات النشاط.
• showInput: إذا تم تعيينها إلى false، فلن تحتوي الاستجابة على إدخال الدالة. القيمة الافتراضية هي true.

يقوم الأسلوب بإرجاع كائن بالخصائص التالية:

• الاسم: اسم دالة المنسق.
• InstanceId: معرف المثيل الخاص بالتزامن (يجب أن يكون هو نفس instanceId الإدخال).
• CreatedTime: الوقت الذي بدأت فيه وظيفة المنسق في التشغيل.
• LastUpdatedTime: الوقت الذي تم فيه آخر نقطة تفتيش للتنسيق.
• الإدخال: إدخال الدالة كقيمة JSON. لا يتم ملء هذا الحقل إذا كان showInput خطأ.
• CustomStatus: حالة التزامن المخصص بتنسيق JSON.
• الإخراج: إخراج الدالة كقيمة JSON (إذا اكتملت الدالة). إذا فشلت دالة المنسق، تتضمن هذه الخاصية تفاصيل الفشل. إذا تم تعليق دالة المنسق أو إنهائها، فإن هذه الخاصية تتضمن سبب التعليق أو الإنهاء (إن وجدت).
• RuntimeStatus: إحدى القيم التالية:
  • معلق: تمت جدولة المثيل ولكن لم يبدأ تشغيله بعد.
  • قيد التشغيل: بدأ تشغيل المثيل.
  • مكتمل: اكتمل المثيل بشكل طبيعي.
  • ContinuedAsNew: قام المثيل بإعادة تشغيل نفسه بمحفوظات جديدة. هذه الحالة هي حالة عابرة.
  • فشل: فشل المثيل مع وجود خطأ.
  • تم الإنهاء: تم إيقاف المثيل فجأة.
  • معلق: تم تعليق المثيل ويمكن استئنافه في وقت لاحق.
• المحفوظات: محفوظات تنفيذ التنسيق. يتم ملء هذا الحقل فقط إذا showHistory تم تعيينه إلى true.

إشعار

لا يتم وضع علامة على المنسق على أنه Completed حتى تنتهي جميع مهامه المجدولة ويعود المنسق. بمعنى آخر، لا يكفي أن يصل المنسق إلى بيانه return حتى يتم وضع علامة عليه على أنه Completed. هذا مهم بشكل خاص للحالات التي WhenAny يتم استخدامها؛ هؤلاء المنسقون غالبا return قبل تنفيذ جميع المهام المجدولة.

يقوم هذا الأسلوب بإرجاع null (.NET وJava) undefined أو (JavaScript) أو None (Python) إذا لم يكن المثيل موجودا.

C#‎

[FunctionName("GetStatus")]
public static async Task Run(
    [DurableClient] IDurableOrchestrationClient client,
    [QueueTrigger("check-status-queue")] string instanceId)
{
    DurableOrchestrationStatus status = await client.GetStatusAsync(instanceId);
    // do something based on the current status.
}

إشعار

التعليمة البرمجية C# السابقة هي ل Durable Functions 2.x. بالنسبة إلى Durable Functions 1.x، يجب استخدام OrchestrationClient السمة بدلا من السمة DurableClient ، ويجب استخدام نوع المعلمة DurableOrchestrationClient بدلا من IDurableOrchestrationClient. لمزيد من المعلومات حول الاختلافات بين الإصدارات، راجع مقالة إصدارات Durable Functions .

JavaScript

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

module.exports = async function(context, instanceId) {
    const client = df.getClient(context);

    const status = await client.getStatus(instanceId);
    // do something based on the current status.
    // example: if status.runtimeStatus === df.OrchestrationRuntimeStatus.Running: ...
}

راجع بدء مثيلات لتكوين function.json.

بايثون

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

async def main(req: func.HttpRequest, starter: str, instance_id: str) -> func.HttpResponse:
    client = df.DurableOrchestrationClient(starter)

    status = await client.get_status(instance_id)
    # do something based on the current status
    # example: if (existing_instance.runtime_status is df.OrchestrationRuntimeStatus.Running) { ...

param($Request, $TriggerMetadata)

# Get instanceid from body
$InstanceId = $Request.Body.InstanceId

$Status = Get-DurableStatus -InstanceId $InstanceId -ShowHistory -ShowHistoryOutput -ShowInput
Write-Host "Status: $($Status | ConvertTo-Json)"

# Do something based on status
# example: if ($Status.runtimeStatus -eq 'Running') { ... }

جاوة

@FunctionName("GetStatus")
public void getStatus(
        @QueueTrigger(name = "instanceID", queueName = "check-status-queue", connection = "Storage") String instanceID,
        @DurableClientInput(name = "durableContext") DurableClientContext durableContext,
        final ExecutionContext context) {
    DurableTaskClient client = durableContext.getClient();        
    OrchestrationMetadata metadata = client.getInstanceMetadata(instanceID, false);
    if (metadata != null) {
        OrchestrationRuntimeStatus status = metadata.getRuntimeStatus();
        switch (status) {
            // do something based on the current status
        }
    }
}

أدوات Azure Functions الأساسية

من الممكن أيضا الحصول على حالة مثيل التنسيق مباشرة باستخدام func durable get-runtime-status الأمر في Core Tools.

إشعار

يتم دعم أوامر Core Tools حاليا فقط عند استخدام موفر Azure Storage الافتراضي لحالة وقت التشغيل المستمرة.

يأخذ الأمر durable get-runtime-status المعلمات التالية:

• id (مطلوب): معرف مثيل التنسيق.
• show-input (اختياري): إذا تم تعيينها إلى true، تحتوي الاستجابة على إدخال الدالة. القيمة الافتراضية هي false.
• show-output (اختياري): إذا تم تعيينها إلى true، تحتوي الاستجابة على إخراج الدالة. القيمة الافتراضية هي false.
• connection-string-setting (اختياري): اسم إعداد التطبيق الذي يحتوي على سلسلة اتصال التخزين المراد استخدامها. الإعداد الافتراضي هو AzureWebJobsStorage.
• task-hub-name (اختياري): اسم مركز مهام Durable Functions المراد استخدامه. الإعداد الافتراضي هو DurableFunctionsHub. يمكن أيضا تعيينه في host.json، باستخدام durableTask:HubName.

يسترد الأمر التالي حالة (بما في ذلك الإدخال والإخراج) لمثيل بمعرف مثيل تنسيق 0ab8c55a66644d68a3a8b220b12d209c. يفترض أنك تقوم بتشغيل func الأمر من الدليل الجذر لتطبيق الوظائف:

func durable get-runtime-status --id 0ab8c55a66644d68a3a8b220b12d209c --show-input true --show-output true

يمكنك استخدام durable get-history الأمر لاسترداد محفوظات مثيل التزامن. يأخذ المعلمات التالية:

• id (مطلوب): معرف مثيل التنسيق.
• connection-string-setting (اختياري): اسم إعداد التطبيق الذي يحتوي على سلسلة اتصال التخزين المراد استخدامها. الإعداد الافتراضي هو AzureWebJobsStorage.
• task-hub-name (اختياري): اسم مركز مهام Durable Functions المراد استخدامه. الإعداد الافتراضي هو DurableFunctionsHub. يمكن أيضا تعيينه في host.json، باستخدام durableTask:HubName.

func durable get-history --id 0ab8c55a66644d68a3a8b220b12d209c

الاستعلام عن جميع المثيلات

يمكنك استخدام واجهات برمجة التطبيقات بلغتك SDK للاستعلام عن حالات جميع مثيلات التنسيق في مركز المهام. تقوم واجهة برمجة التطبيقات هذه "list-instances" أو "get-status" بإرجاع قائمة الكائنات التي تمثل مثيلات التنسيق المطابقة لمعلمات الاستعلام.

C#‎

[FunctionName("GetAllStatus")]
public static async Task Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequestMessage req,
    [DurableClient] IDurableOrchestrationClient client,
    ILogger log)
{
    var noFilter = new OrchestrationStatusQueryCondition();
    OrchestrationStatusQueryResult result = await client.ListInstancesAsync(
        noFilter,
        CancellationToken.None);
    foreach (DurableOrchestrationStatus instance in result.DurableOrchestrationState)
    {
        log.LogInformation(JsonConvert.SerializeObject(instance));
    }
    
    // Note: ListInstancesAsync only returns the first page of results.
    // To request additional pages provide the result.ContinuationToken
    // to the OrchestrationStatusQueryCondition's ContinuationToken property.
}

إشعار

التعليمة البرمجية C# السابقة هي ل Durable Functions 2.x. بالنسبة إلى Durable Functions 1.x، يجب استخدام OrchestrationClient السمة بدلا من السمة DurableClient ، ويجب استخدام نوع المعلمة DurableOrchestrationClient بدلا من IDurableOrchestrationClient. لمزيد من المعلومات حول الاختلافات بين الإصدارات، راجع مقالة إصدارات Durable Functions .

JavaScript

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

module.exports = async function(context, req) {
    const client = df.getClient(context);

    const instances = await client.getStatusAll();
    instances.forEach((instance) => {
        context.log(JSON.stringify(instance));
    });
};

راجع بدء مثيلات لتكوين function.json.

بايثون

import logging
import json
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)

    instances = await client.get_status_all()

    for instance in instances:
        logging.log(json.dumps(instance))

راجع بدء مثيلات لتكوين function.json.

إشعار

هذه الميزة غير مدعومة حاليا في PowerShell، ولكن يمكن تحقيقها باستخدام Durable Functions HTTP API.

جاوة

@FunctionName("GetAllStatus")
public String getAllStatus(
        @HttpTrigger(name = "req", methods = {HttpMethod.GET}) HttpRequestMessage<?> req,
        @DurableClientInput(name = "durableContext") DurableClientContext durableContext) {
    DurableTaskClient client = durableContext.getClient();
    OrchestrationStatusQuery noFilter = new OrchestrationStatusQuery();
    OrchestrationStatusQueryResult result = client.queryInstances(noFilter);
    return "Found " + result.getOrchestrationState().size() + " orchestrations.";
}

أدوات Azure Functions الأساسية

من الممكن أيضا الاستعلام عن المثيلات مباشرة، باستخدام func durable get-instances الأمر في Core Tools.

إشعار

يتم دعم أوامر Core Tools حاليا فقط عند استخدام موفر Azure Storage الافتراضي لحالة وقت التشغيل المستمرة.

يأخذ الأمر durable get-instances المعلمات التالية:

• top (اختياري): يدعم هذا الأمر الترحيل. تتوافق هذه المعلمة مع عدد المثيلات التي تم استردادها لكل طلب. الافتراضي هو 10.
• continuation-token (اختياري): رمز مميز للإشارة إلى الصفحة أو قسم المثيلات المراد استردادها. يقوم كل get-instances تنفيذ بإرجاع رمز مميز إلى المجموعة التالية من المثيلات.
• connection-string-setting (اختياري): اسم إعداد التطبيق الذي يحتوي على سلسلة اتصال التخزين المراد استخدامها. الإعداد الافتراضي هو AzureWebJobsStorage.
• task-hub-name (اختياري): اسم مركز مهام Durable Functions المراد استخدامه. الإعداد الافتراضي هو DurableFunctionsHub. يمكن أيضا تعيينه في host.json، باستخدام durableTask:HubName.

func durable get-instances

مثيلات الاستعلام مع عوامل التصفية

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

C#‎

[FunctionName("QueryStatus")]
public static async Task Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequestMessage req,
    [DurableClient] IDurableOrchestrationClient client,
    ILogger log)
{
    // Get the first 100 running or pending instances that were created between 7 and 1 day(s) ago
    var queryFilter = new OrchestrationStatusQueryCondition
    {
        RuntimeStatus = new[]
        {
            OrchestrationRuntimeStatus.Pending,
            OrchestrationRuntimeStatus.Running,
        },
        CreatedTimeFrom = DateTime.UtcNow.Subtract(TimeSpan.FromDays(7)),
        CreatedTimeTo = DateTime.UtcNow.Subtract(TimeSpan.FromDays(1)),
        PageSize = 100,
    };
    
    OrchestrationStatusQueryResult result = await client.ListInstancesAsync(
        queryFilter,
        CancellationToken.None);
    foreach (DurableOrchestrationStatus instance in result.DurableOrchestrationState)
    {
        log.LogInformation(JsonConvert.SerializeObject(instance));
    }
}

إشعار

التعليمة البرمجية C# السابقة هي ل Durable Functions 2.x. بالنسبة إلى Durable Functions 1.x، يجب استخدام OrchestrationClient السمة بدلا من السمة DurableClient ، ويجب استخدام نوع المعلمة DurableOrchestrationClient بدلا من IDurableOrchestrationClient. لمزيد من المعلومات حول الاختلافات بين الإصدارات، راجع مقالة إصدارات Durable Functions .

JavaScript

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

module.exports = async function(context, req) {
    const client = df.getClient(context);

    const runtimeStatus = [
        df.OrchestrationRuntimeStatus.Completed,
        df.OrchestrationRuntimeStatus.Running,
    ];
    const instances = await client.getStatusBy(
        new Date(2021, 3, 10, 10, 1, 0),
        new Date(2021, 3, 10, 10, 23, 59),
        runtimeStatus
    );
    instances.forEach((instance) => {
        context.log(JSON.stringify(instance));
    });
};

راجع بدء مثيلات لتكوين function.json.

بايثون

import logging
from datetime import datetime
import json
import azure.functions as func
import azure.durable_functions as df
from azure.durable_functions.models.OrchestrationRuntimeStatus import OrchestrationRuntimeStatus

async def main(req: func.HttpRequest, starter: str) -> func.HttpResponse:
    client = df.DurableOrchestrationClient(starter)

    runtime_status = [OrchestrationRuntimeStatus.Completed, OrchestrationRuntimeStatus.Running]

    instances = await client.get_status_by(
        datetime(2021, 3, 10, 10, 1, 0),
        datetime(2021, 3, 10, 10, 23, 59),
        runtime_status
    )

    for instance in instances:
        logging.log(json.dumps(instance))

إشعار

هذه الميزة غير مدعومة حاليا في PowerShell، ولكن يمكن تحقيقها باستخدام Durable Functions HTTP API.

جاوة

@FunctionName("GetRunningInstances")
public String getRunningInstances(
        @HttpTrigger(name = "req", methods = {HttpMethod.GET}) HttpRequestMessage<?> req,
        @DurableClientInput(name = "durableContext") DurableClientContext durableContext) {
    DurableTaskClient client = durableContext.getClient();
    OrchestrationStatusQuery filter = new OrchestrationStatusQuery()
        .setRuntimeStatusList(List.of(OrchestrationRuntimeStatus.PENDING, OrchestrationRuntimeStatus.RUNNING))
        .setCreatedTimeFrom(Instant.now().minus(Duration.ofDays(7)))
        .setCreatedTimeTo(Instant.now().minus(Duration.ofDays(1)));
    OrchestrationStatusQueryResult result = client.queryInstances(filter);
    return "Found " + result.getOrchestrationState().size() + " orchestrations.";
}

أدوات Azure Functions الأساسية

في Azure Functions Core Tools، يمكنك أيضا استخدام durable get-instances الأمر مع عوامل التصفية. بالإضافة إلى المعلمات و connection-string-settingcontinuation-tokenو و المذكورة task-hub-name أعلاهtop، يمكنك استخدام ثلاث معلمات عامل تصفية (created-afterو created-beforeوruntime-status).

إشعار

يتم دعم أوامر Core Tools حاليا فقط عند استخدام موفر Azure Storage الافتراضي لحالة وقت التشغيل المستمرة.

فيما يلي معلمات durable get-instances الأمر .

• created-after (اختياري): استرداد المثيلات التي تم إنشاؤها بعد هذا التاريخ/الوقت (UTC). تم قبول أوقات التاريخ المنسقة ISO 8601.
• created-before (اختياري): استرداد المثيلات التي تم إنشاؤها قبل هذا التاريخ/الوقت (UTC). تم قبول أوقات التاريخ المنسقة ISO 8601.
• runtime-status (اختياري): استرداد المثيلات بحالة معينة (على سبيل المثال، قيد التشغيل أو مكتمل). يمكن أن توفر حالات متعددة (مفصولة بمسافة).
• top (اختياري): عدد المثيلات التي تم استردادها لكل طلب. الافتراضي هو 10.
• continuation-token (اختياري): رمز مميز للإشارة إلى الصفحة أو قسم المثيلات المراد استردادها. يقوم كل get-instances تنفيذ بإرجاع رمز مميز إلى المجموعة التالية من المثيلات.
• connection-string-setting (اختياري): اسم إعداد التطبيق الذي يحتوي على سلسلة اتصال التخزين المراد استخدامها. الإعداد الافتراضي هو AzureWebJobsStorage.
• task-hub-name (اختياري): اسم مركز مهام Durable Functions المراد استخدامه. الإعداد الافتراضي هو DurableFunctionsHub. يمكن أيضا تعيينه في host.json، باستخدام durableTask:HubName.

إذا لم توفر أي عوامل تصفية (created-afterأو created-beforeأو runtime-status)، فإن الأمر يسترد top المثيلات ببساطة، دون أي اعتبار لحالة وقت التشغيل أو وقت الإنشاء.

func durable get-instances --created-after 2021-03-10T13:57:31Z --created-before  2021-03-10T23:59Z --top 15

إنهاء المثيلات

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

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

C#‎

[FunctionName("TerminateInstance")]
public static Task Run(
    [DurableClient] IDurableOrchestrationClient client,
    [QueueTrigger("terminate-queue")] string instanceId)
{
    string reason = "Found a bug";
    return client.TerminateAsync(instanceId, reason);
}

إشعار

التعليمة البرمجية C# السابقة هي ل Durable Functions 2.x. بالنسبة إلى Durable Functions 1.x، يجب استخدام OrchestrationClient السمة بدلا من السمة DurableClient ، ويجب استخدام نوع المعلمة DurableOrchestrationClient بدلا من IDurableOrchestrationClient. لمزيد من المعلومات حول الاختلافات بين الإصدارات، راجع مقالة إصدارات Durable Functions .

JavaScript

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

module.exports = async function(context, instanceId) {
    const client = df.getClient(context);

    const reason = "Found a bug";
    return client.terminate(instanceId, reason);
};

راجع بدء مثيلات لتكوين function.json.

بايثون

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

async def main(req: func.HttpRequest, starter: str, instance_id: str) -> func.HttpResponse:
    client = df.DurableOrchestrationClient(starter)

    reason = "Found a bug"
    return await client.terminate(instance_id, reason)

param($Request, $TriggerMetadata)

# Get instance id from body
$InstanceId = $Request.Body.InstanceId
$Reason = 'Found a bug'

Stop-DurableOrchestration -InstanceId $InstanceId -Reason $Reason

جاوة

@FunctionName("TerminateInstance")
public void terminateInstance(
        @HttpTrigger(name = "req", methods = {HttpMethod.POST}) HttpRequestMessage<String> req,
        @DurableClientInput(name = "durableContext") DurableClientContext durableContext) {
    String instanceID = req.getBody();
    String reason = "Found a bug";
    durableContext.getClient().terminate(instanceID, reason);
}

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

إشعار

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

إيقاف المثيلات مؤقتا واستئنافها

يسمح لك تعليق التنسيق بإيقاف التزامن قيد التشغيل. على عكس الإنهاء، لديك خيار استئناف منسق معلق في وقت لاحق.

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

C#‎

[FunctionName("SuspendResumeInstance")]
public static async Task Run(
    [DurableClient] IDurableOrchestrationClient client,
    [QueueTrigger("suspend-resume-queue")] string instanceId)
{
    // To suspend an orchestration
    string suspendReason = "Need to pause workflow";
    await client.SuspendAsync(instanceId, suspendReason);
    
    // To resume an orchestration
    string resumeReason = "Continue workflow";
    await client.ResumeAsync(instanceId, resumeReason);
}

JavaScript

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

module.exports = async function(context, instanceId) {
    const client = df.getClient(context);

    // To suspend an orchestration
    const suspendReason = "Need to pause workflow";
    await client.suspend(instanceId, suspendReason);

    // To resume an orchestration
    const resumeReason = "Continue workflow";
    await client.resume(instanceId, resumeReason);
};

بايثون

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

async def main(req: func.HttpRequest, starter: str, instance_id: str):
    client = df.DurableOrchestrationClient(starter)

    # To suspend an orchestration
    suspend_reason = "Need to pause workflow"
    await client.suspend(instance_id, suspend_reason)

    # To resume an orchestration
    resume_reason = "Continue workflow"
    await client.resume(instance_id, resume_reason)

param($Request, $TriggerMetadata)

$InstanceId = $Request.Body.InstanceId

# To suspend an orchestration
$SuspendReason = 'Need to pause workflow'
Suspend-DurableOrchestration -InstanceId $InstanceId -Reason $SuspendReason

# To resume an orchestration
$ResumeReason = 'Continue workflow'
Resume-DurableOrchestration -InstanceId $InstanceId -Reason $ResumeReason

إشعار

تتوفر هذه الميزة في Durable Functions PowerShell SDK المستقل فقط. راجع الفرق بين SDK المستقلة وSDK المضمنة القديمة جنبا إلى جنب مع دليل الترحيل.

جاوة

@FunctionName("SuspendResumeInstance")
public void suspendResumeInstance(
        @HttpTrigger(name = "req", methods = {HttpMethod.POST}) HttpRequestMessage<String> req,
        @DurableClientInput(name = "durableContext") DurableClientContext durableContext) {
    String instanceID = req.getBody();
    DurableTaskClient client = durableContext.getClient();  

    // To suspend an orchestration
    String suspendReason = "Need to pause workflow";
    client.suspendInstance(instanceID, suspendReason);

    // To resume an orchestration
    String resumeReason = "Continue workflow";
    client.resumeInstance(instanceID, resumeReason);
}

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

عند استئناف منسق معلق، ستتغير حالته مرة أخرى إلى Running.

أدوات Azure Functions الأساسية

يمكنك أيضا إنهاء مثيل تزامن مباشرة، باستخدام func durable terminate الأمر في Core Tools.

إشعار

يتم دعم أوامر Core Tools حاليا فقط عند استخدام موفر Azure Storage الافتراضي لحالة وقت التشغيل المستمرة.

يأخذ الأمر durable terminate المعلمات التالية:

• id (مطلوب): معرف مثيل التنسيق المراد إنهائه.
• reason (اختياري): سبب الإنهاء.
• connection-string-setting (اختياري): اسم إعداد التطبيق الذي يحتوي على سلسلة اتصال التخزين المراد استخدامها. الإعداد الافتراضي هو AzureWebJobsStorage.
• task-hub-name (اختياري): اسم مركز مهام Durable Functions المراد استخدامه. الإعداد الافتراضي هو DurableFunctionsHub. يمكن أيضا تعيينه في host.json، باستخدام durableTask:HubName.

ينهي الأمر التالي مثيل تزامن بمعرف 0ab8c55a66644d68a3a8b220b12d209c:

func durable terminate --id 0ab8c55a66644d68a3a8b220b12d209c --reason "Found a bug"

إرسال الأحداث إلى المثيلات

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

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

معلمات حدث رفع كما يلي:

• معرف المثيل: المعرف الفريد للمثيل.
• اسم الحدث: اسم الحدث المراد إرساله.
• بيانات الحدث: حمولة JSON قابلة للتسلسل لإرسالها إلى المثيل.

C#‎

[FunctionName("RaiseEvent")]
public static Task Run(
    [DurableClient] IDurableOrchestrationClient client,
    [QueueTrigger("event-queue")] string instanceId)
{
    int[] eventData = new int[] { 1, 2, 3 };
    return client.RaiseEventAsync(instanceId, "MyEvent", eventData);
}

إشعار

التعليمة البرمجية C# السابقة هي ل Durable Functions 2.x. بالنسبة إلى Durable Functions 1.x، يجب استخدام OrchestrationClient السمة بدلا من السمة DurableClient ، ويجب استخدام نوع المعلمة DurableOrchestrationClient بدلا من IDurableOrchestrationClient. لمزيد من المعلومات حول الاختلافات بين الإصدارات، راجع مقالة إصدارات Durable Functions .

JavaScript

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

module.exports = async function(context, instanceId) {
    const client = df.getClient(context);

    const eventData = [ 1, 2, 3 ];
    return client.raiseEvent(instanceId, "MyEvent", eventData);
};

راجع بدء مثيلات لتكوين function.json.

بايثون

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

async def main(req: func.HttpRequest, starter: str, instance_id: str) -> func.HttpResponse:
    client = df.DurableOrchestrationClient(starter)

    event_data = [1, 2 ,3]
    return await client.raise_event(instance_id, 'MyEvent', event_data)

param($Request, $TriggerMetadata)

# Get instance id from body
$InstanceId = $Request.Body.InstanceId
$EventName = 'MyEvent'
$EventData = @(1,2,3)

Send-DurableExternalEvent -InstanceId $InstanceId -EventName $EventName -EventData $EventData

جاوة

@FunctionName("RaiseEvent")
public void raiseEvent(
        @HttpTrigger(name = "req", methods = {HttpMethod.POST}) HttpRequestMessage<String> req,
        @DurableClientInput(name = "durableContext") DurableClientContext durableContext) {
    String instanceID = req.getBody();
    String eventName = "MyEvent";
    int[] eventData = { 1, 2, 3 };
    durableContext.getClient().raiseEvent(instanceID, eventName, eventData);
}

إشعار

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

أدوات Azure Functions الأساسية

يمكنك أيضا رفع حدث إلى مثيل تزامن مباشرة، باستخدام func durable raise-event الأمر في Core Tools.

إشعار

يتم دعم أوامر Core Tools حاليا فقط عند استخدام موفر Azure Storage الافتراضي لحالة وقت التشغيل المستمرة.

يأخذ الأمر durable raise-event المعلمات التالية:

• id (مطلوب): معرف مثيل التنسيق.
• event-name: اسم الحدث الذي يجب رفعه.
• event-data (اختياري): البيانات المراد إرسالها إلى مثيل التنسيق. يمكن أن يكون هذا هو المسار إلى ملف JSON، أو يمكنك توفير البيانات مباشرة على سطر الأوامر.
• connection-string-setting (اختياري): اسم إعداد التطبيق الذي يحتوي على سلسلة اتصال التخزين المراد استخدامها. الإعداد الافتراضي هو AzureWebJobsStorage.
• task-hub-name (اختياري): اسم مركز مهام Durable Functions المراد استخدامه. الإعداد الافتراضي هو DurableFunctionsHub. يمكن أيضا تعيينه في host.json، باستخدام durableTask:HubName.

func durable raise-event --id 0ab8c55a66644d68a3a8b220b12d209c --event-name MyEvent --event-data @eventdata.json

func durable raise-event --id 1234567 --event-name MyOtherEvent --event-data 3

انتظر حتى اكتمال التنسيق

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

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

فيما يلي مثال على دالة مشغل HTTP التي توضح كيفية استخدام واجهة برمجة التطبيقات هذه:

C#‎

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

using System;
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 HttpSyncStart
    {
        private const string Timeout = "timeout";
        private const string RetryInterval = "retryInterval";

        [FunctionName("HttpSyncStart")]
        public static async Task<HttpResponseMessage> Run(
            [HttpTrigger(AuthorizationLevel.Function, methods: "post", Route = "orchestrators/{functionName}/wait")]
            HttpRequestMessage req,
            [DurableClient] IDurableOrchestrationClient 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}'.");

            TimeSpan timeout = GetTimeSpan(req, Timeout) ?? TimeSpan.FromSeconds(30);
            TimeSpan retryInterval = GetTimeSpan(req, RetryInterval) ?? TimeSpan.FromSeconds(1);
            
            return await starter.WaitForCompletionOrCreateCheckStatusResponseAsync(
                req,
                instanceId,
                timeout,
                retryInterval);
        }

        private static TimeSpan? GetTimeSpan(HttpRequestMessage request, string queryParameterName)
        {
            string queryParameterStringValue = request.RequestUri.ParseQueryString()[queryParameterName];
            if (string.IsNullOrEmpty(queryParameterStringValue))
            {
                return null;
            }

            return TimeSpan.FromSeconds(double.Parse(queryParameterStringValue));
        }
    }
}

JavaScript

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

const timeout = "timeout";
const retryInterval = "retryInterval";

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}'.`);

    const timeoutInMilliseconds = getTimeInSeconds(req, timeout) || 30000;
    const retryIntervalInMilliseconds = getTimeInSeconds(req, retryInterval) || 1000;

    const response = client.waitForCompletionOrCreateCheckStatusResponse(
        context.bindingData.req,
        instanceId,
        timeoutInMilliseconds,
        retryIntervalInMilliseconds
    );
    return response;
};

function getTimeInSeconds(req, queryParameterName) {
    const queryValue = req.query[queryParameterName];
    return queryValue
        ? queryValue * 1000 // expected to be in seconds
        : undefined;
}

راجع بدء مثيلات لتكوين function.json.

بايثون

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

timeout = "timeout"
retry_interval = "retryInterval"

async def main(req: func.HttpRequest, starter: str) -> func.HttpResponse:
    client = df.DurableOrchestrationClient(starter)

    instance_id = await client.start_new(req.route_params['functionName'], None, req.get_body())
    logging.log(f"Started orchestration with ID = '${instance_id}'.")

    timeout_in_milliseconds = get_time_in_seconds(req, timeout)
    timeout_in_milliseconds = timeout_in_milliseconds if timeout_in_milliseconds != None else 30000
    retry_interval_in_milliseconds = get_time_in_seconds(req, retry_interval)
    retry_interval_in_milliseconds = retry_interval_in_milliseconds if retry_interval_in_milliseconds != None else 1000

    return await client.wait_for_completion_or_create_check_status_response(
        req,
        instance_id,
        timeout_in_milliseconds,
        retry_interval_in_milliseconds
    )

def get_time_in_seconds(req: func.HttpRequest, query_parameter_name: str):
    query_value = req.params.get(query_parameter_name)
    return query_value if query_value != None else 1000

إشعار

لا يحتوي PowerShell حاليا على أمر مضمن لهذا السيناريو.

جاوة

لا تحتوي Java حاليا على أسلوب واحد لهذا السيناريو. ومع ذلك، يمكن تنفيذه باستخدام بضعة أسطر إضافية من التعليمات البرمجية.

@FunctionName("HttpStartAndWait")
public HttpResponseMessage httpStartAndWait(
        @HttpTrigger(name = "req", route = "orchestrators/{functionName}/wait", methods = {HttpMethod.POST}) 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);
    try {
        String timeoutString = req.getQueryParameters().get("timeout");
        Integer timeoutInSeconds = Integer.parseInt(timeoutString);
        OrchestrationMetadata orchestration = client.waitForInstanceCompletion(
                instanceId,
                Duration.ofSeconds(timeoutInSeconds),
                true /* getInputsAndOutputs */);
        return req.createResponseBuilder(HttpStatus.OK)
                .body(orchestration.getSerializedOutput())
                .header("Content-Type", "application/json")
                .build();
    } catch (TimeoutException timeoutEx) {
        // timeout expired - return a 202 response
        return durableContext.createCheckStatusResponse(req, instanceId);
    }
}

استدعاء الدالة مع السطر التالي. استخدم ثانيتين للمهلة و0.5 ثانية للفاصل الزمني لإعادة المحاولة:

curl -X POST "http://localhost:7071/orchestrators/E1_HelloSequence/wait?timeout=2&retryInterval=0.5"

إشعار

يفترض الأمر cURL أعلاه أن لديك دالة منسق تسمى E1_HelloSequence في مشروعك. بسبب كيفية كتابة دالة مشغل HTTP، يمكنك استبدالها باسم أي دالة منسق في مشروعك.

اعتمادا على الوقت المطلوب للحصول على الاستجابة من مثيل التنسيق، هناك حالتان:

• تكتمل مثيلات التزامن خلال المهلة المحددة (في هذه الحالة ثانيتين)، والاستجابة هي إخراج مثيل التزامن الفعلي، الذي يتم تسليمه بشكل متزامن:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Thu, 14 Dec 2021 06:14:29 GMT
Transfer-Encoding: chunked

[
    "Hello Tokyo!",
    "Hello Seattle!",
    "Hello London!"
]

• لا يمكن إكمال مثيلات التزامن ضمن المهلة المحددة، والاستجابة هي الاستجابة الافتراضية الموضحة في اكتشاف عنوان URL لواجهة برمجة تطبيقات HTTP:

HTTP/1.1 202 Accepted
Content-Type: application/json; charset=utf-8
Date: Thu, 14 Dec 2021 06:13:51 GMT
Location: http://localhost:7071/runtime/webhooks/durabletask/instances/d3b72dddefce4e758d92f4d411567177?taskHub={taskHub}&connection={connection}&code={systemKey}
Retry-After: 10
Transfer-Encoding: chunked

{
    "id": "d3b72dddefce4e758d92f4d411567177",
    "sendEventPostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/d3b72dddefce4e758d92f4d411567177/raiseEvent/{eventName}?taskHub={taskHub}&connection={connection}&code={systemKey}",
    "statusQueryGetUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/d3b72dddefce4e758d92f4d411567177?taskHub={taskHub}&connection={connection}&code={systemKey}",
    "terminatePostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/d3b72dddefce4e758d92f4d411567177/terminate?reason={text}&taskHub={taskHub}&connection={connection}&code={systemKey}",
    "suspendPostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/d3b72dddefce4e758d92f4d411567177/suspend?reason={text}&taskHub={taskHub}&connection={connection}&code={systemKey}",
    "resumePostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/d3b72dddefce4e758d92f4d411567177/resume?reason={text}&taskHub={taskHub}&connection={connection}&code={systemKey}"
}

إشعار

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

استرداد عناوين URL لخطاف الويب لإدارة HTTP

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

تحتوي واجهة برمجة تطبيقات حمولة إدارة HTTP على معلمة واحدة:

• معرف المثيل: المعرف الفريد للمثيل.

ترجع الأساليب كائنا بخصائص السلسلة التالية:

• المعرف: معرف المثيل الخاص بالتزامن (يجب أن يكون هو نفس InstanceId الإدخال).
• StatusQueryGetUri: عنوان URL لحالة مثيل التنسيق.
• SendEventPostUri: عنوان URL "رفع الحدث" لمثيل التنسيق.
• TerminatePostUri: عنوان URL "إنهاء" لمثيل التنسيق.
• PurgeHistoryDeleteUri: عنوان URL "محفوظات التطهير" لمثيل التنسيق.
• suspendPostUri: عنوان URL "تعليق" لمثيل التنسيق.
• resumePostUri: عنوان URL "استئناف" لمثيل التنسيق.

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

C#‎

[FunctionName("SendInstanceInfo")]
public static void SendInstanceInfo(
    [ActivityTrigger] IDurableActivityContext ctx,
    [DurableClient] IDurableOrchestrationClient client,
    [CosmosDB(
        databaseName: "MonitorDB",
        containerName: "HttpManagementPayloads",
        Connection = "CosmosDBConnectionSetting")]out dynamic document)
{
    HttpManagementPayload payload = client.CreateHttpManagementPayload(ctx.InstanceId);

    // send the payload to Azure Cosmos DB
    document = new { Payload = payload, id = ctx.InstanceId };
}

إشعار

التعليمة البرمجية C# السابقة هي ل Durable Functions 2.x. بالنسبة إلى Durable Functions 1.x، يجب استخدام DurableActivityContext بدلا من IDurableActivityContext، يجب استخدام السمة OrchestrationClient بدلا من السمة DurableClient ، ويجب استخدام نوع المعلمة DurableOrchestrationClient بدلا من IDurableOrchestrationClient. لمزيد من المعلومات حول الاختلافات بين الإصدارات، راجع مقالة إصدارات Durable Functions .

JavaScript

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

modules.exports = async function(context, ctx) {
    const client = df.getClient(context);

    const payload = client.createHttpManagementPayload(ctx.instanceId);

    // send the payload to Azure Cosmos DB
    context.bindings.document = JSON.stringify({
        id: ctx.instanceId,
        payload,
    });
};

راجع بدء مثيلات لتكوين function.json.

بايثون

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

async def main(req: func.HttpRequest, starter: str, instance_id: str) -> func.cosmosdb.cdb.Document:
    client = df.DurableOrchestrationClient(starter)

    payload = client.create_check_status_response(req, instance_id).get_body().decode()

    return func.cosmosdb.CosmosDBConverter.encode({
        id: instance_id,
        payload: payload
    })

using namespace System.Net

param($Request, $TriggerMetadata)

$InstanceId = $Request.Body.InstanceId
$Response = New-DurableOrchestrationCheckStatusResponse -Request $Request -InstanceId $InstanceId
Push-OutputBinding -Name Response -Value $Response

جاوة

إشعار

هذه الميزة غير مدعومة حاليا في Java.

مثيلات إرجاع (معاينة)

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

إشعار

لا يقصد بواجهة برمجة التطبيقات هذه أن تكون بديلا عن نهج معالجة الأخطاء وإعادة المحاولة المناسبة. بدلا من ذلك، الغرض منه أن يتم استخدامه فقط في الحالات التي تفشل فيها مثيلات التنسيق لأسباب غير متوقعة. لا يمكن أن تكون التنسيقات في حالات أخرى غير Failed (على سبيل المثال، Running، ، Pending، Terminated، Completed) "rewound". لمزيد من المعلومات حول معالجة الأخطاء وإعادة محاولة النهج، راجع مقالة معالجة الأخطاء .

RewindAsync استخدم الأسلوب (.NET) أو rewind (JavaScript) لربط عميل التزامن لإعادة التنسيق إلى حالة قيد التشغيل. سيقوم هذا الأسلوب أيضا بإعادة تشغيل النشاط أو فشل تنفيذ التزامن الفرعي الذي تسبب في فشل التنسيق.

على سبيل المثال، لنفترض أن لديك سير عمل يتضمن سلسلة من الموافقات البشرية. لنفترض أن هناك سلسلة من وظائف النشاط التي تعلم شخصا ما بأن موافقته مطلوبة، وانتظر الاستجابة في الوقت الفعلي. بعد تلقي كافة أنشطة الموافقة استجابات أو انتهاء مهلتها، افترض أن نشاطا آخر فشل بسبب التكوين الخاطئ للتطبيق، مثل سلسلة اتصال قاعدة بيانات غير صالحة. والنتيجة هي فشل التنسيق في عمق سير العمل. RewindAsync باستخدام واجهة برمجة تطبيقات (.NET) أو rewind (JavaScript)، يمكن لمسؤول التطبيق إصلاح خطأ التكوين، وإرجاع التنسيق الفاشل مرة أخرى إلى الحالة مباشرة قبل الفشل. لا يلزم إعادة الموافقة على أي من خطوات التفاعل البشري، ويمكن الآن إكمال التنسيق بنجاح.

إشعار

لا تدعم ميزة الإرجاع إرجاع مثيلات التنسيق التي تستخدم مؤقتات دائمة.

C#‎

[FunctionName("RewindInstance")]
public static Task Run(
    [DurableClient] IDurableOrchestrationClient client,
    [QueueTrigger("rewind-queue")] string instanceId)
{
    string reason = "Orchestrator failed and needs to be revived.";
    return client.RewindAsync(instanceId, reason);
}

إشعار

التعليمة البرمجية C# السابقة هي ل Durable Functions 2.x. بالنسبة إلى Durable Functions 1.x، يجب استخدام OrchestrationClient السمة بدلا من السمة DurableClient ، ويجب استخدام نوع المعلمة DurableOrchestrationClient بدلا من IDurableOrchestrationClient. لمزيد من المعلومات حول الاختلافات بين الإصدارات، راجع مقالة إصدارات Durable Functions .

JavaScript

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

module.exports = async function(context, instanceId) {
    const client = df.getClient(context);

    const reason = "Orchestrator failed and needs to be revived.";
    return client.rewind(instanceId, reason);
};

راجع بدء مثيلات لتكوين function.json.

بايثون

إشعار

هذه الميزة غير مدعومة حاليا في Python.

إشعار

هذه الميزة غير معتمدة حاليا في PowerShell.

جاوة

إشعار

هذه الميزة غير مدعومة حاليا في Java.

أدوات Azure Functions الأساسية

يمكنك أيضا إرجاع مثيل تزامن مباشرة باستخدام func durable rewind الأمر في Core Tools.

إشعار

يتم دعم أوامر Core Tools حاليا فقط عند استخدام موفر Azure Storage الافتراضي لحالة وقت التشغيل المستمرة.

يأخذ الأمر durable rewind المعلمات التالية:

• id (مطلوب): معرف مثيل التنسيق.
• reason (اختياري): سبب إرجاع مثيل التنسيق.
• connection-string-setting (اختياري): اسم إعداد التطبيق الذي يحتوي على سلسلة اتصال التخزين المراد استخدامها. الإعداد الافتراضي هو AzureWebJobsStorage.
• task-hub-name (اختياري): اسم مركز مهام Durable Functions المراد استخدامه. بشكل افتراضي، يتم استخدام اسم مركز المهام في ملف host.json .

func durable rewind --id 0ab8c55a66644d68a3a8b220b12d209c --reason "Orchestrator failed and needs to be revived."

إزالة محفوظات المثيل

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

يوضح هذا المثال الأول كيفية إزالة مثيل تنسيق واحد.

C#‎

[FunctionName("PurgeInstanceHistory")]
public static Task Run(
    [DurableClient] IDurableOrchestrationClient client,
    [QueueTrigger("purge-queue")] string instanceId)
{
    return client.PurgeInstanceHistoryAsync(instanceId);
}

JavaScript

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

module.exports = async function(context, instanceId) {
    const client = df.getClient(context);
    return client.purgeInstanceHistory(instanceId);
};

راجع بدء مثيلات لتكوين function.json.

بايثون

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

async def main(req: func.HttpRequest, starter: str, instance_id: str) -> func.HttpResponse:
    client = df.DurableOrchestrationClient(starter)

    return await client.purge_instance_history(instance_id)

إشعار

هذه الميزة غير مدعومة حاليا في PowerShell، ولكن يمكن تحقيقها باستخدام Durable Functions HTTP API.

جاوة

@FunctionName("PurgeInstance")
public HttpResponseMessage purgeInstance(
        @HttpTrigger(name = "req", methods = {HttpMethod.POST}, route = "purge/{instanceID}") HttpRequestMessage<?> req,
        @DurableClientInput(name = "durableContext") DurableClientContext durableContext,
        @BindingName("instanceID") String instanceID) {
    PurgeResult result = durableContext.getClient().purgeInstance(instanceID);
    if (result.getDeletedInstanceCount() == 0) {
        return req.createResponseBuilder(HttpStatus.NOT_FOUND)
                .body("No completed instance with ID '" + instanceID + "' was found!")
                .build();
    } else {
        return req.createResponseBuilder(HttpStatus.OK)
                .body("Successfully purged data for " + instanceID)
                .build();
    }
}

يوضح المثال التالي دالة مشغلة من قبل المؤقت تقوم بمسح المحفوظات لكافة مثيلات التنسيق التي اكتملت بعد الفاصل الزمني المحدد. في هذه الحالة، فإنه يزيل البيانات لجميع المثيلات المكتملة منذ 30 يوما أو أكثر. تتم جدولة هذه الدالة على سبيل المثال للتشغيل مرة واحدة يوميا، في الساعة 12:00 مساء بالتوقيت العالمي المتفق عليه:

C#‎

[FunctionName("PurgeInstanceHistory")]
public static Task Run(
    [DurableClient] IDurableOrchestrationClient client,
    [TimerTrigger("0 0 12 * * *")] TimerInfo myTimer)
{
    return client.PurgeInstanceHistoryAsync(
        DateTime.MinValue,
        DateTime.UtcNow.AddDays(-30),  
        new List<OrchestrationStatus>
        {
            OrchestrationStatus.Completed
        });
}

إشعار

التعليمة البرمجية C# السابقة هي ل Durable Functions 2.x. بالنسبة إلى Durable Functions 1.x، يجب استخدام OrchestrationClient السمة بدلا من السمة DurableClient ، ويجب استخدام نوع المعلمة DurableOrchestrationClient بدلا من IDurableOrchestrationClient. لمزيد من المعلومات حول الاختلافات بين الإصدارات، راجع مقالة إصدارات Durable Functions .

JavaScript

purgeInstanceHistoryBy يمكن استخدام الأسلوب لمسح محفوظات المثيلات بشكل مشروط لمثيلات متعددة.

function.json

{
  "bindings": [
    {
      "schedule": "0 0 12 * * *",
      "name": "myTimer",
      "type": "timerTrigger",
      "direction": "in"
    },
    {
      "name": "starter",
      "type": "durableClient",
      "direction": "in"
    }
  ],
  "disabled": false
}

إشعار

يستهدف هذا المثال Durable Functions الإصدار 2.x. في الإصدار 1.x، استخدم orchestrationClient بدلا من durableClient.

index.js

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

module.exports = async function (context, myTimer) {
    const client = df.getClient(context);
    const createdTimeFrom = new Date(0);
    const createdTimeTo = new Date().setDate(today.getDate() - 30);
    const runtimeStatuses = [ df.OrchestrationRuntimeStatus.Completed ];
    return client.purgeInstanceHistoryBy(createdTimeFrom, createdTimeTo, runtimeStatuses);
};

إشعار

هذه الميزة غير مدعومة حاليا في PowerShell، ولكن يمكن تحقيقها باستخدام Durable Functions HTTP API.

بايثون

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

async def main(req: func.HttpRequest, starter: str, instance_id: str) -> func.HttpResponse:
    client = df.DurableOrchestrationClient(starter)
    created_time_from = datetime.min
    created_time_to = datetime.today() + timedelta(days = -30)
    runtime_statuses = [OrchestrationRuntimeStatus.Completed]

    return await client.purge_instance_history_by(created_time_from, created_time_to, runtime_statuses)

جاوة

@FunctionName("PurgeInstances")
public void purgeInstances(
        @TimerTrigger(name = "purgeTimer", schedule = "0 0 12 * * *") String timerInfo,
        @DurableClientInput(name = "durableContext") DurableClientContext durableContext,
        ExecutionContext context) throws TimeoutException {
    PurgeInstanceCriteria criteria = new PurgeInstanceCriteria()
            .setCreatedTimeFrom(Instant.now().minus(Duration.ofDays(60)))
            .setCreatedTimeTo(Instant.now().minus(Duration.ofDays(30)))
            .setRuntimeStatusList(List.of(OrchestrationRuntimeStatus.COMPLETED));
    PurgeResult result = durableContext.getClient().purgeInstances(criteria);
    context.getLogger().info(String.format("Purged %d instance(s)", result.getDeletedInstanceCount()));
}

إشعار

لكي تنجح عملية محفوظات الإزالة، يجب أن تكون حالة وقت التشغيل للمثيل الهدف مكتملة أو منتهية أو فاشلة.

أدوات Azure Functions الأساسية

يمكنك إزالة محفوظات مثيل التزامن باستخدام func durable purge-history الأمر في Core Tools. على غرار المثال الثاني C# في القسم السابق، فإنه يزيل المحفوظات لجميع مثيلات التنسيق التي تم إنشاؤها خلال فاصل زمني محدد. يمكنك تصفية المثيلات التي تمت إزالتها بشكل أكبر حسب حالة وقت التشغيل.

إشعار

يتم دعم أوامر Core Tools حاليا فقط عند استخدام موفر Azure Storage الافتراضي لحالة وقت التشغيل المستمرة.

يحتوي الأمر على durable purge-history العديد من المعلمات:

• created-after (اختياري): إزالة محفوظات المثيلات التي تم إنشاؤها بعد هذا التاريخ/الوقت (UTC). تم قبول أوقات التاريخ المنسقة ISO 8601.
• created-before (اختياري): إزالة محفوظات المثيلات التي تم إنشاؤها قبل هذا التاريخ/الوقت (UTC). تم قبول أوقات التاريخ المنسقة ISO 8601.
• runtime-status (اختياري): إزالة محفوظات المثيلات ذات حالة معينة (على سبيل المثال، قيد التشغيل أو مكتمل). يمكن أن توفر حالات متعددة (مفصولة بمسافة).
• connection-string-setting (اختياري): اسم إعداد التطبيق الذي يحتوي على سلسلة اتصال التخزين المراد استخدامها. الإعداد الافتراضي هو AzureWebJobsStorage.
• task-hub-name (اختياري): اسم مركز مهام Durable Functions المراد استخدامه. بشكل افتراضي، يتم استخدام اسم مركز المهام في ملف host.json .

يحذف الأمر التالي محفوظات جميع المثيلات الفاشلة التي تم إنشاؤها قبل 14 نوفمبر 2021 في الساعة 7:35 مساء (UTC).

func durable purge-history --created-before 2021-11-14T19:35:00.0000000Z --runtime-status failed

حذف مركز مهام

func durable delete-task-hub باستخدام الأمر في Core Tools، يمكنك حذف جميع عناصر التخزين المرتبطة بمركز مهام معين، بما في ذلك جداول تخزين Azure وقوائم الانتظار والكائنات الثنائية كبيرة الحجم.

إشعار

يتم دعم أوامر Core Tools حاليا فقط عند استخدام موفر Azure Storage الافتراضي لحالة وقت التشغيل المستمرة.

يحتوي الأمر على durable delete-task-hub معلمتين:

• connection-string-setting (اختياري): اسم إعداد التطبيق الذي يحتوي على سلسلة اتصال التخزين المراد استخدامها. الإعداد الافتراضي هو AzureWebJobsStorage.
• task-hub-name (اختياري): اسم مركز مهام Durable Functions المراد استخدامه. بشكل افتراضي، يتم استخدام اسم مركز المهام في ملف host.json .

يحذف الأمر التالي جميع بيانات تخزين Azure المقترنة بمركز UserTest المهام.

func durable delete-task-hub --task-hub-name UserTest

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

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

مرجع HTTP API المضمن لإدارة المثيل