エンジンインスタンス | 文書 - Roblox クリエーターハブ

エンジンOpen Cloud APIを使用すると、WebからRobloxゲーム内のInstanceオブジェクトを管理できます。

ベータ制限

これらのAPIは現在ベータ版であり、以下の制限があります。

Script、LocalScript、およびModuleScriptオブジェクトの読み取りと更新のみが可能です。
現在Roblox Studioで開いているスクリプトを更新することはできません。
パッケージの一部であるスクリプトを更新することはできません。
APIキー認証のみを使用できます。universe-place-instancesをAPIシステムとして追加したAPIキーを作成してください。

アクセスを許可したいゲームと必要な読み取りおよび書き込み権限のスコープを指定する必要があります。
アクセスしたいゲームに共同作業セッションが有効である必要があります。
インスタンスの更新などのリクエストボディは、200 KBに制限されています。

子を一覧表示

特定のインスタンスIDを指定し、インスタンスの子を一覧表示メソッドを呼び出すことで、特定のインスタンスのすべての子を一覧表示できます。

これらのメソッドを初めて使用する場合は、インスタンスIDとしてrootを指定してください。トップレベルの子とそのIDのリストを受け取った後、プレイスのインスタンス階層内のより深いインスタンスを見つけるために追加の呼び出しを行うことができます。


import requests

# Generate at https://create.roblox.com/dashboard/credentials
apiKey = "<API_KEY>"
# Find at https://create.roblox.com/dashboard/creations in the overflow menu of a game tile
universeId = "<UNIVERSE_ID>"
# Find Start Place ID at https://create.roblox.com/dashboard/creations in the overflow menu of a game tile
placeId = "<PLACE_ID>"
# The default ID for the root of any place's data model
instanceId = "root"

# Request header
apiKeyHeaderKey = "x-api-key"
# Endpoint URL for List Children method
listChildrenUrl = "https://apis.roblox.com/cloud/v2/universes/%s/places/%s/instances/%s:listChildren"

def ListChildren():
  url = listChildrenUrl % (universeId, placeId, instanceId)
  headerData = {apiKeyHeaderKey: apiKey}
  results = requests.get(url, headers = headerData)
  return results

response = ListChildren()
print("Operation Results:", response.status_code, response.text)

# Parse the Operation object's path to later obtain the Instance resource. See the Polling for Results section for more information.
operationPath = response.json()['path']

単に子を一覧表示するのではなく、応答には異なるエンドポイントを持つOperationオブジェクトが含まれています。このエンドポイントをポーリングして、非同期に実際の子のリストを取得します。より完全なコードサンプルは次のようになります。


import requests
import time

apiKey = "<API_KEY>"
universeId = "<UNIVERSE_ID>"
placeId = "<PLACE_ID>"
instanceId = "root"

apiKeyHeaderKey = "x-api-key"

listChildrenUrl = "https://apis.roblox.com/cloud/v2/universes/%s/places/%s/instances/%s:listChildren"
getOperationUrl = "https://apis.roblox.com/cloud/v2/%s"

numberOfRetries = 10
retryPollingCadence = 5

doneJSONKey = "done"

def ListChildren():
  url = listChildrenUrl % (universeId, placeId, instanceId)
  headerData = {apiKeyHeaderKey: apiKey}
  results = requests.get(url, headers = headerData)
  return results

def GetOperation(operationPath):
  url = getOperationUrl % (operationPath)
  headerData = {apiKeyHeaderKey: apiKey}
  results = requests.get(url, headers = headerData)
  return results

def PollForResults(operationPath):
  currentRetries = 0
  while (currentRetries < numberOfRetries):
    time.sleep(retryPollingCadence)
    results = GetOperation(operationPath)
    currentRetries += 1

    if (results.status_code != 200 or results.json()[doneJSONKey]):
      return results

response = ListChildren()
print("Operation Results:", response.status_code, response.text)
# Parse the Operation object's path to use in polling for the instance resource.
operationPath = response.json()['path']
response = PollForResults(operationPath)
print("Response:", response.status_code, response.text)

最終的な応答は次のようになります。


{
  "path": "universes/1234567890/places/98765432109/instances/root/operations/a1a2a3a4-a1a2-a1a2-a1a2-a1a2a3a4a5a6",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/roblox.open_cloud.cloud.v2.ListInstanceChildrenResponse",
    "instances": [
      {
        "path": "universes/1234567890/places/98765432109/instances/b1b2b3b4-b1b2-b1b2-b1b2-b1b2b3b4b5b6",
        "hasChildren": true,
        "engineInstance": {
          "Id": "b1b2b3b4-b1b2-b1b2-b1b2-b1b2b3b4b5b6",
          "Parent": "a1a2a3a4-a1a2-a1a2-a1a2-a1a2a3a4a5a6",
          "Name": "Workspace",
          "Details": {}
        }
      },

      ...

    ]
  }
}

次にJSONを反復処理して特定のインスタンスIDを見つけることができます。


instances = response.json()['response']['instances']
replicatedStorageId = ""
for i in instances:
  if i['engineInstance']['Name'] == "ReplicatedStorage":
    replicatedStorageId = i['engineInstance']['Id']

if replicatedStorageId:
  # インスタンスIDが取得され、取得または更新が可能です。
else:
  # 名前が見つかりませんでした。

スクリプトには、スクリプトタイプ、ソース、または有効/無効の状態など、Detailsオブジェクトに追加情報が含まれています。

インスタンスを取得

このメソッドは1つのインスタンスを返します。


import requests

# Generate at https://create.roblox.com/dashboard/credentials
apiKey = "<API_KEY>"
# Find at https://create.roblox.com/dashboard/creations in the overflow menu of a game tile
universeId = "<UNIVERSE_ID>"
# Find Start Place ID at https://create.roblox.com/dashboard/creations in the overflow menu of a game tile
placeId = "<PLACE_ID>"
# The default ID for the root of any place's data model
instanceId = "<INSTANCE_ID>"

# Request header
apiKeyHeaderKey = "x-api-key"
# Endpoint URL for Get Instance method
getInstanceUrl = "https://apis.roblox.com/cloud/v2/universes/%s/places/%s/instances/%s"

def GetInstance():
  url = getInstanceUrl % (universeId, placeId, instanceId)
  headerData = {apiKeyHeaderKey: apiKey}
  return requests.get(url, headers = headerData)

response = GetInstance()
print("Response:", response.status_code, response.text)

# Parse the Operation object's path from response. See the Polling for Results section for more information.
operationPath = response.json()['path']

インスタンスの子を一覧表示するメソッドと同様に、応答には実際のインスタンスを取得するためにポーリングしたOperationオブジェクトが含まれています。結果をポーリングする方法については、さらに詳しい情報を参照してください。

インスタンスを更新

適切なインスタンスIDを取得したら、それを更新できます。最初の更新リクエストを行った後は、結果をポーリングすることをお勧めします。


import json
import requests

# Generate at https://create.roblox.com/dashboard/credentials
apiKey = "<API_KEY>"
# Find at https://create.roblox.com/dashboard/creations in the overflow menu of a game tile
universeId = "<UNIVERSE_ID>"
# Find Start Place ID at https://create.roblox.com/dashboard/creations in the overflow menu of a game tile
placeId = "<PLACE_ID>"
instanceId = "<INSTANCE_ID>"
instanceType = ""
propertyName = ""
propertyValue = ""

# Request header
apiKeyHeaderKey = "x-api-key"
contentTypeHeaderKey = "Content-type"
contentTypeHeaderValue = "application/json"
# Endpoint URL for Update Instance method
updateInstanceUrl = "https://apis.roblox.com/cloud/v2/universes/%s/places/%s/instances/%s"
# JSON keys
detailsJSONKey = "Details"
engineInstanceJSONKey = "engineInstance"

def GeneratePostData():
  propertiesDict = {propertyName: propertyValue}
  detailsDict = {instanceType: propertiesDict}
  instanceDict = {detailsJSONKey: detailsDict}
  outerDict = {engineInstanceJSONKey: instanceDict}
  return json.dumps(outerDict)

def UpdateInstance(postData):
    url = updateInstanceUrl % (universeId, placeId, instanceId)
    headerData = {apiKeyHeaderKey: apiKey,
    contentTypeHeaderKey: contentTypeHeaderValue}
    return requests.patch(url, headers = headerData, data = postData)

postData = GeneratePostData()
response = UpdateInstance(postData)
print("Response:", response.status_code, response.text)

# Parse the Operation object's path from response. Poll for results to perform
# the update.
operationPath = response.json()['path']

スクリプトを更新しようとする際にTypeErrorを受け取った場合は、そのスクリプトがRoblox Studioで開いていないことを確認してください。開いている場合は、そのスクリプトエディタタブを閉じてください。また、Studio出力でEngine_OC_API: Processing Error - Live scripting session is activeなどの追加のエラーを確認することもできます。

結果をポーリングする

すべての現在のインスタンスメソッドは、要求したリソースの代わりにOperationオブジェクトを返します。このオブジェクトによって、元の操作を非同期で実行できます。リソースが準備完了になるまで、最初の応答に含まれるOperationオブジェクトのパスを使用してポーリングします。

さまざまなポーリング戦略を使用できます。たとえば、指数バックオフや、リクエスト間の固定遅延などです。以下の例では、5秒ごとに最大10回ポーリングします。


import requests
import time

# Generate at https://create.roblox.com/dashboard/credentials
apiKey = "<API_KEY>"
# Use the Operation path from your initial request
# Takes the form of "universes/<UNIVERSE_ID>/places/<PLACE_ID>/instances/<INSTANCE_ID>/operations/<OPERATION_ID>"
operationPath = "<OPERATION_PATH>"

# Polling constants
numberOfRetries = 10
retryPollingCadence = 5

# Request header
apiKeyHeaderKey = "x-api-key"
# Endpoint URL for long-running operation polling
getOperationUrl = "https://apis.roblox.com/cloud/v2/%s"
# JSON keys
doneJSONKey = "done"

def GetOperation(operationPath):
  url = getOperationUrl % (operationPath)
  headerData = {apiKeyHeaderKey: apiKey}
  results = requests.get(url, headers = headerData)
  return results

def PollForResults(operationPath):
  currentRetries = 0
  while (currentRetries < numberOfRetries):
    time.sleep(retryPollingCadence)
    results = GetOperation(operationPath)
    currentRetries += 1

    if (results.status_code != 200 or results.json()[doneJSONKey]):
      return results

response = PollForResults(operationPath)
print("Response:", response.status_code, response.text)

ポーションショップデモ

ポーションショップのGoogle Sheetsデモは、Webからゲームのスクリプトを更新する方法を示しています。デモは以下の内容で構成されています。

様々なポーションとその価格を表示するモックUIを備えた、コピー解除されたプレイス。
Google Sheetsにインポートする.odsファイル。このスプレッドシートを使用すると、ゲーム内のプロパティに対して値を指定および更新できます。
Googleシートからデータを読み取り、ポーションショップゲーム内のReplicatedStorage > ItemListスクリプトを更新するGoogle Apps Scriptのコード。

デモを設定する

ポーションショップデモの発見ページに移動します。オーバーフローメニューをクリックし、スタジオで編集を選択します。スタジオはプレイスのコピーを開きます。
ファイル→Robloxに保存をクリックし、ポーションショップデモをゲームのデフォルトプレイスとして保存するために必要な情報を入力します。ゲームをテストします。ポーションショップデモのUIが表示されるはずです。ポーションの名前、コスト、および色をメモしてください。後でOpen Cloudを使用してそれらを変更します！

シートを設定する

ポーションショップのスプレッドシートファイルをダウンロードします。
Google Sheetsに移動し、空白のスプレッドシートをクリックします。
表示されたシートで、ファイル > インポートをクリックし、アップロードタブをクリックします。
ポーションショップのスプレッドシートファイルをアップロードウィンドウにドラッグします。
スプレッドシートを置き換えを選択してから、データをインポートをクリックします。
シートのAppScriptタブで、A1セルのコードをコピーします。
拡張機能 > Apps Scriptメニューをクリックし、コードをCode.gsファイルに貼り付けます。プロジェクトを保存します。
スプレッドシートに戻り、ポーションショップの更新タブを選択します。スクリプトを更新ボタンをクリックし、オーバーフローメニューをクリックしてスクリプトを割り当てを選択します。
スクリプトを割り当てるウィンドウでUpdateScriptと入力し、OKをクリックします。

APIキーを作成する

クリエイターハブOpen Cloud APIキーページに移動し、APIキーを作成をクリックします。
フォームに以下の情報を入力します。
- 名前: PotionShop
- APIシステム: universe-place-instances APIシステムを追加します。Potion Shopゲームをこのシステムに追加します。経験オペレーションに対して、読み取りおよび書き込みアクセスを追加します。
- 受け入れられるIPアドレス: 0.0.0.0/0をIPアドレスとして追加します。
- 有効期限: 有効期限なし
- 保存してキーを生成をクリックし、その後、クリップボードにキーをコピーをクリックします。
GoogleシートのイントロタブのAPIキーセル(D2)にAPIキーを貼り付けます。

ユニバースIDとプレイスIDを取得する

クリエイターハブの作成ページに移動し、ポーションショップのゲームタイルにカーソルを合わせてオーバーフローメニューをクリックします。
ユニバースIDをコピーを選択し、イントロタブのユニバースIDセル(E2)に貼り付けます。
開始プレイスIDをコピーを選択し、イントロタブのプレイスIDセル(F2)に貼り付けます。

スクリプトの値を更新する

シートのポーションショップの更新タブで、好きな値を変更し、スクリプトを更新ボタンをクリックします。
Google Sheetsが認証を求めてきた場合は、OKをクリックし、アカウントがスクリプトを実行できるようにします。
スタジオでポーションショップをプレイテストして、変更を確認します。エクスプローラーウィンドウからReplicatedStorage > ItemListスクリプトを開いて変更を確認することもできます。