スタジオやライブゲームのエンジンAPIからデータストアにアクセスすることに加えて（DataStoreService）、オープンクラウドAPIを使って外部スクリプトや他のツールから標準および順序付きデータストアにアクセスできます。
オープンクラウドへのアクセスは、多くの潜在的なユースケースを解放します。たとえば：
- チームがサポートリクエストを直接処理できるカスタマーサポートポータル（ユーザーの在庫を変更したり、返金を発行したりするなど）
- 外部ウェブサイトに表示できるグローバルリーダーボード
- 現在のデータストアからエントリを読み取って新しいスキーマにマッピングし、新しいデータストアにエントリを書き戻すスクリプトによるスキーマの更新
このページの例は、Node.jsとPythonでユーザー在庫サポートポータルと外部リーダーボードを構築する方法を示していますが、好みの言語を使用してください。オープンクラウドAPIは、HTTPリクエストを送信できる任意のプログラミング言語をサポートしています。
エンジンAPIとの違い
オープンクラウドAPIは同じ基盤のデータストアにアクセスしており、DataStoreServiceでの作業に似ていますが、いくつかの主要な違いがあります。
ユニバースID: エンジンAPIとは異なり、オープンクラウドAPIはステートレスであり、どこからでも呼び出すことができるため、ユニバースID、すなわちゲームの一意の識別子を常に提供する必要があります。
作成と更新のための別々の権限: エンジンAPIは、DataStore:SetAsync()を呼び出したときに、存在しない場合は新しいエントリを作成しますが、オープンクラウドの作成と更新エントリのメソッドは別々です。別々の権限は、特定の状況でより安全で柔軟になる場合があります。たとえば、カスタマーサポートツールが新しいユーザーのプロファイルを新規作成するのではなく、既存のユーザープロファイルのみを編集できるようにしたい場合があります。
データのシリアル化: すべてのオープンクラウドエンドポイントは、データを送信する前にシリアル化する必要があります。シリアル化とは、オブジェクトを文字列に変換することを意味します。デシリアル化は逆に、文字列をオブジェクトに変換することを意味します。エンジンAPIはエントリ内容を自動的にシリアル化およびデシリアル化しますが、オープンクラウドでは、JSONにエントリを生成または解析する必要があります。
権限
データストアはしばしばユーザープロファイルや仮想通貨などの機密情報を保持しています。セキュリティを維持するために、各オープンクラウドメソッドには、APIキーに追加する必要がある対応する権限、いわゆるスコープがあります。データストアをリストするメソッドのスコープはuniverse-datastores.control:listです。必要な権限を追加しないと、API呼び出しはエラーを返します。各エンドポイントに必要なスコープについては、リファレンスドキュメントを参照してください。
権限の管理に関する詳細は、APIキーの管理を参照してください。
ユーザー在庫サポートポータル
この例では、Inventoryというデータストアと、各エントリのスキーマとして"userId": {"currency": number, "weapon": string, "level": number}を使用します。キーはuserIdです。
必要なスコープ
この例のためにAPIキーを作成するときは、次のスコープをキーに追加してください：
- universe-datastores.objects:list
- universe-datastores.objects:read
- universe-datastores.objects:update
オプションで、Inventoryデータストアのみの権限を追加し、IPアドレス制限を設定し、有効期限を設定します。
ユーザー在庫サポートポータル用のスクリプトを追加する
例アプリに必要な権限を持つAPIキーを作成した後、エンドポイントにリクエストを送信するスクリプトを作成します。これらのスクリプトは、データストア内の最初の10エントリを取得し、それぞれのcurrency値を10ずつ増加させ、その後、各エントリを更新します。大規模なデータストアの場合、maxPageSizeおよびpageTokenクエリパラメーターを使用してページネーションに対処する必要があります。
incrementCurrency.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/';
async function listEntries(universe, dataStore) {
const listPath = `universes/${universe}/data-stores/${dataStore}/entries`;
const url = baseUrl + listPath;
const response = await fetch(url, {
headers: { [apiHeaderKey]: apiKey }
});
return response.json();
}
async function getEntry(path) {
const url = baseUrl + path;
const response = await fetch(url, {
headers: { [apiHeaderKey]: apiKey }
});
return response.json();
}
async function updateEntry(path, payload) {
const url = baseUrl + path;
const response = await fetch(url, {
method: 'PATCH',
headers: {
[apiHeaderKey]: apiKey,
'Content-Type': 'application/json'
},
body: JSON.stringify(payload) // ボディは文字列でなければなりません
});
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);
}
})();
テストするには、API_KEY環境変数を設定し、依存関係をインストールし、スクリプトを実行します：
外部持続的リーダーボード
この例では、デモ目的のために事前定義されたユーザーのリストを作成しますが、実際のゲームで有用であるためには、実際のユーザーデータストアが必要です。
必要なスコープ
この例のためにAPIキーを作成するときは、次のスコープをキーに追加してください：
- universe.ordered-data-store.scope.entry:read
- universe.ordered-data-store.scope.entry:write
リーダーボード用のスクリプトを追加する
例アプリに必要な権限を持つAPIキーを作成した後、エンドポイントにリクエストを送信するスクリプトを作成します。これらのスクリプトは、ランダムな数値を持つサンプルエントリを順序付きデータストアに追加し、それらを値が高い順に取得します。大規模なデータストアの場合、maxPageSizeおよびpageTokenクエリパラメーターを使用してページネーションに対処する必要があります。
leaderboard.js
const apiKey = process.env.API_KEY;
const apiHeaderKey = 'x-api-key';
const universeId = '';
const orderedDataStoreId = 'PlayerScores';
const scopeId = 'global';
const baseUrl = 'https://apis.roblox.com/cloud/v2/';
async function createOrderedEntry(universe, orderedDataStore, entryId, payload) {
const createPath = `universes/${universe}/ordered-data-stores/${orderedDataStore}/scopes/${scopeId}/entries`;
const url = new URL(baseUrl + createPath);
url.searchParams.append('id', entryId);
const response = await fetch(url, {
method: 'POST',
headers: {
[apiHeaderKey]: apiKey,
'Content-Type': 'application/json',
},
body: JSON.stringify(payload),
});
if (!response.ok) {
const errorText = await response.text();
throw new Error(`APIエラー (${response.status}): ${errorText}`);
}
return response.text();
}
async function listOrderedEntries(universe, orderedDataStore) {
const listPath = `universes/${universe}/ordered-data-stores/${orderedDataStore}/scopes/${scopeId}/entries`;
const url = new URL(baseUrl + listPath);
url.searchParams.append('orderBy', 'value desc');
return fetch(url, {
headers: {
[apiHeaderKey]: apiKey,
},
});
}
async function main() {
if (!apiKey) {
console.error('エラー: API_KEY環境変数が設定されていません。');
process.exit(1);
}
const entryNames = ['Ragdoll', 'Balinese', 'Tabby', 'Siamese'];
console.log('サンプルデータを作成中...');
for (const name of entryNames) {
try {
const randomValue = Math.floor(Math.random() * 50) + 1;
const payload = { value: randomValue };
const responseText = await createOrderedEntry(universeId, orderedDataStoreId, name, payload);
console.log(responseText);
} catch (error) {
console.error(`"${name}"のエントリ作成に失敗しました: ${error.message}`);
}
}
console.log('\nエントリのソートされたリストを取得中...');
try {
const playerScoresResponse = await listOrderedEntries(universeId, orderedDataStoreId);
console.log(playerScoresResponse.status);
const responseText = await playerScoresResponse.text();
console.log(responseText);
} catch (error) {
console.error(`エントリのリストに失敗しました: ${error.message}`);
}
}
main();
テストするには、API_KEY環境変数を設定し、依存関係をインストールし、スクリプトを実行します：