Xử lý yêu cầu API cho các kho dữ liệu

Trước khi gửi yêu cầu đến Open Cloud APIs cho kho dữ liệu tiêu chuẩn và kho dữ liệu được đặt hàng, bạn cần hiểu cách xử lý chúng một cách phù hợp.Đối với thông tin về việc sử dụng API, xem Hướng dẫn sử dụng .

Xác nhận

Giống như tất cả các API Mở đám mây, điểm kết thúc lưu trữ dữ liệu yêu cầu tất cả các yêu cầu bao gồm tiêu đề x-api-key, chứa một chìa khóa API với đủ quyền cho yêu cầu.Điều này yêu cầu bạn áp dụng chìa khóa cho trải nghiệm và kho dữ cửa hàng, và hoạt động cuối cùng được phép.Nếu chìa khóa không hợp lệ, 403 Unauthorized được trả về.Để biết thêm thông tin về chìa khóa API, xem Quản lý chìa khóa API.

Giảm tốc

Tất cả các điểm cuối có hai loại giảm tải cấp vũ trụ: giảm tải theo yêu cầu mỗi phút và giảm tải theo băng thông .Với mỗi trải nghiệm, giới hạn yêu cầu theo phút cho phép bạn gửi một số lượng yêu cầu nhất định mỗi phút, và giới hạn lưu lượng theo phút cho phép bạn gửi một lượng dữ liệu nhất định mỗi phút, bất kể số lượng API key.

Không giống như API Luau, các giới hạn này hiện không tăng theo số lượng người dùng. Vi phạm các giới hạn này khiến điểm cuối trả về 429 Too Many Requests .

Kho dữ liệu tiêu chuẩn giới hạn tắc nghẽn

Cửa hàng dữ liệu được sắp xếp giới hạn bị chậm

Xác thực nhập

Trước khi gửi yêu cầu, hãy chắc chắn để xác minh các tham số điểm cuối trên các yêu cầu và hạn chế dựa trên bảng sau.Các điểm cuối cá nhân có thể có các yêu cầu bổ sung ngoài những điều này.Nếu một tham số không đáp ứng các hạn chế sau, điểm cuối trả về một 400 Bad Request .

ID Vũ trụ

ID Vũ trụ là nhận dạng duy nhất của trải nghiệm mà bạn muốn truy cập các kho dữ liệu của mình.Giá trị của ID Vũ trụ của một trải nghiệm là giá trị của DataModel.GameId , không giống như ID Địa điểm Bắt đầu , xác định địa điểm bắt đầu của một trải nghiệm thay vì toàn bộ trải nghiệm.

Bạn có thể nhận được ID Vũ trụ của một trải nghiệm với các bước sau:

1. Điều hướng đến Bảng điều khiển Nhà sáng tạo.

2. Tìm trải nghiệm với các kho dữ liệu mà bạn muốn truy cập.

3. Chuyển con trỏ qua hình ảnh thu nhỏ của trải nghiệm, nhấp vào nút ⋯ và chọn Sao chép ID Vũ trụ .

   

Phạm vi

Bạn có thể tổ chức các kho dữ liệu của mình bằng cách đặt một chuỗi duy nhất làm phạm vi xác định một thư mục con cho mục nhập.Một khi bạn đặt một phạm vi, nó tự động gán cho tất cả các chìa khóa trong tất cả các hoạt động được thực hiện trên kho dữ cửa hàng.Phạm vi là tùy chọn và mặc định là global cho các kho dữ liệu tiêu chuẩn nhưng cần thiết cho các kho dữ liệu được đặt hàng.

Phạm vi phân loại dữ liệu của bạn với một chuỗi và một dấu phân cách với "/", ví dụ:

Tất cả các phương thức nhập dữ liệu cửa hàng có một tham số Scope khi bạn cần truy cập các mục được lưu dưới một phạm vi không mặc định.Ví dụ, bạn có thể có một chìa khóa 1234 dưới phạm vi mặc định global và chìa khóa tương tự dưới phạm vi special.Bạn có thể truy cập các trước đó mà không sử dụng tham số phạm vi, nhưng để truy cập sau cùng, bạn phải xác định tham số phạm vi như trong hoặc API lần gọi.

Ngoài ra, nếu bạn muốn liệt kê tất cả các chìa khóa được lưu trong một kho dữ liệu có một hoặc nhiều phạm vi không phải mặc định, bạn có thể đặt tham số AllScopes trong phương pháp List Entries để trở thành true , trong đó cuộc gọi trả về một tuple với chuỗi chìa khóa và phạm vi.Trong ví dụ trước, List Entries sẽ trả về cả hai ( 1234 , global ), và ( 1234 , special ) trong phản hồi.

Bạn không thể truyền Scope và AllScopes tham số trên cùng một yêu cầu, nếu không cuộc gọi sẽ trả về lỗi.Nhờ sử dụng chức năng giúp đỡ từ Open Cloud APIs cho mô-đun lưu trữ dữ liệu, mã sau đây minh họa cách bạn có thể đọc mọi chìa khóa trong một kho dữ liệu với một phạm vi tùy chỉnh:

Danh sách chìa khóa cho các phạm vi khác nhau
# Thiết lập
import tutorialFunctions
DatastoresApi = tutorialFunctions.DataStores()
datastoreName = "PlayerInventory"

# Danh sách chìa khóa cho phạm vi toàn cầu
specialScopeKeys = DatastoresApi.list_entries(datastoreName, scope = "global", allScopes = False)
print(keys.content)
# Danh sách chìa khóa cho phạm vi đặc biệt
specialScopeKeys = DatastoresApi.list_entries(datastoreName, scope = "special", allScopes = False)
print(keys.content)
# Danh sách chìa khóa cho tất cảScope được đặt thành true
specialScopeKeys = DatastoresApi.list_entries(datastoreName, allScopes = True)
print(specialScopeKeys.content)

Các chìa khóa có phạm vi tương ứng được trả lại trong phản hồi:

Ví dụ câu trả lời cho các phạm vi khác nhau
// Phản hồi cho phạm vi toàn cầu
{ "keys": [{ "scope": "global", "key": "User_2" }], "nextPageCursor": "" }

// Phản hồi cho phạm vi đặc biệt
{"keys":[{"scope":"special","key":"User_6"},{"scope":"special","key":"User_7"}],"nextPageCursor":""}

// Phản hồi cho AllScopes
{"keys":[{"scope":"global","key":"User_3"},{"scope":"global","key":"User_4"},{"scope":"global","key":"User_5"},{"scope":"special","key":"User_6"},{"scope":"special","key":"User_7"}],"nextPageCursor":""}

Văn bản-MD5

Content-MD5 là checksum MD5 cơ bản-64 của nội dung.Nó là một tiêu đề yêu cầu tùy chọn cho điểm cuối Set Entry kiểm tra tính nguyên vẹn dữ liệu và phát hiện các vấn đề tiềm ẩn.

Bạn có thể sử dụng ngôn ngữ lựa chọn của bạn để tính toán giá trị của tiêu đề content-md5.Ví dụ sau đây sử dụng Python.Các chức năng hashlib.md5() và base64.b64encode() có sẵn trong thư viện tiêu chuẩn Python (2.7, 3+).

Tạo nội dung-MD5
# Với lời nhắc
$ python -c "import base64, hashlib; print('content-md5: ' + str(base64.b64encode(hashlib.md5(bytes(input('content: '), encoding='utf8')).digest()), encoding='utf8'))"
content: 750
content-md5: sTf90fedVsft8zZf6nUg8g==
# Chỉ sử dụng stdin và stdout
$ echo "750" | python -c "import base64, hashlib; print(str(base64.b64encode(hashlib.md5(bytes(input(), encoding='utf8')).digest()), encoding='utf8'))"
sTf90fedVsft8zZf6nUg8g==

Nếu bạn gặp phải vấn đề tạo ra một giá trị hợp lệ content-md5 , bạn có thể cần phải mã hóa cơ thể yêu cầu của bạn trong UTF-8 binary trước khi tính toán checksum.

Người lướt

Các điểm cuối trả về danh sách dữ liệu cũng có thể trả về một chuỗi nextPageCursor.Điều này cho thấy có nhiều dữ liệu hơn có sẵn trong bộ kết quả yêu cài đặt.Để nhận nó, cung cấp chuỗi này trong tham số truy vấn cursor trong yêu cầu tiếp theo.Nếu tham số con trỏ được cung cấp nhưng không hợp lệ, điểm cuối trả về 400 Bad Request .

Định dạng chuỗi con trỏ không được định nghĩa . Bạn không nên hiểu hoặc phân tích chúng vì chúng có thể thay đổi bất cứ lúc nào.

Bộ lọc

Khi gửi yêu cầu đến phương thức List cho các kho dữ liệu được xếp hạng, bạn có thể thêm một tham số truy vấn tùy chọn filter để trả lại các bản ghi có giá trị trong phạm vi được xác định.

Tham số filter hỗ trợ một logic operator, && , và hai operator so sánh, <= để đặt giá trị tối đa và >= để đặt giá trị tối thiểu.Nếu bạn muốn đặt một phạm vi với cả một giá trị tối đa và tối thiểu, hãy thêm && giữa hai chuỗi.

Ví dụ, để trả lại các mục với giá trị nhỏ hơn hoặc bằng 10, bạn cần nhập entry <= 10 làm giá trị filter.Để trả lại các lượt truy cập với giá trị từ 10 đến 50, hãy nhập entry <= 50 && entry >= 10 .

Các ví dụ sau đây là sai filter giá trị có thể làm thất bại yêu cầu của bạn:

• entry <= 10 - không có khoảng trống giữa mỗi phần của chuỗi.
• 10 <= entry - entry và giá trị so sánh ở trên phía sai.
• entry <= 10 && entry <= 50 - && chỉ có thể được sử dụng để xác định phạm vi với cả hai operator so sánh cho giá trị tối thiểu và tối đa.

Cho phép cờ bị thiếu

Khi gửi yêu cầu đến phương thức Update để cập nhật một cơ sở dữ liệu lưu trữ dữ liệu đã đặt hàng hiện có, bạn có thể thêm một thẻ allow_missing tùy chọn để cho phép tạo một cơ sở dữ liệu ngay cả khi cơ sở dữ liệu không tồn tại.

Khi bạn đặt flag allow_missing đến True :

• Nếu mục không tồn tại, phản hồi trả về một mục mới.

• Nếu mục hiện hữu nhưng nội dung phù hợp với giá trị hiện tại của mục, mục hiện tại vẫn không thay đổi.

• Nếu mục tồn tại và nội dung không phù hợp với giá trị hiện có của mục, phản hồi trả lại mục với giá trị nội dung mới được cập nhật.