كيفية استدعاء واجهة برمجة تطبيقات خارجية من Workspace Studio

قد يحتاج سير عمل Google Workspace Studio إلى بيانات من خارج Gmail أو Drive أو Chat: مثل حالة الطلب، أو رقم من قاعدة بيانات، أو رد من أداة داخلية. لاسترداد هذه البيانات أو إرسال معلومات إلى خدمة أخرى، يمكنك إضافة الخطوة إرسال إشعار عبر الويبيقوم هذا بإرسال طلب HTTP إلى عنوان واجهة برمجة التطبيقات (API) التي قمت بتحديدها.

لا تحتاج إلى تهيئة استدعاء دالة Gemini لإجراء هذا الطلب. في Workspace Studio، يُنفّذ التدفق خطوة webhook ويتلقى الاستجابة. بعد ذلك، إذا وجدتَها مفيدة، يمكنك تمرير تلك الاستجابة إلى خطوة أخرى لتلخيصها أو استخراج البيانات منها أو عرض النتيجة.

ما تحتاجه قبل الاتصال بواجهة برمجة التطبيقات (API)

الخطوة الأولى هي التحقق من إمكانية استخدام مؤسستك لتقنية Webhooks. توجد هذه الوظيفة في معاينة محدودة وهو معطل افتراضياً. يجب على المسؤول تسجيل الدخول. التطبيقات > مساحة عمل جوجل > استوديو مساحة العمل > إعدادات Webhook وتمكين ذلك للوحدة التنظيمية المعنية.

في بعض الإصدارات، يمكن للمسؤول أيضًا تقييد الاتصالات بواحدة فقط. قائمة النطاقات وعناوين المواقع الإلكترونية المسموح بهاإذا ظهرت الخطوة في Studio ولكنها فشلت في الاتصال بواجهة برمجة التطبيقات (API)، فتحقق من أن عنوان الوجهة مُصرّح به. كذلك، تتطلب الإجراءات التي تتضمن روابط الويب، بشكل افتراضي، من المستخدم مراجعة الخطوة وتأكيدها قبل تنفيذها.

من الخدمة الخارجية، تحتاج إلى معرفة عنوان URL الخاص بها، وطرق HTTP التي تدعمها، وتنسيق البيانات الذي تتوقعه. كذلك، تحقق من آلية المصادقة: فواجهة برمجة التطبيقات العامة للقراءة فقط لها متطلبات مختلفة عن واجهة برمجة التطبيقات الخاصة التي تتطلب رموزًا مميزة أو رؤوسًا خاصة.

كيفية استدعاء واجهة برمجة التطبيقات (API) من Workspace Studio خطوة بخطوة

يدخل studio.workspace.google.com أنشئ سير عمل مع المُشغِّل الذي تحتاجه. على سبيل المثال، يمكنك تشغيله عند وصول بريد إلكتروني يستوفي شروطًا معينة. ثم اتبع الخطوات التالية:

1. يضعط خطوات إضافية ثم حدد إرسال إشعار عبر الويب.
2. ادخل الرابط الكامل من واجهة برمجة التطبيقات، بما في ذلك البادئة https://يجب تثبيت العنوان: هذا الحقل لا يدعم متغيرات التدفق.
3. اختر طريقة HTTP. يحصل يُستخدم للاستعلام عن البيانات؛ بريدلإرسالها أو إنشاء سجل. وهي متاحة أيضًا وضع، ترقيع، وحذف.
4. إذا كانت واجهة برمجة التطبيقات تتطلب نصًا، فاكتبه في حقل المحتوى أو الحمولةتوصي جوجل باستخدام JSON عندما تتوقع الخدمة المستقبلة ذلك.
5. قم بعمل تنفيذ الاختبارتحقق من النتيجة وقم بتفعيل العملية بمجرد التأكد من أنها تعمل.

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

مثال: إرسال إشعار إلى أداة خارجية

تخيل أن فريقك لديه واجهة برمجة تطبيقات (API) تقوم بإنشاء تنبيهات في https://api.ejemplo.com/v1/avisosهذا العنوان هو توضيحيستحتاج إلى استبداله بالذي هو من خدمتك. إذا كانت وثائق الخدمة تشير إلى أنها تقبل طلبات POST وبيانات JSON، فيمكنك تهيئة الخطوة بمحتوى مثل {"tipo":"nuevo_correo","origen":"Workspace Studio"}.

يمكنك أيضًا إدراج متغير التدفق على سبيل المثال، يمكنك تضمين موضوع البريد الإلكتروني الذي أدى إلى إرساله في نص الرسالة. نفّذ ذلك من مُحدِّد المتغيرات في Studio وتحقق من النتيجة: إذا كان النص المُدرج يحتوي على علامات اقتباس أو أحرف خاصة أخرى، فقد يؤدي ذلك إلى تشويه تنسيق JSON. يمكن استخدام المتغيرات في المحتوى، ولكن غير موجود في حقل عنوان URL.

إذا كنت بحاجة إلى استرجاع البيانات، فاختر GET وأدخل عنوان URL ثابتًا يحتوي بالفعل على المعلمات اللازمة. سيتجاهل Workspace Studio أي محتوى كتبته في نص طلب GET.

ماذا تفعل باستجابة واجهة برمجة التطبيقات (API)؟

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

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

إذا كانت واجهة برمجة التطبيقات تتطلب مصادقة أو منطقًا أكثر تعقيدًا

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

عندما لا يكون ذلك كافياً، يتمثل أحد الخيارات في تطوير خطوة مخصصة لبرنامج Workspace Studio عبر إضافة. في تطبيق Google Apps Script، الخدمة UrlFetchApp يُمكّنك هذا من إرسال طلبات إلى واجهات برمجة التطبيقات الخارجية ومعالجة استجابات JSON. يتطلب هذا الحل تطويرًا وتكوينًا صحيحًا للأذونات؛ وهو غير ضروري للطلبات البسيطة التي يمكن للخطوة الأصلية معالجتها بالفعل.

تجنّب لصق المفاتيح الخاصة في الحقول الظاهرة من مسار البيانات أو تضمينها في رابط مشترك. قبل إرسال البيانات من Gmail أو Chat أو Calendar، تحقّق من المعلومات التي ستتلقاها الخدمة الخارجية وما إذا كانت مخوّلة بمعالجتها.

كيفية تحديد الأخطاء في webhook

في حال فشل الاتصال، افتح علامة التبويب نشاط من خلال مسار العملية، يمكنك الاطلاع على الخطأ الكامل والاستجابة المرسلة من الخادم الوجهة. تساعد هذه المعلومات في التمييز بين مشكلة في إعدادات Studio وطلب مرفوض من واجهة برمجة التطبيقات (API).

• الخطوة غير ظاهرة: تحقق مع مسؤول النظام لديك لمعرفة ما إذا كانت روابط الويب مفعلة لوحدتك التنظيمية.
• تم حظر عنوان URL: تحقق من قائمة العناوين المسموح بها، إذا كانت نسختك تستخدم هذا القيد.
• الخطأ 400: تحقق من تنسيق نص الطلب والحقول المطلوبة من قبل واجهة برمجة التطبيقات (API).
• خطأ 401 أو 403: راجع الأذونات وطريقة المصادقة المطلوبة من قبل الخدمة.
• الخطأ 429: تحقق مما إذا كنت قد تجاوزت حد الطلبات لواجهة برمجة التطبيقات المستهدفة.
• الخطأ 500: تحقق من حالة وسجلات الخدمة التي تتلقى الطلب.

ضع في اعتبارك أيضًا القيود العامة لبرنامج Workspace Studio: فهو يدعم حاليًا ما يصل إلى 25 تدفقًا لكل مستخدم y 20 خطوة لكل تدفقبالإضافة إلى ذلك، يوجد حدٌّ إجماليٌّ للتنفيذ يُعاد ضبطه كل 24 ساعة. إذا توقفت عدة عمليات عن العمل، فراجع نشاطها قبل أن تُعزي العطل إلى واجهة برمجة التطبيقات (API).

بالنسبة لمعظم اتصالات HTTP البسيطة، تكون العملية مباشرة: تفعيل رابط الويب، وتحديد عنوان URL ثابت والطريقة الصحيحة، واختبار الطلب، واستخدام الاستجابة في الخطوات اللاحقة. أما إذا تطلب التكامل مصادقة متقدمة أو تحويل البيانات برمجياً، فمن المنطقي إعداد خطوة مخصصة.