HTTP
مضمّن في Macro Deckأرسل طلبات HTTP من زر واحفظ قيمًا من الاستجابة في متغيرات.
صفحة تكامل HTTP والمفتاح مشغّل ولا توجد خيارات إعداد
- GET وPOST وPUT وPATCH وDELETE وغيرها، مع الاستعلام والترويسات
- مصادقة Basic أو bearer token أو مفتاح API في ترويسة
- أجسام JSON والنماذج والنصوص ورفع الملفات
- حفظ الحالة أو الترويسات أو قيم JSON في متغيرات
- متغيرات في قيم معاملات الاستعلام والترويسات
يرسل تكامل HTTP طلبات ويب من Macro Deck. استخدمه لاستدعاء webhook، أو التحكم في جهاز على شبكتك له واجهة ويب برمجية، أو قراءة قيمة من خدمة عبر الإنترنت وعرضها على زر. يأتي مع Macro Deck ويكون مفعّلًا منذ البداية، فلا يوجد ما تتصل به أو تسجّل الدخول إليه.
إجراءان
يبني إرسال طلب HTTP طلبًا كاملًا. تختار الطريقة، وتدخل عنوان URL وتضيف معاملات الاستعلام والترويسات كأزواج من الاسم والقيمة. في نوع الجسم تختار none أو json أو form أو text أو multipart (رفع ملف مع حقول نموذج إضافية). يتيح الحقل المصادقة الخيارات basic (اسم المستخدم وكلمة المرور) وbearer (رمز) وheader (رمز في ترويسة تسمّيها، مثل X-Api-Key). وتحدد الحالة المتوقعة الاستجابات التي تُعدّ نجاحًا، 2xx افتراضيًا. يمكنك أيضًا ضبط المهلة، وإيقاف اتباع إعادات التوجيه، وتحديد أقصى حجم للاستجابة (بايت).
تحفظ الالتقاطات أجزاءً من الاستجابة في متغيرات. يقرن كل سطر اسم متغير بمحدِّد: $status أو $ok أو $duration أو $body أو $truncated أو $headers أو $header:<name> أو مسار JSON مثل data.items[0].name. ويُنشأ المتغير غير الموجود بعد.
الحصول على قيمة JSON هو الصيغة المختصرة لقراءة قيمة واحدة: أدخل عنوان URL ومسار JSON والمتغير في الحفظ في متغير.
أمثلة على الإعدادات
- زر ينشر
{"text": "Stream is live"}إلى webhook دردشة باستخدام إرسال طلب HTTP ونوع الجسمjson. - زر يشغّل مقبسًا ذكيًا على شبكتك عبر واجهة الويب البرمجية المحلية الخاصة به.
- زر يقرأ السعر الحالي من واجهة برمجية عامة باستخدام الحصول على قيمة JSON ويعرضه في تسميته باستخدام
{{ vars.price }}. - تدفق يرسل طلبًا، ويلتقط
$status، ويستخدم إذا / وإلا لتلوين الزر بالأحمر عندما لا يستجيب الخادم بـ200.
يمكن أن تحتوي قيم معاملات الاستعلام والترويسات على متغيرات، مثل {{ vars.channel }}. يُنفَّذ الطلب على الحاسوب الذي يعمل عليه Macro Deck، لذا تصل عناوين مثل http://192.168.1.20 إلى الأجهزة في شبكة ذلك الحاسوب. يفشل الإجراء برسالة واضحة عندما يتعذّر الوصول إلى الخادم، أو تنتهي مهلة الطلب، أو تُرفض شهادة TLS، أو لا تكون الحالة هي التي توقعتها.
ما تحتاج إليه
- Macro Deck 3 على Windows أو macOS أو Linux
- عنوان واجهة الويب البرمجية أو webhook الذي تريد استدعاءه
- مفتاح API أو رمز أو كلمة مرور، إذا كانت الخدمة تحتاج إلى ذلك
خطوات الإعداد
الخطوة 1: تحقق من أن التكامل مفعّل
في Macro Deck، انقر التكاملات في الشريط الجانبي ثم انقر HTTP. يكون المفتاح في أعلى اليسار مشغّلًا افتراضيًا؛ شغّله إذا كان متوقفًا. لا يوجد ما يُعدّ: تعرض علامة التبويب نظرة عامة الرسالة لا توجد خيارات إعداد متاحة لهذا التكامل.
الخطوة 2: أضف إجراء HTTP إلى زر
في صفحة اللوحة، انقر زرًا. يجب أن تكون اللوحة غير مقفلة: إذا ظهر الزر قفل في أعلى اليسار، فهي غير مقفلة. يُفتح المحرر مع تحديد ضغطة قصيرة. انقر + إضافة إجراء، واختر HTTP على يمين نافذة إضافة إجراء، ثم اختر إرسال طلب HTTP، أو الحصول على قيمة JSON إذا كنت تريد قراءة قيمة واحدة فقط. يمكنك أيضًا كتابة الاسم في ابحث في الإجراءات….
الخطوة 3: أدخل الطلب
اختر الطريقة وأدخل عنوان URL. أضف معاملات الاستعلام والترويسات إذا احتاجت إليها الواجهة البرمجية. لطلب يحمل بيانات، اختر نوع الجسم واملأ جسم JSON أو حقول النموذج أو نص الجسم.
الخطوة 4: أضف المصادقة
إذا كانت الخدمة تحتاج إلى تسجيل دخول أو مفتاح، فاختر ذلك في المصادقة:
basicمع اسم المستخدم وكلمة المرور / الرمز، أوbearerمع الرمز في كلمة المرور / الرمز، أوheaderمع اسم الترويسة والمفتاح في كلمة المرور / الرمز. تعرض معظم الخدمات مفاتيح API أو الرموز في إعدادات الحساب أو إعدادات المطوّر.الخطوة 5: احفظ قيمًا من الاستجابة
لاستخدام الاستجابة، أضف أسطرًا في الالتقاطات: اسم متغير ومحدِّدًا مثل
$statusأو مسار JSON مثلdata.temperature. مع الحصول على قيمة JSON، أدخل مسار JSON واختر المتغير في الحفظ في متغير.الخطوة 6: جرّب الزر
انقر تشغيل في المحرر لإرسال الطلب فورًا، أو احفظ واضغط الزر. إذا فشل الإجراء، تخبرك رسالته بالسبب، مثلًا أنه تعذّر الوصول إلى الخادم أو أن الحالة لم تطابق الحالة المتوقعة.
الإجراءات2
ضعها على زر أو شغّلها من تدفق.
- إرسال طلب HTTP
- يرسل طلب HTTP قابلًا للتخصيص ويمكنه التقاط الاستجابة في متغيرات.
- الحصول على قيمة JSON
- يجلب عنوان URL ويكتب قيمة واحدة من استجابة JSON في متغير.
الأسئلة الشائعة
أين تُخزَّن مفاتيح API وكلمات المرور الخاصة بي؟
ما تدخله في كلمة المرور / الرمز يُخزَّن مشفّرًا ولا يتحول إلى نص عادي إلا عند إرسال الطلب. أما القيم التي تكتبها في الترويسات فتُخزَّن دون تشفير وتنتقل داخل ملفات التعريف المصدّرة، لذا ضع المفاتيح والرموز في حقول المصادقة بدلًا من ذلك.
هل يمكنني استدعاء جهاز على شبكتي المحلية؟
نعم. يُرسَل الطلب من الحاسوب الذي يعمل عليه Macro Deck، لذا يعمل أي عنوان يستطيع ذلك الحاسوب الوصول إليه. لجهاز بشهادة موقّعة ذاتيًا يمكنك إيقاف التحقق من شهادة TLS، لكن لا تفعل ذلك إلا للأجهزة على شبكتك الخاصة.
لماذا يفشل الإجراء رغم أن الخادم استجاب؟
لم تطابق الاستجابة الحالة المتوقعة، وهي 2xx افتراضيًا. أدخل رمز الحالة الذي تعيده الواجهة البرمجية فعلًا، أو نطاقًا مثل 200-204، أو قائمة، أو any لقبول كل الحالات. يتوقع الحصول على قيمة JSON دائمًا استجابة 2xx.
ما مسارات JSON التي يمكنني استخدامها؟
استخدم النقاط والفهارس، مثل data.items[0].name أو [0].id، أو $ للمستند كله. في الالتقاطات، تأتي المحدِّدات المحجوزة مثل $status أولًا، لذا يُقرأ الحقل الذي اسمه فعلًا status باستخدام $.status.
هل عليّ إنشاء المتغيرات أولًا؟
لا. عندما يسمّي التقاط أو الحفظ في متغير متغيرًا غير موجود، ينشئه Macro Deck. وإذا كان متغير بهذا الاسم موجودًا بالفعل بنوع مختلف، يفشل الحفظ برسالة.
المزيد في المنزل الذكي والويب
Home Assistant
مضمّن في Macro Deckشغّل الأضواء وأطفئها، وفعّل المشاهد والنصوص البرمجية، واعرض الحالات المباشرة من Home Assistant على لوحتك.
AdGuard Home
مضمّن في Macro Deckشغّل حماية AdGuard Home أو أوقفها أو أوقفها مؤقتًا، واعرض إحصاءاتها على لوحتك.
خلاصات RSS
مضمّن في Macro Deckتابع خلاصات RSS وAtom، واعرض أحدث مقالاتها في الأدوات، واستجب عند وصول مقالات جديدة.
الطقس
مضمّن في Macro Deckاعرض الطقس الحالي والتوقعات لمواقعك على لوحتك، دون مفتاح API.