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 chi tiết và kiểm soát bảo mật để 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à đị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 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 tài nguyên của mình. 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 bất kỳ tài nguyên nào mà người dùng có quyền, bao gồm 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ị hạn chế cho các trò chơi cụ thể, nhưng không phải tất cả.

Để biết chi tiết về cách tạo 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 thuộc sở hữu của nhóm bên dưới.

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

1. Trong Bảng điều khiển Người sáng tạo, đi đến 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 vô hiệu hóa Hạn chế theo Trải nghiệm. Khi vô hiệu hóa, 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 và bất kỳ trò chơi nào thuộc sở hữu của nhóm mà bạn có quyền phù hợp, bao gồm bất kỳ trò chơi nào bạn tạo trong tương lai.

6. Từ menu 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 xóa bộ nhớ yêu cầu quyền universe.memory-store:flush.

   Để có 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 tính 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 bổ sung cho những người 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ể để tùy chọn 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, hãy đặt 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 khai 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 sáng 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ả các tài nguyên mà tài khoản người dùng có quyền, 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 của mình 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 truy cập được giới hạn nghiêm ngặt cho nhóm mục tiêu. Tài khoản mới này dành riêng cho mục đích tự động hóa chỉ nên được cấp quyền truy cập vào nhóm mục tiêu và được cấp 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 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 đã tạo cho tự động hóa tài nguyên nhóm.

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 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 để cách ly quyền truy cập và giảm 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ỉ cho các trò chơi cụ thể mà bạn cần.

• 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 các dải 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 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 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 luân chuyển khóa, vì tự động hóa của bạn có thể gặp sự cố bất ngờ 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 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 kiểm soát phiên bản hoặc kịch bản nơi chúng có thể bị lộ. Sử dụng 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, hãy sử dụng Kho bí mật.

• Không chia sẻ khóa API qua các kênh công khai: Không bao giờ chia sẻ khóa API qua các kênh giao tiếp 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. Hạn chế quyền truy cập vào những người bạn chia sẻ khóa của mình để giảm thiểu rủi ro 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 một khóa API, hãy chỉ đị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 thông 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ố lượng bit của địa chỉ IP có ý nghĩa cho định tuyến mạng:

• Thông thường: 192.168.0.0
• CIDR: 192.168.0.0/24

Phần trước là địa chỉ IP và phần sau là netmask, đế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. 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

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.

Kiểm tra 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 hay không và liệu khóa hoặc người dùng được tạo gần đây nhất có bị quản lý hay không.

Yêu cầu

(application/json)

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ể có 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ị bỏ qua đối với các phạm vi không hỗ trợ việc 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 đó.

{
  "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"
}