Thanawat Wongchai

Posted on Apr 27 • Originally published at apidog.com

วิธีใช้ Zuplo API

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

ทดลองใช้ Apidog วันนี้

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

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

สรุป (TL;DR)

ลงทะเบียนที่ portal.zuplo.com หรือสร้างโปรเจกต์ในเครื่องด้วย npm create zuplo
กำหนดเส้นทาง (routes) ใน config/routes.oas.json และส่งต่อไปยัง Origin ของคุณด้วย URL Forward Handler
เพิ่มนโยบายขาเข้า (inbound policies) (การรับรองความถูกต้องด้วย API key, การจำกัดอัตรา, การตรวจสอบ Schema) โดยการแก้ไขไฟล์เส้นทาง หรือคลิกผ่าน Route Designer
เขียนตรรกะที่กำหนดเองเป็นโมดูล TypeScript ใน modules/; รันไทม์จะให้การเข้าถึงคำขอ (request), บริบท (context) และสภาพแวดล้อม (environment) ที่มีประเภท (typed access)
พุชไปยังสาขา Git ที่เชื่อมโยงของคุณเพื่อปรับใช้สภาพแวดล้อมพรีวิว; รวม (merge) เพื่อเผยแพร่ไปยัง Production ทั่วกว่า 300 ตำแหน่ง Edge
ทดสอบทุกเส้นทางด้วย Apidog ก่อนที่จะเลื่อนขั้นไปยัง Production
ราคาเริ่มต้นฟรีที่ 100,000 คำขอต่อเดือน; แผน Builder ราคา $25 ต่อเดือน

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

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

บัญชี Zuplo
API ต้นทาง (Origin API) ที่จะวาง Gateway ไว้ด้านหน้า หากคุณยังไม่มี ให้ใช้ https://echo.zuplo.io ซึ่งจะสะท้อนสิ่งที่คุณส่งไป
Node.js 18 หรือสูงกว่า หากคุณวางแผนที่จะใช้ CLI

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

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

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

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

ลงชื่อเข้าใช้ที่ portal.zuplo.com
คลิก “New Project” และเลือกชื่อ เช่น acme-gateway
เลือก “Empty Project” เพื่อไม่ให้มีการสร้างอะไรขึ้นมาโดยอัตโนมัติ
แท็บ 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 หนึ่งคีย์ขึ้นไป):

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

ตัวอย่างเส้นทางและ schema:

"/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 แบบกำหนดเอง

นโยบายสำเร็จรูปครอบคลุมความต้องการส่วนใหญ่ แต่หากต้องการปรับแต่ง สามารถเขียนนโยบาย TypeScript เอง ตัวอย่างนี้เป็น 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"]
}

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

ขั้นตอนที่ 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

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

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

หน้าต่อหนึ่งเส้นทาง พร้อม Schema, คำอธิบาย และคอนโซลทดลอง
ตัวอย่างโค้ดใน cURL, JavaScript, Python, Go ฯลฯ
การออก API Key ด้วยตนเองสำหรับผู้เข้าชมที่ลงทะเบียน
การควบคุมแบรนด์ในพอร์ทัลภายใต้ Developer Portal > Settings

หาก OpenAPI Spec ของคุณมีคำอธิบายและตัวอย่างที่ดี พอร์ทัลจะสมบูรณ์โดยไม่ต้องทำงานเพิ่มเติม หากต้องการปรับแต่งมากขึ้น ซอร์สโค้ดพอร์ทัลมาเป็น Next.js app ที่ fork ได้จาก Zuplo developer portal repo บน GitHub

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

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

เวิร์กโฟลว์ที่แนะนำ:

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

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

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

ฉันสามารถใช้ 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 ที่หายไป และการจำกัดอัตราที่ตั้งไว้สูงเกินไปโดยไม่ตั้งใจก่อน Production ดาวน์โหลด Apidog และเชื่อมต่อ Gateway ของคุณวันนี้

DEV Community