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 một proxy API Edge từ một 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ụ đích mô phỏng Apigee.

Giới thiệu về Sáng kiến API mở

"Sáng kiến Open API (OAI) tập trung vào việc tạo, phát triển và quảng bá một Định dạng mô tả API độc lập với nhà cung cấp dựa trên Quy cách Swagger." Để biết thêm thông tin về Sáng kiến API mở, hãy xem https://openapis.org.

Quy cách OpenAPI sử dụng một định dạng tiêu chuẩn để mô tả một API RESTful. Được viết ở định dạng JSON hoặc YAML, OpenAPI Specification có thể đọc được bằng máy, nhưng cũng dễ dàng để con người đọc và hiểu. Quy cách này mô tả các phần tử của một API, chẳng hạn như đường dẫn cơ sở, đường dẫn và động từ, tiêu đề, tham số truy vấn, thao tác, loại nội dung, nội dung mô tả phản hồi và nhiều phần tử khác. Ngoài ra, OpenAPI Specification thường được dùng để tạo tài liệu API.

Giới thiệu về dịch vụ đích mô phỏng Apigee

Dịch vụ đích mô phỏng Apigee được 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. Bạn không cần 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 một trình duyệt web. Hãy thử bằng cách nhấp vào những nội dung sau:

http://mocktarget.apigee.net

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

Để biết thông tin về toàn bộ các API mà dịch vụ đích mô phỏng hỗ trợ, hãy nhấp vào những API 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 tại phần Tạo tài khoản Apigee Edge.
Một Quy cách OpenAPI. Trong hướng dẫn này, bạn sẽ sử dụng mocktarget.yaml OpenAPI Specification (Quy cách OpenAPI) mô tả dịch vụ đích mô phỏng của Apigee, http://mocktarget.apigee.net. Để 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 các lệnh gọi API từ dòng lệnh; hoặc một trình duyệt web.

Tạo proxy API

Edge

Cách tạo một 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 (API Proxy) trong cửa sổ chính.
Ngoài ra, bạn có thể chọn Develop > API Proxies (Phát triển > API Proxy) 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 OpenAPI Spec cho mẫu Reverse proxy (phổ biến nhất).
Nhấp vào Nhập từ URL rồi nhập các thông tin sau:
- URL của quy cách OpenAPI: Đường dẫn đến nội dung thô trên GitHub cho Quy cách OpenAPI trong trường URL:
```
https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget3.0.yaml
```
- Tên quy cách: Tên cho Quy cách OpenAPI, chẳng hạn như Mục tiêu mô phỏng.
  Tên này được dùng để lưu trữ Quy cách OpenAPI trong kho quy cách. Xem phần Quản lý quy cách.

Nhấp vào Nhập.

Trang thông tin chi tiết trong trình hướng dẫn Create Proxy (Tạo proxy) sẽ xuất hiện. Các trường được điền sẵn bằng các giá trị được xác định trong Đặc tả OpenAPI, như minh hoạ trong phần sau

Bảng sau đây mô tả các giá trị mặc định được điền sẵn bằng cách sử dụng các thuộc tính trong Đặc tả OpenAPI. Đoạn trích của OpenAPI Specification minh hoạ các thuộc tính được dùng xuất hiện sau bảng.

Trường	Mô tả	Mặc định
Tên	Tên của proxy API. Ví dụ: `Mock-Target-API`.	Thuộc tính `title` trong Quy cách OpenAPI có khoảng trắng đượ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 công khai của proxy API này bao gồm tên tổ chức của bạn, một môi trường nơi proxy API này được triển khai và đường dẫn cơ sở này. Ví dụ: `http://myorg-test.apigee.net/mock-target-api`	Nội dung trường Tên được chuyển đổi thành chữ thường
Nội dung mô tả	Nội dung mô tả về proxy API.	thuộc tính `description` trong Quy cách OpenAPI
Mục tiêu (API hiện có)	URL mục tiêu được gọi thay cho proxy API này. Bạn có thể sử dụng mọi URL có thể truy cập qua Internet mở. Ví dụ: `http://mocktarget.apigee.net`	thuộc tính `servers` trong Quy cách OpenAPI

Sau đây là một đoạn trích từ OpenAPI Specification 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 Nội dung mô tả như sau: API proxy for the Apigee mock target service endpoint.
Nhấp vào Tiếp theo.
Trên trang 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 Truy cập trực tiếp (không cần uỷ quyền) rồi nhấp vào Tiếp theo:
Trên trang Luồng, hãy đảm bảo bạn đã chọn tất cả các thao tác.
Lưu ý: Các 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 trong Đặc 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 một lệnh gọi API là 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 một chính sách được đính kèm vào luồng có điều kiện). Chỉ một luồng 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 Máy chủ ảo, hãy chọn mặc định và bảo mật, rồi nhấp vào Tiếp theo.
Trên trang Tóm tắt, hãy nhớ chọn môi trường Kiểm thử trong mục Triển khai không bắt buộc rồi nhấp vào Tạo và triển khai:

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

Classic Edge (Private Cloud)

Cách tạo một proxy API từ một Đặc tả OpenAPI bằng giao diện người dùng Edge kiểu cũ:

Đăng nhập vào https://apigee.com/edge.
Nhấp vào API Proxies (API Proxy) trong cửa sổ chính.
Ngoài ra, bạn có thể chọn Develop > API Proxies (Phát triển > API Proxy) 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 chọn Reverse proxy (most common) (Proxy đảo ngược (phổ biến nhất)) rồi nhấp vào Use OpenAPI (Sử dụng OpenAPI).
Nhấp vào Nhập từ URL, nhập tên cho Quy cách OpenAPI và nhập đường dẫn đến nội dung thô trên GitHub cho Quy cách 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 thông tin chi tiết trong trình hướng dẫn Create Proxy (Tạo proxy) sẽ xuất hiện. Các trường được điền sẵn bằng các giá trị được xác định trong Thông số kỹ thuật OpenAPI, như minh hoạ 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ách sử dụng các thuộc tính trong Đặc tả OpenAPI. Đoạn trích của OpenAPI Specification minh hoạ các thuộc tính được dùng xuất hiện sau bảng.

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

Sau đây là một đoạn trích từ OpenAPI Specification 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 Nội dung 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 bạn đã chọn tất cả các thao tác.
Lưu ý: Các 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 trong Đặc 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 một lệnh gọi API là 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 một chính sách được đính kèm vào luồng có điều kiện). Chỉ một luồng 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 Truy cập trực tiếp (không có) làm lựa chọn bảo mật rồi nhấp vào Tiếp theo.
Trên trang Máy chủ ảo, hãy đảm bảo bạn đã chọn tất cả máy chủ ảo rồi nhấp vào Tiếp theo.
Trên trang Bản dựng, hãy nhớ chọn môi trường thử nghiệm rồi nhấp vào 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 bạn đã tạo thành công và triển khai thành công API proxy mới vào môi trường thử nghiệm.
Nhấp vào Mock-Target-API để 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 Quy cách OpenAPI. Tiếp theo, bạn sẽ kiểm thử để xem cách hoạt động của quy trình này.

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

Hello, Guest!

Bạn làm tốt lắm! Bạn đã tạo một proxy API đơn giản từ một OpenAPI Specification và kiểm thử proxy đó.

Thêm chính sách XML sang JSON

Tiếp theo, bạn sẽ thêm chính sách XML sang JSON vào luồng có điều kiện Xem phản hồi XML. Luồng này được tạo tự động khi bạn tạo proxy API từ Đặc 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 những 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ụ đích, dịch vụ này sẽ 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 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 sang JSON vào luồng có điều kiện Phản hồi XML của chế độ xem trong proxy API.

Nhấp vào thẻ 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 Navigator (Trình điều hướng) bên trái, trong phần Proxy Endpoints (Điểm cuối của proxy) > default (mặc định), hãy nhấp vào luồng có điều kiện View XML Response (Xem phản hồi XML).
Nhấp vào nút +Bước ở dưới cùng, tương ứng với Câu trả lời cho quy trình.

Hộp thoại Thêm bước sẽ mở ra để hiển thị danh sách được phân loại gồm tất cả các chính sách mà bạn có thể thêm.
Di chuyển đến danh mục Dàn xếp rồi chọn XML sang JSON.
Giữ nguyên các giá trị mặc định cho Tên hiển thị và 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.

Giờ đây, khi bạn đã thêm chính sách, hãy gọi lại API bằng cURL. 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, nhưng giờ đây, chính sách trong API proxy sẽ chuyển đổi phản hồi thành JSON. Gọi điện theo cách này:

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

Xin 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 đã kiểm thử thành công việc thực thi một chính sách được thêm vào một luồng có điều kiện.