데이터 저장소 오류 코드 및 한계

데이터 저장소에 대한 요청은 연결 문제가 있거나 기타 문제로 인해 실패할 수 있습니다. 오류를 처리하고 오류 코드와 함께 메시지를 반환하려면 데이터 저장소 기능을 pcall()로 감싸야 합니다.

UpdateAsync()와 같은 실패한 쓰기 호출은 게임 서버가 성공적인 응답을 받지 못했음을 의미합니다. 백엔드 쓰기가 발생하지 않았음을 보장하지는 않습니다. 일부 실패 시나리오에서는 호출자가 캐시 없이 후속 읽기로 확인할 때까지 최종 쓰기 상태를 알 수 없을 수 있습니다.

오류 코드 참조

서버 오류 코드

한계

데이터 모델에는 한계가 있습니다. 경험이 이러한 한계를 초과하면 서비스가 자동으로 경험의 데이터 저장소 사용을 속도 제한하고 이후 요청을 다음 대기열 중 하나에 배치합니다:

• 설정
• 정렬된 설정
• 가져오기
• 정렬된 가져오기

대기열 내의 요청은 수신된 순서대로 처리됩니다. 호출된 함수는 요청이 여전히 대기 중인 한 계속해서 대기해야 합니다. 데이터 저장소 키 자체가 제한된 경우 요청은 대기열에 배치되지만 일시적으로 건너뜁니다.

각 대기열의 한계는 30 요청입니다. 대기열의 한계에 도달하면 요청이 301-306 범위의 오류 코드로 실패하며 요청이 완전히 삭제되었음을 나타냅니다.

접근 한계

데이터 저장소는 경험 및 서버 수준 한계의 적용을 받습니다. 경험 수준 한계는 경험 전반에 걸쳐 총 동시 사용자 수에 따라 증가하며, 서버 수준 한계는 변동 가능하며 크리에이터가 사용하는 도구로 설계되었습니다.

경험 한계

각 경험은 데이터 저장소 유형, 요청 유형 및 동시 사용자 수에 따라 특정 수의 데이터 저장소 요청을 허용합니다. 각 데이터 저장소 유형과 요청 유형에 대해 한계는 나열된 모든 기능 간에 공유됩니다.

• UpdateAsync()는 읽기와 쓰기 요청 예산을 모두 소모합니다. 단일 호출이 두 한계를 모두 감소시킵니다.
• 게임 서버와 오픈 클라우드는 예산을 공유합니다. 오픈 클라우드 트래픽은 경험 내 사용으로 인해 속도가 제한될 수 있으며(그리고 그 반대도 마찬가지입니다). 속도 제한 제어에서 더 자세한 안내를 참조하세요.

표준 데이터 저장소

정렬된 데이터 저장소

속도 제한 제어

오픈 클라우드와 게임 서버의 요청은 공유되므로 각 요청의 소모량을 독립적으로 제어하는 것이 중요합니다.

게임 서버

각 개별 서버는 위에 설명된 내장 한계가 있습니다. SetRateLimitForRequestType()와 GetRequestBudgetForRequestType()의 조합을 사용하여 개별 서버가 총 예산에 기여하는 것을 세부적으로 제어할 수 있습니다.

오픈 클라우드

오픈 클라우드 요청은 외부 속도 제한 솔루션이 필요합니다. 다음 접근 중 하나를 권장합니다:

• (간단하게) 각 요청 후 짧은 타임아웃을 추가합니다. 특히 동일한 API를 연속 루프에서 호출하는 경우에 필요합니다. 이 타임아웃을 60 / (원하는 예산 소모량 분당) 초로 설정하세요. 이 접근 방식은 요청을 일시적으로 보낼 수 없습니다.
• (강력하게) 누수 버킷 전략을 사용하는 로컬 속도 제한기를 구현합니다.

다음 Node.js 코드 샘플에는 참조 구현이 포함되어 있습니다.

const apiKey = process.env.API_KEY;
if (!apiKey) {
    throw new Error('API_KEY 환경 변수가 설정되지 않았습니다.');
}

const apiHeaderKey = 'x-api-key';

const universeId = '';
const dataStoreId = 'Inventory';

const baseUrl = 'https://apis.roblox.com/cloud/v2/';

// --- 작업별 속도 제한 구성 (분당 요청 수) ---
const LIST_RATE_PER_MIN = 60;
const GET_RATE_PER_MIN = 120;
const UPDATE_RATE_PER_MIN = 60;

// 작업별 상한 간격: 60 / (분당 요청 수) 초.
const LIST_INTERVAL_MS = (60 / LIST_RATE_PER_MIN) * 1000;
const GET_INTERVAL_MS = (60 / GET_RATE_PER_MIN) * 1000;
const UPDATE_INTERVAL_MS = (60 / UPDATE_RATE_PER_MIN) * 1000;

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

// 요청을 수행한 다음 이 작업 자체의 간격을 기다립니다.
async function throttledFetch(url, options, intervalMs) {
    const response = await fetch(url, options);
    await sleep(intervalMs);
    return response;
}

async function listEntries(universe, dataStore) {
    const listPath = `universes/${universe}/data-stores/${dataStore}/entries`;
    const url = baseUrl + listPath;
    const response = await throttledFetch(url, {
        headers: { [apiHeaderKey]: apiKey }
    }, LIST_INTERVAL_MS);
    return response.json();
}

async function getEntry(path) {
    const url = baseUrl + path;
    const response = await throttledFetch(url, {
        headers: { [apiHeaderKey]: apiKey }
    }, GET_INTERVAL_MS);
    return response.json();
}

async function updateEntry(path, payload) {
    const url = baseUrl + path;
    const response = await throttledFetch(url, {
        method: 'PATCH',
        headers: {
            [apiHeaderKey]: apiKey,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify(payload) // 본문은 문자열이어야 합니다.
    }, UPDATE_INTERVAL_MS);
    return response;
}

(async () => {
    try {
        const entries = await listEntries(universeId, dataStoreId);

        for (const entry of entries.dataStoreEntries) {
            const path = entry.path;
            console.log(`\n처리 중인 항목: ${path}`);

            const currentData = await getEntry(path);

            currentData.value.currency += 10;

            const payload = { value: currentData.value };

            const updateResponse = await updateEntry(path, payload);

            console.log(`상태: ${updateResponse.status}`);
            console.log(`응답: ${await updateResponse.text()}`);
        }
    } catch (error) {
        console.error('실행 중 오류가 발생했습니다:', error);
    }
})();

서버 한계

각 서버는 해당 서버의 플레이어 수에 따라 각 요청 유형에 대한 구성 가능한 속도 제한을 갖습니다. 서버는 처음 생성될 때 한 번의 시작 버스트 요청 예산이 추가로 수여됩니다. GetRequestBudgetForRequestType()를 사용하여 현재 서버가 언제든지 만들 수 있는 데이터 저장소 요청 수를 확인하세요.

이러한 한계는 크리에이터가 사용하는 SetRateLimitForRequestType() API를 통해 구성 가능합니다. 이 API를 사용하면 크리에이터가 각 요청 유형에 대한 데이터 저장소 속도 제한을 구성할 수 있습니다.

API를 호출하지 않으면 다음 기본 속도 제한이 적용됩니다:

표준 데이터 저장소

정렬된 데이터 저장소

데이터 한계

데이터 저장소는 각 항목에 대해 사용할 수 있는 데이터 양을 제한합니다.

데이터 저장소 이름, 키 이름 및 범위는 모두 특정 문자 길이 이하이어야 합니다. 이들의 길이를 확인하려면 string.len()을 사용하세요.

데이터(키 값)도 초기 유형에 관계없이 문자열로 저장됩니다. JSONEncode() 함수를 통해 데이터의 크기를 확인할 수 있으며, 이 함수는 Luau 데이터를 직렬화된 JSON 테이블로 변환합니다.

메타데이터 한계

사용자가 정의한 메타데이터의 문자 수에 대한 한계입니다.

처리량 한계

키당 처리량 한계는 Roblox 서버에서 성능을 최적화하도록 보장합니다. 각 한계는 경험의 모든 서버에 걸쳐 모든 키에 적용되며 시간에 따라 새로 고쳐집니다.

Roblox는 지난 60초 동안 키와 관련된 할당량의 사용량을 조사합니다. 현재 요청을 포함한 사용량이 처리량 한계 내에 있는 경우 요청이 승인됩니다. 사용량이 한계를 초과하면 요청이 거부됩니다.

위의 처리량 한계 외에도 Roblox는 데이터를 내부 스키마에 따라 파티션으로 구성합니다. 따라서 백엔드 서버가 동일한 데이터 저장소에 대한 요청의 높은 볼륨을 받을 경우 추가적인 속도 제한이 발생할 수 있습니다. 원인에 관계없이, 속도 제한은 처리량 한계를 초과했는지 여부에 따라 DatastoreThrottled 또는 KeyThrottled 오류로 나타납니다. 이러한 오류 메시지는 정렬된 데이터 저장소와 표준 데이터 저장소 모두에 적용됩니다.

저장 한계

저장을 안정적이고 확장 가능하게 유지하기 위해 데이터 저장소는 게임 수준에서 저장 사용량에 대한 한계를 사용합니다.

이 한계는 각 게임에 대한 기본 할당량과 평생 사용자 수에 따라 추가적으로 할당량을 구성합니다. 평생 사용자는 최소한 한 번 게임에 입장한 모든 사용자를 의미합니다.

저장 한계는 다음 공식을 사용하여 계산됩니다: 최신 버전 총 저장 한계 = 500MB + 1MB × 평생 사용자 수.

저장용량 사용량은 각 키의 최신 버전의 압축 크기를 사용하여 측정됩니다. 데이터 저장소는 데이터를 저장하기 전에 자동으로 압축하므로, 스스로 압축하지 마세요. 미리 압축하면 불필요한 CPU 오버헤드를 추가하고 데이터 저장소의 기본 압축 효과를 감소시킬 수 있습니다. 압축되지 않은 데이터를 저장함으로써, Roblox의 압축 알고리즘과 향후 스키마 기반 최적화의 개선의 혜택을 누리게 됩니다.

각 키의 최신 버전만이 저장 용량 사용량에 포함됩니다. 삭제된 키와 대체 버전은 보존 기간 동안 버전 API를 통해 여전히 접근 가능하지만, 저장 용량 사용량에는 포함되지 않습니다. 그러나 Open Cloud DeleteDataStore 메서드를 통해 삭제된 데이터 저장소는 영구 삭제되기 전 30일 간 삭제 처리 기간 동안 저장 용량 사용량에 포함됩니다.