Tạo proxy API từ Đặc tả OpenAPI | Apigee Edge

Trong hướng dẫn này, bạn sẽ tìm hiểu cách tạo proxy API Edge qua Thông số kỹ thuật OpenAPI bằng giao diện người dùng quản lý Apigee Edge. Khi bạn gọi proxy API bằng một ứng dụng HTTP, chẳng hạn như cURL, proxy API sẽ gửi yêu cầu đến dịch vụ mục tiêu mô phỏng Apigee.

Giới thiệu về Open API Initiative

"Sáng kiến API mở (OAI) tập trung vào việc tạo, phát triển và thúc đẩy Định dạng mô tả API trung lập với nhà cung cấp dựa trên Thông số kỹ thuật của Swagger." Để biết thêm thông tin về Sáng kiến API Mở, hãy truy cập vào https://openapis.org.

Thông số kỹ thuật OpenAPI sử dụng một định dạng tiêu chuẩn để mô tả API RESTful. Được viết ở định dạng JSON hoặc YAML, Thông số kỹ thuật OpenAPI giúp máy có thể đọc được nhưng cũng dễ đọc và dễ hiểu. Bản đặc tả kỹ thuật mô tả các phần tử như vậy của API dưới dạng đường dẫn cơ sở, đường dẫn và động từ, tiêu đề, tham số truy vấn, toán tử, loại nội dung, mô tả phản hồi, v.v. Ngoài ra, Thông số kỹ thuật OpenAPI thường được dùng để tạo tài liệu API.

Giới thiệu về dịch vụ mục tiêu mô phỏng Apigee

Dịch vụ mục tiêu mô phỏng Apigee được sử dụng trong hướng dẫn này được lưu trữ tại Apigee và trả về dữ liệu đơn giản. Ứng dụng này không yêu cầu khoá API hoặc mã truy cập. Trên thực tế, bạn có thể truy cập vào tính năng này trong trình duyệt web. Hãy dùng thử bằng cách nhấp vào nút sau:

http://mocktarget.apigee.net

Dịch vụ đích trả về lời chào Hello, guest!

Để biết thông tin về tập hợp đầy đủ các API mà dịch vụ đích mô phỏng hỗ trợ, hãy nhấp vào các mục sau:

http://mocktarget.apigee.net/help

Bạn cần có

Một tài khoản Apigee Edge. Nếu chưa có tài khoản, bạn có thể đăng ký bằng cách làm theo hướng dẫn trong bài viết Tạo tài khoản Apigee Edge.
Thông số kỹ thuật OpenAPI. Trong hướng dẫn này, bạn sẽ dùng mocktarget.yaml Thông số kỹ thuật OpenAPI để mô tả dịch vụ mục tiêu mô phỏng http://mocktarget.apigee.net của Apigee. Để biết thêm thông tin, hãy xem https://github.com/apigee/api-platform-samples/tree/master/default-proxies/helloworld/openapi.
cURL được cài đặt trên máy của bạn để thực hiện lệnh gọi API từ dòng lệnh; hoặc từ một trình duyệt web.

Tạo proxy API

Edge

Cách tạo proxy API từ một Thông số kỹ thuật OpenAPI bằng giao diện người dùng Edge:

Đăng nhập vào https://apigee.com/edge.
Nhấp vào API Proxies trong cửa sổ chính.
Ngoài ra, bạn có thể chọn Phát triển > Proxy API trong thanh điều hướng bên trái.
Nhấp vào + Proxy.
Trong trình hướng dẫn Tạo proxy, hãy nhấp vào Sử dụng thông số kỹ thuật OpenAPI cho mẫu Proxy ngược (phổ biến nhất).
Nhấp vào Nhập từ URL rồi nhập các thông tin sau:
- URL thông số kỹ thuật OpenAPI: Đường dẫn đến nội dung thô trên GitHub cho Thông số kỹ thuật OpenAPI trong trường URL:
```
https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget3.0.yaml
```
- Tên thông số kỹ thuật: Tên cho thông số kỹ thuật OpenAPI, chẳng hạn như Mục tiêu mô phỏng.
  Tên này được dùng để lưu trữ Thông số kỹ thuật OpenAPI trong cửa hàng thông số kỹ thuật. Xem phần Quản lý thông số kỹ thuật.

Nhấp vào Nhập.

Trang Chi tiết trong trình hướng dẫn Tạo proxy sẽ hiển thị. Các trường được điền sẵn bằng giá trị được xác định trong phần Thông số kỹ thuật OpenAPI, như minh hoạ sau đây

Bảng sau đây mô tả các giá trị mặc định được điền sẵn bằng các thuộc tính trong Thông số kỹ thuật OpenAPI. Dưới đây là phần trích dẫn Thông số kỹ thuật OpenAPI minh hoạ các thuộc tính được sử dụng.

Trường	Nội dung mô tả	Mặc định
Tên	Tên của proxy API. Ví dụ: `Mock-Target-API`.	Thuộc tính `title` từ Thông số kỹ thuật OpenAPI có dấu cách được thay thế bằng dấu gạch ngang
Đường dẫn cơ sở	Thành phần đường dẫn xác định duy nhất proxy API này trong tổ chức. URL cho phép công khai của proxy API này bao gồm tên tổ chức của bạn, môi trường nơi triển khai proxy API này và đường dẫn cơ sở này. Ví dụ: `http://myorg-test.apigee.net/mock-target-api`	Nội dung trường Name được chuyển đổi sang tất cả chữ thường
Mô tả	Nội dung mô tả về proxy API.	Thuộc tính `description` từ OpenAPI Specification
Target (API hiện tại)	URL mục tiêu đã được gọi thay cho proxy API này. Bạn có thể sử dụng bất kỳ URL nào truy cập được qua mạng Internet mở. Ví dụ: `http://mocktarget.apigee.net`	Thuộc tính `servers` từ OpenAPI Specification

Phần sau đây cung cấp một phần trích dẫn từ Thông số kỹ thuật OpenAPI cho thấy các thuộc tính được dùng để điền sẵn các trường.

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
...

Chỉnh sửa trường Mô tả như sau: API proxy for the Apigee mock target service endpoint.
Nhấp vào Tiếp theo.
Trên trang Các chính sách chung, trong phần Bảo mật: Uỷ quyền, hãy đảm bảo rằng bạn đã chọn mục Chuyển qua (không cho phép) rồi nhấp vào Tiếp theo:
Trên trang Luồng, hãy đảm bảo tất cả thao tác đều được chọn.
Lưu ý: Luồng có điều kiện được tạo tự động từ các thao tác được xác định trong đối tượng paths ở Thông số kỹ thuật OpenAPI. Luồng có điều kiện cho Edge biết: "Khi bạn thấy điều này, hãy thực hiện logic này". Ví dụ: khi lệnh gọi API là một GET trên tài nguyên /xml (điều kiện), hãy chuyển đổi phản hồi thành JSON (thông qua chính sách đính kèm với quy trình có điều kiện). Chỉ một luồng được thực thi cho mỗi giao dịch – luồng đầu tiên có điều kiện được đánh giá là đúng.
Nhấp vào Tiếp theo.
Trên trang Virtual hosts (Máy chủ ảo), hãy chọn default (mặc định) và secure (bảo mật) rồi nhấp vào Next (Tiếp theo).
Trên trang Tóm tắt, hãy nhớ chọn môi trường Test (Kiểm thử) trong phần Optional Deployment (Triển khai tuỳ chọn) rồi nhấp vào Create and Apple (Tạo và triển khai):

Apigee tạo proxy API mới và triển khai proxy cho môi trường thử nghiệm của bạn:
Nhấp vào Edit proxy (Chỉnh sửa proxy) để hiển thị trang Tổng quan cho proxy API.

Phiên bản cũ (Đám mây riêng tư)

Cách tạo proxy API từ Thông số kỹ thuật OpenAPI bằng giao diện người dùng Classic Edge:

Đăng nhập vào https://apigee.com/edge.
Nhấp vào API Proxies trong cửa sổ chính.
Ngoài ra, bạn có thể chọn Phát triển > Proxy API trong thanh điều hướng bên trái.
Nhấp vào + Proxy.
Trong trình hướng dẫn Create Proxy (Tạo proxy), hãy chọn Đảo ngược proxy (phổ biến nhất) rồi nhấp vào Use OpenAPI (Sử dụng OpenAPI).
Nhấp vào Nhập từ một URL, nhập tên cho Thông số kỹ thuật OpenAPI và nhập đường dẫn đến nội dung thô trên GitHub cho Thông số kỹ thuật OpenAPI trong trường URL:

https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget.yaml
Nhấp vào Chọn.

Nhấp vào Tiếp theo.

Trang Chi tiết trong trình hướng dẫn Tạo proxy sẽ hiển thị. Các trường được điền sẵn bằng giá trị được xác định trong Thông số kỹ thuật OpenAPI, như trong hình sau.

Bảng sau đây mô tả các giá trị mặc định được điền sẵn bằng các thuộc tính trong Thông số kỹ thuật OpenAPI. Dưới đây là phần trích dẫn Thông số kỹ thuật OpenAPI minh hoạ các thuộc tính được sử dụng.

Trường	Nội dung mô tả	Mặc định
Tên proxy	Tên của proxy API. Ví dụ: `Mock-Target-API`.	Thuộc tính `title` từ Thông số kỹ thuật OpenAPI có dấu cách được thay thế bằng dấu gạch ngang
Đường dẫn cơ sở proxy	Thành phần đường dẫn xác định duy nhất proxy API này trong tổ chức. URL cho phép công khai của proxy API này bao gồm tên tổ chức của bạn, môi trường nơi triển khai proxy API này và đường dẫn cơ sở này. Ví dụ: `http://myorg-test.apigee.net/mock-target-api`	Nội dung trường Name được chuyển đổi sang tất cả chữ thường
API hiện tại	URL mục tiêu đã được gọi thay cho proxy API này. Bạn có thể sử dụng bất kỳ URL nào truy cập được qua mạng Internet mở. Ví dụ: `http://mocktarget.apigee.net`	Thuộc tính `servers` từ OpenAPI Specification
Mô tả	Nội dung mô tả về proxy API.	Thuộc tính `description` từ OpenAPI Specification

Phần sau đây cung cấp một phần trích dẫn từ Thông số kỹ thuật OpenAPI cho thấy các thuộc tính được dùng để điền sẵn các trường.

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
...

Chỉnh sửa trường Mô tả như sau: API proxy for the Apigee mock target service endpoint.
Nhấp vào Tiếp theo.
Trên trang Luồng, hãy đảm bảo tất cả thao tác đều được chọn.
Lưu ý: Luồng có điều kiện được tạo tự động từ các thao tác được xác định trong đối tượng paths ở Thông số kỹ thuật OpenAPI. Luồng có điều kiện cho Edge biết: "Khi bạn thấy điều này, hãy thực hiện logic này". Ví dụ: khi lệnh gọi API là một GET trên tài nguyên /xml (điều kiện), hãy chuyển đổi phản hồi thành JSON (thông qua chính sách đính kèm với quy trình có điều kiện). Chỉ một luồng được thực thi cho mỗi giao dịch – luồng đầu tiên có điều kiện được đánh giá là đúng.
Nhấp vào Tiếp theo.
Trên trang Bảo mật, hãy chọn Pass through (none) (Truyền qua (không có) làm phương án bảo mật) rồi nhấp vào Next (Tiếp theo).
Trên trang Virtual Hosts (Máy chủ ảo), hãy đảm bảo tất cả các máy chủ ảo đều đã được chọn rồi nhấp vào Next (Tiếp theo).
Trên trang Build (Tạo), hãy nhớ chọn môi trường test (kiểm thử) rồi nhấp vào Build and Deploy (Tạo và triển khai).
Trên trang Tóm tắt, bạn sẽ thấy thông báo xác nhận rằng proxy API mới đã được tạo thành công và triển khai trong môi trường thử nghiệm.
Nhấp vào Mock-Target-API (API mục tiêu mô phỏng) để hiển thị trang Tổng quan cho proxy API.

Xin chúc mừng! Bạn đã tạo một proxy API từ một Thông số kỹ thuật OpenAPI. Tiếp theo, bạn sẽ kiểm thử để xem nó hoạt động như thế nào.

Kiểm thử proxy API

Bạn có thể kiểm thử API Mock-Target-API bằng cURL hoặc trình duyệt web.

Trong cửa sổ dòng lệnh, hãy chạy lệnh cURL sau đây. Thay thế tên tổ chức của bạn trong URL.

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

Đáp

Bạn sẽ thấy phản hồi như sau:

Hello, Guest!

Bạn làm tốt lắm! Bạn đã tạo một proxy API đơn giản từ Thông số kỹ thuật OpenAPI và kiểm thử thông số đó.

Thêm chính sách XML vào JSON

Tiếp theo, bạn sẽ thêm chính sách XML vào JSON vào quy trình có điều kiện Xem phản hồi XML. Quy trình này được tạo tự động khi bạn tạo proxy API từ Thông số kỹ thuật OpenAPI. Chính sách này sẽ chuyển đổi phản hồi XML của mục tiêu thành phản hồi JSON.

Trước tiên, hãy gọi API để bạn có thể so sánh kết quả với các kết quả nhận được sau khi thêm chính sách. Trong cửa sổ dòng lệnh, hãy thực thi lệnh cURL sau đây. Bạn đang gọi tài nguyên /xml của dịch vụ mục tiêu. Tài nguyên này vốn trả về một khối XML đơn giản. Thay thế tên tổ chức của bạn trong URL.

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

Đáp

Bạn sẽ thấy phản hồi như sau:

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

Bây giờ, hãy làm điều gì đó để chuyển đổi phản hồi XML thành JSON. Thêm chính sách XML vào JSON vào quy trình xem phản hồi XML có điều kiện trong proxy API.

Nhấp vào thẻ Develop (Phát triển) ở góc trên cùng bên phải của trang Tổng quan về Mock-Target-API trong giao diện người dùng Edge.
Trong ngăn Trình điều hướng bên trái, trong phần Điểm cuối proxy > mặc định, hãy nhấp vào quy trình có điều kiện Xem phản hồi XML.
Nhấp vào nút +Step (Bước) ở dưới cùng, tương ứng với Response (Phản hồi) cho quy trình.

Hộp thoại Thêm bước sẽ mở ra để hiển thị một danh sách đã phân loại gồm tất cả các chính sách mà bạn có thể thêm.
Chuyển đến danh mục Dàn xếp và chọn XML sang JSON.
Giữ nguyên các giá trị mặc định cho Display Name (Tên hiển thị) và Name (Tên).
Nhấp vào Thêm. Chính sách XML sang JSON được áp dụng cho phản hồi.
Nhấp vào Lưu.

Bây giờ, bạn đã thêm chính sách, hãy gọi lại API bằng cURL. Xin lưu ý rằng bạn vẫn đang gọi cùng một tài nguyên /xml. Dịch vụ đích vẫn trả về khối XML của dịch vụ đó, nhưng giờ đây chính sách trong proxy API sẽ chuyển đổi phản hồi thành JSON. Thực hiện lệnh gọi này:

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

Lưu ý rằng phản hồi XML được chuyển đổi thành JSON:

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

Xin chúc mừng! Bạn đã thử nghiệm thành công việc thực thi chính sách được thêm vào luồng có điều kiện.