Phát hành API

Bạn đang xem tài liệu về Apigee Edge.
Chuyển đến tài liệu về Apigee X. thông tin

Xuất bản API lên cổng thông tin của bạn để 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 phát hành API

Quy trình phát hành API lên cổng thông tin của bạn gồm hai bước:

  1. Chọn sản phẩm API mà bạn muốn phát hành cho cổng thông tin của mình.
  2. Hiển thị tài liệu tham khảo API từ tài liệu OpenAPI hoặc giản đồ GraphQL để nhà phát triển ứng dụng có thể tìm hiểu về API của bạn. (Để biết thêm thông tin về ảnh chụp nhanh, hãy xem phần Ảnh chụp nhanh là gì?)

Nội dung nào được xuất bản lên cổng thông tin?

Khi bạn phát hành một API, các nội dung cập nhật sau sẽ tự động được thực hiện trên cổng thông tin của bạn:

  • Tài liệu tham khảo API. Giao diện được cung cấp tuỳ thuộc vào việc bạn phát hành API bằng tài liệu OpenAPI hay giản đồ GraphQL. Xem:
  • Thêm đường liên kết đến trang tài liệu tham khảo API 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 phát hành cho cổng thông tin của bạn, được liệt kê theo thứ tự bảng chữ cái, cùng với các đường liên kết đến tài liệu tham khảo API tương ứng để biết thêm thông tin. Nếu muốn, bạn có thể tuỳ chỉnh những nội dung sau:

    • Hình ảnh hiển thị cho mỗi thẻ API
    • Các danh mục dùng để gắn thẻ API để nhà phát triển có thể khám phá các API liên quan trên trang API

    Trang API trong cổng thông tin trực tiếp cho thấy hai danh mục và cách sử dụng hình ảnh

SmartDocs (OpenAPI)

Khi bạn phát hành một API bằng tài liệu OpenAPI, tài liệu tham khảo API SmartDocs sẽ được thêm vào cổng thông tin của bạn.

Nhà phát triển có thể xem tài liệu tham khảo API SmartDocs và sử dụng bảng điều khiển Thử API này để tạo yêu cầu API và xem kết quả. Thử API này hoạt động với các điểm cuối không bảo mật hoặc điểm cuối bảo mật bằng cách sử dụng phương thức xác thực cơ bản, Khoá API hoặc OAuth, dựa trên phương thức bảo mật được xác định trong tài liệu OpenAPI. Đối với OAuth, các luồng sau đây được hỗ trợ: mã uỷ quyền, mật khẩu và thông tin xác thực ứng dụng khách.

Trang tài liệu tham khảo API có chú thích cho biết cách uỷ quyền cho lệnh gọi API, tháo bảng điều khiển Thử API này, tải thông số kỹ thuật có liên quan xuống và thực thi API.

Nhấp vào biểu tượng Toàn màn hình để mở rộng bảng điều khiển Dùng thử API này. Bảng điều khiển mở rộng cho phép bạn xem lệnh gọi curl và mã mẫu ở nhiều định dạng, chẳng hạn như HTTP, Python, Node.js, v.v., như trong hình sau.

Bảng điều khiển Dùng thử API này được mở rộng

Trình khám phá GraphQL

Khi bạn phát hành một API bằng cách sử dụng giản đồ GraphQL, Trình khám phá GraphQL sẽ được thêm vào cổng thông tin của bạn. Trình khám phá GraphQL là một sân chơi tương tác để chạy truy vấn dựa trên API của bạn. Trình khám phá này dựa trên GraphiQL, một phương thức triển khai tham chiếu của IDE GraphQL do GraphQL Foundation phát triển.

Nhà phát triển có thể sử dụng Trình khám phá GraphQL để khám phá tài liệu tương tác dựa trên giản đồ, tạo và chạy truy vấn, xem kết quả truy vấn và tải giản đồ xuống. Để bảo mật quyền truy cập vào API, nhà phát triển có thể truyền tiêu đề uỷ quyền trong ngăn Request Headers (Tiêu đề yêu cầu).

Để biết thêm thông tin về GraphQL, hãy xem graphql.org.

Trình khám phá GraphQL trong cổng thông tin

Ảnh chụp nhanh là gì?

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

Khi phát hành API, bạn sẽ chụp ảnh chụp nhanh của tài liệu OpenAPI hoặc GraphQL để hiển thị tài liệu tham khảo API. Ảnh chụp nhanh đó đại diện cho một phiên bản cụ thể của tài liệu. Nếu sửa đổi tài liệu, bạn có thể quyết định chụp lại ảnh chụp nhanh của tài liệu để phản ánh những thay đổi mới nhất trong tài liệu tham khảo API.

Giới thiệu về URL gọi lại

Nếu ứng dụng của bạn yêu cầu URL gọi lại, chẳng hạn như khi sử dụng loại cấp mã uỷ quyền OAuth 2.0 (thường được gọi là OAuth ba bên), bạn có thể yêu cầu nhà phát triển chỉ định URL gọi lại khi họ đăng ký ứng dụng. URL gọi lại thường chỉ định URL của một ứng dụng được chỉ định để nhận mã uỷ quyền thay mặt cho ứng dụng khách. Để biết thêm thông tin, hãy xem phần Triển khai loại cấp mã uỷ quyền.

Bạn có thể định cấu hình việc có yêu cầu URL gọi lại trong quá trình đăng ký ứng dụng hay không khi thêm API vào cổng thông tin. Bạn có thể sửa đổi chế độ cài đặt này bất cứ lúc nào, như mô tả trong phần Quản lý URL gọi lại cho một API.

Khi đăng ký ứng dụng, nhà phát triển phải nhập URL gọi lại cho tất cả API yêu cầu URL đó, như mô tả trong phần Đăng ký ứng dụng.

Định cấu hình proxy API để hỗ trợ tính năng "Dùng thử API này"

Trước khi phát hành API bằng tài liệu OpenAPI, bạn cần định cấu hình proxy API để hỗ trợ tạo yêu cầu trên bảng điều khiển Thử API này trong tài liệu tham khảo API SmartDocs như sau:

  • Thêm tính năng hỗ trợ CORS vào proxy API để thực thi các yêu cầu qua nhiều nguồn gốc ở phía máy khách

    CORS là một cơ chế chuẩn cho phép các lệnh gọi XMLHttpRequest (XHR) của JavaScript đượ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ông phải 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 mà tất cả trình duyệt đều thực thi.

  • Cập nhật cấu hình proxy API nếu bạn đang sử dụng phương thức xác thực cơ bản hoặc OAuth2

Bảng sau đây tóm tắt các yêu cầu về cấu hình proxy API để hỗ trợ bảng điều khiển Thử API này trong tài liệu tham khảo API SmartDocs dựa trên quyền truy cập xác thực.

Quyền truy cập xác thực Yêu cầu về cấu hình chính sách
Không có hoặc khoá API Thêm tính năng hỗ trợ CORS vào proxy API. Để thuận tiện, hãy sử dụng giải pháp CORS mẫu được cung cấp trên GitHub hoặc làm theo các bước được mô tả trong phần Thêm tính năng hỗ trợ CORS vào proxy API.
Xác thực cơ bản Thực hiện các bước sau:
  1. Thêm tính năng hỗ trợ CORS vào proxy API. Để thuận tiện, hãy sử dụng giải pháp CORS mẫu được cung cấp trên GitHub hoặc làm theo các bước được mô tả trong phần Thêm tính năng hỗ trợ CORS vào proxy API.
  2. Trong chính sách Thêm CORS AssignMessage, hãy đảm bảo tiêu đề Access-Control-Allow-Headers bao gồm thuộc tính authorization. Ví dụ: 
    <Header name="Access-Control-Allow-Headers">
  origin, x-requested-with, accept, content-type, authorization
</Header>
OAuth2
  1. Thêm tính năng hỗ trợ CORS vào proxy API. Để thuận tiện, hãy sử dụng giải pháp CORS mẫu được cung cấp trên GitHub hoặc làm theo các bước được mô tả trong phần Thêm tính năng hỗ trợ CORS vào proxy API.
  2. Trong chính sách Thêm CORS AssignMessage, hãy đảm bảo tiêu đề Access-Control-Allow-Headers bao gồm thuộc tính authorization. Ví dụ: 
    <Header name="Access-Control-Allow-Headers">
  origin, x-requested-with, accept, content-type, authorization
</Header>
  3. Sửa hành vi không tuân thủ RFC trong chính sách OAuth2. Để thuận tiện, hãy sử dụng giải pháp OAuth2 mẫu được cung cấp trên GitHub hoặc thực hiện các bước sau:
    • Đảm bảo rằng phần tử <GrantType> trong chính sách OAuth2 được đặt thành request.formparam.grant_type (tham số biểu mẫu). Để biết thêm thông tin, hãy xem phần <GrantType>.
    • Đảm bảo rằng token_type trong chính sách OAuth2 được đặt thành Bearer chứ không phải BearerToken mặc định.

Quản lý API

Quản lý các API của bạn như mô tả trong các phần sau.

Khám phá API

Sử dụng giao diện người dùng hoặc lệnh curl để xem các API trong cổng thông tin của bạn.

Giao diện người dùng

Cách xem danh mục API:

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

Thẻ API trong danh mục API hiển thị danh sách các API đã được thêm vào cổng thông tin của bạn.

Thẻ API cho biết thông tin về các API, bao gồm tên, nội dung mô tả, chế độ hiển thị, danh mục, thông số kỹ thuật liên quan và thời gian sửa đổi

Như đã nêu trong hình trước, thẻ API cho phép bạn:

curl

Cách liệt kê API:

curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs" \
    -H "Authorization: Bearer ACCESS_TOKEN"

Thay thế nội dung sau:

  • ORG_NAME có tên của tổ chức. Ví dụ: my-org.
  • SITE_ID có tên của cổng thông tin, ở dạng ORG_NAME-PORTAL_NAME, trong đó ORG_NAME là tên của tổ chức và PORTAL_NAME là tên cổng thông tin được chuyển đổi thành chữ thường và xoá khoảng trắng và dấu gạch ngang. Ví dụ: my-org-myportal.
  • ACCESS_TOKEN có mã thông báo xác thực dùng để truy cập vào API Apigee Edge. Để biết thêm thông tin về xác thực và mã thông báo, hãy xem bài viết Xác thực quyền truy cập vào Edge API.

Hãy xem phần Lưu ý về phân trang để biết hướng dẫn về cách sử dụng tính năng phân trang trong tải trọng phản hồi.

Tải trọng phản hồi:

{
  "status": "success",
  "message": "one page of apidocs returned",
  "data": [
    {
      "id": 622759,
      "siteId": "my-org-myportal",
      "title": "Test",
      "description": "",
      "published": false,
      "visibility": false,
      "apiId": "apiproducttest18",
      "apiProductName": "apiproduct_test18",
      "edgeAPIProductName": "apiproduct_test18",
      "specId": null,
      "specContent": null,
      "specTitle": null,
      "snapshotExists": false,
      "snapshotModified": null,
      "modified": 1724144471000,
      "anonAllowed": false,
      "imageUrl": null,
      "snapshotState": null,
      "requireCallbackUrl": false,
      "categoryIds": [],
      "specFormat": null,
      "specModified": null,
      "snapshotOutdated": false,
      "snapshotSourceMissing": false,
      "graphqlSchema": null,
      "graphqlEndpointUrl": null,
      "graphqlSchemaDisplayName": null,
      "grpcFileName": null,
      "grpcZipContent": null
    }
  ],
  "code": null,
  "request_id": "1452867334",
  "error_code": null,
  "next_page_token": ""
}

Trong trường hợp:

  • modified: Thời gian sửa đổi gần đây nhất của mục danh mục tính bằng mili giây kể từ thời gian bắt đầu của hệ thống. Ví dụ: 1698165480000.
  • id: Mã của mặt hàng trong danh mục. Ví dụ: 399668.

Lưu ý về phân trang:

  • Kích thước trang: Sử dụng pageSize để chỉ định số lượng mục danh sách cần trả về trong một trang. Giá trị mặc định là 25 và tối đa là 100. Nếu có thêm trang, nextPageToken sẽ được điền bằng một mã thông báo:

    curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs?pageSize=PAGE_SIZE" \
   -H "Authorization: Bearer ACCESS_TOKEN"

    Thay thế:

    • PAGE_SIZE với số lượng mục trong danh sách cần trả về trong một trang. Ví dụ: 10.

    Tải trọng phản hồi:

    {
  "status": "success",
  "message": "one page of apidocs returned",
  "data": [
    {
      "id": 638007,
      "siteId": "tsnow-mint-liztest",
      "title": "Testing",
      "description": "",
      "published": false,
      "visibility": false,
      "apiId": "testcatalog",
      "apiProductName": "testcatalog",
      "edgeAPIProductName": "testcatalog",
      "specId": "Petstore",
      "specContent": null,
      "specTitle": null,
      "snapshotExists": true,
      "snapshotModified": 1726508367000,
      "modified": 1728582504000,
      "anonAllowed": false,
      "imageUrl": null,
      "snapshotState": "OK_SUBMITTED",
      "requireCallbackUrl": false,
      "categoryIds": [],
      "specFormat": "YAML",
      "specModified": null,
      "snapshotOutdated": false,
      "snapshotSourceMissing": false,
      "graphqlSchema": null,
      "graphqlEndpointUrl": null,
      "graphqlSchemaDisplayName": null,
      "grpcFileName": null,
      "grpcZipContent": null
    }
  ],
  "code": null,
  "request_id": "1068810934",
  "error_code": null,
  "next_page_token": ""
}

  • Mã thông báo trang: Sử dụng pageToken để truy xuất các trang tiếp theo khi có nhiều trang:

    curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs?pageSize=PAGE_SIZE&pageToken=PAGE_TOKEN" \
      -H "Authorization: Bearer ACCESS_TOKEN"

    Thay thế:

    • PAGE_SIZE với số lượng mục trong danh sách cần trả về trong một trang. Ví dụ: 10.
    • PAGE_TOKEN với giá trị nextPageToken. Ví dụ: 7zcqrin9l6xhi4nbrb9.

Thêm API

Sử dụng giao diện người dùng hoặc lệnh curl để thêm API vào cổng thông tin:

Giao diện người dùng

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

  1. Truy cập vào danh mục API.
  2. Nhấp vào thẻ API nếu bạn chưa chọn.

  3. Nhấp vào biểu tượng + Thêm.

    Hộp thoại Thêm sản phẩm API vào danh mục sẽ xuất hiện.

  4. 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. Trang Thông tin chi tiết về API sẽ hiển thị.

  6. Định cấu hình nội dung tài liệu tham khảo API và chế độ hiển thị của tài liệu đó trên trang web:

    Trường Mô tả
    Đã xuất bản Chọn Đã xuất bản để xuất bản API lên cổng thông tin của bạn. Bỏ đánh dấu hộp này nếu bạn chưa sẵn sàng phát hành 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.
    Tiêu đề hiển thị Cập nhật tiêu đề của API xuất hiện trong danh mục. Theo mặc định, tên sản phẩm API sẽ được sử dụng. Bạn có thể thay đổi tiêu đề hiển thị sau, như mô tả trong phần Chỉnh sửa tiêu đề và nội dung mô tả hiển thị.
    Nội dung mô tả hiển thị Cập nhật nội dung mô tả API xuất hiện trong danh mục. Theo mặc định, nội dung mô tả sản phẩm API sẽ được sử dụng. Bạn có thể thay đổi nội dung mô tả hiển thị sau, như mô tả trong phần Chỉnh sửa tiêu đề và nội dung mô tả hiển thị.
    Yêu cầu nhà phát triển chỉ định URL gọi lại Bật nếu bạn muốn yêu cầu nhà phát triển ứng dụng chỉ định một URL gọi lại. Bạn có thể thêm hoặc cập nhật URL gọi lại sau, như mô tả trong phần Quản lý URL gọi lại cho API.
    Tài liệu API

    Cách sử dụng tài liệu OpenAPI:

    1. Chọn OpenAPI document (Tài liệu OpenAPI).
    2. Nhấp vào Chọn tài liệu.
    3. Thực hiện một trong các bước sau:
      • Nhấp vào thẻ Thông số kỹ thuật của tôi rồi chọn một thông số kỹ thuật trong cửa hàng thông số kỹ thuật.
      • Nhấp vào thẻ Tải tệp lên rồi tải tệp lên.
      • Nhấp vào thẻ Nhập từ URL rồi nhập thông số kỹ thuật từ URL.
    4. Nhấp vào Chọn.

    Cách sử dụng giản đồ GraphQL:

    1. Chọn Bản đồ GraphQL.
    2. Nhấp vào Chọn tài liệu.
    3. Chuyển đến và chọn giản đồ GraphQL.
    4. Nhấp vào Chọn.

    Ngoài ra, bạn có thể chọn Không có tài liệu rồi thêm tài liệu sau khi thêm API, như mô tả trong phần Quản lý ảnh chụp nhanh của tài liệu.

    Mức độ hiển thị của API

    Nếu bạn chưa đăng ký sử dụng bản phát hành beta của tính năng quản lý đối tượng, 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 API.
    • Người dùng đã đăng ký để chỉ cho phép người dùng đã đăng ký xem API.

    Nếu bạn đã đăng ký sử dụng bản phát hành beta của tính năng quản lý đối tượng, hãy chọn một trong các tuỳ chọn sau:

    • Công khai (mọi người đều có thể xem) để cho phép tất cả người dùng xem API.
    • Người dùng đã xác thực để chỉ cho phép người dùng đã đăng ký xem API.
    • Đối tượng đã chọn để chọn những đối tượng cụ thể mà bạn muốn có thể xem API.

    Bạn có thể quản lý chế độ hiển thị đối tượng sau, như mô tả trong phần Quản lý chế độ hiển thị của API trong cổng thông tin.

    Hình ảnh hiển thị Để hiển thị hình ảnh trên thẻ API trên trang API, hãy nhấp vào Chọn hình ảnh. Trong hộp thoại Chọn hình ảnh, hãy chọn một hình ảnh hiện có, tải một hình ảnh mới lên hoặc cung cấp URL của một hình ảnh bên ngoài rồi nhấp vào Chọn. Xem trước hình thu nhỏ API rồi nhấp vào Chọn. Bạn có thể thêm hình ảnh vào lúc khác, như mô tả trong phần Quản lý hình ảnh cho thẻ API. Khi bạn chỉ định một hình ảnh có URL bên ngoài, hình ảnh đó sẽ không được tải lên tài sản của bạn. Ngoài ra, việc tải hình ảnh trong cổng thông tin tích hợp sẽ phụ thuộc vào tình trạng của hình ảnh đó. Hình ảnh có thể bị chặn hoặc bị hạn chế theo chính sách bảo mật nội dung.
    Danh mục

    Thêm các danh mục mà API sẽ được gắn thẻ để cho phép nhà phát triển ứng dụng khám phá các API có liên quan trên trang API. Cách xác định một danh mục:

    • Chọn một danh mục trong danh sách thả xuống.
    • Thêm một danh mục mới bằng cách nhập tên danh mục rồi nhấn Enter. Danh mục mới sẽ được thêm vào trang Danh mục và được cung cấp khi thêm hoặc chỉnh sửa các API khác.

  7. Nhấp vào Lưu.

curl

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

curl -X POST "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs" \
    -H "Authorization: Bearer ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
       "title": "TITLE",
       "description": "DESCRIPTION",
       "anonAllowed": ANON_TRUE_OR_FALSE,
       "imageUrl": "IMAGE_URL",
       "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
       "categoryIds": [
         "CATEGORY_ID1",
         "CATEGORY_ID2"
       ],
       "published": PUBLISHED_TRUE_OR_FALSE,
        "apiProductName": "API_PRODUCT"
    }'

Thay thế nội dung sau:

  • ORG_NAME có tên của tổ chức. Ví dụ: my-org.
  • SITE_ID có tên của cổng thông tin, ở dạng ORG_NAME-PORTAL_NAME, trong đó ORG_NAME là tên của tổ chức và PORTAL_NAME là tên cổng thông tin được chuyển đổi thành chữ thường và xoá khoảng trắng và dấu gạch ngang. Ví dụ: my-org-myportal.
  • ACCESS_TOKEN có mã thông báo xác thực dùng để truy cập vào API Apigee Edge. Để biết thêm thông tin về xác thực và mã thông báo, hãy xem bài viết Xác thực quyền truy cập vào Edge API.
  • TITLE có tiêu đề hiển thị. Ví dụ: Hello World 2.
  • DESCRIPTION có nội dung mô tả màn hình. Ví dụ: Simple hello world example.
  • ANON_TRUE_OR_FALSE với true hoặc false (mặc định), trong đó true có nghĩa là API này có chế độ hiển thị công khai và có thể được xem ẩn danh; nếu không, chỉ người dùng đã đăng ký mới có thể xem API này.
  • IMAGE_URL có URL của hình ảnh bên ngoài được dùng cho mục trong danh mục hoặc đường dẫn tệp cho các tệp hình ảnh được lưu trữ trong cổng thông tin, ví dụ: /files/book-tree.jpg. Khi bạn chỉ định URL của hình ảnh bên ngoài, hình ảnh đó sẽ không được tải lên thành phần của bạn; ngoài ra, việc tải hình ảnh trong cổng thông tin tích hợp sẽ phụ thuộc vào tình trạng sẵn có của hình ảnh đó. Hình ảnh có thể bị chặn hoặc hạn chế theo chính sách bảo mật nội dung.
  • CALLBACK_TRUE_OR_FALSE với true hoặc false (mặc định), trong đó true yêu cầu người dùng cổng thông tin nhập URL khi quản lý ứng dụng.
  • CATEGORY_ID có mã nhận dạng của danh mục. Ví dụ: bf6505eb-2a0f-47af-a00a-ded40ac72960. Phân tách nhiều mã danh mục bằng dấu phẩy. Lấy mã danh mục bằng lệnh list API categories (liệt kê danh mục API).
  • PUBLISHED_TRUE_OR_FALSE với true hoặc false (mặc định), trong đó true cho biết API được cung cấp công khai. Khi phát hành, bạn có thể cho phép truy cập cho tất cả người dùng, người dùng đã xác thực hoặc người dùng cụ thể.
  • API_PRODUCT có tên của sản phẩm API. Ví dụ: Hello World 2.

Tải trọng phản hồi:

{
  "status": "success",
  "message": "API created",
  "data": {
    "id": 662423,
    "siteId": "my-org-myportal",
    "title": "My Test Catalog 4",
    "description": "",
    "published": false,
    "visibility": false,
    "apiId": "uxb9wjua",
    "apiProductName": "uXB9wJUa",
    "edgeAPIProductName": "uXB9wJUa",
    "specId": null,
    "specContent": null,
    "specTitle": null,
    "snapshotExists": false,
    "snapshotModified": null,
    "modified": 1729635493000,
    "anonAllowed": false,
    "imageUrl": null,
    "snapshotState": null,
    "requireCallbackUrl": false,
    "categoryIds": [],
    "specFormat": null,
    "specModified": null,
    "snapshotOutdated": null,
    "snapshotSourceMissing": false,
    "graphqlSchema": null,
    "graphqlEndpointUrl": null,
    "graphqlSchemaDisplayName": null,
    "grpcFileName": null,
    "grpcZipContent": null
  },
  "code": null,
  "request_id": "893346193",
  "error_code": null
}

Trong trường hợp:

  • modified: Thời gian sửa đổi gần đây nhất của mục danh mục tính bằng mili giây kể từ thời gian bắt đầu của hệ thống. Ví dụ: 1698165480000.
  • id: Mã của mặt hàng trong danh mục. Ví dụ: 399668.

Chỉnh sửa API

Sau khi thêm một API, hãy sử dụng giao diện người dùng hoặc lệnh gọi API để chỉnh sửa.

Phần này cung cấp ví dụ chi tiết về các bước cần thực hiện để sửa đổi một API hiện có trong cổng thông tin của bạn.

Hãy tham khảo các phần tiếp theo để biết các chế độ cài đặt sửa đổi cụ thể.

Giao diện người dùng

Cách chỉnh sửa API:

  1. Truy cập vào danh mục API.
  2. Nhấp vào thẻ API nếu bạn chưa chọn.
  3. Nhấp vào hàng của API mà bạn muốn chỉnh sửa.
  4. Nhấp vào biểu tượng chỉnh sửaChỉnh sửa.
  5. Trong phần Thông tin chi tiết về API, hãy thực hiện mọi sửa đổi. Xem nội dung mô tả về các tuỳ chọn trong phần Thêm API.
  6. Nhấp vào Lưu.

curl

Sau khi thêm một API, hãy sử dụng lệnh gọi cập nhật để chỉnh sửa.

Ví dụ này hướng dẫn bạn thực hiện các bước cần thiết để thay đổi trạng thái đã phát hành của API trong cổng thông tin từ true thành false. Bạn có thể thay đổi nhiều chế độ cài đặt trong một lệnh gọi API nếu cần.

  1. Để xác định vị trí id được tạo giúp xác định riêng từng API, hãy lấy danh sách các API trong cổng thông tin của bạn như mô tả trong phần Khám phá API.

  2. Trả về các giá trị hiện tại cho một API cụ thể:

    curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
-H "Authorization: Bearer ACCESS_TOKEN"

    Thay thế nội dung sau:

    • ORG_NAME có tên của tổ chức. Ví dụ: my-org.
    • SITE_ID có tên của cổng thông tin, ở dạng ORG_NAME-PORTAL_NAME, trong đó ORG_NAME là tên của tổ chức và PORTAL_NAME là tên cổng thông tin được chuyển đổi thành chữ thường và xoá khoảng trắng và dấu gạch ngang. Ví dụ: my-org-myportal.
    • API_DOC với id được tạo của tài liệu. Ví dụ: 399668. Sử dụng lệnh list API docs (liệt kê tài liệu API) để tìm giá trị này.
    • ACCESS_TOKEN có mã thông báo xác thực dùng để truy cập vào API Apigee Edge. Để biết thêm thông tin về xác thực và mã thông báo, hãy xem bài viết Xác thực quyền truy cập vào Edge API.

    Tải trọng phản hồi:

    {
  "status": "success",
  "message": "apidoc returned",
  "data": {
    "id": 662423,
    "siteId": "my-org-myportal",
    "title": "My Test Catalog 4",
    "description": "",
    "published": false,
    "visibility": false,
    "apiId": "uxb9wjua",
    "apiProductName": "uXB9wJUa",
    "edgeAPIProductName": "uXB9wJUa",
    "specId": null,
    "specContent": null,
    "specTitle": null,
    "snapshotExists": false,
    "snapshotModified": null,
    "modified": 1729635493000,
    "anonAllowed": false,
    "imageUrl": null,
    "snapshotState": null,
    "requireCallbackUrl": false,
    "categoryIds": [],
    "specFormat": null,
    "specModified": null,
    "snapshotOutdated": false,
    "snapshotSourceMissing": false,
    "graphqlSchema": null,
    "graphqlEndpointUrl": null,
    "graphqlSchemaDisplayName": null,
    "grpcFileName": null,
    "grpcZipContent": null
  },
  "code": null,
  "request_id": "601210268",
  "error_code": null
}

  1. Đưa các giá trị có thể thay đổi mà bạn muốn giữ lại vào lệnh gọi cập nhật và sửa đổi các giá trị mà bạn muốn thay đổi. Nếu bạn bỏ qua một dòng, chế độ cài đặt mặc định sẽ được sử dụng. Đối với ví dụ này, hãy thay đổi chế độ cài đặt đã xuất bản từ false thành true:

    curl -X PUT "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
 -H "Authorization: Bearer ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
    "title": "TITLE",
    "anonAllowed": true,
    "published": true
 }'

    Thay thế nội dung sau:

    • TITLE có tiêu đề hiển thị. Ví dụ: Hello World 2.

    Tải trọng phản hồi:

    {
  "status": "success",
  "message": "ApiDoc updated",
  "data": {
    "id": 662423,
    "siteId": "my-org-myportal",
    "title": "My Test Catalog 4",
    "description": "",
    "published": true,
    "visibility": true,
    "apiId": "uxb9wjua",
    "apiProductName": "uXB9wJUa",
    "edgeAPIProductName": "uXB9wJUa",
    "specId": null,
    "specContent": null,
    "specTitle": null,
    "snapshotExists": false,
    "snapshotModified": null,
    "modified": 1729989250000,
    "anonAllowed": true,
    "imageUrl": null,
    "snapshotState": null,
    "requireCallbackUrl": false,
    "categoryIds": [],
    "specFormat": null,
    "specModified": null,
    "snapshotOutdated": null,
    "snapshotSourceMissing": false,
    "graphqlSchema": null,
    "graphqlEndpointUrl": null,
    "graphqlSchemaDisplayName": null,
    "grpcFileName": null,
    "grpcZipContent": null
  },
  "code": null,
  "request_id": "738172002",
  "error_code": null
}

Quản lý ảnh chụp nhanh của tài liệu

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

Cách quản lý ảnh chụp nhanh của tài liệu:

  1. Truy cập vào danh mục API.
  2. Nhấp vào thẻ API nếu bạn chưa chọn.
  3. Nhấp vào hàng của API mà bạn muốn chỉnh sửa.
  4. Kiểm tra trạng thái ảnh chụp nhanh. Nếu tệp này đã lỗi thời, thông báo sau sẽ xuất hiện: Biểu tượng và thông báo cho biết ảnh chụp nhanh đã lỗi thời
  5. Nhấp vào biểu tượng chỉnh sửa.
  6. Thực hiện một trong các thao tác sau:
    • Để làm mới bản tổng quan nhanh của một tài liệu OpenAPI đã lỗi thời, hãy nhấp vào Làm mới bản tổng quan nhanh.
    • Để thay đổi tài liệu dùng để tạo tài liệu cho API, trong phần tài liệu API, hãy nhấp vào Chọn tài liệu rồi chọn tài liệu mới.
  7. Nhấp vào Lưu.

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

Xuất bản là quy trình cung cấp API của bạn cho nhà phát triển ứng dụng sử dụng.

Sử dụng giao diện người dùng hoặc lệnh curl để xuất bản hoặc huỷ xuất bản API trên cổng thông tin của bạn.

Giao diện người dùng

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

  1. Truy cập vào danh mục API.
  2. Nhấp vào thẻ API nếu bạn chưa chọn.
  3. Nhấp vào hàng của API mà bạn muốn chỉnh sửa.
  4. Nhấp vào Biểu tượng chỉnh sửa Chỉnh sửa.
  5. Trong phần Thông tin chi tiết về API, hãy chọn hoặc bỏ chọn Đã xuất bản (có trong danh mục) để xuất bản hoặc huỷ xuất bản API trên cổng thông tin của bạn.
  6. Nhấp vào Lưu.

curl

Thêm một trong những thông tin sau vào lệnh gọi cập nhật:

"published": true,    # API is published to your portal
"published": false,   # API is not published in your portal

Cách chỉnh sửa API:

  1. Trả về các giá trị hiện tại:

    curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs" \
-H "Authorization: Bearer ACCESS_TOKEN"

  2. Sử dụng lệnh gọi cập nhật để chỉnh sửa API. Bao gồm các giá trị có thể thay đổi mà bạn muốn giữ lại và sửa đổi các giá trị mà bạn muốn thay đổi. Nếu bạn bỏ qua một chế độ cài đặt có thể thay đổi, chế độ cài đặt đó sẽ bị ghi đè bằng giá trị mặc định.

    curl -X PUT "https://api.enterprise.apigee.com/v1/organizations/  ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
 -H "Authorization: Bearer ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
    "title": "TITLE",
    "description": "DESCRIPTION",
    "anonAllowed": ANON_TRUE_OR_FALSE,
    "imageUrl": IMAGE_URL,
    "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
    "categoryIds": [
      "CATEGORY_ID1",
     "CATEGORY_ID2"
    ],
    "published": PUBLISHED_TRUE_OR_FALSE
}

Hãy xem phần Quản lý phiên bản tài liệu để biết ví dụ chi tiết về các bước, biến và tải trọng được trả về.

Quản lý chế độ hiển thị của một API trong cổng thông tin

Quản lý chế độ hiển thị của một API trong cổng thông tin bằng cách cho phép truy cập vào:

Sử dụng giao diện người dùng hoặc lệnh curl để quản lý chế độ hiển thị của một API trong cổng thông tin:

Giao diện người dùng

Cách quản lý chế độ hiển thị của một API trong cổng thông tin:

  1. Truy cập vào danh mục API.
  2. Nhấp vào thẻ API nếu bạn chưa chọn.
  3. Nhấp vào hàng của API mà bạn muốn chỉnh sửa.
  4. Nhấp vào Biểu tượng chỉnh sửa Chỉnh sửa.

  5. Chọn chế độ hiển thị. Nếu bạn đã đăng ký sử dụng bản phát hành beta của tính năng đối tượng, hãy chọn một trong các tuỳ chọn sau:

    • Công khai (mọi người đều có thể xem) để cho phép tất cả người dùng xem trang.
    • Người dùng đã xác thực để chỉ cho phép người dùng đã đăng ký xem trang.
    • Đối tượng đã chọn để chọn những đối tượng cụ thể mà bạn muốn có thể xem trang. Xem bài viết Quản lý đối tượng cho cổng thông tin.
    Nếu không, hãy chọn một trong các tuỳ chọn sau:
    • 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.

  6. Nhấp vào Gửi.

curl

Nếu bạn đã đăng ký bản phát hành beta của tính năng quản lý đối tượng, hãy sử dụng giao diện người dùng để quản lý đối tượng.

Nếu bạn chưa đăng ký sử dụng tính năng quản lý đối tượng, chế độ hiển thị sẽ được quản lý bằng anonAllowed.

Thêm một trong các lệnh sau vào lệnh gọi update:

  # When not enrolled in the beta release of the audience management feature:

  "anonAllowed": true,      # Anonymous users can see the API
  "anonAllowed": false,     # Only registered users can see the API

Cách chỉnh sửa API:

  1. Trả về các giá trị hiện tại:

    curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer ACCESS_TOKEN"

  2. Sử dụng lệnh gọi cập nhật để chỉnh sửa API. Bao gồm các giá trị có thể thay đổi mà bạn muốn giữ lại và chỉnh sửa các giá trị mà bạn muốn thay đổi. Nếu bạn bỏ qua một chế độ cài đặt có thể thay đổi, hệ thống sẽ sử dụng giá trị mặc định.

    curl -X PUT "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
        "title": "TITLE",
        "description": "DESCRIPTION",
        "anonAllowed": ANON_TRUE_OR_FALSE,
        "imageUrl": IMAGE_URL,
        "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
        "categoryIds": [
          "CATEGORY_ID1",
          "CATEGORY_ID2"
        ],
        "published": PUBLISHED_TRUE_OR_FALSE
     }'

Hãy xem phần Chỉnh sửa API để biết ví dụ chi tiết về các bước, biến và tải trọng được trả về.

Quản lý URL gọi lại cho một API

Quản lý URL gọi lại cho một API. Xem bài viết Giới thiệu về URL gọi lại.

Sử dụng giao diện người dùng hoặc lệnh curl để quản lý URL gọi lại cho một API:

Giao diện người dùng

Cách quản lý URL gọi lại cho một API:

  1. Truy cập vào danh mục API.
  2. Nhấp vào thẻ API nếu bạn chưa chọn.
  3. Nhấp vào hàng của API mà bạn muốn chỉnh sửa.
  4. Nhấp vào Biểu tượng chỉnh sửa Chỉnh sửa.
  5. Trong phần Thông tin chi tiết về API, hãy chọn hoặc bỏ chọn hộp đánh dấu Yêu cầu nhà phát triển chỉ định URL gọi lại.
  6. Nhấp vào Lưu.

curl

Thêm một trong các lệnh sau vào lệnh gọi update:

  "requireCallbackUrl": true,    # Portal user is required to input a URL
  "requireCallbackUrl": false,   # Portal user is not required to input a URL

Cách chỉnh sửa API:

  1. Trả về các giá trị hiện tại:

    curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer ACCESS_TOKEN"

  2. Sử dụng lệnh gọi cập nhật để chỉnh sửa API. Bao gồm các giá trị có thể thay đổi mà bạn muốn giữ lại và chỉnh sửa các giá trị mà bạn muốn thay đổi. Nếu bạn bỏ qua một chế độ cài đặt có thể thay đổi, hệ thống sẽ sử dụng giá trị mặc định.

    curl -X PUT "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
        "title": "TITLE",
        "description": "DESCRIPTION",
        "anonAllowed": ANON_TRUE_OR_FALSE,
        "imageUrl": IMAGE_URL,
        "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
        "categoryIds": [
          "CATEGORY_ID1",
          "CATEGORY_ID2"
        ],
        "published": PUBLISHED_TRUE_OR_FALSE
     }'

Hãy xem phần Chỉnh sửa API để biết ví dụ chi tiết về các bước, biến và tải trọng được trả về.

Quản lý hình ảnh cho thẻ API

Quản lý hình ảnh xuất hiện cùng với thẻ API trên trang API bằng cách thêm hoặc thay đổi hình ảnh hiện tại.

Sử dụng giao diện người dùng hoặc lệnh curl để quản lý hình ảnh cho thẻ API:

Giao diện người dùng

Cách quản lý hình ảnh cho thẻ API:

  1. Truy cập vào danh mục API.
  2. Nhấp vào thẻ API nếu bạn chưa chọn.
  3. Nhấp vào hàng của API mà bạn muốn chỉnh sửa.
  4. Nhấp vào Biểu tượng chỉnh sửa Chỉnh sửa.

  5. Trong phần Thông tin chi tiết về API:

    • Nhấp vào Chọn hình ảnh để chỉ định hoặc tải hình ảnh lên nếu bạn chưa chọn hình ảnh nào.
    • Nhấp vào Thay đổi hình ảnh để chỉ định hoặc tải một hình ảnh khác lên.
    • Nhấp vào biểu tượng x trong hình ảnh để xoá hình ảnh đó.

    Khi chỉ định hình ảnh, hãy chỉ định một hình ảnh có URL bên ngoài được dùng cho mặt hàng trong danh mục hoặc đường dẫn cho các tệp hình ảnh được lưu trữ trong cổng thông tin, ví dụ: /files/book-tree.jpg. Khi bạn chỉ định URL của hình ảnh bên ngoài, hình ảnh đó sẽ không được tải lên tài sản của bạn; ngoài ra, việc tải hình ảnh trong cổng thông tin tích hợp sẽ phụ thuộc vào tình trạng sẵn có của hình ảnh đó. Hình ảnh có thể bị chặn hoặc hạn chế theo chính sách bảo mật nội dung.

  6. Nhấp vào Lưu.

curl

Thêm nội dung sau vào lệnh gọi update:

  # Omit line for no image file

  "imageUrl": "IMAGE_URL"    # URL of the external image or name of the image file

Cách chỉnh sửa API:

  1. Trả về các giá trị hiện tại:

    curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer ACCESS_TOKEN"

  2. Sử dụng lệnh gọi cập nhật để chỉnh sửa API. Bao gồm các giá trị có thể thay đổi mà bạn muốn giữ lại và chỉnh sửa các giá trị mà bạn muốn thay đổi. Nếu bạn bỏ qua một chế độ cài đặt có thể thay đổi, hệ thống sẽ sử dụng giá trị mặc định.

    curl -X PUT "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
        "title": "TITLE",
        "description": "DESCRIPTION",
        "anonAllowed": ANON_TRUE_OR_FALSE,
        "imageUrl": IMAGE_URL,
        "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
        "categoryIds": [
          "CATEGORY_ID1",
          "CATEGORY_ID2"
        ],
        "published": PUBLISHED_TRUE_OR_FALSE
     }'

Hãy xem phần Chỉnh sửa API để biết ví dụ chi tiết về các bước, biến và tải trọng được trả về.

Gắn thẻ API bằng danh mục

Việc sử dụng danh mục giúp nhà phát triển ứng dụng khám phá các API có liên quan. Xem thêm bài viết Quản lý danh mục.

Gắn thẻ API bằng danh mục theo một trong những cách sau:

  • Quản lý các danh mục mà API được gắn thẻ khi chỉnh sửa API, như mô tả dưới đây.
  • Quản lý các API được gắn thẻ vào một danh mục khi chỉnh sửa danh mục.

Sử dụng giao diện người dùng hoặc lệnh curl để gắn thẻ API bằng các danh mục:

Giao diện người dùng

Cách gắn thẻ API cho các danh mục khi chỉnh sửa API:

  1. Truy cập vào danh mục API.
  2. Nhấp vào thẻ API nếu bạn chưa chọn.
  3. Nhấp vào hàng của API mà bạn muốn chỉnh sửa.
  4. Nhấp vào Biểu tượng chỉnh sửa Chỉnh sửa.
  5. Nhấp vào trường Danh mục rồi thực hiện một trong các bước sau:
    • Chọn một danh mục trong danh sách thả xuống.
    • Thêm một danh mục mới bằng cách nhập tên danh mục rồi nhấn Enter. Danh mục mới sẽ được thêm vào trang Danh mục và được cung cấp khi thêm hoặc chỉnh sửa các API khác.
  6. Lặp lại để gắn thẻ API cho nhiều danh mục hơn.
  7. Nhấp vào Lưu.

curl

Thêm nội dung sau vào lệnh gọi update:

  # Omit line for no categories

  "categoryIds": [
      "CATEGORY_ID1",      # A category ID number
      "CATEGORY_ID2"       # A category ID number
    ],

Sử dụng lệnh list categories (liệt kê danh mục) để lấy mã danh mục.

Cách chỉnh sửa API:

  1. Trả về các giá trị hiện tại:

    curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer ACCESS_TOKEN"

  2. Sử dụng lệnh gọi cập nhật để chỉnh sửa API. Bao gồm các giá trị có thể thay đổi mà bạn muốn giữ lại và chỉnh sửa các giá trị mà bạn muốn thay đổi. Nếu bạn bỏ qua một chế độ cài đặt có thể thay đổi, hệ thống sẽ sử dụng giá trị mặc định.

    curl -X PUT "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
        "title": "TITLE",
        "description": "DESCRIPTION",
        "anonAllowed": ANON_TRUE_OR_FALSE,
        "imageUrl": IMAGE_URL,
        "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
        "categoryIds": [
          "CATEGORY_ID1",
          "CATEGORY_ID2"
        ],
        "published": PUBLISHED_TRUE_OR_FALSE
     }'

Hãy xem phần Chỉnh sửa API để biết ví dụ chi tiết về các bước, biến và tải trọng được trả về.

Chỉnh sửa tiêu đề hiển thị và nội dung mô tả

Sử dụng giao diện người dùng hoặc lệnh curl để chỉnh sửa tiêu đề và nội dung mô tả hiển thị:

Giao diện người dùng

Cách chỉnh sửa tiêu đề và nội dung mô tả hiển thị:

  1. Truy cập vào danh mục API.
  2. Nhấp vào thẻ API nếu bạn chưa chọn.
  3. Nhấp vào hàng của API mà bạn muốn chỉnh sửa.
  4. Nhấp vào Biểu tượng chỉnh sửa Chỉnh sửa.
  5. Chỉnh sửa các trường Tiêu đề hiển thị và Nội dung mô tả hiển thị (nếu cần).
  6. Nhấp vào Lưu.

curl

Thêm nội dung sau vào lệnh gọi update:

  "title": "TITLE",    # Display title
  "description": "DESCRIPTION",  # Display description

Cách chỉnh sửa API:

  1. Trả về các giá trị hiện tại:

    curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer ACCESS_TOKEN"

  2. Sử dụng lệnh gọi cập nhật để chỉnh sửa API. Bao gồm các giá trị có thể thay đổi mà bạn muốn giữ lại và chỉnh sửa các giá trị mà bạn muốn thay đổi. Nếu bạn bỏ qua một chế độ cài đặt có thể thay đổi, hệ thống sẽ sử dụng giá trị mặc định.

    curl -X PUT "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
        "title": "TITLE",
        "description": "DESCRIPTION",
        "anonAllowed": ANON_TRUE_OR_FALSE,
        "imageUrl": IMAGE_URL,
        "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
        "categoryIds": [
          "CATEGORY_ID1",
          "CATEGORY_ID2"
        ],
        "published": PUBLISHED_TRUE_OR_FALSE
     }'

Hãy xem phần Chỉnh sửa API để biết ví dụ chi tiết về các bước, biến và tải trọng được trả về.

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

Sử dụng giao diện người dùng hoặc lệnh curl để xoá một API khỏi cổng thông tin:

Giao diện người dùng

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

  1. Truy cập vào danh mục API.
  2. Chọn API nếu bạn chưa chọn.
  3. Đặt con trỏ lên API trong danh sách để hiển thị trình đơn thao tác.
  4. Nhấp vào Biểu tượng xóa Xoá.

curl

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

curl -X DELETE "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
    -H "Authorization: Bearer ACCESS_TOKEN"

Thay thế nội dung sau:

  • ORG_NAME có tên của tổ chức. Ví dụ: my-org.
  • SITE_ID có tên của cổng thông tin, ở dạng ORG_NAME-PORTAL_NAME, trong đó ORG_NAME là tên của tổ chức và PORTAL_NAME là tên cổng thông tin được chuyển đổi thành chữ thường và xoá khoảng trắng và dấu gạch ngang. Ví dụ: my-org-myportal.
  • API_DOC với id được tạo của tài liệu. Ví dụ: 399668. Sử dụng lệnh list API docs (liệt kê tài liệu API) để tìm giá trị này.
  • ACCESS_TOKEN có mã thông báo xác thực dùng để truy cập vào API Apigee Edge. Để biết thêm thông tin về xác thực và mã thông báo, hãy xem bài viết Xác thực quyền truy cập vào Edge API.

Tải trọng phản hồi:

{
  "status": "success",
  "message": "Apidoc deleted",
  "data": {
  },
  "code": null,
  "request_id": "1790036484",
  "error_code": null
}

Quản lý tài liệu API

Các phần sau đây mô tả cách cập nhật, tải xuống hoặc xoá tài liệu API.

Cập nhật tài liệu về API

Cách tải một phiên bản khác của tài liệu API lên:

Giao diện người dùng

  1. Truy cập vào danh mục API.
  2. Nhấp vào thẻ API nếu bạn chưa chọn.
  3. Nhấp vào hàng của API mà bạn muốn chỉnh sửa.
  4. Kiểm tra trạng thái ảnh chụp nhanh. Nếu tệp này đã lỗi thời, thông báo sau sẽ xuất hiện: Biểu tượng và thông báo cho biết ảnh chụp nhanh đã lỗi thời
  5. Nhấp vào Chỉnh sửa.
  6. Thực hiện một trong các thao tác sau:
    • Để làm mới bản tổng quan nhanh của tài liệu OpenAPI đã lỗi thời, hãy nhấp vào Refresh Snapshot (Làm mới bản tổng quan nhanh).
    • Để thay đổi tài liệu dùng để tạo tài liệu cho API, trong phần tài liệu API, hãy nhấp vào Chọn tài liệu rồi chọn tài liệu mới.
  7. Trong ngăn Tài liệu API, hãy chọn một trong các mục sau:
    • Tài liệu OpenAPI
    • Giản đồ GraphQL
  8. Nhấp vào Chọn tài liệu rồi chọn phiên bản tài liệu mới nhất.
  9. Đối với GraphQL, hãy chỉ định URL điểm cuối.
  10. Nhấp vào Lưu.

Tài liệu tham khảo API được hiển thị từ tài liệu và được thêm vào trang Tài liệu tham khảo API. Trạng thái ảnh chụp nhanh được cập nhật thành hiện tại:

Biểu tượng và thông báo cho biết ảnh chụp nhanh là hiện tại

curl

Cách cập nhật nội dung tài liệu OpenAPI hoặc GraphQL:

OpenAPI

curl -X PATCH "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
    -H "Authorization: Bearer ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"oasDocumentation": {
           "spec":{ "displayName":"DISPLAY_NAME",
                    "contents":"CONTENTS"}
            }
        }'

Thay thế nội dung sau:

  • ORG_NAME có tên của tổ chức. Ví dụ: my-org.
  • SITE_ID có tên của cổng thông tin, ở dạng ORG_NAME-PORTAL_NAME, trong đó ORG_NAME là tên của tổ chức và PORTAL_NAME là tên cổng thông tin được chuyển đổi thành chữ thường và xoá khoảng trắng và dấu gạch ngang. Ví dụ: my-org-myportal.
  • API_DOC với id được tạo của tài liệu. Ví dụ: 399668. Sử dụng lệnh list API docs (liệt kê tài liệu API) để tìm giá trị này.
  • DISPLAY_NAME có tên hiển thị của tài liệu API. Ví dụ: Hello World 2.
  • CONTENTS với chuỗi nội dung được mã hoá base64 của tài liệu API. Hầu hết các môi trường phát triển đều chứa tiện ích chuyển đổi base64 hoặc có nhiều công cụ chuyển đổi trực tuyến.

Tải trọng phản hồi:

{
 "status":"success",
 "message":"Api documentation updated",
 "requestId":"645138278"
 "data": {
   "oasDocumentation": {
     "spec": {
        "displayName": "Hello World 2"
      },
     "Format": "YAML"
   }
 }
}

GraphQL

curl -X PATCH "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"graphqlDocumentation": {
         "schema":{"displayName":"DISPLAY_NAME",
         "contents":"CONTENTS"},
         "endpointUri": "ENDPOINT_URI"
          }
      }'

Thay thế nội dung sau:

  • ORG_NAME có tên của tổ chức. Ví dụ: my-org.
  • SITE_ID có tên của cổng thông tin, ở dạng ORG_NAME-PORTAL_NAME, trong đó ORG_NAME là tên của tổ chức và PORTAL_NAME là tên cổng thông tin được chuyển đổi thành chữ thường và xoá khoảng trắng và dấu gạch ngang. Ví dụ: my-org-myportal.
  • API_DOC với id được tạo của tài liệu. Ví dụ: 399668. Sử dụng lệnh list API docs (liệt kê tài liệu API) để tìm giá trị này.
  • DISPLAY_NAME có tên hiển thị của tài liệu API. Ví dụ: Hello World 2.
  • ENDPOINT_URI với tên miền của URI điểm cuối. Ví dụ: https://demo.google.com/graphql.
  • CONTENTS với chuỗi nội dung được mã hoá base64 của tài liệu API. Hầu hết các môi trường phát triển đều chứa tiện ích chuyển đổi base64 hoặc có nhiều công cụ chuyển đổi trực tuyến.

Tải trọng phản hồi:

{
"status": "success",
"message": "ApiDocDocumentation updated",
"data": {
  "oasDocumentation": null,
  "graphqlDocumentation": {
    "schema": {
      "displayName": "schema.docs.graphql",
      "contents": ""
    },
    "endpointUri": "https://demo.google.com/graphql"
  }
},
"code": null,
"request_id": "640336173",
"error_code": null
}

Tài liệu tham khảo API được hiển thị từ tài liệu và được thêm vào trang API của cổng thông tin trực tiếp.

Tải tài liệu về API xuống

Cách tải tài liệu về API xuống:

Giao diện người dùng

curl

Cách tải tài liệu API xuống bằng lệnh get documentation (tải tài liệu):

curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
    -H "Authorization: Bearer ACCESS_TOKEN"

Thay thế nội dung sau:

  • ORG_NAME có tên của tổ chức. Ví dụ: my-org.
  • SITE_ID có tên của cổng thông tin, ở dạng ORG_NAME-PORTAL_NAME, trong đó ORG_NAME là tên của tổ chức và PORTAL_NAME là tên cổng thông tin được chuyển đổi thành chữ thường và xoá khoảng trắng và dấu gạch ngang. Ví dụ: my-org-myportal.

  • API_DOC với id được tạo của tài liệu. Ví dụ: 399668. Sử dụng lệnh list API docs (liệt kê tài liệu API) để tìm giá trị này.

    Tải trọng phản hồi:

{
  "status": "success",
  "message": "ApiDocDocumentation returned",
  "data": {
    "oasDocumentation": {
      "spec": {
        "displayName": "mock",
        "contents": "b3BlbmFwaTogMy4wLjAKaW5mbzoKICBkZXNjcmlw ..."
      },
      "format": "YAML"
    },
    "graphqlDocumentation": null
  },
  "code": null,
  "request_id": "269996898",
  "error_code": null
}

Trong trường hợp:

contents: Chuỗi nội dung được mã hoá base64 của tài liệu API.

Xoá tài liệu API

Cách xoá tài liệu về API:

Giao diện người dùng

  1. Truy cập vào danh mục API.
  2. Nhấp vào thẻ API nếu bạn chưa chọn.
  3. Nhấp vào hàng của API mà bạn muốn chỉnh sửa.
  4. Nhấp vào Chỉnh sửa.
  5. Trong ngăn Tài liệu về API, hãy chọn Không có tài liệu.
  6. Nhấp vào Lưu.

curl

Để xoá nội dung hiện có, hãy sử dụng update API:

curl -X PATCH "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
    -H "Authorization: Bearer ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{}'

Thay thế nội dung sau:

  • ORG_NAME có tên của tổ chức. Ví dụ: my-org.
  • SITE_ID có tên của cổng thông tin, ở dạng ORG_NAME-PORTAL_NAME, trong đó ORG_NAME là tên của tổ chức và PORTAL_NAME là tên cổng thông tin được chuyển đổi thành chữ thường và xoá khoảng trắng và dấu gạch ngang. Ví dụ: my-org-myportal.
  • API_DOC với id được tạo của tài liệu. Ví dụ: 399668. Sử dụng lệnh list API docs (liệt kê tài liệu API) để tìm giá trị này.

Tải trọng phản hồi:

{
  "status": "success",
  "message": "ApiDocDocumentation updated",
  "data": {
    "oasDocumentation": null,
    "graphqlDocumentation": null
  },
  "code": null,
  "request_id": "304329676",
  "error_code": null
}

Quản lý các danh mục dùng để khám phá các API có liên quan

Gắn thẻ API bằng các danh mục để cho phép nhà phát triển ứng dụng khám phá các API có liên quan trên trang API của cổng thông tin đang hoạt động. Thêm và quản lý các danh mục như mô tả trong các phần sau.

Khám phá các danh mục

Sử dụng giao diện người dùng hoặc lệnh curl để xem các API trong cổng thông tin của bạn.

Giao diện người dùng

Cách xem trang Danh mục:

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

    Ngoài ra, bạn có thể chọn Danh mục 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 thẻ Danh mục.

Thẻ Categories (Danh mục) trong danh mục API hiển thị danh sách các danh mục đã được xác định cho cổng thông tin của bạn.

Thẻ Danh mục cho biết tên danh mục, tên và tổng số API được chỉ định

Như đã nêu trong hình trước, trang API cho phép bạn:

curl

Cách liệt kê danh mục:

curl -X GET "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories" \
    -H "Authorization: Bearer ACCESS_TOKEN"

Thay thế nội dung sau:

  • ORG_NAME có tên của tổ chức. Ví dụ: my-org.
  • SITE_ID có tên của cổng thông tin, ở dạng ORG_NAME-PORTAL_NAME, trong đó ORG_NAME là tên của tổ chức và PORTAL_NAME là tên cổng thông tin được chuyển đổi thành chữ thường và xoá khoảng trắng và dấu gạch ngang. Ví dụ: my-org-myportal.
  • ACCESS_TOKEN có mã thông báo xác thực dùng để truy cập vào API Apigee Edge. Để biết thêm thông tin về xác thực và mã thông báo, hãy xem bài viết Xác thực quyền truy cập vào Edge API.

Tải trọng phản hồi:

{
  "status": "success",
  "message": "all ApiCategory items returned",
  "data": [
    {
      "id": "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
      "siteId": "my-org-myportal",
      "name": "My Category"
    },
    {
      "id": "61c1014c-89c9-40e6-be3c-69cca3505620",
      "siteId": "my-org-myportal",
      "name": "test2"
    }
  ],
  "code": null,
  "request_id": "1263510680",
  "error_code": null
}

Trong trường hợp:

  • id: Mã của mục danh mục. Ví dụ: 61c1014c-89c9-40e6-be3c-69cca3505620.

Thêm danh mục

Thêm danh mục theo một trong các cách sau:

Danh mục mới sẽ được thêm vào trang Danh mục và được cung cấp khi thêm hoặc chỉnh sửa các API khác.

Sử dụng giao diện người dùng hoặc lệnh curl để thêm danh mục:

Giao diện người dùng

Cách thêm danh mục theo cách thủ công:

  1. Truy cập vào trang Danh mục.
  2. Nhấp vào biểu tượng + Thêm.
  3. Nhập tên cho danh mục mới.
  4. Bạn có thể chọn một hoặc nhiều API để gắn thẻ cho danh mục.
  5. Nhấp vào Tạo.

curl

Cách thêm danh mục:

curl -X POST "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories" \
    -H "Authorization: Bearer ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"name": "CATEGORY_NAME" }'

Thay thế nội dung sau:

  • ORG_NAME có tên của tổ chức. Ví dụ: my-org.
  • SITE_ID có tên của cổng thông tin, ở dạng ORG_NAME-PORTAL_NAME, trong đó ORG_NAME là tên của tổ chức và PORTAL_NAME là tên cổng thông tin được chuyển đổi thành chữ thường và xoá khoảng trắng và dấu gạch ngang. Ví dụ: my-org-myportal.
  • ACCESS_TOKEN có mã thông báo xác thực dùng để truy cập vào API Apigee Edge. Để biết thêm thông tin về xác thực và mã thông báo, hãy xem bài viết Xác thực quyền truy cập vào Edge API.
  • CATEGORY_NAME có tên của danh mục. Ví dụ: demo-backend.

Tải trọng phản hồi:

{
  "status": "success",
  "message": "API category created",
  "data": {
    "id": "61de810e-b48b-4cc1-8f22-959038aadcce",
    "siteId": "my-org-myportal",
    "name": "demo-backend"
  },
  "code": null,
  "request_id": "363146927",
  "error_code": null
}

Chỉnh sửa danh mục

Sử dụng giao diện người dùng hoặc lệnh curl để chỉnh sửa danh mục:

Giao diện người dùng

Cách chỉnh sửa danh mục:

  1. Truy cập vào trang Danh mục.
  2. Nhấp vào Chỉnh sửa.
  3. Chỉnh sửa tên danh mục.
  4. Thêm hoặc xoá thẻ API.
  5. Nhấp vào Lưu.

curl

Cách chỉnh sửa danh mục:

curl -X PATCH "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories/CATEGORY_ID"  \
    -H "Authorization: Bearer ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"name": "CATEGORY_NAME" }'

Thay thế nội dung sau:

  • ORG_NAME có tên của tổ chức. Ví dụ: my-org.
  • SITE_ID có tên của cổng thông tin, ở dạng ORG_NAME-PORTAL_NAME, trong đó ORG_NAME là tên của tổ chức và PORTAL_NAME là tên cổng thông tin được chuyển đổi thành chữ thường và xoá khoảng trắng và dấu gạch ngang. Ví dụ: my-org-myportal.
  • CATEGORY_ID có mã nhận dạng của danh mục. Ví dụ: bf6505eb-2a0f-47af-a00a-ded40ac72960. Phân tách nhiều mã danh mục bằng dấu phẩy. Lấy mã danh mục bằng lệnh list API categories (liệt kê danh mục API).
  • ACCESS_TOKEN có mã thông báo xác thực dùng để truy cập vào API Apigee Edge. Để biết thêm thông tin về xác thực và mã thông báo, hãy xem bài viết Xác thực quyền truy cập vào Edge API.
  • CATEGORY_NAME có tên của danh mục. Ví dụ: demo-backend.

Tải trọng phản hồi:

{
  "status": "success",
  "message": "ApiCategory updated",
  "data": {
    "id": "61de810e-b48b-4cc1-8f22-959038aadcce",
    "siteId": "my-org-myportal",
    "name": "demo-backend-test"
  },
  "code": null,
  "request_id": "1976875617",
  "error_code": null
}

Xóa danh mục

Khi bạn xoá một danh mục, tất cả thẻ API liên quan đến danh mục đó cũng sẽ bị xoá.

Sử dụng giao diện người dùng hoặc lệnh curl để xoá một danh mục:

Giao diện người dùng

Cách xoá danh mục:

  1. Truy cập vào trang Danh mục.
  2. Đặt con trỏ lên danh mục mà bạn muốn chỉnh sửa để trình đơn thao tác xuất hiện.
  3. Nhấp vào Xoá.
  4. Nhấp vào Xoá để xác nhận.

curl

Cách xoá một danh mục:

curl -X DELETE "https://api.enterprise.apigee.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories/CATEGORY_ID" \
    -H "Authorization: Bearer ACCESS_TOKEN" \
    -H "Content-Type: application/json"

Thay thế nội dung sau:

  • ORG_NAME có tên của tổ chức. Ví dụ: my-org.
  • SITE_ID có tên của cổng thông tin, ở dạng ORG_NAME-PORTAL_NAME, trong đó ORG_NAME là tên của tổ chức và PORTAL_NAME là tên cổng thông tin được chuyển đổi thành chữ thường và xoá khoảng trắng và dấu gạch ngang. Ví dụ: my-org-myportal.
  • CATEGORY_ID có mã nhận dạng của danh mục. Ví dụ: bf6505eb-2a0f-47af-a00a-ded40ac72960. Lấy mã danh mục bằng lệnh list API categories (liệt kê danh mục API).
  • ACCESS_TOKEN có mã thông báo xác thực dùng để truy cập vào API Apigee Edge. Để biết thêm thông tin về xác thực và mã thông báo, hãy xem bài viết Xác thực quyền truy cập vào Edge API.

Tải trọng phản hồi:

{
  "status": "success",
  "message": "ApiCategory deleted",
  "data": {
  },
  "code": null,
  "request_id": "2032819627",
  "error_code": null
}

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

Các phần sau đây cung cấp thông tin giúp bạn khắc phục các lỗi cụ thể với các API đã phát hành của chúng tôi.

Lỗi: Không tìm nạp được lỗi được trả về khi sử dụng tính năng Dùng thử API này

Khi sử dụng tính năng Thử API này, nếu lỗi TypeError: Failed to fetch được trả về, 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 này có thể là do một vấn đề đã biết về swagger-ui. 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 tài liệu OpenAPI. Ví dụ:

    schemes:
   - https
   - http

  • Đối với lỗi hạn chế Chia sẻ tài nguyên trên nhiều nguồn gốc (CORS), 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 trên nhiều nguồn gốc phía máy khách. Xem phần Định cấu hình proxy API để hỗ trợ tính năng Dùng thử API này.

Lỗi: Tiêu đề "Access-Control-Allow-Origin" chứa nhiều giá trị "*, *", nhưng chỉ cho phép một giá trị

Khi sử dụng tính năng Thử API này, bạn có thể nhận được thông báo lỗi sau đây nếu tiêu đề Access-Control-Allow-Origin đã tồn tại:

The Access-Control-Allow-Origin header contains multiple values '*, *', but only one is allowed.

Để khắc phục lỗi này, hãy sửa đổi chính sách AssignMessage để sử dụng <Set> nhằm đặt tiêu đề CORS thay vì <Add>, như trong đoạn trích bên dưới. Để biết thêm thông tin, hãy xem phần Lỗi CORS : tiêu đề chứa nhiều giá trị "*, *", nhưng chỉ cho phép một giá trị.

<AssignMessage async="false" continueOnError="false" enabled="true" name="add-cors">
    <DisplayName>Add CORS</DisplayName>
    <FaultRules/>
    <Properties/>
    <Set>
        <Headers>
            <Header name="Access-Control-Allow-Origin">{request.header.origin}</Header>
            <Header name="Access-Control-Allow-Headers">origin, x-requested-with, accept, content-type, authorization</Header>
            <Header name="Access-Control-Max-Age">3628800</Header>
            <Header name="Access-Control-Allow-Methods">GET, PUT, POST, DELETE</Header>
        </Headers>
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

Lỗi: Không được phép sử dụng trường tiêu đề yêu cầu

Khi sử dụng tính năng Thử API này, nếu gặp lỗi Request header field not allowed tương tự như ví dụ bên dưới, bạn có thể cần cập nhật các tiêu đề được hỗ trợ trong chính sách CORS. Ví dụ:

Access to XMLHttpRequest ... has been blocked by CORS policy: Request header field
content-type is not allowed by Access-Control-Allow-Headers in preflight response

Trong ví dụ này, bạn cần thêm tiêu đề content-type vào phần Access-Control-Allow-Headers trong chính sách CORS AssignMessage, như mô tả trong phần Đính kèm chính sách Thêm CORS vào proxy API mới.

Lỗi: Quyền truy cập bị từ chối khi gọi proxy API bằng OAuth2

Chính sách OAuthV2 của Apigee trả về một phản hồi mã thông báo chứa một số thuộc tính không tuân thủ RFC. Ví dụ: chính sách sẽ trả về một mã thông báo có giá trị BearerToken, thay vì giá trị Bearer tuân thủ RFC dự kiến. Phản hồi token_type không hợp lệ này có thể dẫn đến lỗi Access denied khi sử dụng tính năng Thử API này.

Để khắc phục vấn đề này, bạn có thể tạo chính sách JavaScript hoặc AssignMessage để chuyển đổi đầu ra chính sách thành định dạng tuân thủ. Để biết thêm thông tin, hãy xem phần Hành vi không tuân thủ RFC.