كيف تربط أي API خارجي بموقعك — بدون ما ينكشف مفتاحك
تربط أي API خارجي بموقعك على ابني عبر دالة سحابة: تحفظ المفتاح في «الأسرار»، ويكتب ابني دالة على الخادم تنادي المزوّد وترجّع النتيجة لصفحتك. المفتاح ما يمرّ بالمتصفح، ولا يظهر بكود الموقع، ولا يوصل للذكاء الاصطناعي. والوكيل يقدر يبحث عن توثيق المزوّد ويقرأه ويجرّب الطرف فعلياً قبل ما يكتب سطر واحد. هالصفحة تشرح الخطوات الخمس، والحدود الحقيقية للتنفيذ، وكيف تتصرّف لما يرد المزوّد بخطأ.
نُشر في:
ابدأ مجاناًالطريق الذي يسلكه الطلب
الربط الصحيح فيه أربع محطات، والمفتاح يعيش في محطة واحدة منها فقط.
الأرقام التي تحكم أي ربط
هذي حدود التنفيذ الفعلية داخل دالة السحابة. صمّم ربطك على أساسها من البداية بدل ما تصطدم فيها بعدين.
خمس خطوات لربط API بموقعك
اطلب الربط بالمحادثة بلغة عادية
قل لابني وين تبي توصل وليش، مثلاً: «اربط الموقع بـ API شركة الشحن عشان أعرض سعر الشحن قبل تأكيد الطلب». ابني يقدر يبحث بالويب عن توثيق المزوّد ويقرأه، ويجرّب الطرف فعلياً برد حقيقي قبل ما يكتب الكود. هذي الخطوة أهم مما تبدو: أغلب أخطاء الربط سببها افتراض شكل رد مختلف عن الرد الفعلي.
أعطِ المفتاح في البطاقة الآمنة
لما يحتاج ابني مفتاحاً، يطلع لك داخل المحادثة حقل إدخال آمن. القيمة تروح للخادم مباشرة وما تمرّ بالنموذج ولا تنكتب بسجل المحادثة. اسم المفتاح لازم يكون بصيغة SHIPPING_API_KEY — حروف كبيرة وأرقام وشرطة سفلية، حتى 40 حرفاً — والقيمة حتى 2000 حرف. تقدر كمان تضيفه بنفسك من لوحة «الأسرار» بالمحرر، أو تختار مزوّداً من المعرض إذا كان من المزوّدين المشروحين: تويليو، بوت تيليجرام، واتساب أعمال، Calendly، Airtable، Notion، خرائط جوجل، يوتيوب، Mailchimp، سلاك، ديسكورد.
ابني يكتب الدالة على الخادم
الدالة ملف باسم functions/اسمها.js يصدّر async function handler(req) حيث req فيه method وpayload. جوّاها يقرأ المفتاح بـ ebnii.secrets.get وينادي المزوّد بـ ebnii.fetch مع method وheaders وbody. انتبه لتفصيلة عملية: جسم الرد يرجع نصاً خاماً، فالدالة هي اللي تحلّله وتتحقق من رمز الحالة. الأسرار المحمّلة للصندوق هي أسرار هالمشروع فقط، لا غير.
جرّبها من صفحتك
من كود الصفحة تنادي الدالة بسطر واحد: cloud.fn.call مع اسم الدالة والبيانات. الحدود على النداء واضحة: 30 نداء بالدقيقة لك أنت، و60 بالدقيقة لكل زائر حسب عنوانه، و240 بالدقيقة للمشروع كله. لو موقعك يتوقّع ضغطاً أعلى من هذا على طرف واحد، الحل مو رفع الحد — الحل تخزين النتيجة بقاعدة بيانات الموقع وقراءتها من هناك.
تأكد إن المفتاح فعلاً شغّال
لحظة الحفظ، المنصة تسوي نداءً واحداً رخيصاً وآمن التكرار للمزوّد وتسجّل النتيجة. تشوف بلوحة الأسرار «شغّال ✓» إذا قبله المزوّد، أو «الخدمة رفضته» إذا رجع رفضاً صريحاً للصلاحية، أو «محفوظ» إذا كان المزوّد ما عنده طريقة فحص معروفة عندنا. «محفوظ» يعني ما في فحص تلقائي لهالمفتاح — مو يعني إنه فاشل.
شو متوفر داخل الدالة بالضبط
الدوال تشتغل داخل صندوق QuickJS معزول على الخادم — مو بيئة Node.js. هذا معناه إن اللي تحت متوفر، واللي مو مذكور غالباً مو موجود.
| الأداة | تسوي ماذا | الحد العملي |
|---|---|---|
| ebnii.fetch | نداء HTTP خارجي بـ method وheaders وbody | 8 نداءات بالتشغيلة، والجسم يرجع نصاً خاماً |
| ebnii.secrets.get | تقرأ مفتاحك على الخادم | ما يرجع للمتصفح، ويُشطب من السجلات والتقارير |
| ebnii.crypto | hmac وhash وtimingSafeEqual وjwtSign وjwtVerify | توقيع HS256 وRS256، وrandomHex وuuid |
| ebnii.db | list وinsert وupdate وremove بصلاحية صاحب الموقع | list يوقف عند 200 صف وما فيه offset ولا listAll |
| ebnii.email.send | ترسل لأي عنوان بريد | 5 رسائل بالتشغيلة الواحدة |
| ebnii.jobs.enqueue | تؤجل الشغل الطويل لتشغيلة ثانية | 10 مهام بالتشغيلة، 500 باليوم، 200 معلّقة |
| ebnii.format وebnii.csv وebnii.url | تنسيق عملة وتواريخ، وقراءة وكتابة CSV | بديل عن Intl وURL — الاثنان غير موجودين |
| مكتبات npm وrequire وsetTimeout وfs وprocess | غير موجودة أصلاً | الصندوق معزول تماماً عن Node والمتصفح |
متى يكون الربط المباشر هو الحل الصحيح
الربط داخل ابني ممتاز لنمط معيّن من التكاملات، وسيّئ لنمط ثاني. اعرف الفرق قبل ما تبني عليه.
مناسب تماماً
- عملية من نداء أو نداءين: تسعيرة شحن، إرسال رسالة، إنشاء سجل عند مزوّد، فحص رصيد.
- المزوّد يوثّق REST بمفتاح Bearer أو Basic بدون SDK إجباري.
- العملية تخلص بثوانٍ والزائر مستنّي النتيجة قدامه على الشاشة.
- تحتاج توقيعاً أو تجزئة: ebnii.crypto فيه HMAC وJWT وtimingSafeEqual جاهزين بلا مكتبات.
- تبي تخزّن ناتج النداء عندك: ebnii.db يكتب بصلاحية صاحب الموقع مباشرة.
فكّر بطريقة ثانية
- المزوّد ما عنده إلا مكتبة npm ولا يوثّق REST — ما في require داخل الصندوق.
- العملية تحتاج أكثر من 8 نداءات خارجية أو أطول من 10 ثوانٍ — قسّمها على مهام مؤجلة بـ ebnii.jobs.enqueue بدل ما تصطدم بالمهلة.
- تحتاج تحويل ملفات مثل PDF إلى وورد أو ضغط فيديو — هذا غير مدعوم داخل الدوال إطلاقاً.
- الطرف اللي تناديه داخل شبكة خاصة أو على عنوان محلي: النداءات للشبكات الداخلية وعناوين البيانات الوصفية مرفوضة، وكل قفزة بسلسلة التحويلات تُفحص لحالها.
- تبي ترسل بريداً عبر Resend أو SendGrid أو SMTP: مرفوض بالاسم — البريد مُدار من المنصة عبر cloud.email.
- تحتاج تسحب آلاف الصفوف من قاعدة بياناتك داخل الدالة: list يوقف عند 200 صف بلا offset.
التعامل مع الأخطاء بدل ما تنكسر الصفحة
ارجع رسالة عربية واضحة من الدالة، ولا ترمي رد المزوّد كما هو للزائر. رد المزوّد يوصلك نصاً خاماً من ebnii.fetch: تتحقق من رمز الحالة، تقرأ الحقل اللي يهمك، وترجّع للصفحة شيئاً مفهوماً مثل «ما قدرنا نجيب سعر الشحن لهالمدينة الآن، جرّب بعد شوي». رسالة الخطأ اللي تشرح المشكلة بلغة الزائر تقلّل الاتصالات على خدمة العملاء أكثر من أي تحسين آخر بالصفحة.
لو تجاوزت الدالة مهلتها، ترجع «انتهت مهلة التنفيذ». هذا مو عطل عشوائي — هذا إشارة إنك تحاول تسوي شغلاً أكثر من اللازم بتشغيلة وحدة. القسمة الصحيحة إن التشغيلة الأولى تستقبل الطلب وتخزّنه بقاعدة البيانات وترد على الزائر فوراً، وebnii.jobs.enqueue تكمّل الباقي بالخلفية. المهام المؤجلة تُعاد ثلاث محاولات بتباعد متزايد قبل ما تُعتبر فاشلة، وebnii.sleep داخل الدالة أقصاه خمس ثوانٍ فما ينفع تنتظر فيها رداً بطيئاً.
سجّل بلا ما تسرّب. ebnii.log يطبع لك أثناء التطوير، وقيم الأسرار وأشكال بيانات الزوّار تُشطب تلقائياً من السجلات وتقارير الأخطاء. يعني تقدر تطبع الرد الكامل من المزوّد وأنت مرتاح إن المفتاح ما راح يظهر بالسجل. وأخيراً: لو الربط صار عبر ويبهوك داخل من طرف خارجي، تذكّر إن هوية المستخدم داخل الويبهوك دائماً فارغة، والتحقق من صحة الطلب يتم بالتوقيع لا بالهوية.
أسئلة شائعة
اقرأ أيضاً
اربط أول API لك اليوم
افتح محادثة مع ابني، قل له وين تبي توصل، وأعطه المفتاح في البطاقة الآمنة — هو يقرأ التوثيق ويكتب الدالة ويجرّبها على موقعك.
ابدأ مجاناً