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

  • مقالة

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

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

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

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

systemKey هو مفتاح تخويل تم تجديده تلقائيًا من قبل مضيف "وظائف Azure". وهو يمنح على وجه التحديد الوصول إلى واجهات برمجة التطبيقات ملحق المهام الدائمة ويمكن إدارته بنفس الطريقة مثل مفاتيح الوصول الأخرى لوظائف Azure. يمكنك إنشاء عناوين URL التي تحتوي على قيم سلسلة الاستعلام الصحيحة taskHub، وconnection، وsystemKey باستخدام واجهات برمجة التطبيقات ربط عميل التنسيق، مثل واجهات برمجة تطبيقات CreateCheckStatusResponse وCreateHttpManagementPayload في .NET وواجهات برمجة تطبيقات createCheckStatusResponse وcreateHttpManagementPayload في JavaScript، إلخ.

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

بدء التنسيق

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

Request

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

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

في الإصدار 2.x من وقت تشغيل الوظائف، يحتوي تنسيق URL على كافة المعلمات نفسها ولكن مع بادئة مختلفة قليلًا:

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

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

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

Response

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

  • HTTP 202 (Accepted): تمت جدولة دالة المنسق المحددة لبدء التشغيل. يحتوي عنوان الاستجابة Location على URL للتحقق من حالة التنسيق.
  • HTTP 400 (Bad request): دالة المنسق المحددة غير موجودة، ومعرف المثيل المحدد غير صالح، أو محتوى طلب JSON غير صالح.

التالي هو طلب مثال يبدأ بوظيفة منسق RestartVMs ويتضمن البيانات الأساسية لعنصر JSON:

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

{
    "resourceGroup": "myRG",
    "subscriptionId": "111deb5d-09df-4604-992e-a968345530a9"
}

البيانات الأساسية للاستجابة لحالات HTTP 202 هي عنصر JSON مع الحقول التالية:

الحقل ‏‏الوصف
id معرف مثيل التنسيق.
statusQueryGetUri حالة URL لمثيل التنسيق.
sendEventPostUri URL «تنفيذ حدث» لمثيل التنسيق.
terminatePostUri URL «الإنهاء» لمثيل التنسيق.
purgeHistoryDeleteUri URL «سجل المسح» لمثيل التنسيق.
rewindPostUri (معاينة) URL «الإرجاع» لمثيل التنسيق.
suspendPostUri عنوان URL «للتوقف مؤقتًا» لمثيل التنسيق.
resumePostUri عنوان URL «للاستئناف» لمثيل التنسيق.

نوع البيانات لكافة الحقول هي 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 مقصودة لتكون متوافقة مع نمط المستهلك للتحقق. كما تتضمن عناوين الاستجابة الملحوظة التالية:

  • Location: عنوان URL لنقطة نهاية الحالة. يحتوي URL هذا على نفس قيمة حقل statusQueryGetUri.
  • Retry-After: عدد الثواني التي يجب الانتظار بين عمليات التحقق. القيمة الافتراضية هي 10.

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

الحصول على حالة المثيل

احصل على حالة مثيل تنسيق محدد.

Request

للحصول على الإصدار 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]

في الإصدار 2.x من وقت تشغيل الوظائف، يحتوي تنسيق URL على كافة المعلمات نفسها ولكن مع بادئة مختلفة قليلًا:

GET /runtime/webhooks/durabletask/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 إذا كان المثيل في حالة فشل. هذه المعلمة مخصصة لسيناريوهات التحقق من للحالة التلقائية.

Response

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

  • HTTP 200 (OK): المثيل المحدد في حالة إكمال أو فشل.
  • HTTP 202 (Accepted): المثيل المحدد قيد التقدم.
  • HTTP 400 (Bad Request): فشل المثيل المحدد أو تم إنهاؤه.
  • HTTP 404 (Not Found): المثيل المحدد غير موجود أو لم يتم بدء تشغيله.
  • HTTP 500 (Internal Server Error): يتم إرجاعه فقط عند تعيين 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 أيضًا عنوان استجابة Location التي تشير إلى نفس URL مثل حقل statusQueryGetUri المذكور سابقًا.

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

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

Request

للحصول على الإصدار 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}

في الإصدار 2.x من وقت تشغيل الوظائف، يحتوي تنسيق URL على كافة المعلمات نفسها ولكن مع بادئة مختلفة قليلًا:

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}

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

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

Response

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

[
    {
        "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 إذا كنت تستخدم default Azure Storage provider وإذا كان هناك الكثير من الصفوف في جدول المثيلات. يمكن العثور على مزيد من التفاصيل حول جدول المثيل في وثائق موفر Azure Storage.

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

تنبيه

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

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

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

حذف المحفوظات والبينات الاصطناعية المرتبطة لمثيل تنسيق محدد.

Request

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

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

في الإصدار 2.x من وقت تشغيل الوظائف، يحتوي تنسيق URL على كافة المعلمات نفسها ولكن مع بادئة مختلفة قليلًا:

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

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

الحقل نوع المعلمة ‏‏الوصف
instanceId URL معرف مثيل التنسيق.

Response

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

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

البيانات الأساسية للاستجابة لحالة HTTP 200 هي عنصر JSON مع الحقل التالي:

الحقل نوع البيانات ‏‏الوصف
instancesDeleted integer عدد المثيلات المحذوفة. بالنسبة لحالة المثيل الواحد، يجب أن تكون هذه القيمة دائمًا 1.

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

{
    "instancesDeleted": 1
}

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

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

Request

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

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

في الإصدار 2.x من وقت تشغيل الوظائف، يحتوي تنسيق URL على كافة المعلمات نفسها ولكن مع بادئة مختلفة قليلًا:

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

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

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

إشعار

يمكن أن تكون هذه العملية مكلفة للغاية من حيث الإدخال/إخراج تخزين Azure إذا كنت تستخدم default Azure Storage provider وإذا كان هناك العديد من الصفوف في المثيلات و/أو جداول المحفوظات. يمكن العثور على مزيد من التفاصيل حول هذه الجداول في وثائق Performance and scale in Durable Functions (Azure Functions).

Response

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

  • HTTP 200 (OK): تم إزالة محفوظات المثيل بنجاح.
  • HTTP 404 (Not Found): لم يتم العثور على مثيلات تطابق تعبير عامل التصفية.

البيانات الأساسية للاستجابة لحالة HTTP 200 هي عنصر JSON مع الحقل التالي:

الحقل نوع البيانات ‏‏الوصف
instancesDeleted integer عدد المثيلات المحذوفة.

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

{
    "instancesDeleted": 250
}

تنفيذ حدث

يرسل رسالة إعلام بالحدث إلى مثيل تنسيق قيد التشغيل.

Request

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

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

في الإصدار 2.x من وقت تشغيل الوظائف، يحتوي تنسيق URL على كافة المعلمات نفسها ولكن مع بادئة مختلفة قليلًا:

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

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

الحقل نوع المعلمة ‏‏الوصف
instanceId URL معرف مثيل التنسيق.
eventName عنوان URL اسم الحدث الذي ينتظره مثيل التنسيق المستهدف.
{content} طلب المحتوى حمولة الحدث منسقة بـ JSON.

Response

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

  • HTTP 202 (Accepted): تم قبول الحدث الذي تم إنشاءه للمعالجة.
  • HTTP 400 (Bad request): لم يكن محتوى الطلب من النوع application/json أو لم يكن JSON صالحًا.
  • HTTP 404 (Not Found): المثيل المحدد لم يتم العثور عليه.
  • HTTP 410 (Gone): لقد اكتمل المثيل المحدد أو فشل ولا يمكنه معالجة أي أحداث تم ناشئة.

هنا مثال طلب يرسل سلسلة JSON "incr" إلى مثيل انتظار حدث يسمى operation:

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

"incr"

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

إنهاء المثيل

إنهاء مثيل تنسيق قيد التشغيل.

Request

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

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

في الإصدار 2.x من وقت تشغيل الوظائف، يحتوي تنسيق URL على كافة المعلمات نفسها ولكن مع بادئة مختلفة قليلًا:

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

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

الحقل نوع المعلمة ‏‏الوصف
instanceId URL معرف مثيل التنسيق.
reason سلسلة الاستعلام اختياري. سبب إنهاء مثيل التنسيق.

Response

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

  • HTTP 202 (Accepted): تم قبول طلب الإنهاء للمعالجة.
  • HTTP 404 (Not Found): المثيل المحدد لم يتم العثور عليه.
  • HTTP 410 (Gone): لقد اكتمل المثيل المحدد أو فشل.

هنا مثال طلب ينهي مثيل قيد التشغيل ويحدد سبب لـ لعربات:

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

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

تعليق المثيل

إيقاف مثيل تنسيق قيد التشغيل مؤقتًا.

Request

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

POST /runtime/webhooks/durabletask/instances/{instanceId}/suspend
    ?reason={text}
    &taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
الحقل نوع المعلمة ‏‏الوصف
instanceId URL معرف مثيل التنسيق.
reason سلسلة الاستعلام اختياري. سبب إيقاف مثيل التنسيق مؤقتًا.

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

  • HTTP 202 (Accepted): تم قبول طلب الإيقاف مؤقتًا للمعالجة.
  • HTTP 404 (Not Found): المثيل المحدد لم يتم العثور عليه.
  • HTTP 410 (Gone): لقد اكتمل المثيل المحدد أو فشل أو تم إنهاؤه.

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

استئناف المثيل

استئناف مثيل تنسيق متوقف مؤقتًا.

Request

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

POST /runtime/webhooks/durabletask/instances/{instanceId}/resume
    ?reason={text}
    &taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
الحقل نوع المعلمة ‏‏الوصف
instanceId URL معرف مثيل التنسيق.
reason سلسلة الاستعلام اختياري. سبب استئناف مثيل التنسيق.

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

  • HTTP 202 (Accepted): تم قبول طلب الاستئناف للمعالجة.
  • HTTP 404 (Not Found): المثيل المحدد لم يتم العثور عليه.
  • HTTP 410 (Gone): لقد اكتمل المثيل المحدد أو فشل أو تم إنهاؤه.

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

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

يستعيد مثيل تنسيق فاشل إلى حالة تشغيل عن طريق إعادة تشغيل العمليات الفاشلة الأخيرة.

Request

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

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

في الإصدار 2.x من وقت تشغيل الوظائف، يحتوي تنسيق URL على كافة المعلمات نفسها ولكن مع بادئة مختلفة قليلًا:

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

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

الحقل نوع المعلمة ‏‏الوصف
instanceId URL معرف مثيل التنسيق.
reason سلسلة الاستعلام اختياري. سبب إرجاع مثيل التنسيق.

Response

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

  • HTTP 202 (Accepted): تم قبول طلب للإرجاع للمعالجة.
  • HTTP 404 (Not Found): المثيل المحدد لم يتم العثور عليه.
  • HTTP 410 (Gone): لقد اكتمل المثيل المحدد أو تم إنهاؤه.

هنا مثال طلب يرجع مثيل فشل ويحدد سبب ثابت:

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

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

كيان الإشارة

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

إشعار

الكيانات الدائمة متاحة بدءًا من الوظائف الدائمة 2.0.

Request

تم تنسيق طلب 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

إشعار

بشكل افتراضي، باستخدام كيانات على أساس الفئة في .NET، لتحدد قيمة op لـ delete ستحذف حالة الكيان. إذا حدد الكيان عملية باسم delete، ومع ذلك، سيتم استدعاء هذه العملية المحددة من قبل المستخدم بدلًا من ذلك.

Response

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

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

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

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

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

Request

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

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

Response

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

  • HTTP 200 (OK): الكيان المحدد موجود.
  • HTTP 404 (Not Found): الكيان المحدد لم يتم العثور عليه.

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

مثال

المثال التالي لطلب HTTP يحصل على حالة كيان Counter موجود مسمى steps:

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

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

{
    "currentValue": 5
}

قائمة الكيانات

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

Request

تم تنسيق طلب 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 سلسلة الاستعلام المعلمة الاختيارية. عند تحديد، تحد من عدد الكيانات التي تم إرجاعها بواسطة الاستعلام.

Response

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

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

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

مثال - عرض كافة الكيانات

يعرض طلب HTTP للمثال التالي كافة الكيانات في مركز المهمة:

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

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

يعرض طلب HTTP المثال التالي فقط أول كيانين من نوع 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 }
    }
]

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

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