مرجع واجهة برمجة تطبيقات HTTP

يعرض ملحق Durable Functions مجموعة من واجهات برمجة تطبيقات HTTP المضمنة التي يمكنها تنفيذ مهام الإدارة على orchestrations، entities، ومراكز task. واجهات برمجة تطبيقات HTTP هذه هي إخطارات على الويب القابلة للتوسعة التي يخولها مضيف دالات Azure، ولكن ملحق Durable Functions يعالج مباشرة.

قبل استخدام واجهات برمجة تطبيقات HTTP هذه، تأكد من أن لديك:

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

عنوان URL الأساسي والمعلمات الشائعة

تشترك جميع واجهات برمجة تطبيقات HTTP في نفس عنوان URL الأساسي مثل تطبيق الوظائف. عند التطوير محليا باستخدام دالات Azure Core Tools، يكون عنوان URL الأساسي عادة http://localhost:7071. في الخدمة المستضافة دالات Azure، يكون عنوان URL الأساسي عادة https://{appName}.azurewebsites.net. يدعم الملحق أيضا أسماء المضيفين المخصصة إذا تم تكوينها على تطبيق App Service.

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

المعلمة	نوع المعلمة	الوصف
`taskHub`	سلسلة الاستعلام	اسم مركز المهام. إذا لم يتم تحديده، يفترض اسم مركز المهام لتطبيق الدالة الحالي.
`connection`	سلسلة الاستعلام	اسم إعداد تطبيق الاتصال لمزود التخزين الخلفي. إذا لم يتم تحديده، يفترض أن يكون التكوين الافتراضي للاتصال لتطبيق الوظيفة.
`systemKey`	سلسلة الاستعلام	مفتاح التفويض المطلوب لاستدعاء واجهة برمجة التطبيقات.

كيفية الحصول على قيم المعلمات

استخدام روابط عميل التزامن (مستحسن): إنشاء عناوين URL كاملة تلقائيا باستخدام واجهات برمجة التطبيقات لربط عميل التنسيق :

.NET: CreateCheckStatusResponse()، CreateHttpManagementPayload()
JavaScript: createCheckStatusResponse()، createHttpManagementPayload()

إنشاء عنوان URL اليدوي:

taskHub: تم استرداده من host.json الملف:
- v2.x: extensions.durableTask.hubName
- v1.x: durableTask.hubName
- يمكن أيضا تكوينه عبر إعدادات التطبيق باستخدام %AppSettingName% بناء الجملة
connection: اسم إعداد التطبيق الذي يحتوي على اتصال التخزين. تم الاسترداد من host.json:
- v2.x: extensions.durableTask.storageProvider.connectionStringName (الإعدادات الافتراضية إلى AzureWebJobsStorage إذا لم يتم تحديدها)
- v1.x: durableTask.azureStorageConnectionStringName (الإعدادات الافتراضية إلى AzureWebJobsStorage إذا لم يتم تحديدها)
- يمكن استخدام سلاسل الاتصال أو الاتصالات المستندة إلى identity (المصادقة Microsoft Entra)
systemKey: مفتاح تخويل خاص بالملحق لواجهات برمجة تطبيقات المهام الدائمة. تم استرداده من مدخل Azure:
1. افتح تطبيق الوظائف
2. حدد Functions → App keys في القائمة اليسرى
3. ضمن قسم مفاتيح النظام ، حدد موقع المفتاح (عادة ما يتم إنشاؤه تلقائيا للملحق)
4. نسخ قيمة المفتاح
️ ملاحظة الأمان: يمنح مفتاح النظام الوصول إلى جميع واجهات برمجة تطبيقات HTTP Durable Functions. لا تشاركه بشكل عام أو قم بتضمينه في التعليمات البرمجية من جانب العميل.

تدعم كل واجهة برمجة تطبيقات HTTP مجموعة متسقة من أنماط الطلب/الاستجابة. توفر الأقسام التالية معلومات لكل عملية.

سير عمل واجهة برمجة التطبيقات الشائعة

تتبع دورة حياة التزامن النموذجية هذا التسلسل:

بدء التنسيق → POST /runtime/webhooks/durabletask/orchestrators/{functionName} → إرجاع معرف المثيل وعنوان URL للحالة
التحقق من حالة → GET /runtime/webhooks/durabletask/instances/{instanceId} تقدم → Monitor
إرسال حدث (اختياري) → POST /runtime/webhooks/durabletask/instances/{instanceId}/raiseEvent/{eventName} → إرسال إشارات خارجية
تنظيف (اختياري) → DELETE /runtime/webhooks/durabletask/instances/{instanceId} محفوظات إزالة →

للحصول على تفاصيل العملية وأمثلة الطلب/الاستجابة، راجع المرجع أدناه.

ابدأ التوزيع الأوركسترالي

يبدأ تنفيذ نسخة جديدة من وظيفة التنسيق المحددة.

الطلب

مهم

يختلف تنسيق URL حسب إصدار وقت تشغيل الوظائف. حدد التنسيق الذي يتطابق مع بيئتك.

وقت تشغيل الوظائف 2.x (مستحسن):

POST /runtime/webhooks/durabletask/orchestrators/{functionName}/{instanceId?}
     ?taskHub={taskHub}
     &connection={connectionName}
     &code={systemKey}

وقت تشغيل الوظائف 1.x (قديم):

POST /admin/extensions/DurableTaskExtension/orchestrators/{functionName}/{instanceId?}
     ?taskHub={taskHub}
     &connection={connectionName}
     &code={systemKey}

تتضمن معلمات الطلب لواجهة برمجة التطبيقات هذه المجموعة الافتراضية المذكورة سابقا والمعلمات الفريدة التالية:

الميدان	نوع المعلمة	الوصف
`functionName`	عنوان URL	اسم وظيفة الموزع للبدء.
`instanceId`	عنوان URL	معلمة اختيارية. معرف نسخة التوزيع الأوركسترالي. إذا لم يتم تحديدها، تبدأ دالة المنسق بمعرف مثيل عشوائي.
`{content}`	طلب المحتوى	اختياري. مدخل وظيفة التنسيق JSON.

الاستجابة

يمكن إرجاع عدة قيم محتملة لرموز الحالة.

HTTP 202 (مقبول): تم جدولة وظيفة المنسق المحددة لتبدأ التشغيل. يحتوي رأس Location الرد على رابط لاستطلاع حالة التوزيع الأوركستراني.
HTTP 400 (طلب غير صالح): دالة المنسق المحددة غير موجودة، أو معرف المثيل المحدد غير صالح، أو محتوى الطلب غير صالح JSON.

فيما يلي مثال على طلب يبدأ دالة RestartVMs منسق ويتضمن حمولة كائن JSON:

POST /runtime/webhooks/durabletask/orchestrators/RestartVMs?code=XXX
Content-Type: application/json
Content-Length: 83

{
    "resourceGroup": "myRG",
    "subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e"
}

حمولة الاستجابة لحالات HTTP 202 هي كائن JSON يحتوي على الحقول التالية:

الميدان	الوصف
`id`	معرف نسخة التوزيع الأوركسترالي.
`statusQueryGetUri`	رابط الحالة لنسخة التوزيع الموسيقي.
`sendEventPostUri`	رابط "raise event" الخاص بمثيل التنسيق.
`terminatePostUri`	عنوان URL "الإنهاء" لمثيل التوزيع الموسيقي.
`purgeHistoryDeleteUri`	رابط "تاريخ التطهير" لحالة التوزيع الموسيقي.
`rewindPostUri`	(معاينة) رابط "إعادة الوراء" لنسخة التوزيع الموسيقي.
`suspendPostUri`	رابط "تعليق" لنسخة التوزيع الموسيقي.
`resumePostUri`	رابط "resum" الخاص بنسخة التوزيع الموسيقي.

نوع البيانات لجميع الحقول هو string.

إليك مثال على حمولة الاستجابة لحالة توزيع التنسيق مع abc123 معرفه (مهيأ لسهولة القراءة):

{
    "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",
    "suspendPostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123/suspend?reason={text}&code=XXX",
    "resumePostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123/resume?reason={text}&code=XXX"
}

استجابة HTTP مصممة لتكون متوافقة مع نمط استطلاع المستهلك. كما يتضمن رؤوس الردود البارزة التالية:

الموقع: عنوان URL لنقطة نهاية الحالة، التي تحتوي على نفس قيمة statusQueryGetUri الحقل.
إعادة المحاولة بعد الاختبار: عدد الثواني التي يجب الانتظار بين عمليات الاقتراع. القيمة الافتراضية هي 10.

لمزيد من المعلومات حول نمط استطلاع HTTP غير المتزامن، راجع وثائق تتبع عمليات HTTP غير المتزامنة .

احصل على حالة النسخة

يحصل على حالة حالة توزيع محدد. استخدم هذا لمراقبة تقدم التنسيق واسترداد النتائج.

الطلب

وقت تشغيل الوظائف 2.x (مستحسن):

GET /runtime/webhooks/durabletask/instances/{instanceId}
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &showHistory=[true|false]
    &showHistoryOutput=[true|false]
    &showInput=[true|false]
    &returnInternalServerErrorOnFailure=[true|false]

وقت تشغيل الوظائف 1.x (قديم):

GET /admin/extensions/DurableTaskExtension/instances/{instanceId}
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &showHistory=[true|false]
    &showHistoryOutput=[true|false]
    &showInput=[true|false]
    &returnInternalServerErrorOnFailure=[true|false]

الميدان	نوع المعلمة	الوصف
`instanceId`	عنوان URL	معرف نسخة التوزيع الأوركسترالي.
`showInput`	سلسلة الاستعلام	معلمة اختيارية. إذا تم تعيينه إلى `false`، فلن يتم تضمين إدخال الدالة في حمولة الاستجابة.
`showHistory`	سلسلة الاستعلام	معلمة اختيارية. إذا تم تعيينها إلى `true`، يتم تضمين محفوظات تنفيذ التزامن في حمولة الاستجابة.
`showHistoryOutput`	سلسلة الاستعلام	معلمة اختيارية. إذا تم تعيينها إلى `true`، يتم تضمين مخرجات الدالة في محفوظات تنفيذ التنسيق.
`createdTimeFrom`	سلسلة الاستعلام	معلمة اختيارية. عند التحديد، يقوم بتصفية قائمة النسخات المرتجعة التي تم إنشاؤها عند أو بعد الطابع الزمني ISO8601 المعطا.
`createdTimeTo`	سلسلة الاستعلام	معلمة اختيارية. عند تحديدها، تقوم بتصفية قائمة المثيلات التي تم إنشاؤها عند أو قبل الطابع الزمني ISO8601 المعطا.
`runtimeStatus`	سلسلة الاستعلام	معلمة اختيارية. عند التحديد، يقوم بتصفية قائمة النسختين المرتجعات بناء على حالة وقت التشغيل الخاصة بها. للاطلاع على قائمة قيم حالة وقت التشغيل الممكنة، راجع مقالة الاستعلام عن مثيلات التشغيل.
`returnInternalServerErrorOnFailure`	سلسلة الاستعلام	معلمة اختيارية. إذا تم تعيينه إلى `true`، فترجع واجهة برمجة التطبيقات هذه استجابة HTTP 500 بدلا من 200 إذا كان المثيل في حالة فشل. هذا المعامل مخصص لسيناريوهات استطلاع الحالة الآلي.

الاستجابة

يمكن إرجاع عدة قيم محتملة لرموز الحالة.

HTTP 200 (OK): الحالة المحددة في حالة مكتملة أو فاشلة.
HTTP 202 (مقبول): الحالة المحددة قيد التنفيذ.
HTTP 400 (طلب سيء): فشل النسخة المحددة أو تم إنهاؤها.
HTTP 404 (غير موجود): المثيل المحدد غير موجود أو لم يبدأ تشغيله.
HTTP 500 (خطأ داخلي في الخادم): يعود فقط عندما يتم تعيين النسخة returnInternalServerErrorOnFailure على وفشل true النسخة المحددة مع استثناء غير معالج.

حمولة الاستجابة لحالتي HTTP 200وHTTP 202 هي كائن JSON يحتوي على الحقول التالية:

الميدان	نوع البيانات	الوصف
`runtimeStatus`	سلسلة نصية	حالة وقت التشغيل للمثيل. تشمل القيم تشغيل، قيد الانتظار، فشل، ملغي، منتهى، مكتمل، معلق.
`input`	JSON	بيانات JSON المستخدمة لتهيئة النسخة. هذا الحقل هو `null` إذا `showInput` كان معامل سلسلة الاستعلام مضبوطا على `false`.
`customStatus`	JSON	بيانات JSON المستخدمة لحالة التوزيع المخصص. هذا الحقل هو `null` إذا لم يكن مجمعا.
`output`	JSON	مخرجات JSON للمشكلة. هذا الحقل هو `null` إذا لم تكن الحالة في حالة مكتملة.
`createdTime`	سلسلة نصية	الوقت الذي تم فيه إنشاء النسخة. يستخدم تدوين ISO 8601 الموسع.
`lastUpdatedTime`	سلسلة نصية	الوقت الذي استمر فيه الحدث آخر مرة. يستخدم تدوين ISO 8601 الموسع.
`historyEvents`	JSON	مصفوفة JSON تحتوي على تاريخ تنفيذ التوزيع الأوركسترالي. هذا الحقل هو `null` ما لم `showHistory` يكن معامل سلسلة الاستعلام مضبوطا على `true`.

إليك مثال على حمولة الاستجابة بما في ذلك تاريخ تنفيذ التنسيق ومخرجات النشاط (مهيأة لسهولة القراءة):

{
  "createdTime": "2018-02-28T05:18:49Z",
  "historyEvents": [
      {
          "EventType": "ExecutionStarted",
          "FunctionName": "E1_HelloSequence",
          "Timestamp": "2018-02-28T05:18:49.3452372Z"
      },
      {
          "EventType": "TaskCompleted",
          "FunctionName": "E1_SayHello",
          "Result": "Hello Tokyo!",
          "ScheduledTime": "2018-02-28T05:18:51.3939873Z",
          "Timestamp": "2018-02-28T05:18:52.2895622Z"
      },
      {
          "EventType": "TaskCompleted",
          "FunctionName": "E1_SayHello",
          "Result": "Hello Seattle!",
          "ScheduledTime": "2018-02-28T05:18:52.8755705Z",
          "Timestamp": "2018-02-28T05:18:53.1765771Z"
      },
      {
          "EventType": "TaskCompleted",
          "FunctionName": "E1_SayHello",
          "Result": "Hello London!",
          "ScheduledTime": "2018-02-28T05:18:53.5170791Z",
          "Timestamp": "2018-02-28T05:18:53.891081Z"
      },
      {
          "EventType": "ExecutionCompleted",
          "OrchestrationStatus": "Completed",
          "Result": [
              "Hello Tokyo!",
              "Hello Seattle!",
              "Hello London!"
          ],
          "Timestamp": "2018-02-28T05:18:54.3660895Z"
      }
  ],
  "input": null,
  "customStatus": { "nextActions": ["A", "B", "C"], "foo": 2 },
  "lastUpdatedTime": "2018-02-28T05:18:54Z",
  "output": [
      "Hello Tokyo!",
      "Hello Seattle!",
      "Hello London!"
  ],
  "runtimeStatus": "Completed"
}

يتضمن رد HTTP 202 أيضا رأس استجابة الموقع الذي يشير إلى نفس عنوان URL للحقل statusQueryGetUri المذكور سابقا.

احصل على حالة جميع الحالات

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

الطلب

وقت تشغيل الوظائف 2.x (مستحسن):

GET /runtime/webhooks/durabletask/instances?
    taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &createdTimeFrom={timestamp}
    &createdTimeTo={timestamp}
    &runtimeStatus={runtimeStatus1,runtimeStatus2,...}
    &instanceIdPrefix={prefix}
    &showInput=[true|false]
    &top={integer}

وقت تشغيل الوظائف 1.x (قديم):

GET /admin/extensions/DurableTaskExtension/instances
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &createdTimeFrom={timestamp}
    &createdTimeTo={timestamp}
    &runtimeStatus={runtimeStatus1,runtimeStatus2,...}
    &instanceIdPrefix={prefix}
    &showInput=[true|false]
    &top={integer}

الميدان	نوع المعلمة	الوصف
`showInput`	سلسلة الاستعلام	معلمة اختيارية. إذا تم تعيينه إلى `false`، فلن يتم تضمين إدخال الدالة في حمولة الاستجابة.
`showHistoryOutput`	سلسلة الاستعلام	معلمة اختيارية. إذا تم تعيينه إلى `true`، يتضمن مخرجات الدالة في محفوظات تنفيذ التنسيق.
`createdTimeFrom`	سلسلة الاستعلام	معلمة اختيارية. عند التحديد، يقوم بتصفية قائمة النسخات المرتجعة التي تم إنشاؤها عند أو بعد الطابع الزمني ISO8601 المعطا.
`createdTimeTo`	سلسلة الاستعلام	معلمة اختيارية. عند تحديدها، تقوم بتصفية قائمة المثيلات التي تم إنشاؤها عند أو قبل الطابع الزمني ISO8601 المعطا.
`runtimeStatus`	سلسلة الاستعلام	معلمة اختيارية. عند التحديد، يقوم بتصفية قائمة النسختين المرتجعات بناء على حالة وقت التشغيل الخاصة بها. للاطلاع على قائمة قيم حالة وقت التشغيل الممكنة، راجع مقالة الاستعلام عن مثيلات التشغيل.
`instanceIdPrefix`	سلسلة الاستعلام	معلمة اختيارية. عند تحديدها، تقوم بتصفية قائمة العينات المرتجعة لتشمل فقط الحالات التي يبدأ معرف مثيلها بسلسلة البادئة المحددة. متوفر بدءا من version 2.7.2 للملحق.
`top`	سلسلة الاستعلام	معلمة اختيارية. عند تحديدها، يحد عدد الحالات التي يعيدها الاستعلام.

الاستجابة

إليك مثال على حمولة الاستجابة بما في ذلك حالة التنسيق (مهيأة لسهولة القراءة):

[
    {
        "instanceId": "7af46ff000564c65aafbfe99d07c32a5",
        "runtimeStatus": "Completed",
        "input": null,
        "customStatus": null,
        "output": [
            "Hello Tokyo!",
            "Hello Seattle!",
            "Hello London!"
        ],
        "createdTime": "2018-06-04T10:46:39Z",
        "lastUpdatedTime": "2018-06-04T10:46:47Z"
    },
    {
        "instanceId": "80eb7dd5c22f4eeba9f42b062794321e",
        "runtimeStatus": "Running",
        "input": null,
        "customStatus": null,
        "output": null,
        "createdTime": "2018-06-04T15:18:28Z",
        "lastUpdatedTime": "2018-06-04T15:18:38Z"
    },
    {
        "instanceId": "9124518926db408ab8dfe84822aba2b1",
        "runtimeStatus": "Completed",
        "input": null,
        "customStatus": null,
        "output": [
            "Hello Tokyo!",
            "Hello Seattle!",
            "Hello London!"
        ],
        "createdTime": "2018-06-04T10:46:54Z",
        "lastUpdatedTime": "2018-06-04T10:47:03Z"
    },
    {
        "instanceId": "d100b90b903c4009ba1a90868331b11b",
        "runtimeStatus": "Pending",
        "input": null,
        "customStatus": null,
        "output": null,
        "createdTime": "2018-06-04T15:18:39Z",
        "lastUpdatedTime": "2018-06-04T15:18:39Z"
    }
]

ملاحظة

يمكن أن تكون هذه العملية مكلفة من حيث تخزين Azure الإدخال/الإخراج إذا كنت تستخدم موفر تخزين Azure وهناك العديد من الصفوف في جدول المثيلات. لمزيد من المعلومات حول جدول المثيلات، راجع وثائق موفر تخزين Azure.

إذا وجدت نتائج أكثر، يتم إرجاع رمز الاستمرار في رأس الرد. اسم الرأس هو x-ms-continuation-token.

تنبيه

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

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

تاريخ النسخة الفردية من التطهير

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

الطلب

وقت تشغيل الوظائف 2.x (مستحسن):

DELETE /runtime/webhooks/durabletask/instances/{instanceId}
    ?taskHub={taskHub}
    &connection={connection}
    &code={systemKey}

وقت تشغيل الوظائف 1.x (قديم):

DELETE /admin/extensions/DurableTaskExtension/instances/{instanceId}
    ?taskHub={taskHub}
    &connection={connection}
    &code={systemKey}

الميدان	نوع المعلمة	الوصف
`instanceId`	عنوان URL	معرف نسخة التوزيع الأوركسترالي.

الاستجابة

يمكن إرجاع قيم رمز حالة HTTP التالية.

HTTP 200 (OK): تمت إزالة محفوظات المثيل بنجاح.
HTTP 404 (غير موجود): النسخة المحددة غير موجودة.

حمولة الاستجابة لحالة HTTP 200 هي كائن JSON مع الحقل التالي:

الميدان	نوع البيانات	الوصف
`instancesDeleted`	عدد صحيح	عدد الحالات المحذوفة. في حالة الحالة الفردية، يجب أن تكون `1`هذه القيمة دائما .

إليك مثال على حمولة الاستجابة (مهيأة لسهولة القراءة):

{
    "instancesDeleted": 1
}

تطهير تاريخ المثيلات المتعددة

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

الطلب

وقت تشغيل الوظائف 2.x (مستحسن):

DELETE /runtime/webhooks/durabletask/instances
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &createdTimeFrom={timestamp}
    &createdTimeTo={timestamp}
    &runtimeStatus={runtimeStatus1,runtimeStatus2,...}

وقت تشغيل الوظائف 1.x (قديم):

DELETE /admin/extensions/DurableTaskExtension/instances
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &createdTimeFrom={timestamp}
    &createdTimeTo={timestamp}
    &runtimeStatus={runtimeStatus1,runtimeStatus2,...}

الميدان	نوع المعلمة	الوصف
`createdTimeFrom`	سلسلة الاستعلام	يقوم بتصفية قائمة الحالات المحطفة التي تم إنشاؤها عند أو بعد الطابع الزمني ISO8601 المعطى.
`createdTimeTo`	سلسلة الاستعلام	معلمة اختيارية. عند التحديد، يقوم بتصفية قائمة الحالات التي تم إنشاؤها عند أو قبل الطابع الزمني ISO8601 المعطى.
`runtimeStatus`	سلسلة الاستعلام	معلمة اختيارية. عند تحديدها، تقوم بتصفية قائمة العينات التي تم حذفها بناء على حالة وقت التشغيل الخاصة بها. للاطلاع على قائمة قيم حالة وقت التشغيل الممكنة، راجع مقالة الاستعلام عن مثيلات التشغيل.

ملاحظة

يمكن أن تكون هذه العملية مكلفة من حيث تخزين Azure الإدخال/الإخراج إذا كنت تستخدم موفر تخزين Azure وهناك العديد من الصفوف في جداول المثيلات أو المحفوظات. لمزيد من المعلومات حول هذه الجداول، راجع المقياس والمقياس في Durable Functions (دالات Azure).

الاستجابة

يمكن إرجاع قيم رمز حالة HTTP التالية.

HTTP 200 (OK): تمت إزالة محفوظات المثيل بنجاح.
HTTP 404 (غير موجود): لم يتم العثور على أي نسخ تطابق تعبير المرشح.

حمولة الاستجابة لحالة HTTP 200 هي كائن JSON مع الحقل التالي:

الميدان	نوع البيانات	الوصف
`instancesDeleted`	عدد صحيح	عدد الحالات المحذوفة.

إليك مثال على حمولة الاستجابة (مهيأة لسهولة القراءة):

{
    "instancesDeleted": 250
}

فعالية الرفع

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

الطلب

وقت تشغيل الوظائف 2.x (مستحسن):

POST /runtime/webhooks/durabletask/instances/{instanceId}/raiseEvent/{eventName}
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}

وقت تشغيل الوظائف 1.x (قديم):

POST /admin/extensions/DurableTaskExtension/instances/{instanceId}/raiseEvent/{eventName}
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}

الميدان	نوع المعلمة	الوصف
`instanceId`	عنوان URL	معرف نسخة التوزيع الأوركسترالي.
`eventName`	عنوان URL	اسم الحدث الذي ينتظره الوضع التنظيمي المستهدف.
`{content}`	طلب المحتوى	حمولة الأحداث بتنسيق JSON.

الاستجابة

يمكن إرجاع عدة قيم محتملة لرموز الحالة.

HTTP 202 (مقبول): تم قبول الحدث المرتفع للمعالجة.
HTTP 400 (طلب غير صالح): لم يكن محتوى الطلب من النوع application/json أو لم يكن JSON صالحا.
HTTP 404 (غير موجود): لم يتم العثور على المثيل المحدد.
HTTP 410 (Gone): اكتمل المثيل المحدد أو فشل ولا يمكنه معالجة أي أحداث مرفوعة.

إليك نموذج طلب يرسل سلسلة "incr" JSON إلى مثيل ينتظر عملية تحمل اسم حدث:

POST /admin/extensions/DurableTaskExtension/instances/bcf6fb5067b046fbb021b52ba7deae5a/raiseEvent/operation?taskHub=DurableFunctionsHub&connection=Storage&code=XXX
Content-Type: application/json
Content-Length: 6

"incr"

لا تحتوي الاستجابات لواجهة برمجة التطبيقات هذه على أي محتوى.

إنهاء الحالة

ينهي نسخة أوركسترا جارية.

الطلب

وقت تشغيل الوظائف 2.x (مستحسن):

POST /runtime/webhooks/durabletask/instances/{instanceId}/terminate
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &reason={text}

وقت تشغيل الوظائف 1.x (قديم):

POST /admin/extensions/DurableTaskExtension/instances/{instanceId}/terminate
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &reason={text}

تتضمن معلمات الطلب لواجهة برمجة التطبيقات هذه المجموعة الافتراضية المذكورة سابقا والمعلمة الفريدة التالية.

الميدان	نوع المعلمة	الوصف
`instanceId`	عنوان URL	معرف نسخة التوزيع الأوركسترالي.
`reason`	سلسلة الاستعلام	اختياري. سبب إنهاء حالة التوزيع الموسيقي.

الاستجابة

يمكن إرجاع عدة قيم محتملة لرموز الحالة.

HTTP 202 (مقبول): تم قبول طلب الإنهاء للمعالجة.
HTTP 404 (غير موجود): لم يتم العثور على المثيل المحدد.
HTTP 410 (اختفى): تم إكمال أو فشل النسخة المحددة.

إليك مثال على طلب ينهي مثيلا قيد التشغيل ويحدد سبب وجود خلل:

POST /admin/extensions/DurableTaskExtension/instances/bcf6fb5067b046fbb021b52ba7deae5a/terminate?reason=buggy&taskHub=DurableFunctionsHub&connection=Storage&code=XXX

لا تحتوي الاستجابات لواجهة برمجة التطبيقات هذه على أي محتوى.

تعليق النسخة

إيقاف مثيل تنسيق قيد التشغيل مؤقتا دون إنهائه. يمكن استئناف المثيل لاحقا باستخدام resume العملية.

الطلب

في الإصدار 2.x من وقت تشغيل الوظائف، يتم تنسيق الطلب كما يلي (تظهر عدة أسطر للتوضيح):

POST /runtime/webhooks/durabletask/instances/{instanceId}/suspend
    ?reason={text}
    &taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}

الميدان	نوع المعلمة	الوصف
`instanceId`	عنوان URL	معرف نسخة التوزيع الأوركسترالي.
`reason`	سلسلة الاستعلام	اختياري. سبب تعليق حالة التوزيع الموسيقي.

الاستجابة

يمكن إرجاع عدة قيم محتملة لرموز الحالة.

HTTP 202 (مقبول): تم قبول طلب التعليق للمعالجة. لا يتم إرجاع أي نص استجابة.
HTTP 404 (غير موجود): لم يتم العثور على المثيل المحدد.
HTTP 410 (ذهب): المثيل المحدد قد اكتمل أو فشل أو أنهى ولا يمكن إيقافه مؤقتا.

التحقق: بعد تلقي HTTP 202، استعلم عن حالة المثيل باستخدام GET /runtime/webhooks/durabletask/instances/{instanceId} للتحقق من أن runtimeStatus قد تغير إلى "Suspended".

مثال السيرة الذاتية

استئناف تنفيذ مثيل تزامن تم تعليقه مسبقا.

الطلب

في الإصدار 2.x من وقت تشغيل الوظائف، يتم تنسيق الطلب كما يلي (تظهر عدة أسطر للتوضيح):

POST /runtime/webhooks/durabletask/instances/{instanceId}/resume
    ?reason={text}
    &taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}

الميدان	نوع المعلمة	الوصف
`instanceId`	عنوان URL	معرف نسخة التوزيع الأوركسترالي.
`reason`	سلسلة الاستعلام	اختياري. سبب استئناف التوزيع الأوركسترالي.

الاستجابة

يمكن إرجاع عدة قيم محتملة لرموز الحالة.

HTTP 202 (مقبول): تم قبول طلب السيرة الذاتية للمعالجة. لا يتم إرجاع أي نص استجابة.
HTTP 404 (غير موجود): لم يتم العثور على المثيل المحدد.
HTTP 410 (ذهب): المثيل المحدد قد اكتمل أو فشل أو أنهى ولا يمكن استئنافه.

التحقق: بعد تلقي HTTP 202، استعلم عن حالة المثيل باستخدام GET /runtime/webhooks/durabletask/instances/{instanceId} للتحقق من أن runtimeStatus قد تغير إلى "Running".

إعادة الحلقة (المعاينة)

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

الطلب

وقت تشغيل الوظائف 2.x (مستحسن):

POST /runtime/webhooks/durabletask/instances/{instanceId}/rewind
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &reason={text}

وقت تشغيل الوظائف 1.x (قديم):

POST /admin/extensions/DurableTaskExtension/instances/{instanceId}/rewind
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &reason={text}

تتضمن معلمات الطلب لواجهة برمجة التطبيقات هذه المجموعة الافتراضية المذكورة سابقا والمعلمة الفريدة التالية.

الميدان	نوع المعلمة	الوصف
`instanceId`	عنوان URL	معرف نسخة التوزيع الأوركسترالي.
`reason`	سلسلة الاستعلام	اختياري. سبب إعادة حالة التوزيع الأوركسترالي.

الاستجابة

يمكن إرجاع عدة قيم محتملة لرموز الحالة.

HTTP 202 (مقبول): تم قبول طلب الرجوع للمعالجة.
HTTP 404 (غير موجود): لم يتم العثور على المثيل المحدد.
HTTP 410 (اختفى): تم إكمال أو إنهاء النسخة المحددة.

إليك مثال على طلب يعيد الرجوع لحالة فاشلة ويحدد سبب الإصلاح:

POST /admin/extensions/DurableTaskExtension/instances/bcf6fb5067b046fbb021b52ba7deae5a/rewind?reason=fixed&taskHub=DurableFunctionsHub&connection=Storage&code=XXX

لا تحتوي الاستجابات لواجهة برمجة التطبيقات هذه على أي محتوى.

كيان الإشارة

يرسل رسالة عملية باتجاه واحد إلى كيان دائم. إذا لم يكن الكيان موجودا، يتم إنشاؤه تلقائيا. تتم معالجة عمليات الكيان بشكل تسلسلي ومستمر بشكل دائم.

ملاحظة

تتوفر الكيانات الدائمة بدءا من Durable Functions 2.0.

الطلب

يتم تنسيق طلب HTTP كما يلي (تظهر عدة أسطر للتوضيح):

POST /runtime/webhooks/durabletask/entities/{entityName}/{entityKey}
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &op={operationName}

الميدان	نوع المعلمة	الوصف
`entityName`	عنوان URL	اسم (نوع) الكيان.
`entityKey`	عنوان URL	المفتاح (معرف فريد) للكيان.
`op`	سلسلة الاستعلام	اختياري. اسم العملية التي يحددها المستخدم ليتم استدعاؤها.
`{content}`	طلب المحتوى	حمولة الأحداث بتنسيق JSON.

إليك نموذج طلب يرسل رسالة "أضافة" معرفة من قبل المستخدم إلى Counter كيان باسم steps. محتوى الرسالة هو القيمة 5. إذا لم يكن الكيان موجودا بالفعل، يقوم هذا الطلب بإنشائه:

POST /runtime/webhooks/durabletask/entities/Counter/steps?op=Add
Content-Type: application/json

5

ملاحظة

بشكل افتراضي مع الكيانات المستندة إلى class في .NET، يؤدي تحديد القيمة opdelete إلى حذف حالة الكيان. إذا كان الكيان يعرف عملية تسمى delete، ومع ذلك، يتم استدعاء هذه العملية المعرفة من قبل المستخدم بدلا من ذلك.

الاستجابة

لهذه العملية عدة استجابات محتملة:

HTTP 202 (مقبول): تم قبول عملية الإشارة للمعالجة غير المتزامنة.
HTTP 400 (طلب غير صالح): لم يكن محتوى الطلب من النوع application/json، أو لم يكن JSON صالحا، أو كان له قيمة غير صالحة entityKey .
HTTP 404 (Not Found): لم يتم العثور على المحدد entityName .

لا يحتوي طلب HTTP الناجح على أي محتوى في الاستجابة. قد يحتوي طلب HTTP الفاشل على معلومات خطأ بتنسيق JSON في محتوى الاستجابة.

الحصول على الكيان

يحصل على حالة الكيان المحدد.

الطلب

يتم تنسيق طلب HTTP كما يلي (تظهر عدة أسطر للتوضيح):

GET /runtime/webhooks/durabletask/entities/{entityName}/{entityKey}
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}

الاستجابة

لهذه العملية استجابتان محتملتان:

HTTP 200 (OK): الكيان المحدد موجود.
HTTP 404 (غير موجود): لم يتم العثور على الكيان المحدد.

يحتوي الرد الناجح على الحالة المتسلسلة عبر JSON للكيان كمحتواه.

مثال

للحصول على حالة كيان موجود Counter يسمى steps:

GET /runtime/webhooks/durabletask/entities/Counter/steps

إذا كان الكيان Counter يحتوي فقط على عدد من الخطوات المحفوظة في حقل currentValue ، فقد يبدو محتوى الاستجابة كما يلي (منسق لسهولة القراءة):

{
    "currentValue": 5
}

سرد الكيانات

يمكنك الاستعلام عن عدة كيانات باسم الكيان أو حسب تاريخ آخر عملية.

الطلب

يتم تنسيق طلب HTTP كما يلي (تظهر عدة أسطر للتوضيح):

GET /runtime/webhooks/durabletask/entities/{entityName}
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &lastOperationTimeFrom={timestamp}
    &lastOperationTimeTo={timestamp}
    &fetchState=[true|false]
    &top={integer}

الميدان	نوع المعلمة	الوصف
`entityName`	عنوان URL	اختياري. عند تحديدها، تقوم بتصفية قائمة الكيانات المرتجعة حسب اسم الكيان الخاص بها (غير حساس للحرف).
`fetchState`	سلسلة الاستعلام	معلمة اختيارية. إذا تم تعيينها إلى `true`، يتم تضمين حالة الكيان في حمولة الاستجابة.
`lastOperationTimeFrom`	سلسلة الاستعلام	معلمة اختيارية. عند تحديدها، تقوم بتصفية قائمة الكيانات التي أعالجت العمليات بعد الطابع الزمني ISO8601 المحدد.
`lastOperationTimeTo`	سلسلة الاستعلام	معلمة اختيارية. عند تحديدها، تقوم بتصفية قائمة الكيانات التي أعالجت العمليات قبل الطابع الزمني ISO8601 المعطى.
`top`	سلسلة الاستعلام	معلمة اختيارية. عند تحديدها، يحد عدد الكيانات التي يعيدها الاستعلام.

الاستجابة

يحتوي استجابة HTTP 200 الناجحة على مصفوفة مسلسلة عبر JSON من الكيانات، واختياريا حالة كل كيان.

بشكل افتراضي، تقوم العملية بإرجاع أول 100 كيان تتطابق مع معايير الاستعلام. يمكن للمتصل تحديد قيمة معلمة سلسلة الاستعلام ل top ل لإعادة عدد مختلف من النتائج. إذا وجدت نتائج أكثر مما يتم إرجاعه، يتم أيضا إرجاع رمز الاستمرار في رأس الرد. اسم الرأس هو x-ms-continuation-token.

مثال - سرد جميع الكيانات

لسرد كافة الكيانات في مركز المهام:

GET /runtime/webhooks/durabletask/entities

قد تبدو استجابة JSON كما يلي (منسقة لسهولة القراءة):

[
    {
        "entityId": { "key": "cats", "name": "counter" },
        "lastOperationTime": "2019-12-18T21:45:44.6326361Z",
    },
    {
        "entityId": { "key": "dogs", "name": "counter" },
        "lastOperationTime": "2019-12-18T21:46:01.9477382Z"
    },
    {
        "entityId": { "key": "mice", "name": "counter" },
        "lastOperationTime": "2019-12-18T21:46:15.4626159Z"
    },
    {
        "entityId": { "key": "radio", "name": "device" },
        "lastOperationTime": "2019-12-18T21:46:18.2616154Z"
    },
]

مثال - تصفية قائمة الكيانات

لسرد أول كيانين counter وجلب حالتهما:

GET /runtime/webhooks/durabletask/entities/counter?top=2&fetchState=true

قد تبدو استجابة JSON كما يلي (منسقة لسهولة القراءة):

[
    {
        "entityId": { "key": "cats", "name": "counter" },
        "lastOperationTime": "2019-12-18T21:45:44.6326361Z",
        "state": { "value": 9 }
    },
    {
        "entityId": { "key": "dogs", "name": "counter" },
        "lastOperationTime": "2019-12-18T21:46:01.9477382Z",
        "state": { "value": 10 }
    }
]

مثال كامل على سير العمل

يوضح هذا المثال دورة حياة التزامن الكامل باستخدام curl الأوامر. يمكنك أيضا استخدام Postman أو Thunder Client أو أي عميل HTTP.

1. بدء تنسيق

بدء تزامن جديد ProcessOrder مع بيانات الإدخال:

curl -X POST "http://localhost:7071/runtime/webhooks/durabletask/orchestrators/ProcessOrder" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "ORD-12345",
    "customerId": "CUST-789",
    "amount": 150.00
  }'

الاستجابة (HTTP 202):

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

حفظ معرف المثيل: abc123def456

2. الاستقصاء عن الحالة

تحقق من تقدم التنسيق:

curl "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123def456?code=XXX"

الاستجابة أثناء التشغيل (HTTP 202):

{
  "runtimeStatus": "Running",
  "input": { "orderId": "ORD-12345", "customerId": "CUST-789", "amount": 150.00 },
  "output": null,
  "createdTime": "2026-01-23T10:30:00Z",
  "lastUpdatedTime": "2026-01-23T10:30:05Z"
}

الاستجابة عند اكتمالها (HTTP 200):

{
  "runtimeStatus": "Completed",
  "input": { "orderId": "ORD-12345", "customerId": "CUST-789", "amount": 150.00 },
  "output": { "status": "shipped", "trackingNumber": "TRK-98765" },
  "createdTime": "2026-01-23T10:30:00Z",
  "lastUpdatedTime": "2026-01-23T10:30:15Z"
}

3. إرسال حدث خارجي (اختياري)

إذا كان التنسيق في انتظار الموافقة، أرسل حدث الموافقة:

curl -X POST "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123def456/raiseEvent/ApprovalReceived?code=XXX" \
  -H "Content-Type: application/json" \
  -d '{ "approved": true, "reviewer": "manager@contoso.com" }'

الاستجابة: HTTP 202 (مقبول)

4. تنظيف المحفوظات (اختياري)

بعد اكتمال التزامن، قم بإزالة تاريخه:

curl -X DELETE "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123def456?code=XXX"

الاستجابة (HTTP 200):

{
  "instancesDeleted": 1
}

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

تعلم كيفية استخدام Application Insights لمراقبة وظائفك المتينة

الملاحظات

هل كانت هذه الصفحة مفيدة؟

Last updated on 2026-06-03

مرجع واجهة برمجة تطبيقات HTTP

عنوان URL الأساسي والمعلمات الشائعة

كيفية الحصول على قيم المعلمات

سير عمل واجهة برمجة التطبيقات الشائعة

ابدأ التوزيع الأوركسترالي

الطلب

الاستجابة

احصل على حالة النسخة

الطلب

الاستجابة

احصل على حالة جميع الحالات

الطلب

الاستجابة

تاريخ النسخة الفردية من التطهير

الطلب

الاستجابة

تطهير تاريخ المثيلات المتعددة

الطلب

الاستجابة

فعالية الرفع

الطلب

الاستجابة

إنهاء الحالة

الطلب

الاستجابة

تعليق النسخة

الطلب

الاستجابة

مثال السيرة الذاتية

الطلب

الاستجابة

إعادة الحلقة (المعاينة)

الطلب

الاستجابة

كيان الإشارة

الطلب

الاستجابة

الحصول على الكيان

الطلب

الاستجابة

مثال

سرد الكيانات

الطلب

الاستجابة

مثال - سرد جميع الكيانات

مثال - تصفية قائمة الكيانات

مثال كامل على سير العمل

1. بدء تنسيق

2. الاستقصاء عن الحالة

3. إرسال حدث خارجي (اختياري)

4. تنظيف المحفوظات (اختياري)

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

الملاحظات

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