الاتصال أو استدعاء نقاط نهاية REST API من مهام سير العمل في Azure Logic Apps

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

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

القيود

تدعم عمليات HTTP + Swagger المضمنة حاليا OpenAPI 2.0 فقط، وليس OpenAPI 3.0.

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

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

• عنوان URL لملف Swagger الذي يصف نقطة نهاية واجهة برمجة تطبيقات REST الهدف التي تريد الاتصال بها

  عادة، يجب أن تفي نقطة نهاية REST بالمعايير التالية للمشغل أو الإجراء للعمل:

  • يجب استضافة ملف Swagger على عنوان URL ل HTTPS يمكن الوصول إليه بشكل عام.

  • يجب أن يحتوي ملف Swagger على خاصية operationID لكل عملية في التعريف. إذا لم يكن الأمر كما هو، فإن الموصل يعرض العملية الأخيرة فقط في ملف Swagger.

  • يجب تمكين مشاركة الموارد عبر المنشأ (CORS) لملف Swagger.

  تستخدم الأمثلة في هذا الدليل Azure الذكاء الاصطناعي Face، والذي يتطلب مفتاح مورد خدمات Azure الذكاء الاصطناعي والمنطقة.

  إشعار

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

• سير عمل Consumption أو Standard logic app من حيث تريد استدعاء نقطة النهاية الهدف. للبدء بمشغل HTTP + Swagger ، قم بإنشاء مورد تطبيق منطقي بسير عمل فارغ. لاستخدام إجراء HTTP + Swagger ، ابدأ سير العمل بأي مشغل تريده. يستخدم هذا المثال مشغل HTTP + Swagger كلعملية أولى.

إضافة مشغل HTTP + Swagger

يرسل هذا المشغل المضمن طلب HTTP إلى عنوان URL لملف Swagger الذي يصف واجهة برمجة تطبيقات REST. ثم يقوم المشغل بإرجاع استجابة تحتوي على محتوى هذا الملف.

قياسي

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

2. على المصمم، اتبع هذه الخطوات العامة لإضافة مشغل HTTP المسمى HTTP + Swagger.

3. في مربع Swagger Endpoint ، أدخل عنوان URL لملف Swagger الذي تريده، وحدد Add Action.

   تأكد من استخدام نقطة النهاية الخاصة بك أو إنشائها. كمثال فقط، تستخدم هذه الخطوات عنوان URL التالي Azure الذكاء الاصطناعي Face API Swagger الموجود في منطقة غرب الولايات المتحدة وقد لا تعمل في المشغل المحدد:

   https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/export?DocumentFormat=Swagger&ApiName=Face%20API%20-%20V1.0

   

4. عندما يعرض المصمم العمليات الموضحة بواسطة ملف Swagger، حدد العملية التي تريد استخدامها.

   يعيد المثال التالي تسمية المشغل إلى Face - Detect بحيث يكون للمشغل اسم وصفي أكثر.

   

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

6. لإضافة معلمات أخرى متوفرة، افتح قائمة المعلمات المتقدمة، وحدد المعلمات التي تريدها.

   لمزيد من المعلومات حول أنواع المصادقة المتوفرة ل HTTP + Swagger، راجع إضافة مصادقة إلى المكالمات الصادرة.

7. تابع إنشاء سير العمل الخاص بك مع الإجراءات التي تريد تشغيلها عند تشغيل المشغل.

8. عند الانتهاء، احفظ سير العمل الخاص بك. في شريط أدوات المصمم، حدد "Save".

استهلاك

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

2. على المصمم، اتبع هذه الخطوات العامة لإضافة مشغل HTTP المسمى HTTP + Swagger.

3. في المربع SWAGGER ENDPOINT URL ، أدخل عنوان URL لملف Swagger الذي تريده، وحدد التالي.

   تأكد من استخدام نقطة النهاية الخاصة بك أو إنشائها. كمثال فقط، تستخدم هذه الخطوات عنوان URL التالي Azure الذكاء الاصطناعي Face API Swagger الموجود في منطقة غرب الولايات المتحدة وقد لا تعمل في المشغل المحدد:

   https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/export?DocumentFormat=Swagger&ApiName=Face%20API%20-%20V1.0

   

4. عندما يعرض المصمم العمليات الموضحة بواسطة ملف Swagger، حدد العملية التي تريد استخدامها.

   

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

   يعيد المثال التالي تسمية المشغل إلى Face - Detect بحيث يكون للمشغل اسم وصفي أكثر.

   

6. لإضافة معلمات أخرى متوفرة، افتح قائمة إضافة معلمات جديدة، وحدد المعلمات التي تريدها.

   لمزيد من المعلومات حول أنواع المصادقة المتوفرة ل HTTP + Swagger، راجع إضافة مصادقة إلى المكالمات الصادرة.

7. تابع إنشاء سير العمل الخاص بك مع الإجراءات التي تريد تشغيلها عند تشغيل المشغل.

8. عند الانتهاء، احفظ سير العمل الخاص بك. في شريط أدوات المصمم، حدد "Save".

إضافة إجراء HTTP + Swagger

يرسل هذا الإجراء المضمن طلب HTTP إلى عنوان URL لملف Swagger الذي يصف واجهة برمجة تطبيقات REST. ثم يقوم الإجراء بإرجاع استجابة تحتوي على محتوى هذا الملف.

قياسي

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

2. على المصمم، اتبع هذه الخطوات العامة لإضافة إجراء HTTP المسمى HTTP + Swagger.

3. في مربع Swagger Endpoint ، أدخل عنوان URL لملف Swagger الذي تريده، وحدد Add Action.

   تأكد من استخدام نقطة النهاية الخاصة بك أو إنشائها. كمثال فقط، تستخدم هذه الخطوات عنوان URL التالي Azure الذكاء الاصطناعي Face API Swagger الموجود في منطقة غرب الولايات المتحدة وقد لا تعمل في المشغل المحدد:

   https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/export?DocumentFormat=Swagger&ApiName=Face%20API%20-%20V1.0

   

4. عندما يعرض المصمم العمليات الموضحة بواسطة ملف Swagger، حدد العملية التي تريد استخدامها.

   يعيد المثال التالي تسمية الإجراء إلى Face - Identify بحيث يكون للإجراء اسم وصفي أكثر.

   

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

6. لإضافة معلمات أخرى متوفرة، افتح قائمة المعلمات المتقدمة، وحدد المعلمات التي تريدها.

   لمزيد من المعلومات حول أنواع المصادقة المتوفرة ل HTTP + Swagger، راجع إضافة مصادقة إلى المكالمات الصادرة.

7. تابع إنشاء سير العمل الخاص بك مع أي إجراءات أخرى تريد تشغيلها.

8. عند الانتهاء، احفظ سير العمل الخاص بك. في شريط أدوات المصمم، حدد "Save".

استهلاك

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

2. على المصمم، اتبع هذه الخطوات العامة لإضافة إجراء HTTP المسمى HTTP + Swagger.

3. في المربع SWAGGER ENDPOINT URL ، أدخل عنوان URL لملف Swagger الذي تريده، وحدد التالي.

   تأكد من استخدام نقطة النهاية الخاصة بك أو إنشائها. كمثال فقط، تستخدم هذه الخطوات عنوان URL التالي Azure الذكاء الاصطناعي Face API Swagger الموجود في منطقة غرب الولايات المتحدة وقد لا تعمل في الإجراء المحدد:

   https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/export?DocumentFormat=Swagger&ApiName=Face%20API%20-%20V1.0

   

4. عندما يعرض المصمم العمليات الموضحة بواسطة ملف Swagger، حدد العملية التي تريد استخدامها.

   

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

   لا يحتوي هذا المثال على معلمات، ولكنه يعيد تسمية الإجراء إلى Face - Identify بحيث يكون للعملية اسم وصفي أكثر.

   

6. لإضافة معلمات أخرى متوفرة، افتح قائمة إضافة معلمات جديدة، وحدد المعلمات التي تريدها.

   لمزيد من المعلومات حول أنواع المصادقة المتوفرة ل HTTP + Swagger، راجع إضافة مصادقة إلى المكالمات الصادرة.

7. تابع إنشاء سير العمل الخاص بك مع أي إجراءات أخرى تريد تشغيلها.

8. عند الانتهاء، احفظ سير العمل الخاص بك. في شريط أدوات المصمم، حدد "Save".

Host Swagger في Azure Storage

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

1. إنشاء حساب تخزين Azure.

2. الآن قم بتمكين CORS للكائن الثنائي كبير الحجم. في قائمة حساب التخزين الخاص بك، حدد CORS. في علامة التبويب خدمة Blob، حدد هذه القيم، ثم حدد حفظ.

   الخاصية	القيمة
   الأصول المسموح بها	*
   الأساليب المسموح بها	GET، ، HEADPUT
   الرؤوس المسموح بها	*
   الرؤوس المكشوفة	*
   الحد الأقصى للعمر (بالثوان)	200

   على الرغم من أن هذا المثال يستخدم مدخل Microsoft Azure، يمكنك استخدام أداة مثل Azure Storage Explorer، أو تكوين هذا الإعداد تلقائيا باستخدام نموذج البرنامج النصي PowerShell هذا.

3. إنشاء حاوية كائن ثنائي كبير الحجم. في جزء نظرة عامة على الحاوية، حدد تغيير مستوى الوصول. من قائمة مستوى الوصول العام، حدد Blob (الوصول للقراءة المجهولة للكائنات الثنائية كبيرة الحجم فقط)، وحدد موافق.

4. قم بتحميل ملف Swagger إلى حاوية الكائن الثنائي كبير الحجم، إما من خلال مدخل Azure أو Azure Storage Explorer.

5. للإشارة إلى الملف في حاوية الكائن الثنائي كبير الحجم، احصل على عنوان URL HTTPS الذي يتبع هذا التنسيق، وهو حساس لحالة الأحرف، من Azure Storage Explorer:

   https://<storage-account-name>.blob.core.windows.net/<blob-container-name>/<complete-swagger-file-name>?<query-parameters>

مرجع تقني للموصل

يوفر هذا القسم المزيد من المعلومات حول المخرجات من مشغل HTTP + Swagger وإجراء.

المخرجات

يقوم استدعاء HTTP + Swagger بإرجاع المعلومات التالية:

اسم الخاصية	كتابة	‏‏الوصف
العناوين	‏‏الكائن	الرؤوس من الطلب
النص الأساسي	‏‏الكائن	الكائن الذي يحتوي على محتوى النص الأساسي من الطلب
رمز الحالة	رقم صحيح	رمز الحالة من الطلب

كود الحالة	‏‏الوصف
200	موافق
202	مقبول
400	طلب غير صالح
401	غير مصرح به
403	محظور
404	غير موجود
500	خطأ خادم داخلي. حدث خطأ غير معروف.

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

• الموصلات المُدارة لـ Azure Logic Apps
• الموصلات المدمجة لـ Azure Logic Apps