Phát hành API

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 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. Kết xuất tài liệu tham khảo API từ tài liệu OpenAPI hoặc giản đồ GraphQL để giúp nhà phát triển ứng dụng tìm hiểu về các 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 là gì?)

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

Khi bạn xuất bản một API, 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:

  • Tài liệu tham khảo API. Giao diện được cung cấp tuỳ thuộc vào việc bạn xuất bản API bằng tài liệu OpenAPI hay giản đồ GraphQL. Xem:
  • Đã thêm một đườ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 mẫu) cung cấp danh sách tất cả các API được xuất bản trên cổng của bạn, được liệt kê theo thứ tự bảng chữ cái, 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 các mục sau:

    • Hình ảnh hiển thị cho mỗi thẻ API
    • Danh mục dùng để gắn thẻ API, giúp nhà phát triển 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 2 danh mục và cách sử dụng hình ảnh

SmartDocs (OpenAPI)

Khi bạn xuất bản 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 của bạn và sử dụng bảng điều khiển Dùng thử API này để đưa ra yêu cầu API và xem đầu ra. Thử API này hoạt động với các điểm cuối không bảo mật hoặc các điểm cuối bảo mật bằng cách sử dụng 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 của bạn. Đối với OAuth, các quy trình sau được hỗ trợ: mã uỷ quyền, mật khẩu và thông tin đăng nhập của ứng dụng.

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

Nhấp vào 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à các đoạn mã mẫu ở nhiều định dạng, chẳng hạn như HTTP, Python, Node.js, v.v., như minh hoạ trong hình sau.

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

GraphQL Explorer

Khi bạn xuất bản một API bằng lược đồ GraphQL, GraphQL Explorer sẽ được thêm vào cổng thông tin của bạn. GraphQL Explorer là một môi trường tương tác để chạy các truy vấn đối với API của bạn. Trình khám phá này dựa trên GraphiQL, một cách 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 GraphQL Explorer để 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 của bạn, nhà phát triển có thể truyền tiêu đề uỷ quyền trong ngăn Tiêu đề yêu cầu.

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

GraphQL Explorer 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 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 tài liệu, bạn cần nhận thức được tác động của các thay đổi đối với API của bạn trong các giai đoạn khác của 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 tài liệu?.

Khi xuất bản API, bạn sẽ chụp ảnh 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 đó thể hiện 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 một ảnh chụp nhanh khác 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 một 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 một URL gọi lại khi họ đăng ký ứng dụng của mình. 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 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 xem có cần URL gọi lại trong quá trình đăng ký ứng dụng hay không khi thêm một 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 này, 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 xuất bản API bằng tài liệu OpenAPI, bạn cần định cấu hình proxy API để hỗ trợ việc đưa ra yêu cầu trên bảng điều khiển Dùng 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 các proxy API để thực thi các yêu cầu trên nhiều nguồn gốc ở phía máy khách

    CORS 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ô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 do tất cả các trình duyệt thực thi.

  • Cập nhật cấu hình của 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 Dùng 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 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 một 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 chế độ hỗ trợ CORS vào một proxy API.
  2. Trong chính sách Add 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 chế độ hỗ trợ CORS vào một proxy API.
  2. Trong chính sách Add 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. Chỉnh 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 <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ý API của bạn như mô tả trong các phần sau.

Khám phá các API

Sử dụng giao diện người dùng hoặc lệnh curl để xem các API có 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 rồi chọn cổng 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 sẽ 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ả, khả năng hiển thị, danh mục, quy cách liên kết và thời gian sửa đổi

Như được làm nổi bật trong hình trước, thẻ API cho phép bạn:

curl

Cách liệt kê các 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 bằng tên của cổng, ở 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 được chuyển đổi thành tất cả chữ thường và đã xoá dấu cách cũng như dấu gạch ngang. Ví dụ: my-org-myportal.
  • ACCESS_TOKEN bằng 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ề quy trình 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 Ghi chú về tính năng 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 gần đây nhất mặt hàng trong danh mục được sửa đổi 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ã nhận dạng của mặt hàng trong danh mục. Ví dụ: 399668.

Ghi chú về việc phân trang:

  • Kích thước trang: Sử dụng pageSize để chỉ định số lượng mục trong danh sách cần trả về trong một trang. Giá trị mặc định là 25 và giá trị tối đa là 100. Nếu có các trang bổ sung, nextPageToken sẽ được điền sẵ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 một 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 danh mục API.
  2. Nhấp vào thẻ API nếu thẻ này chưa được chọn.

  3. Nhấp vào + Thêm.

    Hộp thoại Thêm một 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ẽ xuất hiện.

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

    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 kiểm 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.
    Tiêu đề hiển thị Cập nhật tiêu đề API xuất hiện trong danh mục. Theo mặc định, tên sản phẩm API sẽ được dùng. Bạn có thể thay đổi tiêu đề hiển thị sau này, 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ả về API của bạn 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 này, 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 một 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. Sau này, bạn có thể thêm hoặc cập nhật URL gọi lại, như mô tả trong phần Quản lý URL gọi lại cho một API.
    Tài liệu API

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

    1. Chọn 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ẻ Quy cách của tôi rồi chọn một quy cách trong cửa hàng quy cách.
      • Nhấp vào thẻ Tải tệp lên rồi tải một tệp lên.
      • Nhấp vào thẻ Nhập từ URL rồi nhập một quy cách từ URL.
    4. Nhấp vào Chọn.

    Cách sử dụng lược đồ GraphQL:

    1. Chọn GraphQL Schema.
    2. Nhấp vào Chọn tài liệu.
    3. Di 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 và thêm tài liệu sau khi API được thêm, như mô tả trong phần Quản lý ảnh chụp nhanh của tài liệu.

    Khả năng hiển thị của API

    Nếu bạn chưa đăng ký tham gia bản phát hành thử nghiệm 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ý tham gia bản phát hành thử nghiệm tính năng quản lý đối tượng, hãy chọn một trong các lựa chọn sau:

    • Công khai (mọi người đều có thể thấy) để 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.

    Sau này, bạn có thể quản lý chế độ hiển thị của đối tượng 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 sau, 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 bằng URL 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 tích hợp sẽ tuỳ thuộc vào tính 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.
    Danh mục

    Thêm các danh mục mà API sẽ được gắn thẻ để giú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 phím Enter. Danh mục mới sẽ được thêm vào trang Danh mục và có sẵn khi bạn 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 một 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 bằng tên của cổng, ở 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 được chuyển đổi thành tất cả chữ thường và đã xoá dấu cách cũng như dấu gạch ngang. Ví dụ: my-org-myportal.
  • ACCESS_TOKEN bằng 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ề quy trình 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ùng tên hiển thị. Ví dụ: Hello World 2.
  • DESCRIPTION có nội dung mô tả hiển thị. Ví dụ: Simple hello world example.
  • ANON_TRUE_OR_FALSE có true hoặc false (mặc định), trong đó true có nghĩa là API này có khả năng hiển thị công khai và có thể xem ẩn danh; nếu không, chỉ người dùng đã đăng ký mới có thể xem.
  • IMAGE_URL bằng URL của một hình ảnh từ bên ngoài được dùng cho mặt hàng trong danh mục hoặc đường dẫn tệp cho tệp hình ảnh được lưu trữ trong cổng, ví dụ: /files/book-tree.jpg. Khi bạn chỉ định URL của một hình ảnh từ 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 tích hợp sẽ tuỳ thuộc vào tính sẵn có của 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 một 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 có true hoặc false (mặc định), trong đó true cho biết API được cung cấp công khai. Khi xuất bản, bạn có thể cho phép truy cập đối với 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 gần đây nhất mặt hàng trong danh mục được sửa đổi 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ã nhận dạng của mặt hàng trong danh mục. Ví dụ: 399668.

Chỉnh sửa API

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

Phần này cung cấp một 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 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 danh mục API.
  2. Nhấp vào thẻ API nếu thẻ này chưa được 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 nội dung sửa đổi. Xem nội dung mô tả về các lựa 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 dùng lệnh gọi update để chỉnh sửa.

Ví dụ này hướng dẫn bạn các bước cần thiết để thay đổi trạng thái đã xuất bản 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 id được tạo và nhận dạng 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 bằng tên của cổng, ở 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 được chuyển đổi thành tất cả chữ thường và đã xoá dấu cách cũng như dấu gạch ngang. Ví dụ: my-org-myportal.
    • API_DOC bằng id đã tạo của tài liệu. Ví dụ: 399668. Sử dụng lệnh list API docs để tìm giá trị này.
    • ACCESS_TOKEN bằng 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ề quy trình 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 update 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. Trong 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ùng 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 xuất bản API, bạn có thể chụp ảnh nhanh mới về 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 xuất bản 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 danh mục API.
  2. Nhấp vào thẻ API nếu thẻ này chưa được 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 của ảnh chụp nhanh. Nếu đã hết hạn, 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 đã cũ
  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 ảnh chụp nhanh của một tài liệu OpenAPI đã lỗi thời, hãy nhấp vào Làm mới ảnh chụp nhanh.
    • Để thay đổi tài liệu dùng để tạo tài liệu cho API, trong phần Tài liệu về 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 một 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 hủy xuất bản một 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 một API trên cổng thông tin:

  1. Truy cập danh mục API.
  2. Nhấp vào thẻ API nếu thẻ này chưa được 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 biểu tượng 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 hủy 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 update để 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 của 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ý khả năng 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ý khả năng hiển thị của một API trong cổng thông tin của bạn:

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 danh mục API.
  2. Nhấp vào thẻ API nếu thẻ này chưa được 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 biểu tượng Chỉnh sửa.

  5. Chọn chế độ hiển thị. Nếu bạn đã đăng ký tham gia bản phát hành thử nghiệm của tính năng đối tượng, hãy chọn một trong các lựa 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 này.
    • 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 phần Quản lý đối tượng cho cổng thông tin của bạn.
    Nếu khô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 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ý tham gia bản phát hành thử nghiệm 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, thì khả năng hiển thị sẽ được quản lý bằng anonAllowed.

Thêm một trong những nội dung 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 update để chỉnh sửa API. Thê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, giá trị mặc định sẽ được dùng.

    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 danh mục API.
  2. Nhấp vào thẻ API nếu thẻ này chưa được 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 biểu tượng 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 những nội dung 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 update để chỉnh sửa API. Thê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, giá trị mặc định sẽ được dùng.

    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 danh mục API.
  2. Nhấp vào thẻ API nếu thẻ này chưa được 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 biểu tượng 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 một 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 dấu x trong hình ảnh để xoá hình ảnh đó.

    Khi chỉ định một hình ảnh, hãy chỉ định một hình ảnh có URL bên ngoài được dùng cho mục trong danh mục hoặc một đườ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 một hình ảnh từ 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 tích hợp sẽ tuỳ thuộc vào tính 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 những thông tin 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 update để chỉnh sửa API. Thê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, giá trị mặc định sẽ được dùng.

    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ẻ cho 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 phần Quản lý danh mục.

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

  • Quản lý các danh mục mà một 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 bạn 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ẻ cho một API bằng các danh mục:

Giao diện người dùng

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

  1. Truy cập danh mục API.
  2. Nhấp vào thẻ API nếu thẻ này chưa được 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 biểu tượng 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 phím Enter. Danh mục mới sẽ được thêm vào trang Danh mục và có sẵn khi bạn thêm hoặc chỉnh sửa các API khác.
  6. Lặp lại để gắn thẻ API vào nhiều danh mục khác.
  7. Nhấp vào Lưu.

curl

Thêm những thông tin 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 số 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 update để chỉnh sửa API. Thê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, giá trị mặc định sẽ được dùng.

    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 đề và nội dung mô tả hiển thị

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 danh mục API.
  2. Nhấp vào thẻ API nếu thẻ này chưa được 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 biểu tượng 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 những thông tin 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 update để chỉnh sửa API. Thê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, giá trị mặc định sẽ được dùng.

    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á một 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 danh mục API.
  2. Chọn API nếu chưa chọn.
  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 biểu tượng Biểu tượng xoá Xoá.

curl

Cách xoá một 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 bằng tên của cổng, ở 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 được chuyển đổi thành tất cả chữ thường và đã xoá dấu cách cũng như dấu gạch ngang. Ví dụ: my-org-myportal.
  • API_DOC bằng id đã tạo của tài liệu. Ví dụ: 399668. Sử dụng lệnh list API docs để tìm giá trị này.
  • ACCESS_TOKEN bằng 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ề quy trình 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 về 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 về API lên:

Giao diện người dùng

  1. Truy cập danh mục API.
  2. Nhấp vào thẻ API nếu thẻ này chưa được 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 của ảnh chụp nhanh. Nếu đã hết hạn, 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 đã cũ
  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 ảnh chụp nhanh của một tài liệu OpenAPI đã lỗi thời, hãy nhấp vào Làm mới ảnh chụp nhanh.
    • Để thay đổi tài liệu dùng để tạo tài liệu cho API, trong phần Tài liệu về 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 về 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 chứng từ rồi chọn phiên bản mới nhất của chứng 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 kết xuất từ tài liệu và thêm vào trang Tài liệu tham khảo API. Trạng thái của ả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à ảnh mới nhất

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 bằng tên của cổng, ở 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 được chuyển đổi thành tất cả chữ thường và đã xoá dấu cách cũng như dấu gạch ngang. Ví dụ: my-org-myportal.
  • API_DOC bằng id đã tạo của tài liệu. Ví dụ: 399668. Sử dụng lệnh list API docs để tìm giá trị này.
  • DISPLAY_NAME có tên hiển thị của tài liệu về API. Ví dụ: Hello World 2.
  • CONTENTS có 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 có một phần mềm 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 bằng tên của cổng, ở 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 được chuyển đổi thành tất cả chữ thường và đã xoá dấu cách cũng như dấu gạch ngang. Ví dụ: my-org-myportal.
  • API_DOC bằng id đã tạo của tài liệu. Ví dụ: 399668. Sử dụng lệnh list API docs để tìm giá trị này.
  • DISPLAY_NAME có tên hiển thị của tài liệu về API. Ví dụ: Hello World 2.
  • ENDPOINT_URI bằng tên miền của URI điểm cuối. Ví dụ: https://demo.google.com/graphql.
  • CONTENTS có 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 có một phần mềm 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à 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 về API xuống bằng lệnh get documentation (lấy 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 bằng tên của cổng, ở 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 được chuyển đổi thành tất cả chữ thường và đã xoá dấu cách cũng như dấu gạch ngang. Ví dụ: my-org-myportal.

  • API_DOC bằng id đã tạo của tài liệu. Ví dụ: 399668. Sử dụng lệnh list API docs để 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 được mã hoá base64 của nội dung trong 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 danh mục API.
  2. Nhấp vào thẻ API nếu thẻ này chưa được 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 API cập nhật:

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 bằng tên của cổng, ở 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 được chuyển đổi thành tất cả chữ thường và đã xoá dấu cách cũng như dấu gạch ngang. Ví dụ: my-org-myportal.
  • API_DOC bằng id đã tạo của tài liệu. Ví dụ: 399668. Sử dụng lệnh list API docs để 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 danh mục để cho phép nhà phát triển ứng dụng khám phá các API liên quan trên trang API của cổng thông tin đang hoạt động. Thêm và quản lý 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 có 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 rồi chọn cổng 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ẻ 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ư minh hoạ 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 bằng tên của cổng, ở 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 được chuyển đổi thành tất cả chữ thường và đã xoá dấu cách cũng như dấu gạch ngang. Ví dụ: my-org-myportal.
  • ACCESS_TOKEN bằng 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ề quy trình 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ã nhận dạng 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ó sẵn khi bạn 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 trang Danh mục.
  2. Nhấp vào + Thêm.
  3. Nhập tên của danh mục mới.
  4. Bạn có thể chọn một hoặc nhiều API để gắn thẻ vào 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 bằng tên của cổng, ở 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 được chuyển đổi thành tất cả chữ thường và đã xoá dấu cách cũng như dấu gạch ngang. Ví dụ: my-org-myportal.
  • ACCESS_TOKEN bằng 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ề quy trình 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 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 một danh mục:

Giao diện người dùng

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

  1. Truy cập 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 bằng tên của cổng, ở 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 được chuyển đổi thành tất cả chữ thường và đã xoá dấu cách cũng như 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 bằng 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ề quy trình 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 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 cho 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á một danh mục:

  1. Truy cập 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 biểu tượng 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 bằng tên của cổng, ở 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 được chuyển đổi thành tất cả chữ thường và đã xoá dấu cách cũng như 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 bằng 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ề quy trình 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 vấn đề 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 API đã xuất bản của chúng tôi.

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

Khi sử dụng Dùng thử API này, nếu lỗi TypeError: Failed to fetch xảy ra, hãy cân nhắc các nguyên nhân và giải pháp có thể có 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 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ỉ được phép có một giá trị

Khi sử dụng Dù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ư minh hoạ trong đoạn trích bên dưới. Để biết thêm thông tin, hãy xem Lỗi CORS : tiêu đề chứa nhiều giá trị "*, *", nhưng chỉ được phép có 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 dùng trường tiêu đề của yêu cầu

Khi sử dụng Try this API (Thử dùng API này), nếu nhận được lỗi Request header field not allowed, tương tự như ví dụ bên dưới, thì 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 một proxy API mới.

Lỗi: Quyền truy cập bị từ chối khi gọi một 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ị tuân thủ RFC dự kiến là Bearer. 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 Thử API này.

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