Quản lý khóa API

Open Cloud xác thực và ủy quyền truy cập API bằng cách sử dụng các khóa API, cho phép bạn thêm quyền phân quyền chi tiết và kiểm soát bảo mật cho việc truy cập và sử dụng một số tài nguyên nhất định trong trò chơi của bạn, chẳng hạn như kho dữ liệu và các địa điểm.

Tất cả các API Open Cloud yêu cầu bạn tạo một khóa API với quyền hợp lệ và bao gồm một tiêu đề x-api-key trong yêu cầu của bạn, cho phép ứng dụng xác thực với Open Cloud thay mặt cho bạn.

Tạo khóa API

Bạn có thể tạo và cấu hình các khóa API để truy cập vào tài nguyên của bạn. Quyền truy cập của một khóa API được xác định bởi quyền của người dùng sở hữu nó. Điều này có nghĩa là nó có thể truy cập vào bất kỳ tài nguyên nào mà người dùng có quyền, bao gồm tất cả các trò chơi cá nhân của họ và bất kỳ trò chơi nào thuộc sở hữu của nhóm mà họ có vai trò phù hợp. Một số phạm vi có thể bị giới hạn cho các trò chơi cụ thể, nhưng không phải tất cả.

Để biết thêm chi tiết về cách tạo các khóa API để quản lý tài nguyên nhóm, hãy xem phần Tạo khóa API để quản lý tài nguyên nhóm dưới đây.

Để tạo một khóa API:

1. Trong Bảng Điều Khiển Người Tạo, truy cập vào trang Khóa API.

2. Nhấp vào nút Tạo khóa API.

3. Nhập một tên duy nhất cho khóa API của bạn. Sử dụng một tên có thể giúp bạn nhớ lại mục đích sau này, chẳng hạn như PLACE_PUBLISHING_KEY để xuất bản các địa điểm vào trò chơi của bạn.

4. Trong phần Quyền Truy Cập, chọn một API từ menu Chọn Hệ Thống API. Lặp lại bước này nếu bạn cần thêm nhiều API vào khóa.

5. Nếu có thể, chọn trò chơi mà bạn muốn truy cập bằng khóa API.

   Bạn có thể tùy chọn tắt Hạn chế theo Trải Nghiệm. Khi tắt, khóa API của bạn có quyền truy cập vào tất cả các trò chơi thuộc sở hữu của người dùng của bạn và các trò chơi thuộc sở hữu của nhóm nơi bạn có quyền hợp lệ, bao gồm cả các trò chơi mà bạn tạo trong tương lai.

6. Từ danh sách thả xuống Chọn Hoạt Động, chọn các hoạt động mà bạn muốn kích hoạt cho khóa API.

   Hầu hết các hoạt động trong tài liệu API bao gồm các phạm vi quyền cần thiết. Ví dụ, hoạt động đổ bộ nhớ yêu cầu quyền universe.memory-store:flush.

   Để biết danh sách tất cả các phạm vi và các API mà chúng hỗ trợ, hãy xem Phạm vi.

7. (Tùy chọn) Trong phần Bảo Mật, hạn chế truy cập IP đến khóa bằng cách sử dụng định dạng CIDR. Bạn có thể tìm địa chỉ IP của máy cục bộ của bạn và thêm nó vào phần Địa Chỉ IP Được Chấp Nhận cùng với các địa chỉ IP khác cần truy cập. Nếu bạn không có IP cố định, hoặc bạn chỉ sử dụng khóa API trong môi trường cục bộ, bạn có thể để nút chuyển đổi Hạn chế địa chỉ IP không được chọn để cho phép bất kỳ IP nào sử dụng khóa API của bạn.

8. (Tùy chọn): Để thêm bảo vệ bổ sung cho tài nguyên của bạn, thiết lập ngày hết hạn cho khóa của bạn.

9. Nhấp vào nút Lưu & Tạo khóa.

10. Sao chép và lưu chuỗi khóa API vào một vị trí an toàn, không phải là một kho lưu trữ công cộng cho mã của bạn.

11. Xác minh trạng thái của khóa API của bạn trên trang Mở Rộng API của Bảng Điều Khiển Người Tạo.

Tạo khóa API để quản lý tài nguyên thuộc sở hữu của nhóm

Một khóa API cấp quyền truy cập vào tất cả tài nguyên mà tài khoản người dùng có quyền truy cập, bao gồm các trò chơi cá nhân bên ngoài nhóm. Nếu bạn sử dụng khóa API của tài khoản cá nhân cho tự động hóa nhóm và khóa đó bị xâm phạm, các tài nguyên khác mà bạn có quyền truy cập cũng sẽ gặp rủi ro.

Để ngăn chặn điều này, chúng tôi khuyến nghị mạnh mẽ tạo một khóa API riêng trên một tài khoản thay thế chuyên dụng với quyền hạn chế nghiêm ngặt đối với nhóm mục tiêu. Tài khoản mới này dành cho mục đích tự động hóa chỉ nên được cấp quyền truy cập đến nhóm mục tiêu và được cấp các quyền tối thiểu cần thiết cho nhiệm vụ của nó.

1. Tạo một tài khoản Roblox mới, chuyên dụng cho tự động hóa của bạn.
2. Mời tài khoản mới vào nhóm của bạn.
3. Gán cho nó một vai trò nhóm với các quyền tối thiểu cần thiết cho nhiệm vụ của nó (ví dụ: chỉ "Tạo và chỉnh sửa trải nghiệm nhóm").
4. Đăng nhập vào tài khoản mới và làm theo các bước trong phần trên để tạo một khóa API.
5. Sử dụng khóa API được tạo để tự động hóa tài nguyên nhóm.

Các Thực Hành Tốt Nhất Để Quản Lý Khóa API

Khóa API là thông tin nhạy cảm cần được giữ an toàn để ngăn chặn việc truy cập trái phép vào dữ liệu của bạn. Dưới đây là một số thực hành tốt nhất để quản lý khóa API.

• Tạo các khóa riêng cho mỗi ứng dụng: Tạo các khóa API riêng cho mỗi ứng dụng hoặc trường hợp sử dụng để phân lập quyền truy cập và giảm thiểu tác động nếu một khóa bị xâm phạm.

• Chọn quyền tối thiểu cần thiết: Khi cấu hình các phạm vi, chọn quyền tối thiểu cần thiết cho mục đích sử dụng của khóa. Đối với những phạm vi cho phép bạn hạn chế quyền truy cập theo trò chơi, hãy giới hạn quyền truy cập chỉ đến các trò chơi cụ thể cần thiết.

• Sử dụng hạn chế địa chỉ IP: Hạn chế quyền truy cập khóa API đến các địa chỉ IP cụ thể hoặc khoảng CIDR để ngăn chặn việc sử dụng trái phép từ các vị trí không xác định. Không sử dụng hạn chế địa chỉ IP khi sử dụng khóa API của bạn trong các địa điểm Roblox để đảm bảo rằng khóa của bạn có thể được sử dụng với các máy chủ Roblox.

• Đặt ngày hết hạn: Đối với các trường hợp sử dụng ngắn hạn, cấu hình ngày hết hạn để tự động vô hiệu hóa các khóa sau một khoảng thời gian nhất định, giảm thiểu rủi ro nếu một khóa bị xâm phạm. Việc đặt ngày hết hạn không được khuyến nghị cho các trường hợp sử dụng dài hạn trừ khi bạn có quy trình xoay vòng khóa, vì tự động hóa của bạn có thể đột ngột thất bại khi khóa hết hạn.

• Sử dụng tài khoản thay thế chuyên dụng cho quản lý tài nguyên nhóm: Sử dụng một tài khoản chuyên dụng với các quyền tối thiểu cho quản lý tài nguyên nhóm, như đã nêu trong phần Tạo khóa API để quản lý tài nguyên thuộc sở hữu của nhóm.

• Lưu trữ khóa API một cách an toàn: Không bao giờ lưu trữ khóa API trực tiếp trong mã nguồn của bạn, hệ thống quản lý phiên bản, hoặc kịch bản mà chúng có thể bị lộ. Sử dụng một hệ thống quản lý bí mật để lưu trữ và kiểm soát quyền truy cập vào các khóa của bạn. Trong các địa điểm Roblox, sử dụng Kho Bí Mật.

• Không chia sẻ khóa API thông qua các kênh công khai: Không bao giờ chia sẻ khóa API thông qua các kênh truyền thông công khai, diễn đàn hoặc mạng xã hội. Chỉ chia sẻ khóa qua các kênh an toàn, riêng tư với các thành viên trong nhóm đáng tin cậy. Giới hạn quyền truy cập vào những người mà bạn chia sẻ khóa của bạn để giảm thiểu vùng ảnh hưởng nếu một khóa bị xâm phạm.

Định dạng CIDR

Để bảo vệ tài nguyên của bạn hơn nữa, khi tạo khóa API, hãy xác định các địa chỉ IP có thể truy cập khóa API bằng cách sử dụng địa chỉ IP thông thường hoặc sử dụng định dạng CIDR. Một địa chỉ IP CIDR trông giống như một địa chỉ IP bình thường ngoại trừ việc nó kết thúc bằng một dấu gạch chéo và một số thập phân đại diện cho số bit của địa chỉ IP quan trọng cho định tuyến mạng:

• Bình thường: 192.168.0.0
• CIDR: 192.168.0.0/24

Phần đầu tiên là địa chỉ IP và phần sau là mặt nạ mạng, đếm số bit 1 trong định dạng nhị phân. Trong ví dụ trước, 24 có nghĩa là 255.255.255.0 (24 bit 1) cho phép tất cả các IP giữa 192.168.0.0 và 192.168.0.255. Việc hiểu định dạng CIDR đặc biệt hữu ích nếu bạn dự định chạy các ứng dụng của mình trên một máy chủ.

Trạng thái khóa API

Các khóa API ban đầu có trạng thái hoạt động, nhưng chúng có thể trở nên không hoạt động trong suốt vòng đời của chúng. Để tìm hiểu lý do tại sao một khóa API đã thay đổi trạng thái và cách đưa khóa API trở lại trạng thái hoạt động, hãy xem bảng sau.

Giám sát khóa API

POST api-keys/v1/introspect

Lấy thông tin về một khóa API. Xác minh xem khóa có thể được sử dụng từ địa chỉ IP của người yêu cầu và liệu khóa hoặc người dùng được tạo gần nhất có bị quản lý hay không.

Yêu cầu

(application/json)

Ví dụ Yêu cầu Giám sát Khóa API
curl --location --request POST 'https://apis.roblox.com/api-keys/v1/introspect' \
--header 'Content-Type: application/json' \
--data '{
    "apiKey": "your-api-key"
}'

Phản hồi

Có bốn định danh tài nguyên có thể xuất hiện trong mỗi đối tượng phạm vi:

• userId
• groupId
• universeId
• universeDatastore

Các định danh userId và groupId chỉ liên quan đến các phạm vi có mục tiêu là người tạo. Định danh universeDatastore chỉ liên quan đến các phạm vi có mục tiêu là universe-datastore. Định danh tài nguyên sẽ bị loại bỏ cho các phạm vi không hỗ trợ lựa chọn tài nguyên.

Một dấu hoa thị (*) trong danh sách định danh tài nguyên cho biết rằng phạm vi có quyền trên tất cả các tài nguyên của loại đó.

Ví dụ Phản hồi Giám sát Khóa API
{
  "name": "test key",
  "authorizedUserId": 234,
  "scopes": [
    {
      "name": "universe-datastores.objects",
      "operations": [
        "create"
      ],
      "universeDatastores": [
        {
          "universeId": "123",
          "datastoreName": "playerData"
        }
      ]
    },
    {
      "name": "asset",
      "operations": [
        "write"
      ],
      "groupIds": [
        "*"
      ],
      "userIds": [
        "*"
      ]
    }
  ],
  "enabled": true,
  "expired": false,
  "expirationTimeUtc": "2026-01-01T12:00:00.000Z"
}