إنشاء مهام سير العمل التي يمكنك الاتصال بها أو تشغيلها أو تداخلها باستخدام نقاط نهاية HTTPS في Azure Logic Apps

  • مقالة

ينطبق على: Azure Logic Apps (الاستهلاك + قياسي)

قد تتطلب بعض السيناريوهات إنشاء سير عمل تطبيق منطقي يمكنه تلقي طلبات واردة من خدمات أو مهام سير عمل أخرى، أو سير عمل يمكنك الاتصال به باستخدام عنوان URL. بالنسبة لهذه المهمة، يمكنك عرض نقطة نهاية HTTPS متزامنة أصلية على سير العمل الخاص بك عند استخدام أي من أنواع المشغلات التالية المستندة إلى الطلب:

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

المتطلبات الأساسية

  • حساب واشتراك Azure. إذا لم يكن لديك اشتراك، فيجب التسجيل للحصول على حساب Azure مجاني.

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

  • لاختبار عنوان URL لنقطة النهاية القابلة للاستدعاء التي تقوم بإنشائها، ستحتاج إلى أداة أو تطبيق مثل Postman.

إنشاء نقطة نهاية قابلة للاستدعاء

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

  1. في مدخل Microsoft Azure، افتح مورد تطبيق المنطق القياسي وسير العمل الفارغ في المصمم.

  2. اتبع هذه الخطوات العامة لإضافة مشغل الطلب المسمى عند تلقي طلب HTTP.

  3. اختيارياً، في مربع "Request Body JSON Schema"، يمكنك إدخال مخطط JSON يصف البيانات الأساسية أو البيانات التي تتوقع أن يتلقاها المشغل.

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

    في هذا المثال، أدخل المخطط التالي:

    {
   "type": "object",
   "properties": {
      "address": {
         "type": "object",
         "properties": {
            "streetNumber": {
               "type": "string"
            },
            "streetName": {
               "type": "string"
            },
            "town": {
               "type": "string"
            },
            "postalCode": {
               "type": "string"
            }
         }
      }
   }
}

    Screenshot shows Standard workflow with Request trigger and Request Body JSON Schema parameter with example schema.

    أو يمكنك إنشاء مخطط JSON عن طريق توفير عينة البيانات الأساسية:

    1. في مشغّل Request، حدد "Use sample payload to generate schema".

    2. في المربع "Enter or paste a sample JSON payload"، أدخل عينة البيانات الأساسية، على سبيل المثال:

      {
   "address": {
      "streetNumber": "00000",
      "streetName": "AnyStreet",
      "town": "AnyTown",
      "postalCode": "11111-1111"
  }
}

    3. عندما تكون جاهزًا، حدد تم.

      الآن، يعرض مربع "Request Body JSON Schema" المخطط الذي تم إنشاؤه.

  4. احفظ سير العمل الخاص بك.

    يعرض مربع HTTP POST URL الآن عنوان URL لرد الاتصال الذي تم إنشاؤه الذي يمكن أن تستخدمه الخدمات الأخرى للاتصال بسير عمل تطبيق المنطق وتشغيله. يتضمن عنوان URL هذا معلمات الاستعلام التي تحدد مفتاح توقيع الوصول المشترك (SAS)، والذي يستخدم للمصادقة.

    Screenshot shows Standard workflow, Request trigger, and generated callback URL for endpoint.

  5. لنسخ عنوان URL لرد الاتصال، لديك هذه الخيارات:

    • على يمين مربع HTTP POST URL ، حدد نسخ عنوان URL (أيقونة نسخ الملفات).

    • انسخ عنوان URL لرد الاتصال من صفحة نظرة عامة على سير العمل.

      1. في قائمة سير العمل، حدد Overview.

      2. في صفحة نظرة عامة ، ضمن عنوان URL لسير العمل، حرك المؤشر فوق عنوان URL، وحدد نسخ إلى الحافظة:

        Screenshot shows Standard workflow and Overview page with workflow URL.

  6. لاختبار عنوان URL لرد الاتصال الذي لديك الآن لمشغل الطلب، استخدم أداة أو تطبيقا مثل Postman، وأرسل الطلب باستخدام الطريقة التي يتوقعها مشغل الطلب.

    يستخدم هذا المثال الأسلوب POST:

    POST https://{logic-app-name}.azurewebsites.net:443/api/{workflow-name}/triggers/{trigger-name}/invoke?api-version=2022-05-01&sp=%2Ftriggers%2F{trigger-name}%2Frun&sv=1.0&sig={shared-access-signature}

تحديد أسلوب الطلب المتوقع

بشكل افتراضي، يتوقع مشغّل Request طلب POST. ومع ذلك، يمكنك تحديد أسلوب مختلف يجب أن يستخدمه المتصل، ولكن أسلوب واحد فقط.

  1. في مشغل الطلب، افتح قائمة Advanced parameters ، وحدد Method، الذي يضيف هذه الخاصية إلى المشغل.

  2. من القائمة "Method"، حدد الأسلوب الذي يجب أن يتوقعه المشغّل بدلاً من ذلك. أو يمكنك تحديد أسلوب مخصص.

    على سبيل المثال، حدد أسلوب "GET" بحيث يمكنك اختبار عنوان URL لنقطة النهاية لاحقاً.

تمرير المعلمات من خلال عنوان URL لنقطة النهاية

عندما تريد قبول قيم المعلمات من خلال عنوان URL لنقطة النهاية، لديك هذه الخيارات:

  • قبول القيم من خلال معلمات GET أو معلمات URL.

    يتم تمرير هذه القيم كأزواج اسم-قيمة في عنوان URL لنقطة النهاية. لهذا الخيار، تحتاج إلى استخدام أسلوب GET في مشغّل Request. في إجراء لاحق، يمكنك الحصول على قيم المعلمات كإخراجات مشغّل باستخدام الدالة triggerOutputs() في تعبير.

  • قبول القيم من خلال مسار نسبي للمعلمات في مشغّل Request.

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

قبول القيم من خلال معلمات GET

  1. في مشغل الطلب، افتح المعلمات المتقدمة، وأضف الخاصية Method إلى المشغل، وحدد أسلوب GET .

    لمزيد من المعلومات، راجع تحديد أسلوب الطلب المتوقع.

  2. في المصمم، اتبع هذه الخطوات العامة لإضافة الإجراء حيث تريد استخدام قيمة المعلمة.

    في هذا المثال، حدد الإجراء المسمى Response.

  3. لإنشاء التعبير triggerOutputs() الذي يسترد قيمة المعلمة، اتبع الخطوات التالية:

    1. في إجراء الاستجابة، حدد داخل الخاصية Body بحيث تظهر خيارات المحتوى الديناميكي (أيقونة البرق) ومحرر التعبير (أيقونة الصيغة). حدد أيقونة الصيغة لفتح محرر التعبير.

    2. في مربع التعبير، أدخل التعبير التالي، واستبدل parameter-name باسم المعلمة، وحدد موافق.

      triggerOutputs()['queries']['parameter-name']

      Screenshot shows Standard workflow, Response action, and the triggerOutputs() expression.

      في الخاصية Body، يتم حل التعبير إلى الرمز المميز triggerOutputs().

      Screenshot shows Standard workflow with Response action's resolved triggerOutputs() expression.

      إذا قمت بحفظ سير العمل، وانتقلت بعيدا عن المصمم، والعودة إلى المصمم، يعرض الرمز المميز اسم المعلمة التي حددتها، على سبيل المثال:

      Screenshot shows Standard workflow with Response action's resolved expression for parameter name.

      في طريقة عرض التعليمات البرمجية، تظهر الخاصية Body في تعريف إجراء Response كما يلي:

      "body": "@{triggerOutputs()['queries']['parameter-name']}",

      على سبيل المثال، افترض أنك تريد تمرير قيمة لمعلمة باسم postalCode. تحدد الخاصية Body السلسلة، Postal Code: مع مسافة لاحقة، متبوعة بالتعبير المقابل:

      Screenshot shows Standard workflow with Response action and example triggerOutputs() expression.

اختبار نقطة النهاية القابلة للاستدعاء

  1. من مشغل الطلب، انسخ عنوان URL لسير العمل، والصق عنوان URL في نافذة مستعرض أخرى. في عنوان URL، أضف اسم المعلمة وقيمتها إلى عنوان URL بالتنسيق التالي، واضغط على Enter.

    ...invoke/{parameter-name}/{parameter-value}?api-version=2022-05-01...

    على سبيل المثال:

    https://mystandardlogicapp.azurewebsites.net/api/Stateful-Workflow/triggers/When_a_HTTP_request_is_received/invoke/address/12345?api-version=2022-05-01&sp=%2Ftriggers%2FWhen_a_HTTP_request_is_received%2Frun&sv=1.0&sig={shared-access-signature}

    يقوم المستعرض بإرجاع استجابة بهذا النص: Postal Code: 123456

    Screenshot shows browser with Standard workflow response from request to callback URL.

إشعار

إذا كنت تريد تضمين رمز التجزئة أو الرمز (#) في URI، فاستخدم هذا الإصدار المشفر بدلاً من: %25%23

قبول القيم من خلال مسار نسبي

  1. في مشغل الطلب، افتح قائمة المعلمات المتقدمة، وحدد المسار النسبي، الذي يضيف هذه الخاصية إلى المشغل.

    Screenshot shows Standard workflow, Request trigger, and added property named Relative path.

  2. في خاصية "Relative path"، حدد المسار النسبي للمعلمة في مخطط JSON الذي تريد أن يقبله عنوان URL، على سبيل المثال، /address/{postalCode}.

    Screenshot shows Standard workflow, Request trigger, and Relative path parameter value.

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

    على سبيل المثال، أضف إجراء Response.

  4. في الخاصية Body لإجراء Response، قم بتضمين الرمز المميز الذي يمثل المعلمة التي حددتها في المسار النسبي للمشغّل.

    على سبيل المثال، افترض أنك تريد أن يرجع إجراء Response Postal Code: {postalCode}.

    1. في خاصية Body، أدخل Postal Code: مع مسافة لاحقة. احتفظ بالمؤشر في مربع التحرير حتى تظل قائمة المحتوى الديناميكي مفتوحة.

    2. في قائمة المحتوى الديناميكي، من قسم When a HTTP request is received ، حدد إخراج مشغل Path Parameters postalCode .

      Screenshot shows Standard workflow, Response action, and specified trigger output to include in response body.

      الآن، تتضمن خاصية Body المعلمة المحددة:

      Screenshot shows Standard workflow and example response body with parameter.

  5. احفظ سير العمل الخاص بك.

    في مشغّل Request، يتم تحديث عنوان URL لرد الاتصال ويتضمن الآن المسار النسبي، على سبيل المثال:

    https://mystandardlogicapp.azurewebsites.net/api/Stateful-Workflow/triggers/When_a_HTTP_request_is_received/invoke/address/%7BpostalCode%7D?api-version=2022-05-01&sp=%2Ftriggers%2FWhen_a_HTTP_request_is_received%2Frun&sv=1.0&sig={shared-access-signature}

  6. لاختبار نقطة النهاية القابلة للاستدعاء، انسخ عنوان URL لرد الاتصال المُحدّث من مشغّل Request، والصق عنوان URL في نافذة مستعرض أخرى، واستبدل %7BpostalCode%7D في عنوان URL بـ 123456، واضغط على Enter.

    يقوم المستعرض بإرجاع استجابة بهذا النص: Postal Code: 123456

    Screenshot shows browser with Standard workflow response from request to callback URL.

إشعار

إذا كنت تريد تضمين رمز التجزئة أو الرمز (#) في URI، فاستخدم هذا الإصدار المشفر بدلاً من: %25%23

استدعاء سير العمل من خلال عنوان URL لنقطة النهاية

بعد إنشاء نقطة النهاية، يمكنك تشغيل سير العمل عن طريق إرسال طلب HTTPS إلى عنوان URL الكامل لنقطة النهاية. تحتوي مهام سير عمل Azure Logic Apps على دعم مضمن لنقاط نهاية الوصول المباشر.

الرموز المميزة التي تم إنشاؤها من المخطط

عند توفير مخطط JSON في مشغل الطلب، ينشئ مصمم سير العمل رموزا مميزة للخصائص في هذا المخطط. يمكنك بعد ذلك استخدام هذه الرموز المميزة لتمرير البيانات من خلال سير العمل الخاص بك.

على سبيل المثال، إذا قمت بإضافة المزيد من الخصائص، مثل "suite"، إلى مخطط JSON الخاص بك، تتوفر الرموز المميزة لهذه الخصائص لاستخدامها في الخطوات اللاحقة لسير العمل الخاص بك. إليك مخطط JSON الكامل:

{
   "type": "object",
   "properties": {
      "address": {
         "type": "object",
         "properties": {
            "streetNumber": {
               "type": "string"
            },
            "streetName": {
               "type": "string"
            },
            "suite": {
               "type": "string"
            },
            "town": {
               "type": "string"
            },
            "postalCode": {
               "type": "string"
            }
         }
      }
   }
}

استدعاء مهام سير العمل الأخرى

يمكنك استدعاء مهام سير العمل الأخرى التي يمكنها تلقي الطلبات عن طريق تضمينها داخل سير العمل الحالي. لاستدعاء مهام سير العمل هذه، اتبع الخطوات التالية:

  1. في المصمم، اتبع هذه الخطوات العامة لإضافة إجراء عمليات سير العمل المسمى استدعاء سير عمل في تطبيق سير العمل هذا.

    تعرض قائمة اسم سير العمل مهام سير العمل المؤهلة التي تريد تحديدها.

  2. من القائمة اسم سير العمل، حدد سير العمل الذي تريد الاتصال به، على سبيل المثال:

    Screenshot shows Standard workflow, action named Invoke a workflow in this workflow app, opened Workflow Name list, and available workflows to call.

مرجع المحتوى من طلب وارد

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

على سبيل المثال، إذا كنت تقوم بتمرير محتوى يحتوي على نوع application/xml، يمكنك استخدام التعبير @xpath() لإجراء استخراج XPath، أو استخدام التعبير @json() لتحويل XML إلى JSON. تعرف على المزيد حول العمل مع أنواع المحتويات المدعومة.

للحصول على الإخراج من طلب وارد، يمكنك استخدام التعبير @triggerOutputs. على سبيل المثال، افترض أن لديك إخراجاً مثل هذا المثال:

{
   "headers": {
      "content-type" : "application/json"
   },
   "body": {
      "myProperty" : "property value"
   }
}

للوصول إلى الخاصية body على وجه التحديد، يمكنك استخدام التعبير @triggerBody() كاختصار.

الاستجابة للطلبات

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

لكي يتمكن المتصل الأصلي من الحصول على الاستجابة بنجاح، يجب أن تنتهي جميع الخطوات المطلوبة للاستجابة ضمن حد مهلة الطلب ما لم يتم استدعاء سير العمل الذي تم تشغيله كسير عمل متداخل. إذا لم يتم إرجاع أي استجابة ضمن هذا الحد، فستنتهي مهلة الطلب الوارد ويتلقى الاستجابة 408 Client timeout.

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

إنشاء الاستجابة

في نص الاستجابة، يمكنك تضمين عناوين متعددة وأي نوع من المحتوى. على سبيل المثال، يحدد عنوان الاستجابة التالية أن نوع محتوى الاستجابة هو application/json وأن النص الأساسي يحتوي على قيم للخصائص town و postalCode ، استنادا إلى مخطط JSON الموضح سابقا في هذا الموضوع لمشغل الطلب.

Screenshot shows Response action and response content type.

تتميز الاستجابات بهذه الخصائص:

الخاصية (Display) خاصية (JSON) ‏‏الوصف
رمز الحالة statusCode رمز حالة HTTPS لاستخدامه في الاستجابة للطلب الوارد. يمكن أن يكون هذا الرمز أي رمز حالة صالح يبدأ بـ 2xx، أو 4xx، أو 5xx. ومع ذلك، لا يسمح باستخدام رموز الحالة 3xx.
رؤوس headers عنوان واحد أو أكثر لتضمينه في الاستجابة
نص الرسالة body يمكن أن يكون عنصر النص الأساسي سلسلة أو عنصر JSON أو قد يكون محتوًى ثنائياً مشاراً إليه من خطوة سابقة

لعرض تعريف JSON لإجراء الاستجابة وتعريف JSON الكامل لسير العمل، قم بالتغيير من طريقة عرض المصمم إلى طريقة عرض التعليمات البرمجية.

"Response": {
   "type": "Response",
   "kind": "http",
   "inputs": {
      "body": {
         "postalCode": "@triggerBody()?['address']?['postalCode']",
         "town": "@triggerBody()?['address']?['town']"
      },
      "headers": {
         "content-type": "application/json"
      },
      "statusCode": 200
   },
   "runAfter": {}
}

Q & A

س: ماذا عن أمان عنوان URL للمكالمات الواردة؟

ج: يقوم Azure بإنشاء عناوين URL لرد اتصال تطبيق المنطق بأمان باستخدام توقيع الوصول المشترك (SAS). يمر هذا التوقيع كمعلمة استعلام ويجب التحقق من صحته قبل تشغيل سير العمل. ينشئ Azure التوقيع باستخدام تركيبة فريدة من مفتاح سري لكل تطبيق منطق واسم المشغّل والعملية التي يتم تنفيذها. لذلك ما لم يكن لدى شخص ما حق الوصول إلى مفتاح تطبيق المنطق السري، فلن يتمكن من إنشاء توقيع صالح.

هام

بالنسبة لأنظمة الإنتاج وأعلى مستوى من الأمان، ننصح بشدة بعدم الاتصال بسير العمل مباشرة من المستعرض لهذه الأسباب:

  • يظهر مفتاح الوصول المشترك في عنوان URL.
  • لا يمكنك إدارة نُهج محتوى الأمان بسبب المجالات المشتركة عبر عملاء Azure Logic Apps.

لمزيد من المعلومات حول الأمان والتخويل والتشفير للمكالمات الواردة إلى سير العمل الخاص بك، مثل أمان طبقة النقل (TLS)، المعروف سابقا باسم طبقة مآخذ التوصيل الآمنة (SSL)، أو مصادقة Microsoft Entra ID Open Authentication (Microsoft Entra ID OAuth) أو تعريض سير عمل تطبيق المنطق الخاص بك باستخدام Azure API Management، أو تقييد عناوين IP التي تنشأ المكالمات الواردة، راجع الوصول الآمن والبيانات - الوصول إلى المكالمات الواردة إلى المشغلات المستندة إلى الطلب.

س: هل يمكنني تكوين نقاط نهاية قابلة للاستدعاء بشكل أكبر؟

ج: نعم، تدعم نقاط نهاية HTTPS تكويناً أكثر تقدماً من خلال Azure API Management. توفر لك هذه الخدمة أيضاً القدرة على إدارة جميع واجهات برمجة التطبيقات باستمرار، بما في ذلك تطبيقات المنطق، وإعداد أسماء المجالات المخصصة، واستخدام المزيد من أساليب المصادقة، وغير ذلك، على سبيل المثال:

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