วิธีใช้ Zuplo API

Ashley Innocent

Ashley Innocent

27 April 2026

วิธีใช้ Zuplo API

หากคุณเคยอ่านเกี่ยวกับ Zuplo และต้องการสร้างโปรเจกต์จริงด้วย Zuplo โพสต์นี้เหมาะสำหรับคุณ แพลตฟอร์มนี้เรียนรู้ได้รวดเร็ว แต่เอกสารประกอบจะกระจายอยู่ตามขั้นตอนพอร์ทัล, คำสั่ง CLI และบทความในศูนย์การเรียนรู้ คู่มือนี้จะรวบรวมส่วนต่างๆ เข้าด้วยกันเป็นบทช่วยสอนเดียว: สร้างโปรเจกต์, เปิดเผยเส้นทาง (route), เพิ่มการรับรองความถูกต้องด้วย API Key และการจำกัดอัตรา, เขียนนโยบาย TypeScript แบบกำหนดเอง, ปรับใช้ (deploy) ไปยัง Edge และทดสอบทั้งหมดด้วย Apidog

ปุ่ม

ในตอนท้าย คุณจะได้ API Gateway ที่ทำงานได้อย่างสมบูรณ์อยู่ด้านหน้า Origin ของคุณ พร้อมด้วยการรับรองความถูกต้อง, การจำกัดอัตรา, พอร์ทัลสำหรับนักพัฒนาที่สร้างขึ้นโดยอัตโนมัติ และเวิร์กโฟลว์ Git ที่เป็นมิตรกับ CI การดำเนินการทั้งหมดใช้เวลาประมาณสามสิบนาที

หากคุณยังตัดสินใจไม่ได้ว่า Zuplo เป็นเครื่องมือที่เหมาะสมหรือไม่ ลองเริ่มต้นด้วยโพสต์คู่มือของเรา: Zuplo API Gateway คืออะไร สำหรับทุกสิ่งทุกอย่าง เอกสาร Zuplo จะครอบคลุมกรณีพิเศษที่คู่มือนี้ไม่ได้กล่าวถึง

สรุป (TL;DR)

ข้อกำหนดเบื้องต้น

คุณต้องมีสามสิ่งก่อนเริ่มต้น:

สำหรับการพัฒนาในเครื่อง คุณยังต้องมี Code Editor ด้วย VS Code พร้อมส่วนขยาย TypeScript เป็นทางเลือกที่ง่ายที่สุด และคุณสามารถใช้งานร่วมกับ ส่วนขยาย Apidog VS Code เพื่อส่งคำขอโดยไม่ต้องออกจาก Editor ของคุณ

ขั้นตอนที่ 1: สร้างโปรเจกต์ Zuplo ของคุณ

คุณมีสองวิธีในการเริ่มต้น: เว็บพอร์ทัล หรือ CLI ทีมส่วนใหญ่เริ่มต้นในพอร์ทัลเนื่องจากสาธิตได้เร็วกว่า จากนั้นจึงย้ายไปใช้ CLI เมื่อต้องการ CI/CD

ตัวเลือก A: เริ่มต้นด้วยพอร์ทัล

  1. ลงชื่อเข้าใช้ที่ portal.zuplo.com
  2. คลิก “New Project” และเลือกชื่อ เช่น acme-gateway
  3. เลือก “Empty Project” เพื่อไม่ให้มีการสร้างอะไรขึ้นมาโดยอัตโนมัติ
  4. แท็บ Code จะเปิดไปยังโครงสร้างไฟล์เริ่มต้น

โดยค่าเริ่มต้น พอร์ทัลจะเชื่อมโยงโปรเจกต์กับ Git Repo ที่มีการจัดการ คุณสามารถเชื่อมต่อ GitHub, GitLab, Bitbucket หรือ Azure DevOps Repo ของคุณเองได้ในภายหลังจากการตั้งค่า (Settings)

ตัวเลือก B: เริ่มต้นด้วย CLI

CLI จะสร้างโครงสร้างโปรเจกต์เดียวกันในเครื่องเพื่อให้คุณสามารถแก้ไขใน IDE และใช้ Git ได้ตั้งแต่วันแรก

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

Dev server จะเริ่มต้นที่พอร์ต 9000 และแสดงลิงก์ไปยัง Route Designer ในเครื่องที่ http://localhost:9100 การเปลี่ยนแปลงใดๆ ที่คุณทำใน Editor หรือใน Designer จะโหลดซ้ำทันที (hot-reloads)

หากต้องการเชื่อมโยงโปรเจกต์ในเครื่องเข้ากับบัญชี Zuplo ของคุณเมื่อพร้อมที่จะปรับใช้:

npx zuplo link

เลือกบัญชีและสภาพแวดล้อมเมื่อระบบถาม จากนั้น npx zuplo deploy จะเผยแพร่ Git branch ปัจจุบัน

ขั้นตอนที่ 2: กำหนดเส้นทางแรกของคุณ

เปิด config/routes.oas.json นี่คือเอกสาร OpenAPI 3 ที่มีส่วนขยาย Zuplo สำหรับ Handlers และ Policies เพิ่มเส้นทางที่ส่งต่อ GET /v1/products ไปยัง Origin ของคุณ:

{
  "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} ดึงมาจากตัวแปรสภาพแวดล้อม (environment variables) เพื่อให้คุณสามารถกำหนดเป้าหมายไปยังแบ็กเอนด์ที่แตกต่างกันในแต่ละสภาพแวดล้อมได้

ตั้งค่า ORIGIN_URL จาก Settings > Environment Variables ในพอร์ทัล หรือโดยการแก้ไข config/.env ในเครื่อง ใช้ https://echo.zuplo.io หากคุณยังไม่มี Origin จริง

บันทึกแล้ว Dev server ในเครื่องจะโหลดซ้ำ เข้าถึง http://localhost:9000/v1/products แล้วคุณจะเห็นคำขอที่ถูกสะท้อนกลับมา Gateway ที่ปรับใช้จะตอบสนองจากศูนย์ข้อมูล Edge ที่ใกล้ที่สุดแทน

ขั้นตอนที่ 3: เพิ่มการรับรองความถูกต้องด้วย API Key

API สาธารณะต้องการข้อมูลประจำตัว Zuplo มีบริการ API Key ที่จัดการให้คุณจึงไม่ต้องสร้างที่เก็บคีย์ด้วยตัวเอง

แก้ไขเส้นทางเพื่อเพิ่มนโยบายขาเข้า (inbound policy):

"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
    }
  }
}

ตอนนี้สร้างผู้บริโภค (Consumer) (เอนทิตีที่เป็นเจ้าของ API Key หนึ่งคีย์ขึ้นไป):

  1. ไปที่ Services > API Key Service ในพอร์ทัล
  2. คลิก “Create Consumer”
  3. ตั้งค่า Subject เป็นตัวระบุที่เสถียร เช่น acme-customer-1
  4. เพิ่มอีเมลของผู้ที่ควรจัดการคีย์
  5. คัดลอก API Key ที่สร้างขึ้น

ทดสอบด้วย curl หากไม่มี Header คุณควรเห็น 401:

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

เมื่อมี Header คุณควรเห็นการตอบกลับ 200 เดิม:

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

หากคุณต้องการขับเคลื่อนสิ่งนี้จาก Client จริง ให้นำเข้า OpenAPI Spec ของ Gateway ไปยัง Apidog ตั้งค่า Global Header สำหรับ Authorization: Bearer {{api_key}} และผูก api_key กับตัวแปรสภาพแวดล้อม คุณจะได้พื้นที่ทดสอบที่สะอาดสำหรับทุกเส้นทางภายในไม่กี่วินาที

ขั้นตอนที่ 4: จำกัดอัตรา (Rate Limit) เส้นทาง

อย่าเผยแพร่ Public API โดยไม่มีการจำกัดอัตรา นโยบายจำกัดอัตราเริ่มต้นของ Zuplo จะให้การควบคุมตาม IP, ตาม Key หรือตาม Custom Attribute

เพิ่มลงในรายการ Inbound หลังจากการรับรองความถูกต้อง:

"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" ใช้ Subject ที่ได้รับการรับรองความถูกต้องจากนโยบาย API key เป็นกุญแจในการกำหนด Bucket ดังนั้นลูกค้าแต่ละรายจะได้รับโควต้า 60 ครั้งต่อนาทีของตนเอง แทนที่ด้วย "ip" หากคุณต้องการควบคุมการเข้าชมที่ไม่ระบุตัวตน

คำขอครั้งที่ 61 ภายในหน้าต่างหกสิบวินาทีใดๆ จะคืนค่า 429 พร้อมกับ Retry Headers ที่แนบมา ทดสอบโดยการยิงคำขอ 70 ครั้งใน Loop และดูรหัสตอบกลับที่เปลี่ยนไป

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: ตรวจสอบ Payload ของคำขอ

หากคุณมีเส้นทาง POST ที่รับ JSON body นโยบายการตรวจสอบคำขอ (request validation policy) จะดักจับ Payload ที่มีรูปแบบผิดพลาดที่ Gateway แทนที่จะเป็นที่ Origin ของคุณ มันใช้ JSON Schema ที่ฝังอยู่ใน OpenAPI Operation ของคุณ ดังนั้นคุณจึงได้สิ่งนี้ฟรีหาก Spec ของคุณถูกต้อง

เพิ่มเส้นทางที่มี Request Body:

"/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 ก่อนที่จะไปถึง Origin ของคุณ ทดสอบด้วย Apidog โดยบันทึกคำขอ “happy path”, คำขอ “missing required field” และคำขอ “wrong enum value” เป็นตัวอย่างแยกกันในกลุ่มคำขอเดียวกัน คุณสามารถเรียกใช้ทั้งสามอย่างได้ด้วยการคลิกเพียงครั้งเดียว

ขั้นตอนที่ 6: เขียนนโยบาย TypeScript แบบกำหนดเอง

นโยบายสำเร็จรูปครอบคลุมความต้องการส่วนใหญ่ของทีม แต่จุดเด่นของ Zuplo คือในกรณีที่คุณต้องการอะไรที่กำหนดเอง นี่คือนโยบายขาออก (outbound policy) ที่เพิ่ม Header 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"]
}

นโยบายแบบกำหนดเองเป็นเพียงฟังก์ชันหนึ่ง คุณสามารถทดสอบ Unit Test ได้ด้วย Vitest หรือ Jest โดยส่ง Response และ ZuploRequest สังเคราะห์เข้าไป และตรวจสอบ Header โดยไม่จำเป็นต้องใช้ Integration Harness

ขั้นตอนที่ 7: ปรับใช้ไปยัง Edge

การปรับใช้คือการทำ Git Push

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

Zuplo สร้างสภาพแวดล้อมพรีวิวสำหรับทุก Branch และแสดง URL ในบันทึกการสร้าง Preview จะได้รับ Subdomain ของตัวเอง เช่น https://acme-gateway-feature-products-gateway-abc123.zuplo.app โดยมีนโยบายทั้งหมดของคุณทำงานอยู่และชี้ไปยัง ORIGIN_URL ที่ตั้งค่าไว้สำหรับสภาพแวดล้อมนั้น

ทดสอบ URL พรีวิวด้วย Apidog โดยตั้งค่าเป็นสภาพแวดล้อมใหม่ในโปรเจกต์ของคุณ เรียกใช้ชุดทดสอบทั้งหมดของคุณกับมัน หากทุกอย่างผ่าน ให้รวม (merge) Branch

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

การรวมจะกระตุ้นการปรับใช้ Production ภายในหกสิบวินาทีเวอร์ชันใหม่จะพร้อมใช้งานในกว่า 300 ตำแหน่ง Edge การเลื่อนขั้น (Promote) และการย้อนกลับ (Rollback) ล้วนเป็นการดำเนินการ git push ไม่มี UI แยกต่างหาก

ขั้นตอนที่ 8: สร้างพอร์ทัลสำหรับนักพัฒนา

พอร์ทัลถูกโฮสต์ที่ https://YOUR-PROJECT.developers.zuplo.com และจะถูกสร้างใหม่ทุกครั้งที่มีการปรับใช้ ซึ่งรวมถึง:

หาก OpenAPI Spec ของคุณมีคำอธิบายและตัวอย่างที่ดี พอร์ทัลจะดูสมบูรณ์โดยไม่ต้องทำงานเพิ่มเติม หาก Spec ของคุณยังไม่สมบูรณ์ ตอนนี้คือเวลาที่คุณจะรู้

หากต้องการปรับแต่ง ซอร์สโค้ดของพอร์ทัลจะมาในรูปแบบแอป Next.js แยกต่างหากที่คุณสามารถ Fork ได้จาก Zuplo developer portal repo บน GitHub ทีมส่วนใหญ่ยังคงใช้เวอร์ชันที่โฮสต์อยู่

ขั้นตอนที่ 9: ทดสอบทุกอย่างด้วย Apidog

เมื่อ Gateway ของคุณทำงานแล้ว วินัยที่ช่วยป้องกันเหตุการณ์ใน Production คือการทดสอบทุกเส้นทาง ทุกนโยบาย และทุกเส้นทางข้อผิดพลาด Apidog ช่วยให้สิ่งนี้ทำได้อย่างรวดเร็ว

เวิร์กโฟลว์ที่ทำงานได้ดี:

  1. นำเข้า OpenAPI Spec ของ Gateway จาก https://YOUR-PROJECT.zuplo.app/openapi Apidog จะเปลี่ยนแต่ละ Operation ให้เป็นคำขอที่คุณสามารถส่งได้
  2. สร้างสภาพแวดล้อมสำหรับ local, preview และ production โดยแต่ละสภาพแวดล้อมมี base_url และ api_key ของตัวเอง
  3. บันทึกคำขออย่างน้อยสามรายการต่อเส้นทาง: happy path, auth failure และ rate-limit trigger เรียกใช้เป็นกลุ่มก่อนการปรับใช้ทุกครั้ง
  4. ใช้ Automated Test Scenarios ของ Apidog เพื่อเชื่อมโยงการเรียกเข้าด้วยกัน (สร้างผลิตภัณฑ์, แสดงรายการ, ลบผลิตภัณฑ์) และยืนยันรูปแบบการตอบกลับ
  5. สร้างตัวอย่างโค้ดในภาษาหลักของทีมคุณและวางลงใน Runbooks ของคุณ

หากคุณกำลังย้ายจาก Postman คู่มือการทดสอบ API โดยไม่ต้องใช้ Postman จะแนะนำการนำเข้า ดาวน์โหลด Apidog หากคุณยังไม่ได้ทำ

คำถามที่พบบ่อยเกี่ยวกับการใช้ Zuplo

ฉันจะสลับเส้นทางระหว่างสภาพแวดล้อมโดยไม่ต้องเปลี่ยน Spec ได้อย่างไร?

ใช้ตัวแปรสภาพแวดล้อม กำหนด ORIGIN_URL สำหรับแต่ละสภาพแวดล้อมในการตั้งค่าพอร์ทัล (portal Settings) หรือใน config/.env ในเครื่อง และอ้างอิงเป็น ${env.ORIGIN_URL} ภายในตัวเลือก Handler เส้นทางจะยังคงเหมือนเดิม มีเพียงตัวแปรเท่านั้นที่เปลี่ยนแปลง

ฉันสามารถเรียกใช้ Zuplo แบบออฟไลน์ได้หรือไม่?

ได้ npm run dev จะเริ่มต้น Local Gateway บนพอร์ต 9000 พร้อมกับ Local Route Designer บนพอร์ต 9100 นโยบายแบบกำหนดเอง การตรวจสอบ และการจำกัดอัตรา ล้วนทำงานในเครื่องได้ สิ่งเดียวที่ต้องใช้การเชื่อมต่ออินเทอร์เน็ตคือบริการ API Key แบบจัดการ และคุณสามารถเรียกใช้ npx zuplo link เพื่อใช้บริการ Cloud จากอินสแตนซ์ในเครื่องของคุณ

ฉันจะ Rollback การปรับใช้ที่ไม่ดีได้อย่างไร?

ทำ git revert สำหรับ Merge Commit และ Push Zuplo จะปรับใช้สถานะก่อนหน้าอีกครั้ง ไม่มีปุ่ม “Rollback” แยกต่างหากเนื่องจากประวัติ Git เป็นแหล่งข้อมูลที่ถูกต้องที่สุด

เกิดอะไรขึ้นกับคำขอที่อยู่ระหว่างดำเนินการ (In-flight requests) ระหว่างการปรับใช้?

การปรับใช้เป็นแบบอะตอมมิคที่ Edge; คำขอที่อยู่ระหว่างดำเนินการจะเสร็จสิ้นบนเวอร์ชันเก่า และคำขอใหม่จะเข้าถึงเวอร์ชันใหม่ จะไม่มีช่วงเวลาที่ระบบหยุดทำงาน

ฉันสามารถใช้ Zuplo กับ gRPC หรือ WebSockets ได้หรือไม่?

ได้ urlForwardHandler จะพร็อกซีการอัปเกรด WebSocket อย่างโปร่งใส และ gRPC รองรับผ่าน gRPC Handler REST และ GraphQL เป็นสิ่งที่สำคัญและเป็นกรณีที่พบบ่อยที่สุด

ฉันจะเปิดเผย Zuplo API ของฉันให้ AI Agents ได้อย่างไร?

เพิ่ม MCP Server Handler ไปยังเส้นทาง ชี้ไปที่ OpenAPI Spec ของคุณ และเลือก Operations ที่จะเปิดเผย นโยบายการรับรองความถูกต้องและการจำกัดอัตราเดียวกันนี้ใช้กับคำขอ MCP เอกสาร Zuplo MCP Server ครอบคลุมการตั้งค่า

Gateway มีค่าใช้จ่ายเท่าไรใน Production?

แพลนฟรีครอบคลุม 100,000 คำขอต่อเดือน แพลน Builder เพิ่ม 1 ล้านคำขอในราคา $25 ต่อเดือน และคำขอเพิ่มเติมมีค่าใช้จ่าย $100 ต่อ 100,000 คำขอ ราคา Enterprise เริ่มต้นที่ $1,000 ต่อเดือนภายใต้สัญญาประจำปี ดูรายละเอียดทั้งหมดได้ที่ หน้าการกำหนดราคาของ Zuplo

สรุป

ตอนนี้คุณมี Zuplo Gateway ที่ทำงานได้พร้อมการรับรองความถูกต้องด้วย API Key, การจำกัดอัตราต่อคีย์, การตรวจสอบคำขอ, นโยบายขาออก TypeScript แบบกำหนดเอง และพอร์ทัลสำหรับนักพัฒนา ซึ่งทั้งหมดปรับใช้ผ่าน Git ไปยัง Global Edge โปรเจกต์เดียวกันนี้จัดการสภาพแวดล้อมพรีวิว, การปรับใช้ Production และการเข้าถึง AI Agent ผ่าน MCP

ส่วนที่ทำให้ระบบมีความเสถียรคือ Test Loop ใช้ Apidog กับทุกพรีวิวก่อนที่จะรวม (merge) และคุณจะตรวจพบ Header การรับรองความถูกต้องที่ผิดพลาด, ฟิลด์ Schema ที่หายไป และการจำกัดอัตราที่ตั้งไว้สูงเกินไปโดยไม่ตั้งใจก่อนที่จะเผยแพร่ ดาวน์โหลด Apidog และเชื่อมต่อเข้ากับ Gateway ของคุณได้เลยวันนี้

ปุ่ม

ฝึกการออกแบบ API แบบ Design-first ใน Apidog

ค้นพบวิธีที่ง่ายขึ้นในการสร้างและใช้ API