エンジンインスタンス

エンジンオープンクラウド API では、Web から Roblox の経験で Instance オブジェクトを管理できます。

ベータ制限

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

読み込みと更新が可能なのは、Script、LocalScript、およびModuleScriptオブジェクトのみです。
Roblox Studio で現在開いているスクリプトは更新できません。
パッケージの一部であるスクリプトを更新することはできませんパッケージ。
API キー認証のみを使用できます。API システムとしてユニバースプレースインスタンスを追加して API キーを作成します。

キーがアクセスできる必要があるエクスペリエンスと、読み込みと書き込みの許可スコープを指定する必要があります。You must specify the experiences you want the key to have access to as well as the desired read and write permission scopes.
アクセスしたいエクスペリエンスに対して、共同作業セッションが有効になっている必要があります。
リクエストボディ、例えばインスタンスの更新、は 200KB に制限されています。

子供をリストする

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

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


import requests

# https://create.roblox.com/ashboard/credentials で生成
apiKey = "<API_KEY>"
# エクスペリエンスタイルのオーバーフローメニューで https://create.roblox.com/dashboard/creations を見つける
universeId = "<UNIVERSE_ID>"
# エクスペリエンスタイルのオーバーフローメニューで https://create.roblox.com/dashboard/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/ashboard/credentials で生成
apiKey = "<API_KEY>"
# エクスペリエンスタイルのオーバーフローメニューで https://create.roblox.com/dashboard/creations を見つける
universeId = "<UNIVERSE_ID>"
# エクスペリエンスタイルのオーバーフローメニューで https://create.roblox.com/dashboard/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/ashboard/credentials で生成
apiKey = "<API_KEY>"
# エクスペリエンスタイルのオーバーフローメニューで https://create.roblox.com/dashboard/creations を見つける
universeId = "<UNIVERSE_ID>"
# エクスペリエンスタイルのオーバーフローメニューで https://create.roblox.com/dashboard/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 などの追加エラーの Studio 出力をチェックすることもできます。

結果の調査票

すべての現在のインスタンスメソッドは、リソースを要求したものではなく Operation オブジェクトを返します。このオブジェクトでは、オリジナルの操作を非同期で実行できます。Operation オブジェクトのパス (初期応答に含まれる) を使用して、リソースが準備完了したときを調査します。

幾何級のバックオフやリクエストの間の固定遅延など、さまざまな調査戦略を使用できます。次の例では、5秒ごとに、最大 10回調査します。


import requests
import time

# https://create.roblox.com/ashboard/credentials で生成
apiKey = "<API_KEY>"
# 最初のリクエストからオペレーションパスを使用
# 形式は "universes/<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 スプレッドシートにインポートする .ods ファイル。このスプレッドシートでは、エクスペリエンス内のプロパティの値を指定して更新できます。
Google スプレットシートからデータを読み込み、ポーションショップエクスペリエンスの ReplicatedStorage > ItemList スクリプトを更新する Google Apps スクリプトのコード。

デモを設定する

ポーションショップデモ発見ページに移動します。オーバーフローメニューをクリックし、次に Studio で編集。スタジオは場プレースのコピーで開きます。
クリックファイル → Roblox に保存、およびポーションショップデモをエクスペリエンスのデフォルト場所として保存するための必要な情報を記入します。エクスペリエンスをテストします。ポーションショップデモの UI を見るべきです。ポーションの名前、コスト、色をメモします。オープンクラウドを使用して後で変更します!

シートを設定する

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

API キーを作成する

Go to the クリエイターハブオープンクラウドAPIキー page and click APIキーを作成 .
以下の情報でフォームを記入してください。
- 名前 : PotionShop
- API システム : ユニバースプレースインスタンス API システムを追加。ポーションショップの経験をシステムに追加します。For エクスペリエンス操作、読み込みと書き込みアクセスアクセス, 書き込み権限 (write access)追加します。
- 承認された IP アドレス : IP アドレス 0.0.0.0/0 を追加
- 有効期限 : 期限なし
- クリック保存してキーを生成、そしてクリップボードにキーをコピー。
Google スプレットシートのイントロタブの API キーセル (D2) に API キーを貼り付けます。

宇宙と場所IDを取得

クリエイターハブ作品ページに移動し、ポーションショップのエクスペリエンスタイルをホバーし、オーバーフローメニューをクリックします。
Select ユニバースIDをコピー and paste it into the ユニバースID cell (E2) on the Intro tab of your Google Sheet.
Select コピー開始場所IDを選択と paste it into the 場所ID セル (F2) on the Intro tab of your Google Sheet.

スクリプト値を更新する

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

ページ内容