Przetwarzanie żądań API dla przechowywania danych

Zanim wyślesz żądania do otwartych chmurowych API dla standardowych magazynów danych i zamówionych magazynów danych, musisz zrozumieć, jak je właściwie obsługiwać.Aby uzyskać informacje o wykorzystaniu API, zobacz Przewodnik użytkowania.

Autoryzacja

Podobnie jak wszystkie otwarte chmurkowe API, końce punktów przechowywania danych wymagają wszystkich żądań, aby zawierały nagłówek x-api-key, który zawiera klucz API z wystarczającymi uprawnieniami dla prośba.Wymaga to, aby zastosować klucz do doświadczenia i sklepdanych, a operacja końcowa jest dozwolona.Jeśli klucz jest nieprawidłowe, 403 Unauthorized zostanie zwrócony.Aby uzyskać więcej informacji o kluczach API, zobacz Zarządzaj kluczami API.

Ograniczanie prędkości

Wszystkie końce mają dwa rodzaje ograniczania poziomu wszechświata: ograniczanie żądań na minutę i ograniczanie przepustowości .Z każdym doświadczeniem, ograniczenie żądań na minutę pozwala wysyłać pewną liczbę żądań na minutę, a ograniczenie przepustowości pozwala wysyłać pewną ilość danych na minutę, niezależnie od liczby kluczy API.

W przeciwieństwie do API Luau, ograniczenia te obecnie nie są skalowane w zależności od liczby użytkowników. Przekroczenie tych ograniczeń powoduje, że końcówka zwraca 429 Too Many Requests .

Standardowe magazyny danych ograniczają limity przepustowości

Sortowane magazyny danych ograniczają limity przepustowości

Weryfikacja wejściowa

Zanim wyślesz swoją prośba, upewnij się, że poprawnie zweryfikujesz parametry końca na wymaganiach i ograniczeniach formatowania na podstawie poniższej tabeli.Poszczególne końce mogą mieć dodatkowe wymagania poza tymi.Jeśli parametr nie spełnia następujących ograniczeń, końcowy punkt zwraca 400 Bad Request.

ID wszechświata

ID Wszechświata jest unikalnym identyfikatorem doświadczenia, w którym chcesz uzyskać dostęp do swoich magazynów danych.Wartość ID wszechświata doświadczenia jest wartością jego DataModel.GameId, nie taka sama jak ID miejsca startowego , który identyfikuje początkowe miejsce doświadczenia, a nie całe doświadczenie.

Możesz uzyskać identyfikator wszechświata do doświadczenia za pomocą następujących kroków:

1. Przejdź do Pulpitu nawigacyjnego twórcy.

2. Znajdź doświadczenie z magazynami danych, do których chcesz uzyskać dostęp.

3. Najedź kursorem na miniaturę miniatura, kliknij przycisk ⋯ i wybierz Kopiuj ID wszechświata .

   

Zakresy

Możesz zorganizować swoje magazyny danych, ustawiając unikalną strunę jako zakres, który określa podfoldrę dla wpisu.Gdy ustawisz zakres, automatycznie dodaje się do wszystkich kluczy we wszystkich wykonywanych na sklepdanych operacjach.Zakresy są opcjonalne i domyślnie jako global dla standardowych magazynów danych, ale wymagane są dla zamówionych magazynów danych.

Zakres kategoryzuje twoje dane za pomocą ciągu i separatora za pomocą "/", takiego jak:

Wszystkie metody operacji przechowywania danych mają parametr Scope dla przypadku, gdy musisz uzyskać dostęp do zapisanych pod nie domyślnym zakresem wpisów.Na przykład możesz mieć klucz 1234 pod domyślnym zakresem global i ten sam klucz pod zakresem special.Możesz uzyskać dostęp do pierwszego bez użycia parametru zakresu, ale aby uzyskać dostęp do drugiego, musisz określić parametr zakresu jako w lub wezwaniach API.

Ponadto, jeśli chcesz wymienić wszystkie klucze przechowywane w magazynie danych, który ma jeden lub więcej nie domyślnych zakresów, możesz ustawić parametr w metodzie , w której wezwanie zwraca tabelę z kluczem i zakresem.W poprzednim przykładzie List Entries wróciłoby oba ( 1234 , global ), a także ( 1234 , special ) w odpowiedzi.

Nie możesz przekazać parametrów Scope i AllScopes na tej samej prośba, w przeciwnym razie wezwanie zwraca błąd.Wykorzystując funkcje pomocnicze z otwartych API chmury dla modułu przechowywania danych, następujący kod pokazuje, jak można odczytać każdy klucz w przechowywaniu danych za pomocą niestandardowego zakresu:

Lista kluczy dla różnych zakresów
# Ustaw
import tutorialFunctions
DatastoresApi = tutorialFunctions.DataStores()
datastoreName = "PlayerInventory"

# Lista kluczy dla globalnego zakresu
specialScopeKeys = DatastoresApi.list_entries(datastoreName, scope = "global", allScopes = False)
print(keys.content)
# Lista kluczy dla specjalnego zakresu
specialScopeKeys = DatastoresApi.list_entries(datastoreName, scope = "special", allScopes = False)
print(keys.content)
# Lista kluczy dla wszystkich skryptów ustawionych na prawdę
specialScopeKeys = DatastoresApi.list_entries(datastoreName, allScopes = True)
print(specialScopeKeys.content)

Klucze z odpowiadającym zakresem są zwracane w odpowiedzi:

Przykładowe odpowiedzi na różne zakresy
// Odpowiedź dla globalnego zakresu
{ "keys": [{ "scope": "global", "key": "User_2" }], "nextPageCursor": "" }

// Odpowiedź dla specjalnego zakresu
{"keys":[{"scope":"special","key":"User_6"},{"scope":"special","key":"User_7"}],"nextPageCursor":""}

// Odpowiedź dla 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":""}

Treść-MD5

Content-MD5 jest podstawową-64 zakodowaną sumą kontrolną MD5 treści.Jest to opcjonalny nagłówek żądania dla punktu końcowego Ustaw wpis, który sprawdza integralność danych i wykrywa potencjalne problemy.

Możesz użyć języka swojego wyboru, aby obliczyć wartość nagłówka content-md5.Poniższy przykład używa Python.Funkcje hashlib.md5() i base64.b64encode() są dostępne w standardowych bibliotekach Python (2.7, 3+).

Generowanie treści-MD5
# Z powiadomieniami
$ 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==
# Używanie tylko stdin i stdout
$ echo "750" | python -c "import base64, hashlib; print(str(base64.b64encode(hashlib.md5(bytes(input(), encoding='utf8')).digest()), encoding='utf8'))"
sTf90fedVsft8zZf6nUg8g==

Jeśli napotkasz problemy z generowaniem ważnej wartości content-md5 , możesz potrzebować zakodować swoje ciało żądania w binarnym formacie UTF-8 przed obliczeniem sumy kontrolnej.

Kursorzy

Końcówki, które zwracają listy danych, mogą również zwrócić ciąg.Wskazuje to, że istnieje więcej danych dostępnych w żądanym ustawiaćwyników.Aby go otrzymać, podaj tę strunę w parametrze zapytania cursor na kolejnej prośba.Jeśli parametr kurora jest podany, ale jest nieprawidłowe, końcowy punkt zwrotu zwraca 400 Bad Request .

Format ciągów kursoresów nie jest zdefiniowany . Nie powinieneś ich interpretować ani analizować, ponieważ mogą się zmieniać w dowolnym momencie.

Filtry

Wysyłając żądania do metody List na zamówione magazyny danych, możesz dodać opcjonalny parametr zapytania filter w celu zwrotu wpisów z wartościami w określonym zakresie.

Parametr filter wspiera jeden operator logiczny, && , i dwa operatory porównywania, <= , do ustawienia maksymalnej wartości i >= do ustawienia minimalnej wartości.Jeśli chcesz ustawić zakres z maksymalną i minimalną wartością, dodaj && między dwoma sekwencjami.

Na przykład, aby zwrócić wpisy z wartościami mniejszymi niż lub równymi 10, musisz wprowadzić entry <= 10 jako wartość filter.Aby zwrócić wpisy z wartościami pomiędzy 10 a 50, wprowadź entry <= 50 && entry >= 10.

Poniższe przykłady są nieprawidłowymi filter wartościami, które mogą nie powodować powodzenia żądań:

• entry <= 10 - brak spacji między każdą częścią sekwencji.
• 10 <= entry - entry i wartość porównania jest po niewłaściwej stronie.
• entry <= 10 && entry <= 50 - && można używać tylko do określenia zakresu z obu operatorami porównania dla wartości minimalnej i maksymalnej.

Pozwól na brakujące flagi

Wysyłając żądania do metody Update aktualizującej istniejące zamówione wejście do przechowywania danych, możesz dodać opcjonalną flagę allow_missing, aby umożliwić stworzenie wpisu, nawet jeśli wpis nie istnieje.

Gdy ustawisz flagę allow_missing na True:

• Jeśli wpis nie istnieje, odpowiedź zwraca nowy wpis.

• Jeśli wpis istnieje, ale zawartość pasuje do istniejącej wartości wpisu, istniejący wpis pozostaje niezmieniony.

• Jeśli wpis istnieje i zawartość nie pasuje do istniejącej wartości wpisu, odpowiedź zwraca wpis z aktualną wartością nowej zawartości.