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

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

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

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

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

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

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

http://mocktarget.apigee.net

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

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

http://mocktarget.apigee.net/help

สิ่งที่ต้องมี

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

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

Edge

วิธีสร้างพร็อกซี API จากข้อกำหนดของ OpenAPI โดยใช้ Edge UI

ลงชื่อเข้าใช้ https://apigee.com/edge
คลิกพร็อกซี API ในหน้าต่างหลัก
อีกทางเลือกหนึ่งคือ เลือก Develop > พร็อกซี API ในแถบนำทางด้านซ้าย
คลิก + พร็อกซี
ในวิซาร์ดสร้างพร็อกซี ให้คลิกใช้ข้อกำหนดของ OpenAPI สำหรับเทมเพลตพร็อกซีแบบย้อนกลับ (ใช้มากที่สุด)
คลิกนำเข้าจาก URL แล้วป้อนข้อมูลต่อไปนี้
- OpenAPI Spec URL: เส้นทางไปยังเนื้อหาดิบใน GitHub สำหรับข้อกำหนดของ OpenAPI ในช่อง URL ดังนี้
```
https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget3.0.yaml
```
- ชื่อข้อกำหนด: ชื่อของข้อกำหนดของ OpenAPI เช่น Mock Target
  ชื่อนี้ใช้ในการจัดเก็บข้อกำหนดของ 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 (ผ่านนโยบายที่แนบกับโฟลว์แบบมีเงื่อนไข) เฉพาะ หนึ่งการดำเนินการจะทำงานต่อธุรกรรม ซึ่งเป็นขั้นตอนแรกที่มีเงื่อนไขในการประเมินเป็น true
คลิกถัดไป
ในหน้าโฮสต์เสมือน ให้เลือกเริ่มต้นและปลอดภัย แล้วคลิก ถัดไป
ในหน้าสรุป ให้ตรวจสอบว่าสภาพแวดล้อมการทดสอบ ไว้ในหัวข้อการทำให้ใช้งานได้ที่ไม่บังคับ แล้วคลิกสร้างและ deploy:

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

คลาสสิก Edge (Private Cloud)

วิธีสร้างพร็อกซี API จากข้อกำหนดของ OpenAPI โดยใช้ Edge UI แบบคลาสสิก

ลงชื่อเข้าใช้ https://apigee.com/edge
คลิกพร็อกซี API ในหน้าต่างหลัก
อีกทางเลือกหนึ่งคือ เลือก Develop > พร็อกซี 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 (ผ่านนโยบายที่แนบกับโฟลว์แบบมีเงื่อนไข) เฉพาะ หนึ่งการดำเนินการจะทำงานต่อธุรกรรม ซึ่งเป็นขั้นตอนแรกที่มีเงื่อนไขในการประเมินเป็น true
คลิกถัดไป
ในหน้าความปลอดภัย ให้เลือกส่งผ่าน (ไม่มี) เป็นการรักษาความปลอดภัย แล้วคลิกถัดไป
ในหน้าโฮสต์เสมือน ตรวจสอบให้แน่ใจว่าได้เลือกโฮสต์เสมือนทั้งหมดแล้ว และคลิก ถัดไป
ในหน้าบิลด์ ให้ตรวจสอบว่าได้เลือกสภาพแวดล้อมทดสอบแล้ว และ ให้คลิกสร้างและทำให้ใช้งานได้
ในหน้าสรุป คุณจะเห็นการรับทราบว่ามีการสร้างพร็อกซี 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 ไปยังขั้นตอนแบบมีเงื่อนไขของ View XML Response ในพร็อกซี API

คลิกแท็บพัฒนาที่มุมขวาบนของ Mock-Target-API หน้าภาพรวมใน Edge UI
ในแผงการนำทางที่ด้านซ้าย ในส่วนปลายทางของพร็อกซี > คลิก มุมมอง ขั้นตอนแบบมีเงื่อนไขของการตอบกลับ 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"}}

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