كيفية استخدام Zuplo API؟

إذا كنت قد قرأت عن Zuplo وترغب في إطلاق شيء حقيقي باستخدامه، فهذا هو المنشور المناسب لك. المنصة سريعة التعلم، لكن الوثائق منتشرة عبر تدفقات البوابة (portal flows) وأوامر CLI ومقالات مركز التعلم. يجمع هذا الدليل الأجزاء معًا في دليل تعليمي واحد: إنشاء مشروع، كشف مسار (route)، إضافة مصادقة بمفتاح API وتحديد المعدل (rate limiting)، كتابة سياسة TypeScript مخصصة، النشر إلى الحافة (edge)، واختبار كل شيء باستخدام Apidog.

زر

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

إذا كنت لا تزال تقرر ما إذا كان Zuplo هو الأداة المناسبة، فابدأ بمنشورنا المصاحب: ما هي بوابة API Zuplo. لكل شيء آخر، تغطي وثائق Zuplo الحالات الخاصة التي يتخطاها هذا الدليل.

ملخص سريع

سجل في portal.zuplo.com أو أنشئ مشروعًا محليًا باستخدام npm create zuplo.
حدد المسارات في config/routes.oas.json وقم بإعادة توجيهها إلى مصدرك باستخدام معالج إعادة توجيه URL (URL Forward Handler).
أضف سياسات واردة (مصادقة مفتاح API، تحديد المعدل، التحقق من المخطط) عن طريق تعديل ملف المسار أو النقر عبر مصمم المسارات (Route Designer).
اكتب منطقًا مخصصًا كوحدات TypeScript في modules/؛ يمنحك وقت التشغيل وصولاً مكتوبًا إلى الطلب والسياق والبيئة.
ادفع إلى فرع Git المرتبط لنشر بيئة معاينة؛ ادمج للنشر إلى الإنتاج عبر أكثر من 300 موقع حافة (edge locations).
اختبر كل مسار باستخدام Apidog قبل الترقية إلى الإنتاج.
تبدأ الأسعار مجانًا بـ 100 ألف طلب شهريًا؛ خطة Builder تبلغ 25 دولارًا شهريًا.

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

تحتاج إلى ثلاثة أشياء قبل البدء:

حساب Zuplo
مصدر API لوضع البوابة أمامه. إذا لم يكن لديك واحد، فاستخدم https://echo.zuplo.io، والذي يعكس ما ترسله إليه.
Node.js 18 أو أعلى إذا كنت تخطط لاستخدام CLI.

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

الخطوة 1: إنشاء مشروع Zuplo الخاص بك

لديك طريقتان للبدء: بوابة الويب أو CLI. تبدأ معظم الفرق في البوابة لأنها أسرع للعرض التوضيحي، ثم تنتقل إلى CLI بمجرد رغبتها في CI/CD.

الخيار أ: البوابة أولاً

سجل الدخول إلى portal.zuplo.com.
انقر على "مشروع جديد" واختر اسمًا مثل acme-gateway.
اختر "مشروع فارغ" حتى لا يتم إنشاء أي شيء تلقائيًا.
تفتح علامة التبويب "الكود" (Code) على شجرة ملفات البداية.

تربط البوابة المشروع بمستودع Git مُدار افتراضيًا. يمكنك ربط مستودع GitHub أو GitLab أو Bitbucket أو Azure DevOps الخاص بك من الإعدادات لاحقًا.

الخيار ب: CLI أولاً

يقوم CLI بإنشاء نفس تخطيط المشروع محليًا حتى تتمكن من التحرير في بيئة التطوير المتكاملة (IDE) واستخدام Git من اليوم الأول.

npm create zuplo@latest -- --name acme-gateway
cd acme-gateway
npm install
npm run dev

يبدأ خادم التطوير على المنفذ 9000 ويطبع رابطًا إلى مصمم المسارات المحلي (Route Designer) على http://localhost:9100. أي تغيير تجريه في المحرر أو في المصمم يتم إعادة تحميله فورًا.

لربط المشروع المحلي بحساب Zuplo الخاص بك بمجرد أن تصبح جاهزًا للنشر:

npx zuplo link

اختر الحساب والبيئة عند الطلب. من هنا، يقوم npx zuplo deploy بشحن فرع Git الحالي.

الخطوة 2: تعريف مسارك الأول

افتح config/routes.oas.json. هذا مستند OpenAPI 3 مع امتدادات Zuplo للمعالجات والسياسات. أضف مسارًا يعيد توجيه GET /v1/products إلى مصدرك:

{
  "openapi": "3.1.0",
  "info": { "title": "Acme Gateway", "version": "1.0.0" },
  "paths": {
    "/v1/products": {
      "get": {
        "summary": "List products",
        "operationId": "list-products",
        "x-zuplo-route": {
          "corsPolicy": "anything-goes",
          "handler": {
            "export": "urlForwardHandler",
            "module": "$import(@zuplo/runtime)",
            "options": {
              "baseUrl": "${env.ORIGIN_URL}"
            }
          },
          "policies": { "inbound": [] }
        },
        "responses": {
          "200": { "description": "Success" }
        }
      }
    }
  }
}

قليلة من التفاصيل تستحق الملاحظة. امتداد x-zuplo-route هو حيث يعيش Zuplo داخل ملف OpenAPI قياسي بخلاف ذلك. يصف handler ما يحدث عندما يتطابق المسار؛ urlForwardHandler هو الوكيل المدمج. يسحب المرجع ${env.ORIGIN_URL} من متغيرات البيئة حتى تتمكن من استهداف نهايات خلفية مختلفة لكل بيئة.

عيّن ORIGIN_URL من الإعدادات > متغيرات البيئة في البوابة، أو عن طريق تعديل config/.env محليًا. استخدم https://echo.zuplo.io إذا لم يكن لديك مصدر حقيقي بعد.

احفظ وسيعيد خادم التطوير المحلي التحميل. قم بالوصول إلى http://localhost:9000/v1/products ويجب أن ترى الطلب المعكوس. ستستجيب البوابات المنشورة من أقرب مركز بيانات حافة بدلاً من ذلك.

الخطوة 3: إضافة مصادقة مفتاح API

تحتاج واجهات برمجة التطبيقات العامة إلى بيانات اعتماد. يوفر Zuplo خدمة مفتاح API مُدارة حتى لا تضطر إلى بناء مخزن مفاتيح بنفسك.

عدّل المسار لإضافة السياسة الواردة:

"policies": {
  "inbound": ["api-key-auth"]
}

ثم أضف تعريف السياسة إلى config/policies.json (ينشئ Zuplo هذا الملف في المرة الأولى التي تضيف فيها سياسة):

{
  "name": "api-key-auth",
  "policyType": "api-key-inbound",
  "handler": {
    "export": "ApiKeyInboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "allowUnauthenticatedRequests": false
    }
  }
}

الآن أنشئ مستهلكًا (الكيان الذي يمتلك واحدًا أو أكثر من مفاتيح API):

انتقل إلى الخدمات (Services) > خدمة مفتاح API (API Key Service) في البوابة.
انقر على "إنشاء مستهلك" (Create Consumer).
عيّن الموضوع (subject) إلى معرف ثابت مثل acme-customer-1.
أضف بريدًا إلكترونيًا لمن يجب أن يدير المفتاح.
انسخ مفتاح API الذي تم إنشاؤه.

اختبر باستخدام curl. بدون الرأس، يجب أن ترى 401:

curl -i https://YOUR-PROJECT.zuplo.app/v1/products
# HTTP/2 401

مع الرأس، يجب أن ترى استجابة 200 الأصلية:

curl -i https://YOUR-PROJECT.zuplo.app/v1/products \
  -H "Authorization: Bearer YOUR_API_KEY"
# HTTP/2 200

إذا كنت تفضل تشغيل هذا من عميل حقيقي، فاستورد مواصفات OpenAPI للبوابة إلى Apidog، وقم بتعيين رأس عام لـ Authorization: Bearer {{api_key}}، وربط api_key بمتغير بيئة. ستحصل على سطح اختبار نظيف لكل مسار في ثوانٍ.

الخطوة 4: تحديد معدل المسار

لا تقم أبدًا بنشر واجهة برمجة تطبيقات عامة بدون تحديد معدل. تمنحك سياسة تحديد المعدل الافتراضية في Zuplo تقييدًا لكل IP، أو لكل مفتاح، أو لكل سمة مخصصة.

أضفها إلى قائمة السياسات الواردة، بعد المصادقة:

"policies": {
  "inbound": ["api-key-auth", "rate-limit-by-key"]
}

عرّفها في config/policies.json:

{
  "name": "rate-limit-by-key",
  "policyType": "rate-limit-inbound",
  "handler": {
    "export": "RateLimitInboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "rateLimitBy": "sub",
      "requestsAllowed": 60,
      "timeWindowMinutes": 1
    }
  }
}

يستخدم rateLimitBy: "sub" المفتاح للموضوع المصادق عليه من سياسة مفتاح API، بحيث يحصل كل عميل على حصته الخاصة البالغة 60 طلبًا في الدقيقة. استبدله بـ "ip" إذا كنت تريد تقييد حركة المرور المجهولة.

الطلب الحادي والستين خلال أي نافذة مدتها ستون ثانية يُرجع 429 مع رؤوس إعادة المحاولة المرفقة. اختبرها عن طريق إطلاق 70 طلبًا في حلقة ومشاهدة رموز الاستجابة تتغير.

for i in {1..70}; do
  curl -s -o /dev/null -w "%{http_code}\n" \
    https://YOUR-PROJECT.zuplo.app/v1/products \
    -H "Authorization: Bearer YOUR_API_KEY"
done | sort | uniq -c

يجب أن ترى 60 سطرًا يقرأ 200 و 10 يقرأ 429.

الخطوة 5: التحقق من حمولات الطلب

إذا كان لديك مسار POST يتلقى نص JSON، فإن سياسة التحقق من الطلب (request validation policy) تلتقط الحمولات ذات التنسيق الخاطئ عند البوابة بدلاً من مصدرك. تستخدم مخطط JSON المضمن في عملية OpenAPI الخاصة بك، لذا تحصل على هذا مجانًا إذا كانت مواصفاتك دقيقة.

أضف مسارًا به نص طلب:

"/v1/products": {
  "post": {
    "summary": "Create product",
    "operationId": "create-product",
    "requestBody": {
      "required": true,
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": ["name", "priceCents"],
            "properties": {
              "name": { "type": "string", "minLength": 1 },
              "priceCents": { "type": "integer", "minimum": 1 },
              "category": { "type": "string", "enum": ["food", "drink"] }
            }
          }
        }
      }
    },
    "x-zuplo-route": {
      "handler": { /* same as above */ },
      "policies": {
        "inbound": [
          "api-key-auth",
          "rate-limit-by-key",
          "validate-request"
        ]
      }
    }
  }
}

أضف السياسة:

{
  "name": "validate-request",
  "policyType": "open-api-request-validation-inbound",
  "handler": {
    "export": "OpenApiRequestValidationInboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "validateBody": "reject"
    }
  }
}

الآن، سيتم رفض طلب POST به حقل مفقود برمز 400 قبل أن يصل إلى مصدرك. اختبره باستخدام Apidog عن طريق حفظ طلب "المسار السعيد" (happy path)، وطلب "حقل مطلوب مفقود"، وطلب "قيمة تعداد خاطئة" كأمثلة منفصلة في نفس مجموعة الطلبات. يمكنك تشغيل الثلاثة بنقرة واحدة.

الخطوة 6: كتابة سياسة TypeScript مخصصة

تغطي السياسات المدمجة معظم ما تحتاجه الفرق. ومع ذلك، فإن جوهر Zuplo يكمن في اللحظة التي تحتاج فيها إلى شيء مخصص. إليك سياسة صادرة (outbound policy) تضيف رأس Cache-Control للعملاء المدفوعين و no-store للعملاء المجانيين.

أنشئ modules/tiered-cache.ts:

import { ZuploRequest, ZuploContext, HttpProblems } from "@zuplo/runtime";

interface PolicyOptions {
  paidPlanHeader: string;
  paidMaxAge: number;
}

export default async function (
  response: Response,
  request: ZuploRequest,
  context: ZuploContext,
  options: PolicyOptions,
): Promise<Response> {
  const plan = request.user?.data?.plan ?? "free";

  if (plan === "free") {
    response.headers.set("Cache-Control", "no-store");
  } else {
    response.headers.set(
      "Cache-Control",
      `public, max-age=${options.paidMaxAge}`,
    );
  }

  context.log.info(`Cache header set for plan=${plan}`);
  return response;
}

قم بربطها في config/policies.json:

{
  "name": "tiered-cache",
  "policyType": "custom-code-outbound",
  "handler": {
    "export": "default",
    "module": "$import(./modules/tiered-cache)",
    "options": {
      "paidPlanHeader": "x-plan",
      "paidMaxAge": 300
    }
  }
}

واستدعها من المسار:

"policies": {
  "inbound": ["api-key-auth", "rate-limit-by-key"],
  "outbound": ["tiered-cache"]
}

السياسة المخصصة هي مجرد دالة. يمكنك اختبارها بوحدة باستخدام Vitest أو Jest عن طريق تمرير Response و ZuploRequest اصطناعيين والتأكيد على الرؤوس، دون الحاجة إلى هياكل تكامل.

الخطوة 7: النشر إلى الحافة

النشر هو عملية دفع Git.

git add .
git commit -m "Add products gateway with auth, rate limit, and tiered cache"
git push origin feature/products-gateway

ينشئ Zuplo بيئة معاينة لكل فرع ويطبع عنوان URL في سجل البناء. تحصل المعاينة على نطاقها الفرعي الخاص بها مثل https://acme-gateway-feature-products-gateway-abc123.zuplo.app، مع تفعيل جميع سياساتك وتشير إلى أي ORIGIN_URL تم تعيينه لتلك البيئة.

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

git checkout main
git merge feature/products-gateway
git push origin main

يؤدي الدمج إلى تشغيل نشر الإنتاج. في غضون ستين ثانية، يكون الإصدار الجديد مباشرًا في أكثر من 300 موقع حافة. كل من الترقية والتراجع هما عمليتا git push؛ لا توجد واجهة مستخدم منفصلة.

الخطوة 8: إنشاء بوابة المطورين

تستضاف البوابة على https://YOUR-PROJECT.developers.zuplo.com ويتم إعادة بنائها مع كل نشر. وتشمل:

صفحة واحدة لكل مسار، مع المخطط والوصف ووحدة تحكم "جربها".
أمثلة على الأكواد في cURL و JavaScript و Python و Go وعدد قليل آخر.
إصدار مفتاح API ذاتي الخدمة لأي زائر يسجل.
عناصر تحكم العلامة التجارية في البوابة ضمن بوابة المطورين (Developer Portal) > الإعدادات (Settings).

إذا كانت مواصفات OpenAPI الخاصة بك تحتوي على أوصاف وأمثلة جيدة، تبدو البوابة مكتملة دون الحاجة إلى مزيد من العمل. إذا كانت مواصفاتك ضعيفة، فهذه هي اللحظة التي تكتشف فيها ذلك.

للتخصيص، يتم شحن مصدر البوابة كتطبيق Next.js منفصل يمكنك تفرعه من مستودع بوابة المطورين Zuplo على GitHub. معظم الفرق تبقى على الإصدار المستضاف.

الخطوة 9: اختبار كل شيء باستخدام Apidog

بمجرد أن تكون بوابتك مباشرة، فإن الانضباط الذي يمنع حوادث الإنتاج هو اختبار كل مسار، وكل سياسة، وكل مسار خطأ. يجعل Apidog هذا سريعًا.

سير العمل الذي يعمل بشكل جيد:

استورد مواصفات OpenAPI للبوابة من https://YOUR-PROJECT.zuplo.app/openapi. يقوم Apidog بتحويل كل عملية إلى طلب يمكنك إطلاقه.
أنشئ بيئات لـ local و preview و production، كل منها بعناصره الخاصة base_url و api_key.
احفظ ما لا يقل عن ثلاثة طلبات لكل مسار: مسار سعيد، فشل مصادقة، وتحديد معدل. قم بتشغيلها كمجموعة قبل كل نشر.
استخدم سيناريوهات الاختبار الآلية في Apidog لربط المكالمات ببعضها البعض (إنشاء منتج، إدراجه، حذفه) والتأكيد على أشكال الاستجابة.
أنشئ عينات أكواد باللغة الأساسية لفريقك والصقها في دفاتر التشغيل الخاصة بك.

إذا كنت تنتقل من Postman، فإن دليل اختبار API بدون Postman يشرح عملية الاستيراد. قم بتنزيل Apidog إذا لم تكن قد فعلت ذلك بالفعل.

أسئلة شائعة حول استخدام Zuplo

كيف يمكنني تبديل مسار بين البيئات دون تغيير المواصفات؟

استخدم متغيرات البيئة. حدد ORIGIN_URL لكل بيئة في إعدادات البوابة أو في config/.env محليًا، وارجع إليه كـ ${env.ORIGIN_URL} داخل خيارات المعالج. يبقى المسار متطابقًا؛ يتغير المتغير فقط.

هل يمكنني تشغيل Zuplo دون اتصال بالإنترنت؟

نعم. يبدأ npm run dev بوابة محلية على المنفذ 9000 مع مصمم المسارات المحلي على المنفذ 9100. تعمل السياسات المخصصة والتحقق وتحديد المعدل جميعها محليًا؛ الشيء الوحيد الذي يتطلب اتصالاً بالإنترنت هو خدمة مفتاح API المُدارة، ويمكنك تشغيل npx zuplo link لاستخدام الخدمة السحابية من مثيلك المحلي.

كيف يمكنني التراجع عن عملية نشر سيئة؟

قم بـ git revert لالتزام الدمج وادفع. يقوم Zuplo بإعادة نشر الحالة السابقة. لا يوجد زر "تراجع" منفصل لأن سجل Git هو مصدر الحقيقة.

ماذا يحدث للطلبات قيد المعالجة أثناء النشر؟

عمليات النشر ذرية على الحافة؛ تنتهي الطلبات قيد المعالجة على الإصدار القديم وتضرب الطلبات الجديدة الإصدار الجديد. لا توجد فترة توقف.

هل يمكنني استخدام Zuplo مع gRPC أو WebSockets؟

نعم. يقوم urlForwardHandler بإعادة توجيه ترقيات WebSocket بشفافية، ويتم دعم gRPC من خلال معالج gRPC. تعد REST و GraphQL من الدرجة الأولى والحالة الأكثر شيوعًا.

كيف يمكنني كشف واجهة برمجة تطبيقات Zuplo الخاصة بي لوكلاء الذكاء الاصطناعي؟

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

كم تكلفة البوابة في الإنتاج؟

تغطي الطبقة المجانية 100 ألف طلب شهريًا. تضيف خطة Builder مليون طلب مقابل 25 دولارًا شهريًا، وتكلف الطلبات الإضافية 100 دولار لكل 100 ألف. تبدأ أسعار Enterprise من 1000 دولار شهريًا بعقد سنوي. يمكن الاطلاع على التفاصيل الكاملة في صفحة تسعير Zuplo.

الخاتمة

لديك الآن بوابة Zuplo عاملة مع مصادقة مفتاح API، وتحديد معدل لكل مفتاح، والتحقق من الطلبات، وسياسة TypeScript صادرة مخصصة، وبوابة للمطورين، وكل ذلك يتم نشره عبر Git إلى الحافة العالمية. يتعامل نفس المشروع مع بيئات المعاينة، ونشر الإصدارات الإنتاجية، ووصول وكلاء الذكاء الاصطناعي عبر MCP.

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

زر