Phát hành API (phiên bản gốc)

Bạn đang xem tài liệu về Apigee Edge.
Truy cập vào tài liệu Apigee X. thông tin

Xuất bản API lên cổng thông tin để các nhà phát triển ứng dụng có thể sử dụng, như mô tả trong các phần sau.

Tổng quan về việc xuất bản bằng API

Quy trình xuất bản API lên cổng thông tin của bạn là quy trình gồm 2 bước:

  1. Chọn sản phẩm API mà bạn muốn xuất bản lên cổng thông tin.
  2. Tự động tạo tài liệu tham khảo API từ ảnh chụp nhanh của OpenAPI Specification để giúp nhà phát triển ứng dụng tìm hiểu về API của bạn. (Để biết thêm thông tin về bản tổng quan nhanh, hãy xem bài viết Bản tổng quan nhanh về Quy cách OpenAPI là gì?

Khi bạn xuất bản một API lên cổng thông tin, những nội dung cập nhật sau đây sẽ tự động được thực hiện đối với cổng thông tin của bạn:

  • Một trang Tài liệu tham khảo API sẽ được thêm vào cổng thông tin của bạn
    Trang Tài liệu tham khảo API hiển thị tài liệu tham khảo API mà bạn được tạo tự động từ một ảnh chụp nhanh của OpenAPI Specification. Nhà phát triển có thể xem tài liệu API của bạn và nhấp vào Dùng thử để đưa ra yêu cầu API và xem đầu ra.

    Lưu ý: Bạn không thể chỉnh sửa trực tiếp nội dung của trang này; trang này không xuất hiện trong danh sách các trang trong cổng thông tin của bạn.

  • Đường liên kết đến trang Tài liệu tham khảo về API được thêm vào trang API
    Trang API (có trong cổng thông tin mẫu) cung cấp danh sách tất cả API được xuất bản trên cổng thông tin của bạn, kèm theo đường liên kết đến tài liệu tham khảo API tương ứng để biết thêm thông tin.

    Lưu ý: Bạn không thể chỉnh sửa trực tiếp nội dung của trang này; trang này không xuất hiện trong danh sách các trang trong cổng thông tin của bạn.

Ảnh chụp nhanh của OpenAPI Specification là gì?

Mỗi OpenAPI Specification đóng vai trò là nguồn dữ liệu đáng tin cậy trong suốt vòng đời của một API. Cùng một quy cách được dùng ở mỗi giai đoạn trong vòng đời API, từ phát triển đến xuất bản rồi giám sát. Khi sửa đổi một quy cách, bạn cần phải nhận thức được tác động của các thay đổi đối với API của mình thông qua các giai đoạn khác trong vòng đời, như mô tả trong phần Điều gì sẽ xảy ra nếu tôi sửa đổi một quy cách?

Khi xuất bản API, bạn sẽ chụp ảnh nhanh của Đặc tả OpenAPI để tạo tài liệu tham khảo API. Ảnh chụp nhanh đó thể hiện một phiên bản cụ thể của quy cách trong kho quy cách. Nếu sửa đổi OpenAPI Specification bằng trình chỉnh sửa spec, bạn có thể quyết định chụp một ảnh chụp nhanh khác của spec để phản ánh những thay đổi mới nhất trong tài liệu tham khảo API.

Thêm tính năng hỗ trợ CORS vào các proxy API

Trước khi xuất bản API, bạn cần thêm tính năng hỗ trợ CORS vào các proxy API để hỗ trợ các yêu cầu khác nguồn gốc ở phía máy khách.

CORS (Chia sẻ tài nguyên trên nhiều nguồn gốc) là một cơ chế tiêu chuẩn cho phép các lệnh gọi JavaScript XMLHttpRequest (XHR) được thực thi trong một trang web tương tác với các tài nguyên từ các miền khác nguồn gốc. CORS là một giải pháp thường được triển khai cho chính sách cùng nguồn gốc do tất cả các trình duyệt thực thi. Ví dụ: nếu bạn thực hiện lệnh gọi XHR đến Twitter API từ mã JavaScript đang thực thi trong trình duyệt, thì lệnh gọi sẽ không thành công. Điều này là do miền phân phát trang cho trình duyệt của bạn không giống với miền phân phát API Twitter. CORS cung cấp một giải pháp cho vấn đề này bằng cách cho phép các máy chủ "chọn sử dụng" nếu muốn cung cấp tính năng chia sẻ tài nguyên khác nguồn gốc.

Để biết thông tin về cách thêm tính năng hỗ trợ CORS vào các proxy API trước khi xuất bản API, hãy xem phần Thêm tính năng hỗ trợ CORS vào một proxy API.

Lưu ý: Hầu hết các trình duyệt hiện đại đều thực thi CORS. Xem danh sách đầy đủ các trình duyệt được hỗ trợ. Để biết nội dung mô tả chi tiết về CORS, hãy xem Đề xuất của W3C về cơ chế Chia sẻ tài nguyên trên nhiều nguồn gốc.

Khám phá trang API

Cách truy cập vào trang API:

  1. Chọn Xuất bản > Cổng rồi chọn cổng của bạn.
  2. Nhấp vào API trên trang chủ của cổng thông tin.

Ngoài ra, bạn có thể chọn API trong trình đơn thả xuống của cổng thông tin ở thanh điều hướng trên cùng.

Danh sách API sẽ xuất hiện.

Tài liệu tham khảo API

Như minh hoạ trong hình trước, trang API cho phép bạn:

Thêm API vào cổng

Lưu ý: Bạn có thể thêm tối đa 100 API vào cổng thông tin của mình.

Cách thêm API vào cổng thông tin:

  1. Chọn Xuất bản > Cổng rồi chọn cổng của bạn.
  2. Nhấp vào API trên trang chủ của cổng thông tin.
    Ngoài ra, bạn có thể chọn API trong trình đơn thả xuống của cổng thông tin ở thanh điều hướng trên cùng.
  3. Nhấp vào + API.
    Hộp thoại Add API Product to Portal (Thêm sản phẩm API vào Cổng thông tin) sẽ xuất hiện.

  4. Trên thẻ API Product (Sản phẩm API) trong hộp thoại, hãy chọn sản phẩm API mà bạn muốn thêm vào cổng thông tin.

  5. Nhấp vào Tiếp theo.

  6. Chọn nguồn để dùng cho ảnh chụp nhanh.
    Nếu bạn đã tạo proxy API có trong sản phẩm API bằng một OpenAPI Specification, hãy chọn thông số kỹ thuật đó trong danh sách thả xuống.
    Thêm ảnh chụp nhanh

    Ngoài ra, bạn có thể chọn:

    • Không có thông số kỹ thuật và thêm thông số kỹ thuật sau khi API được xuất bản, như mô tả trong phần Chụp nhanh thông số kỹ thuật.
    • Chọn một quy cách khác để chọn hoặc tải một quy cách mới lên.

  7. Chọn hộp đánh dấu Đã xuất bản để xuất bản API lên cổng thông tin của bạn. Bỏ chọn Đã xuất bản nếu bạn chưa sẵn sàng xuất bản API.
    Bạn có thể thay đổi chế độ cài đặt này sau, như mô tả trong phần Xuất bản hoặc huỷ xuất bản API trên cổng thông tin.

  8. Trong phần Đối tượng, hãy chọn một trong các lựa chọn sau để quản lý đối tượng cho API của bạn bằng cách cho phép truy cập vào:

    • Người dùng ẩn danh để cho phép tất cả người dùng xem trang.
    • Người dùng đã đăng ký để chỉ cho phép người dùng đã đăng ký xem trang.

    Bạn có thể thay đổi chế độ cài đặt này sau, như mô tả trong phần Quản lý đối tượng cho một API trên cổng thông tin của bạn.

  9. Nhấp vào Hoàn tất.

Chụp ảnh nhanh về quy cách

Sau khi xuất bản API, bất cứ lúc nào bạn cũng có thể chụp nhanh OpenAPI Specification để cập nhật tài liệu tham khảo API được xuất bản trên cổng thông tin của bạn.

Cách chụp nhanh OpenAPI Specification:

  1. Chọn Xuất bản > Cổng rồi chọn cổng của bạn.
  2. Nhấp vào API trên trang chủ của cổng thông tin.
    Ngoài ra, bạn có thể chọn API trong trình đơn thả xuống của cổng thông tin ở thanh điều hướng trên cùng.
  3. Đặt con trỏ lên API mà bạn muốn chụp nhanh để hiển thị các thao tác.

  4. Nhấp vào Biểu tượng ảnh chụp nhanh.

    Lưu ý: Một thông báo sẽ xuất hiện nếu ảnh chụp nhanh của bạn hiện tại có thông số nguồn được chọn.

  5. Chọn một quy cách hiện có trong trình đơn thả xuống Nguồn ảnh chụp nhanh hoặc chọn Chọn một quy cách khác để chọn hoặc tải một quy cách mới lên để dùng cho việc tạo tài liệu cho API. Ngoài ra, bạn có thể chọn Không có quy cách để xoá quy cách hiện tại.

  6. Nhấp vào Cập nhật ảnh chụp nhanh (hoặc Xoá ảnh chụp nhanh nếu bạn đã chọn Không có thông số kỹ thuật).

Tài liệu tham khảo API được tạo từ quy cách và thêm vào trang Tài liệu tham khảo API.

Xuất bản hoặc huỷ xuất bản một API trên cổng thông tin

Cách xuất bản hoặc huỷ xuất bản một API trên cổng thông tin:

  1. Chọn Xuất bản > Cổng rồi chọn cổng của bạn.
  2. Nhấp vào API trên trang chủ của cổng thông tin.
    Ngoài ra, bạn có thể chọn API trong trình đơn thả xuống của cổng thông tin ở thanh điều hướng trên cùng.
  3. Đặt con trỏ lên API mà bạn muốn xuất bản hoặc huỷ xuất bản.
  4. Nhấp vào Biểu tượng cài đặt.
  5. Chọn hộp đánh dấu Đã bật để xuất bản API trên cổng thông tin của bạn. Huỷ chọn Đã bật để huỷ phát hành API.
  6. Nhấp vào Lưu.

Quản lý đối tượng cho một API trên cổng thông tin

Quản lý đối tượng cho API của bạn trên cổng thông tin bằng cách cho phép truy cập vào:

  • Tất cả người dùng
  • Chỉ dành cho người dùng đã đăng ký

Cách quản lý đối tượng cho một API trên cổng thông tin:

  1. Chọn Xuất bản > Cổng rồi chọn cổng của bạn.
  2. Nhấp vào API trên trang chủ của cổng thông tin.
    Ngoài ra, bạn có thể chọn API trong trình đơn thả xuống của cổng thông tin ở thanh điều hướng trên cùng.
  3. Đặt con trỏ lên API mà bạn muốn quản lý đối tượng để hiển thị các thao tác.
  4. Nhấp vào Biểu tượng cài đặt.
  5. Trong phần Đối tượng người xem, hãy chọn một trong các lựa chọn sau:
    • Người dùng ẩn danh để cho phép tất cả người dùng xem sản phẩm API.
    • Người dùng đã đăng ký để chỉ cho phép người dùng đã đăng ký xem sản phẩm API.
  6. Nhấp vào Lưu.

Xoá một API khỏi cổng thông tin

Cách xoá một API khỏi cổng thông tin:

  1. Chọn Xuất bản > Cổng rồi chọn cổng của bạn.
  2. Nhấp vào API trên trang chủ của cổng thông tin.
    Ngoài ra, bạn có thể chọn API trong trình đơn thả xuống của cổng thông tin ở thanh điều hướng trên cùng.
  3. Đặt con trỏ lên API trong danh sách để trình đơn thao tác xuất hiện.
  4. Nhấp vào Xoá.

Khắc phục vấn đề với các API đã xuất bản

Khi sử dụng tính năng Thử ngay, nếu lỗi TypeError: Failed to fetch xuất hiện, hãy cân nhắc các nguyên nhân và giải pháp có thể xảy ra sau đây:

  • Đối với lỗi nội dung hỗn hợp, lỗi có thể do vấn đề đã biết về swagger-ui gây ra. Một giải pháp có thể là đảm bảo rằng bạn chỉ định HTTPS trước HTTP trong định nghĩa schemes trong Quy cách OpenAPI. Ví dụ: 

     schemes:
   - https
   - http

  • Đối với lỗi hạn chế CORS (Chia sẻ tài nguyên trên nhiều nguồn gốc), hãy đảm bảo rằng CORS được hỗ trợ cho các proxy API của bạn. CORS là một cơ chế tiêu chuẩn cho phép các yêu cầu khác nguồn gốc ở phía máy khách. Xem phần Thêm tính năng hỗ trợ CORS cho một proxy API. Đảm bảo bạn cũng đã bật CORS trong trình duyệt.