สร้างพร็อกซี API จากข้อกําหนด OpenAPI | Apigee Edge

ในบทแนะนำนี้ คุณจะได้เรียนรู้วิธีสร้างพร็อกซี API ของ Edge จากข้อมูลจำเพาะของ OpenAPI โดยใช้ UI การจัดการของ Apigee Edge เมื่อคุณเรียกพร็อกซี API ด้วยไคลเอ็นต์ HTTP เช่น cURL พร็อกซี API จะส่งคำขอไปยังบริการเป้าหมายจำลองของ Apigee

เกี่ยวกับ Open API Initiative

"The Open API Initiative (OAI) มุ่งเน้นที่การสร้าง พัฒนา และส่งเสริมรูปแบบคำอธิบาย API ที่เป็นกลางของผู้ให้บริการโดยอิงตามข้อมูลจำเพาะของ Swagger Specification." ดูข้อมูลเพิ่มเติมเกี่ยวกับ Open API Initiative ได้ที่ https://openapis.org

ข้อมูลจำเพาะของ OpenAPIใช้รูปแบบมาตรฐานเพื่ออธิบาย RESTful API ข้อมูลจำเพาะของ OpenAPI เขียนด้วยรูปแบบ JSON หรือ YAML ก็ได้ ซึ่งเครื่องอ่านได้ แต่ก็ อ่านและทำความเข้าใจได้ง่ายสำหรับมนุษย์ ข้อมูลจำเพาะจะอธิบายองค์ประกอบต่างๆ ของ API เช่น เส้นทางฐาน เส้นทางและคำกริยา ส่วนหัว พารามิเตอร์การค้นหา การดำเนินการ ประเภทเนื้อหา คำอธิบายการตอบกลับ และอื่นๆ นอกจากนี้ ข้อมูลจำเพาะของ OpenAPI ยังใช้กันโดยทั่วไปในการสร้างเอกสารประกอบเกี่ยวกับ API

เกี่ยวกับบริการเป้าหมายจำลองของ Apigee

บริการเป้าหมายจำลองของ Apigee ที่ใช้ในบทแนะนำนี้โฮสต์อยู่ที่ Apigee และแสดงผล ข้อมูลอย่างง่าย โดยไม่จำเป็นต้องใช้คีย์ API หรือโทเค็นเพื่อการเข้าถึง คุณสามารถเข้าถึงบริการนี้ได้ในเว็บ เบราว์เซอร์ ลองใช้โดยคลิกที่ลิงก์ต่อไปนี้

http://mocktarget.apigee.net

บริการเป้าหมายจะแสดงผลคำทักทาย Hello, guest!

หากต้องการดูข้อมูลเกี่ยวกับชุด API ทั้งหมดที่บริการเป้าหมายจำลองรองรับ ให้คลิกที่ ลิงก์ต่อไปนี้

http://mocktarget.apigee.net/help

สิ่งที่คุณต้องมี

บัญชี Apigee Edge หากไม่มีบัญชี ให้ลงชื่อสมัครใช้โดยทำตาม วิธีการที่ การสร้างบัญชี Apigee Edge account
ข้อมูลจำเพาะของ OpenAPI ในบทแนะนำนี้ คุณจะได้ใช้ข้อมูลจำเพเพาะของ OpenAPI mocktarget.yaml ซึ่งอธิบายบริการเป้าหมายจำลองของ Apigee http://mocktarget.apigee.net ดูข้อมูลเพิ่มเติมได้ที่ https://github.com/apigee/api-platform-samples/tree/master/default-proxies/helloworld/openapi.
cURL ที่ติดตั้งในเครื่องเพื่อเรียก API จากบรรทัดคำสั่ง หรือเว็บเบราว์เซอร์

สร้างพร็อกซี API

Edge

วิธีสร้างพร็อกซี API จากข้อมูลจำเพาะของ OpenAPI โดยใช้ UI ของ Edge

ลงชื่อเข้าใช้ https://apigee.com/edge
คลิกพร็อกซี API ในหน้าต่างหลัก
หรือจะเลือกพัฒนา > พร็อกซี API ในแถบการนำทางด้านซ้ายก็ได้
คลิก + พร็อกซี
ในวิซาร์ดสร้างพร็อกซี ให้คลิกใช้ข้อมูลจำเพาะของ OpenAPI สำหรับเทมเพลตพร็อกซีแบบย้อนกลับ (พบมากที่สุด)
คลิกนำเข้าจาก URL แล้วป้อนข้อมูลต่อไปนี้
- URL ของข้อมูลจำเพาะของ OpenAPI: เส้นทางไปยังเนื้อหาดิบบน GitHub สำหรับข้อมูลจำเพาะของ OpenAPI ในช่อง URL
```
https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget3.0.yaml
```
- ชื่อข้อมูลจำเพาะ: ชื่อสำหรับข้อมูลจำเพาะของ OpenAPI เช่น เป้าหมายจำลอง
  ชื่อนี้ใช้เพื่อจัดเก็บข้อมูลจำเพาะของ OpenAPI ในที่เก็บข้อมูลจำเพาะ ดูหัวข้อจัดการข้อมูลจำเพาะ

คลิกนำเข้า

หน้า "รายละเอียด" ในวิซาร์ดสร้างพร็อกซีจะปรากฏขึ้น ระบบจะป้อนค่าในช่องล่วงหน้า โดยใช้ค่าที่กำหนดไว้ในข้อมูลจำเพาะของ OpenAPI ดังที่แสดงในรูปต่อไปนี้

ตารางต่อไปนี้อธิบายค่าเริ่มต้นที่ระบบป้อนไว้ล่วงหน้าโดยใช้ พร็อพเพอร์ตี้ในข้อมูลจำเพาะของ OpenAPI ส่วนหนึ่งของข้อมูลจำเพาะของ OpenAPI ที่แสดงพร็อพเพอร์ตี้ที่ใช้จะแสดงอยู่หลังตาราง

ช่อง	คำอธิบาย	ค่าเริ่มต้น
ชื่อ	ชื่อของพร็อกซี API เช่น `Mock-Target-API`	พร็อพเพอร์ตี้ `title` จากข้อมูลจำเพาะของ OpenAPI โดยแทนที่ช่องว่างด้วยขีดกลาง
เส้นทางฐาน	คอมโพเนนต์เส้นทางที่ระบุพร็อกซี API นี้อย่างไม่ซ้ำกันภายในองค์กร URL ที่แสดงต่อสาธารณะของพร็อกซี API นี้ประกอบด้วยชื่อองค์กร สภาพแวดล้อมที่พร็อกซี API นี้ใช้งาน และเส้นทางฐานนี้ เช่น ตัวอย่าง: `http://myorg-test.apigee.net/mock-target-api`	เนื้อหาในช่องชื่อ ที่แปลงเป็นตัวพิมพ์เล็กทั้งหมด
คำอธิบาย	คำอธิบายของพร็อกซี API	พร็อพเพอร์ตี้ `description` จากข้อมูลจำเพาะของ OpenAPI
เป้าหมาย (API ที่มีอยู่)	URL เป้าหมายที่เรียกใช้ในนามของพร็อกซี API นี้ คุณสามารถใช้ URL ใดก็ได้ที่เข้าถึงได้ผ่าน อินเทอร์เน็ตแบบเปิด เช่น `http://mocktarget.apigee.net`	พร็อพเพอร์ตี้ `servers` จากข้อมูลจำเพาะของ OpenAPI

ส่วนต่อไปนี้เป็นส่วนหนึ่งของข้อมูลจำเพาะของ OpenAPI ที่แสดง พร็อพเพอร์ตี้ที่ใช้ในการป้อนค่าในช่องล่วงหน้า

openapi: 3.0.0
info:
  description: OpenAPI Specification for the Apigee mock target service endpoint.
  version: 1.0.0
  title: Mock Target API
paths:
  /:
    get:
      summary: View personalized greeting
      operationId: View a personalized greeting
      description: View a personalized greeting for the specified or guest user.
      parameters:
        - name: user
          in: query
          description: Your user name.
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Success
...
servers:
  - url: http://mocktarget.apigee.net
  - url: https://mocktarget.apigee.net
...

แก้ไขช่องคำอธิบาย เป็น API proxy for the Apigee mock target service endpoint.
คลิกถัดไป
ในหน้านโยบายทั่วไป ในส่วนความปลอดภัย: การให้สิทธิ์ ตรวจสอบว่าได้เลือกส่งผ่าน (ไม่มีการให้สิทธิ์) แล้วคลิกถัดไป
ในหน้า "โฟลว์" ตรวจสอบว่าได้เลือกการดำเนินการทั้งหมดแล้ว
เคล็ดลับ: ระบบจะสร้างโฟลว์แบบมีเงื่อนไขโดยอัตโนมัติจากการดำเนินการที่กำหนดไว้ในออบเจ็กต์ paths ในข้อมูลจำเพาะของ OpenAPI โฟลว์แบบมีเงื่อนไขจะบอก Edge ว่า "เมื่อเห็นสิ่งนี้ ให้ดำเนินการตามตรรกะนี้" เช่น เมื่อการเรียก API เป็น GET ในทรัพยากร /xml (เงื่อนไข) ให้แปลงการตอบกลับเป็น JSON (ผ่านนโยบายที่แนบกับโฟลว์แบบมีเงื่อนไข) ระบบจะดำเนินการโฟลว์เพียง 1 รายการต่อธุรกรรม ซึ่งก็คือโฟลว์แรกที่มีเงื่อนไขเป็น จริง
คลิกถัดไป
ในหน้าโฮสต์เสมือน ให้เลือกค่าเริ่มต้น และปลอดภัย แล้วคลิก ถัดไป
ในหน้าสรุป ตรวจสอบว่าได้เลือกสภาพแวดล้อมทดสอบ ในส่วนการใช้งานที่ไม่บังคับ แล้วคลิกสร้างและใช้งาน

Apigee จะสร้างพร็อกซี API ใหม่และใช้งานในสภาพแวดล้อมการทดสอบ
คลิกแก้ไขพร็อกซี เพื่อแสดงหน้าภาพรวมของพร็อกซี API

Classic Edge (Private Cloud)

วิธีสร้างพร็อกซี API จากข้อมูลจำเพาะของ OpenAPI โดยใช้ UI ของ Classic Edge

ลงชื่อเข้าใช้ https://apigee.com/edge
คลิกพร็อกซี API ในหน้าต่างหลัก
หรือจะเลือกพัฒนา > พร็อกซี API ในแถบการนำทางด้านซ้ายก็ได้
คลิก + พร็อกซี
ในวิซาร์ดสร้างพร็อกซี ให้เลือกพร็อกซีแบบย้อนกลับ (พบมากที่สุด) และ คลิก ใช้ OpenAPI
คลิกนำเข้าจาก URL ป้อนชื่อสำหรับข้อมูลจำเพาะของ OpenAPI แล้วป้อนเส้นทางไปยังเนื้อหาดิบบน GitHub สำหรับข้อมูลจำเพาะของ OpenAPI ในช่อง URL

https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget.yaml
คลิกเลือก

คลิกถัดไป

หน้า "รายละเอียด" ในวิซาร์ดสร้างพร็อกซีจะปรากฏขึ้น ระบบจะป้อนค่าในช่องล่วงหน้า โดยใช้ค่าที่กำหนดไว้ในข้อมูลจำเพาะของ OpenAPI ดังที่แสดงในรูปต่อไปนี้

ตารางต่อไปนี้อธิบายค่าเริ่มต้นที่ระบบป้อนไว้ล่วงหน้าโดยใช้ พร็อพเพอร์ตี้ในข้อมูลจำเพาะของ OpenAPI ส่วนหนึ่งของข้อมูลจำเพาะของ OpenAPI ที่แสดงพร็อพเพอร์ตี้ที่ใช้จะแสดงอยู่หลังตาราง

ช่อง	คำอธิบาย	ค่าเริ่มต้น
ชื่อพร็อกซี	ชื่อของพร็อกซี API เช่น `Mock-Target-API`	พร็อพเพอร์ตี้ `title` จากข้อมูลจำเพาะของ OpenAPI โดยแทนที่ช่องว่างด้วยขีดกลาง
เส้นทางฐานของพร็อกซี	คอมโพเนนต์เส้นทางที่ระบุพร็อกซี API นี้อย่างไม่ซ้ำกันภายในองค์กร URL ที่แสดงต่อสาธารณะของพร็อกซี API นี้ประกอบด้วยชื่อองค์กร สภาพแวดล้อมที่พร็อกซี API นี้ใช้งาน และเส้นทางฐานนี้ เช่น ตัวอย่าง: `http://myorg-test.apigee.net/mock-target-api`	เนื้อหาในช่องชื่อ ที่แปลงเป็นตัวพิมพ์เล็กทั้งหมด
API ที่มีอยู่	URL เป้าหมายที่เรียกใช้ในนามของพร็อกซี API นี้ คุณสามารถใช้ URL ใดก็ได้ที่เข้าถึงได้ผ่าน อินเทอร์เน็ตแบบเปิด เช่น `http://mocktarget.apigee.net`	พร็อพเพอร์ตี้ `servers` จากข้อมูลจำเพาะของ OpenAPI
คำอธิบาย	คำอธิบายของพร็อกซี API	พร็อพเพอร์ตี้ `description` จากข้อมูลจำเพาะของ OpenAPI

ส่วนต่อไปนี้เป็นส่วนหนึ่งของข้อมูลจำเพาะของ OpenAPI ที่แสดง พร็อพเพอร์ตี้ที่ใช้ในการป้อนค่าในช่องล่วงหน้า

openapi: 3.0.0
info:
  description: OpenAPI Specification for the Apigee mock target service endpoint.
  version: 1.0.0
  title: Mock Target API
paths:
  /:
    get:
      summary: View personalized greeting
      operationId: View a personalized greeting
      description: View a personalized greeting for the specified or guest user.
      parameters:
        - name: user
          in: query
          description: Your user name.
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Success
...
servers:
  - url: http://mocktarget.apigee.net
  - url: https://mocktarget.apigee.net
...

แก้ไขช่องคำอธิบาย เป็น API proxy for the Apigee mock target service endpoint.
คลิกถัดไป
ในหน้า "โฟลว์" ตรวจสอบว่าได้เลือกการดำเนินการทั้งหมดแล้ว
เคล็ดลับ: ระบบจะสร้างโฟลว์แบบมีเงื่อนไขโดยอัตโนมัติจากการดำเนินการที่กำหนดไว้ในออบเจ็กต์ paths ในข้อมูลจำเพาะของ OpenAPI โฟลว์แบบมีเงื่อนไขจะบอก Edge ว่า "เมื่อเห็นสิ่งนี้ ให้ดำเนินการตามตรรกะนี้" เช่น เมื่อการเรียก API เป็น GET ในทรัพยากร /xml (เงื่อนไข) ให้แปลงการตอบกลับเป็น JSON (ผ่านนโยบายที่แนบกับโฟลว์แบบมีเงื่อนไข) ระบบจะดำเนินการโฟลว์เพียง 1 รายการต่อธุรกรรม ซึ่งก็คือโฟลว์แรกที่มีเงื่อนไขเป็น จริง
คลิกถัดไป
ในหน้า "ความปลอดภัย" ให้เลือกส่งผ่าน (ไม่มี) เป็นตัวเลือกความปลอดภัย แล้วคลิกถัดไป
ในหน้า "โฮสต์เสมือน" ตรวจสอบว่าได้เลือกโฮสต์เสมือนทั้งหมดแล้วคลิก ถัดไป
ในหน้า "สร้าง" ตรวจสอบว่าได้เลือกสภาพแวดล้อมทดสอบ แล้ว คลิกสร้างและใช้งาน
ในหน้า "สรุป" คุณจะเห็นการยืนยันว่าระบบสร้างพร็อกซี API ใหม่เรียบร้อยแล้ว และใช้งานในสภาพแวดล้อมการทดสอบ
คลิก Mock-Target-API เพื่อแสดงหน้าภาพรวมของพร็อกซี API

ยินดีด้วย คุณสร้างพร็อกซี API จากข้อมูลจำเพาะของ OpenAPI ได้แล้ว ขั้นตอนถัดไปคือการทดสอบเพื่อดูว่าพร็อกซีทำงานอย่างไร

ทดสอบพร็อกซี API

คุณสามารถทดสอบ API Mock-Target-API โดยใช้ cURL หรือเว็บเบราว์เซอร์

ในหน้าต่างเทอร์มินัล ให้เรียกใช้คำสั่ง cURL ต่อไปนี้ แทนที่ชื่อองค์กรของคุณใน URL

curl http://<org_name>-test.apigee.net/mock-target-api

การตอบกลับ

คุณควรเห็นการตอบกลับต่อไปนี้

Hello, Guest!

เยี่ยมไปเลย คุณสร้างพร็อกซี API อย่างง่ายจากข้อมูลจำเพาะของ OpenAPI และทดสอบ พร็อกซีแล้ว

เพิ่มนโยบาย XML เป็น JSON

ขั้นตอนถัดไปคือการเพิ่มนโยบาย XML เป็น JSON ลงในโฟลว์แบบมีเงื่อนไขดูการตอบกลับ XML ซึ่งสร้างขึ้นโดยอัตโนมัติเมื่อคุณสร้างพร็อกซี API จาก ข้อมูลจำเพาะของ OpenAPI นโยบายจะแปลงการตอบกลับ XML ของเป้าหมายเป็นการตอบกลับ JSON การตอบกลับ

ขั้นแรก ให้เรียก API เพื่อให้คุณเปรียบเทียบผลลัพธ์กับผลลัพธ์ที่ได้รับหลังจากเพิ่ม นโยบายได้ ในหน้าต่างเทอร์มินัล ให้เรียกใช้คำสั่ง cURL ต่อไปนี้ คุณกำลังเรียกทรัพยากร /xml ของบริการเป้าหมาย ซึ่งแสดงผลบล็อก XML อย่างง่ายโดยค่าเริ่มต้น แทนที่ชื่อองค์กรของคุณใน URL

curl http://<org_name>-test.apigee.net/mock-target-api/xml

การตอบกลับ

คุณควรเห็นการตอบกลับต่อไปนี้

<root> 
  <city>San Jose</city> 
  <firstName>John</firstName> 
  <lastName>Doe</lastName> 
  <state>CA</state> 
</root>

ตอนนี้มาทำบางอย่างที่จะแปลงการตอบกลับ XML เป็น JSON กัน เพิ่มนโยบาย XML เป็น JSON ลงในโฟลว์แบบมีเงื่อนไข "ดูการตอบกลับ XML" ในพร็อกซี API

คลิกแท็บพัฒนา ที่มุมขวาบนของหน้าภาพรวม Mock-Target-API ใน UI ของ Edge
ในบานหน้าต่าง Navigator ด้านซ้าย ในส่วนปลายทางพร็อกซี > ค่าเริ่มต้น ให้คลิกโฟลว์แบบมีเงื่อนไขดู การตอบกลับ XML
คลิกปุ่ม + ขั้นตอน ด้านล่าง ซึ่งสอดคล้องกับ การตอบกลับ สำหรับโฟลว์

กล่องโต้ตอบ "เพิ่มขั้นตอน" จะเปิดขึ้นเพื่อแสดงรายการนโยบายทั้งหมดที่คุณเพิ่มได้ ซึ่งจัดเป็นหมวดหมู่
เลื่อนไปที่หมวดหมู่การไกล่เกลี่ย แล้วเลือก XML เป็น JSON
เก็บค่าเริ่มต้นสำหรับ ชื่อที่แสดง และ ชื่อ ไว้
คลิกเพิ่ม ระบบจะใช้นโยบาย XML เป็น JSON กับการตอบกลับ
คลิกบันทึก

ตอนนี้คุณเพิ่มนโยบายแล้ว ให้เรียก API อีกครั้งโดยใช้ cURL โปรดทราบว่าคุณยังคงเรียกทรัพยากร /xml เดียวกัน บริการเป้าหมายยังคงแสดงผลบล็อก XML แต่ตอนนี้พร็อกซี API จะแปลงการตอบกลับเป็น JSON เรียกใช้ ดังนี้

curl http://<org_name>-test.apigee.net/mock-target-api/xml

โปรดทราบว่าการตอบกลับ XML จะถูกแปลงเป็น JSON

{"root":{"city":"San Jose","firstName":"John","lastName":"Doe","state":"CA"}}

ยินดีด้วย คุณทดสอบการดำเนินการของนโยบายที่เพิ่มลงใน โฟลว์แบบมีเงื่อนไขเรียบร้อยแล้ว