인벤토리 API를 사용하면 Roblox 내 인벤토리 페이지와 동일한 정보를 대부분 액세스할 수 있습니다. 사용자가 개별 아이템을 소유하고 있는지 확인하고 플레이어가 소유한 아이템의 전체 목록을 검색할 수 있습니다.
인벤토리 API의 응답에는 다음 카테고리의 아이템이 포함됩니다:
- 의류 (액세서리, 하의, 클래식 의류, 신발, 상의)
- 구매 및 보상 (뱃지, 패스, 구매한 장소, 개인 서버)
- 아바타 아이템 (아바타 애니메이션, 클래식 머리, 이모티콘, 얼굴, 머리카락, 머리)
인벤토리 API를 사용하기 전에 API 키 생성을 하거나 OAuth 2 구성을 해야 합니다. 이 페이지의 예제는 API 키를 사용합니다.
아이템 소유 확인
사용자가 특정 아이템(예: 한정판, 배지, 패스 또는 개인 서버)을 소유하고 있는지 확인하려면 filter 매개변수를 사용하여 하나 이상의 ID의 쉼표로 구분된 목록을 확인하십시오. 이 코드 샘플은 세 개의 자산 ID를 확인합니다:
const https = require('node:https');
const userId = 11111111111;
const hostname = 'apis.roblox.com';
const path = `/cloud/v2/users/${userId}/inventory-items`;
const params = '?filter=assetIds=62724852,1028595,4773588762';
const url = 'https://' + hostname + path + params;
const apiKey = '123456789012345678901234567890123456789012345678';
const options = {
headers: {
'x-api-key': `${apiKey}`,
},
};
https
.get(url, options, (response) => {
console.log('statusCode:', response.statusCode);
let data = '';
response.on('data', (d) => {
data += d;
});
response.on('end', () => {
if (response.statusCode === 200) {
const jsonData = JSON.parse(data);
console.log('Response Data:', JSON.stringify(jsonData, null, 2));
} else {
console.error('Error:', response.statusCode, response.statusMessage);
}
});
})
.on('error', (e) => {
console.error(e);
});
다음 응답은 사용자가 세 개의 아이템 중 하나를 소유하고 있음을 나타냅니다:
{
"inventoryItems": [
{
"path": "users/11111111111/inventory-items/VVNFUl9BU1NFVF9JRD0yMDAxMDUxMTkzODg",
"assetDetails": {
"assetId": "1028595",
"inventoryItemAssetType": "CLASSIC_TSHIRT",
"instanceId": "200105119388"
}
}
],
"nextPageToken": ""
}
아이템 필터링
사용자가 소유한 수집품만 표시하고 싶다면 위와 같은 코드를 사용하되, filter 매개변수를 다르게 설정하세요.
const params = '?filter=onlyCollectibles=true;inventoryItemAssetTypes=*';
세미콜론으로 구분된 목록을 사용하여 필터를 혼합하고 일치시킬 수 있습니다. 다음은 몇 가지 예시입니다:
API에 대한 대부분의 호출에는 특별한 권한이 필요하지 않지만, 몇몇 필터는 인벤토리 읽기 권한이 필요합니다. 더 많은 정보는 필터링을 참조하세요.
결과 페이지 매기기
응답에 nextPageToken 값이 포함되어 있으면, 이 값을 이후 요청의 pageToken 매개변수에 사용하여 다음 페이지를 검색합니다. 더 많은 정보는 페이지 매기기를 참조하세요.
결과 수가 maxPageSize로 나누어 떨어지면(예: 결과가 50개이고 maxPageSize가 25인 경우), 응답에 nextPageToken이 포함되어 있지만 그 토큰을 사용한 요청이 결과를 반환하지 않는 상황을 만날 수 있습니다:
GET /cloud/v2/users/{userId}/inventory-items?maxPageSize=25&pageToken=cccDDD
{
"inventoryItems": [],
"nextPageToken": ""
}
앱에서 페이지 매기기를 구현할 때는 빈 nextPageToken이 아닌지와 함께 빈 inventoryItems 배열이 아닌지 확인하는 것이 모범 사례입니다.