엔진 인스턴스 | 설명서 - Roblox 크리에이터 허브

엔진 오픈 클라우드 API를 사용하면 Roblox 경험에서 Instance 개체를 웹에서 관리할 수 있습니다.

베타 제한

이러한 API는 현재 베타 단계에 있으며 다음과 같은 제한이 있습니다.

Class.Script, LocalScript, 그리고 ModuleScript 개체만 읽고 업데이트할 수 있습니다.
Roblox Studio에서 현재 열려 있는 스크립트를 업데이트할 수 없습니다.
패키지의 일부인 스크립트를 업데이트할 수 없습니다.
API 키 인증만 사용할 수 있습니다. API 키를 생성하고 유니버스 장소 인스턴스를 추가한 API 시스템으로 사용자에게 제공합니다.

키가 액세스할 경험과 원하는 읽기 및 쓰기 권한 범위를 지정해야 합니다.
액세스하려는 경험에 대해 공동 작업 세션이 활성화되어 있어야 합니다.
요청 바디, 예를 들어 인스턴스 업데이트,은 200 KB로 제한됩니다.

어린이 목록

특정 인스턴스의 모든 자식을 식별하려면 인스턴스 ID를 지정하고 목록 인스턴스 자식 호출 메서드를 호출합니다.

이 메서드를 처음 사용할 때 인스턴스 ID에 대해 root를 지정합니다. 최상위 자식의 목록과 해당 아이디를 받으면 플레이스인스턴스 계층 더 깊이에서 인스턴스를 더 찾을 수 있습니다.


import requests

# https://create.roblox.com/dashboard/credentials에서 생성
apiKey = "<API_KEY>"
# 경험 타일의 대시보드에서 경험 내 생성 메뉴에서 찾아보세요.
universeId = "<UNIVERSE_ID>"
# 경험 타일의 결과 메뉴에서 https://create.roblox.com/dashboards/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": {}
        }
      },

      ...

    ]
  }
}

그런 다음 자바스크립트를 반복하여 특정 인스턴스 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/dashboard/credentials에서 생성
apiKey = "<API_KEY>"
# 경험 타일의 대시보드에서 경험 내 생성 메뉴에서 찾아보세요.
universeId = "<UNIVERSE_ID>"
# 경험 타일의 결과 메뉴에서 https://create.roblox.com/dashboards/creations에서 시작 장소 ID를 찾습니다.
placeId = "<PLACE_ID>"
# 모든 플레이스데이터 모델의 루트에 대한 기본 ID
instanceId = "<INSTANCE_ID>"

# 요청 헤더
apiKeyHeaderKey = "x-api-key"
# 인스턴스 생성 메서드에 대한 엔드포인트 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']

List 인스턴스 자식 메서드와 마찬가지로 응답에는 실제 인스턴스를 검색하려는 Operation 개체가 포함되어 있습니다. 자세한 내용은 결과 검색을 위한 참조하십시오.

인스턴스 업데이트

적절한 인스턴스 ID를 얻은 후, 업데이트할 수 있습니다. 결과 투표 후 초기 업데이트 요청을 작성한 후.


import json
import requests

# https://create.roblox.com/dashboard/credentials에서 생성
apiKey = "<API_KEY>"
# 경험 타일의 대시보드에서 경험 내 생성 메뉴에서 찾아보세요.
universeId = "<UNIVERSE_ID>"
# 경험 타일의 결과 메뉴에서 https://create.roblox.com/dashboards/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에서 스크립트가 열리지 않은지 확인하십시오. 열려 있으면 스크립트 편집기 탭을 닫습니다. 또한 Studio 출력에 대해 자세한 오류를 확인할 수 있습니다. 예를 들어, Engine_OC_API: Processing Error - Live scripting session

결과에 대한 조사

모든 현재 인스턴스 메서드는 원하는 리소스가 아닌 Operation 개체를 반환합니다. 이 개체를 사용하면 원격 코드를 동기적으로 실행할 수 있습니다. 리소스가 준비되면 Operation 개체의 경로(포함된 첫 번째 응답)를 사용하여 비동기적으로 검색합니다

다양한 조사 전략을 사용할 수 있습니다, 예를 들어 기하급수 백오프를 사용하거나 요청 간의 고정 지연. 다음 예는 5초마다 조사됩니다, 최대 10번까지.


import requests
import time

# https://create.roblox.com/dashboard/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"
# Long-running operation polling에 대한 종료점 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 Sheet에서 데이터를 읽고 포션 상점 경험에서 ReplicatedStorage 스크립트를 업데이트하는 Google Apps 스크립트의 코드.

데모 설정

go to the 포션 상점 데모 Discover page. Click on the overflow menu, and then Studio에서 편집 . Studio opens with a copy of the 플레이스.
클릭 파일 파일 파일 파일 파일 파일 파일 파일 파일 파일 파일 파일 파일 파일 파일 파일 파일 파일 파일 파일 파일 파일 파일 파일 파일 파일 파일 파일 파일 파일 파일 파일 파일 파일 파일 파일 파일 파일 파일 파일 파일 파일 파일 파일 파일 파일

시트 설정

다운로드 물약 상점 스프레드시트 파일을 다운로드하십시오.
Google Sheets로 이동하고 빈 스프레드시트를 클릭하십시오.
표시되는 서식에서 파일 > 가져오기를 클릭하고 업로드 탭을 클릭하십시오.
물약 상점 스프레드시트 파일을 업로드 창에 드래그하십시오.
Choose 서식지를 대체하기 및 다음 데이터 가져오기 .
시트의 앱스크립트 탭에서 셀 A1에 코드를 복사합니다.
클릭하십시오 확장 메뉴 스크립트 및 코드를 Code.gs 파일에 붙여넣고 프로젝트를 저장합니다.
스프레드시트로 돌아가서 포션 상점 업데이트 탭을 클릭하십시오. 스크립트 업데이트 버튼을 클릭하고 넘겨주기 메뉴를 클릭하고 스크립트 할당을 선택합니다.
In the 스크립트 할당 창 에서 UpdateScript를 입력하고 확인 을 클릭하십시오.

API 키 생성

크리에이터 허브 오픈 클라우드 API 키 페이지로 이동하고 API 키 생성을 클릭하십시오.
다음 정보를 입력하세요.
- 이름 : PotionShop
- API 시스템 : 유니버스 장소 인스턴스를 추가합니다. 포션 상점 경험을 시스템에 추가합니다. 대한 액션 작업에 대해 읽기 및 쓰기 액세스 를 추가합니다.
- 허용된 IP 주소 : 0.0.0.0/0 을 IP 주소로 추가
- 만료 : 만료 없음
- 클릭하십시오 Save & Generate Key 및 다음 키를 클립보드에 복사 .
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 시트에서 권한을 부여하도록 요청하면 OK 를 클릭하고 계정에서 스크립트를 실행할 수 있습니다.
In Studio, playtest the Potion Shop to see any reflected changes. 从 Explorer 창에서, you can also open the ReplicatedStorage script to inspect the changes.