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

エンジンオープンクラウド API は、Roblox エクスペリエンスのウェブから Instance オブジェクトを管理します。

ベータ版の制限

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

Class.Script 、LocalScript 、ModuleScript オブジェクトのみを読み取り、更新できます。
Roblox Studio で現在開いているスクリプトは更新できません。
パッケージの一部であるスクリプトを更新することはできません。
API キーのみを使用できます。ユニバース-プレースインスタンスを追加した API システムとして、API キーを作成できます。

キーにアクセスしたいエクスペリエンスと、読み取りと書き込み権限のスコープを指定する必要があります。
アクセスしたいエクスペリエンスには、コラボレーションセッションを有効にする必要があります。
リクエストボディ、例えばインスタンスを更新するは、200 KB に制限されています。

子供たちをリスト

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

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


import requests

# https://create.roblox.com/dash/credentials で生成
apiKey = "<API_KEY>"
# エクスペリエンスタイルのオーバーフローメニューで、https://create.roblox.com/dashboards/creations で見つける
universeId = "<UNIVERSE_ID>"
# エクスペリエンスタイルのオーバーフローメニューで、https://create.roblox.com/dash/creations でスタート場所 ID を見つけます
placeId = "<PLACE_ID>"
# 任意の場プレースのデータモデルのルートのデフォルト ID
instanceId = "root"

# リクエストヘッダー
apiKeyHeaderKey = "x-api-key"
# リストの子メソッドのエンドポイント URL
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)

# オペレーションオブジェクトのパスを分析して、インスタンス資源を後で入手します。「結果の調査」セクションを参照してください。
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)
# インスタンス資源の調査票に使用するオペレーションオブジェクトのパスをパラスします。
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:
  # The name wasn't found.

スクリプトは、Detailsオブジェクトに追加の情報を含みます。スクリプトの種入力、ソース、および有効化の有無など。

インスタンスを取得する

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


import requests

# https://create.roblox.com/dash/credentials で生成
apiKey = "<API_KEY>"
# エクスペリエンスタイルのオーバーフローメニューで、https://create.roblox.com/dashboards/creations で見つける
universeId = "<UNIVERSE_ID>"
# エクスペリエンスタイルのオーバーフローメニューで、https://create.roblox.com/dash/creations でスタート場所 ID を見つけます
placeId = "<PLACE_ID>"
# 任意の場プレースのデータモデルのルートのデフォルト ID
instanceId = "<INSTANCE_ID>"

# リクエストヘッダー
apiKeyHeaderKey = "x-api-key"
# GetInstance メソッドのエンドポイント URL
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)

# オペレーションオブジェクトのパスをレポートからパースします。「結果の調査」セクションを参照してください。
operationPath = response.json()['path']

リストインスタンスの子メソッドと同様、レポートには、実際のインスタンスを取得するために Operation オブジェクトを含まれています。詳細は、「結果の調査」を参照してください。

インスタンスを更新する

適切なインスタンス ID を入手した後、更新できます。結果のために投票後、最初の更新リクエストを行う。


import json
import requests

# https://create.roblox.com/dash/credentials で生成
apiKey = "<API_KEY>"
# エクスペリエンスタイルのオーバーフローメニューで、https://create.roblox.com/dashboards/creations で見つける
universeId = "<UNIVERSE_ID>"
# エクスペリエンスタイルのオーバーフローメニューで、https://create.roblox.com/dash/creations でスタート場所 ID を見つけます
placeId = "<PLACE_ID>"
instanceId = "<INSTANCE_ID>"
instanceType = ""
propertyName = ""
propertyValue = ""

# リクエストヘッダー
apiKeyHeaderKey = "x-api-key"
contentTypeHeaderKey = "Content-type"
contentTypeHeaderValue = "application/json"
# アップデートインスタンスメソッドのエンドポイント URL
updateInstanceUrl = "https://apis.roblox.com/cloud/v2/universes/%s/places/%s/instances/%s"
# JSON キー
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)

# オペレーションオブジェクトのパスをリスポンスからパラースします。結果を実行するために
# アップデート。
operationPath = response.json()['path']

スクリプトの更新を試行しているときに TypeError が表示される場合、スクリプトが Roblox Studio で開いていないことを確認してください。如果、そうである場合は、スクリプトエディタタブを閉じてください。また、Engine_OC_API: Processing Error - Live scripting session is active など

結果に投票する

すべての現在のインスタンスメソッドは、リクエストしたリソースではなく Operation。このオブジェクトは、リソースを非同期で実行することができます。 Operation オブジェクトのパス (含まれている場合) を使用して、リソースが準備されたときにポリを実行します。

さまざまな調査ストラテジーを使用できます。たとえば、凸状バックオフを使用するか、リクエスト間の固定遅延を使用するなどです。次の例は、5秒ごとに 10回まで、凸状バックオフを使用します。


import requests
import time

# https://create.roblox.com/dash/credentials で生成
apiKey = "<API_KEY>"
# 最初のリクエストからオペレーションパスを使用する
# 「universe/<UNIVERSE_ID>/places/<PLACE_ID>/instances/<Instance_ID>/Operations/<OPERATION_ID>」の形式を取ります
operationPath = "<OPERATION_PATH>"

# 定数の調査
numberOfRetries = 10
retryPollingCadence = 5

# リクエストヘッダー
apiKeyHeaderKey = "x-api-key"
# 長時間のオペレーションのモニタリングのエンドポイント URL
getOperationUrl = "https://apis.roblox.com/cloud/v2/%s"
# JSON キー
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 シーツのデモでは、ウェブからエクスペリエンスのスクリプトを更新する方法を示しています。デモにはフォロー中のコンポーネントが含まれています：

さまざまなポーションとその価格を表示するモック UI でロックを解除されていない場所。
Google Sheets にインポートする .ods ファイル。このスプレッドシートで、エクスペリエンス内のプロパティに値を指定し、更新できます。
Google Sheet からデータを読み込み、ポーションショップのエクスペリエンスで ReplicatedStorage スクリプトを更新するコード。

デモをセットアップ中

ポーションショップデモへ行くポーションショップデモページを発見する。オーバーフローメニューをクリックし、Studio で編集をクリックします。Studio は、プレース所のコピーを持って開きます。
クリックファイル → Roblox に保存と必要な情報を入力して、ポーションショップデモをデフォルトの場所として保存します。テストエクスペリエンス。You'll see the UI for the Potion Shop Demo.Make a note of the name, cost, and colors of the potions.You'll change them later using Open Cloud!

シートの設定

ポーションショップのスプレッドシートファイルをダウンロードする
Google Sheets に移動し、 Blank Spreadsheet をクリックします。
表示されるリートで、ファイル > インポートをクリックし、アップロードタブをクリックします。
ポーションショップのスプレッドシートファイルをアップロードウィンドウにドラッグします。
Choose スプレッドシートを置き換えるとデータをインポートするを選択します。
シートのアプスクリプトタブに、セル A1 のコードをコピーします。
クリックしてくださいエクステンション > Apps Script メニュー、コードを Code.gs ファイルに入れてください。その後、プロジェクトを保存します。
スプレッドシートに戻り、ポーションショップの更新タブを選択します。スクリプトの更新ボタンをクリックし、オーバーフローメニューをクリックし、2>スクリプトの割り当て2> を選択します。
In the スクリプトの割り当てウィンドウ, enter UpdateScript and click OK .

API キーを作成する

クリエイターハブのオープンクラウド API キーのページに移動し、API キーを作成をクリックします。
フォームに以下の情報を記入してください。
- 名前 : ポーションショップ
- API システム : 宇宙の場所インスタンスを追加する API システムを追加します。ポーションショップエクスペリエンスをシステムに追加します。エクスペリエンス操作の場合、読み取りと書き込みアクセスを追加します。
- 承認された IP アドレス : 0.0.0.0/0 を IP アドレスとして追加
- 有効期限 : 有効期限なし
- クリックして保存とキーを生成する、そしてクリップボードにキーをコピーする。
Google Sheet のイントロタブにある API キーを API キーセル (D2) に貼り付けます。

ユニバースと場所の ID を取得する

クリエイターハブのクリエーションページに移動し、ポーションショップのエクスペリエンスタイルの上にマウスポインタを置き、オーバーフローメニューをクリックします。
Select コピーユニバースID and paste it into the ユニバースID cell (E2) on the Intro tab of your Google Sheet.
Select コピースタート地点ID and paste it into the 場所ID cell (F2) on the Intro tab of your Google Sheet.

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

In the ポーションショップの更新 tab of the ページ, 変更したい値を変更し、スクリプトの更新ボタンをクリックします。
Google Sheets があなたに認可を求める場合は、 OK をクリックし、アカウントでスクリプトを実行できるようにします。
Studio でポーションショップをプレイテストして、反映された変更を確認します。From the エクスプローラーウィンドウから、 ReplicatedStorage スクリプトを開き、変更をインスペクトすることもできます。