엔진 인스턴스

엔진 Open Cloud API를 사용하면 웹에서 Roblox 경험의 Instance 객체를 관리할 수 있습니다.

베타 제한 사항

이 API는 현재 베타 상태이며 다음과 같은 제한 사항이 있습니다:

Script, LocalScript, 및 ModuleScript 객체만 읽고 업데이트할 수 있습니다.
Roblox Studio에서 현재 열려 있는 스크립트는 업데이트할 수 없습니다.
패키지의 일부인 스크립트는 업데이트할 수 없습니다.
API 키 인증만 사용할 수 있습니다. universe-place-instances가 추가된 API 키를 생성하세요.

키가 접근할 수 있는 경험과 원하는 읽기 및 쓰기 권한 범위를 지정해야 합니다.
접근하려는 경험에 대해 협업 세션이 활성화되어 있어야 합니다.
Update Instance와 같은 요청 본체는 200 KB로 제한됩니다.

자식 목록

인스턴스 ID를 지정하고 List Instance Children 메소드를 호출하여 특정 인스턴스의 모든 자식을 나열합니다.

이 메소드를 처음 사용할 때는 인스턴스 ID로 root를 지정하십시오. 최상위 자식 및 그 ID 목록을 받은 후에는 추가 호출을 통해 경험의 인스턴스 계층 구조 내에서 더 깊은 인스턴스를 찾을 수 있습니다.


import requests

# https://create.roblox.com/dashboard/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)

# Operation 객체의 경로를 파싱하여 나중에 Instance 리소스를 얻습니다. 결과를 폴링하는 섹션을 참조하십시오.
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)
# Operation 객체의 경로를 파싱하여 인스턴스 리소스 폴링에 사용합니다.
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 객체에 포함되어 있습니다.

인스턴스 가져오기

이 메소드는 단일 Instance를 반환합니다.


import requests

# https://create.roblox.com/dashboard/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"
# Get Instance 메소드의 엔드포인트 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)

# 응답에서 Operation 객체의 경로를 파싱합니다. 결과를 폴링하는 섹션을 참조하십시오.
operationPath = response.json()['path']

자식 인스턴스 목록 메소드와 마찬가지로, 응답에는 실제 인스턴스를 검색하기 위해 폴링하는 Operation 객체가 포함됩니다. 결과 폴링을 참조하여 더 많은 정보를 얻으십시오.

인스턴스 업데이트

해당 인스턴스 ID를 얻은 후에는 이를 업데이트할 수 있습니다. 초기 업데이트 요청을 보낸 후 결과를 폴링하세요.


import json
import requests

# https://create.roblox.com/dashboard/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"
# Update Instance 메소드의 엔드포인트 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)

# 응답에서 Operation 객체의 경로를 파싱합니다. 업데이트를 수행하기 위해 결과를 폴링합니다.
operationPath = response.json()['path']

스크립트를 업데이트하려고 할 때 TypeError가 발생하면, 스크립트가 Roblox Studio에서 열려 있지 않은지 확인하십시오. 열려 있다면 스크립트 편집기 탭을 닫으세요. 또한 Engine_OC_API: Processing Error - Live scripting session is active와 같은 추가 오류에 대한 Studio 출력을 확인할 수 있습니다.

결과 폴링

현재 모든 Instance 메소드는 요청한 리소스 대신 Operation 객체를 반환합니다. 이 객체를 사용하여 원래 작업을 비동기적으로 수행할 수 있습니다. Operation 객체의 경로(초기 응답에 포함됨)를 사용하여 리소스가 준비될 때까지 폴링합니다.

다양한 폴링 전략을 사용할 수 있습니다. 예를 들어, 지수 백오프를 사용하거나 요청 간에 고정 지연을 두는 방법이 있습니다. 다음 예제는 10번에 걸쳐 5초 간격으로 폴링합니다.


import requests
import time

# https://create.roblox.com/dashboard/credentials에서 생성
apiKey = "<API_KEY>"
# 초기 요청에서의 Operation 경로 사용
# "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 Sheets 데모는 웹에서 경험의 스크립트를 업데이트하는 방법을 보여줍니다. 이 데모는 다음으로 구성됩니다:

다양한 포션과 가격을 표시하는 모의 UI가 있는 잠금 해제되지 않은 장소.
Google Sheets로 가져오는 .ods 파일. 이 스프레드시트를 통해 경험 내 속성에 대한 값을 지정하고 업데이트할 수 있습니다.
Google 시트에서 데이터를 읽고 포션 상점 경험의 ReplicatedStorage > ItemList 스크립트를 업데이트하는 Google Apps 스크립트의 코드.

데모 설정

포션 상점 데모 Discover 페이지로 이동합니다. 오버플로우 메뉴를 클릭한 다음 Edit in Studio를 클릭합니다. Studio는 장소의 복사본으로 열립니다.
File → Save to Roblox를 클릭하고 포션 상점 데모를 경험의 기본 장소로 저장하기 위해 필요한 정보를 입력합니다. 경험을 테스트하십시오. 포션 상점 데모의 UI를 볼 수 있어야 합니다. 나중에 Open Cloud를 사용하여 변경할 포션의 이름, 비용 및 색상을 메모해 두세요!

시트 설정

포션 상점 스프레드시트 파일을 다운로드합니다.
Google Sheets로 가서 빈 스프레드시트를 클릭합니다.
나타난 시트에서 파일 > 가져오기를 클릭하고 업로드 탭을 클릭합니다.
포션 상점 스프레드시트 파일을 업로드 창으로 드래그합니다.
스프레드시트 교체를 선택한 다음 데이터 가져오기를 클릭합니다.
시트의 AppScript 탭에서 A1 셀의 코드를 복사합니다.
확장 > Apps Script 메뉴를 클릭하고 Code.gs 파일에 코드를 붙여넣습니다. 그런 다음 프로젝트를 저장합니다.
스프레드시트로 돌아가서 Update Potion Shop 탭을 선택합니다. Update Script 버튼을 클릭하고 오버플로우 메뉴에서 Assign script를 선택합니다.
Assign script 창에서 UpdateScript를 입력하고 OK를 클릭합니다.

API 키 생성

Creator Hub Open Cloud API Keys 페이지로 가서 Create API Key를 클릭합니다.
다음 정보를 사용하여 양식을 작성합니다.
- 이름: PotionShop
- API 시스템: universe-place-instances API 시스템을 추가합니다. 포션 상점 경험을 시스템에 추가합니다. Experience Operations에 대해 읽기 및 쓰기 액세스를 추가합니다.
- 허용된 IP 주소: 0.0.0.0/0을 IP 주소로 추가합니다.
- 만료: 만료 없음
- 저장 & 키 생성를 클릭한 다음 클립보드에 키 복사를 클릭합니다.
Google 시트의 Introduce 탭의 API Key 셀(D2)에 API 키를 붙여넣습니다.

유니버스 및 장소 ID 얻기

Creator Hub Creations 페이지로 가서 포션 상점 경험 타일에 마우스를 올린 다음 오버플로우 메뉴를 클릭합니다.
Copy Universe ID를 선택하고 이를 Google 시트의 Introduce 탭의 Universe ID 셀(E2)에 붙여넣습니다.
Copy Start Place ID를 선택하고 이를 Google 시트의 Introduce 탭의 Place ID 셀(F2)에 붙여넣습니다.

스크립트 값 업데이트

시트의 Update Potion Shop 탭에서 원하는 값을 수정하고 Update Script 버튼을 클릭합니다.
Google Sheets에서 승인 요청이 표시되면 OK를 클릭하고 스크립트를 실행할 수 있도록 계정을 허용합니다.
Studio에서 포션 상점을 재생하여 반영된 변경 사항을 확인합니다. Explorer 창에서 ReplicatedStorage > ItemList 스크립트를 열어 변경 사항을 확인할 수도 있습니다.

이 페이지