엔진 인스턴스

엔진 오픈 클라우드 API를 사용하면 웹에서 Roblox 경험의 개체를 Instance

베타 제한

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

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

키가 액세스할 수 있는 경험과 원하는 읽기 및 쓰기 권한 범위를 지정해야 합니다.
액세스하려는 경험에 대해 공동 작업 세션을 활성화해야 합니다.
요청 본문, 예를 들어 인스턴스 업데이트에 대한 요청은 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 찾기 Find Start Place ID at https://create.roblox.com/dashboard/creations in the overflow menu of an experience tile
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)
# 인스턴스 리소스에 대한 폴링에 사용할 작업 개체의 경로를 분석합니다. 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:
  # 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 찾기 Find Start Place ID at https://create.roblox.com/dashboard/creations in the overflow menu of an experience tile
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']

목록 인스턴스 자식 메서드와 마찬가지로 응답에는 실제 인스턴스를 검색하기 위해 폴링하는 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 찾기 Find Start Place ID at https://create.roblox.com/dashboard/creations in the overflow menu of an experience tile
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 is active).

결과 조사

현재의 모든 인스턴스 메서드는 요청한 리소스 대신 Operation 개체를 반환합니다.이 개체를 사용하면 원래 작업을 비동기적으로 수행할 수 있습니다.Operation 개체의 경로(초기 응답에 포함)를 사용하여 리소스가 준비되는 시기를 조사합니다.

지수 백오프 또는 요청 사이에 고정된 지연과 같은 다양한 조사 전략을 사용할 수 있습니다.다음 예제에서는 5초마다, 최대 10회 폴링합니다.


import requests
import time

# https://create.roblox.com/ashboard/credentials에서 생성
apiKey = "<API_KEY>"
# 처음 요청에서 작업 경로 사용
# 형식은 "우주/<UNIVERSE_ID>/장소/<PLACE_ID>/인스턴스/<INSTANCE_ID>/작업/<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 시트에서 데이터를 읽고 Potion Shop 경험에서 ReplicatedStorage > ItemList 스크립트를 업데이트하는 Google Apps 스크립트의 코드.

데모 설정

포션 상점 데모 발견 페이지로 이동합니다.오버플로 메뉴를 클릭한 다음 Studio에서 편집 을 클릭합니다.스튜디오가 장소의 복사본으로 열립니다.
클릭 파일 → Roblox에 저장 및 경험의 기본 장소로 포션 상점 데모를 저장하기 위한 필요한 정보를 채우십시오.경험을 테스트하십시오.포션 상점 데모의 UI를 볼 수 있어야 합니다.물약의 이름, 비용 및 색상을 기록하십시오.Open Cloud를 사용하여 나중에 변경할 수 있습니다!

시트 설정

포션 상점 스프레드시트 파일을 다운로드합니다.
Google 시트로 이동하고 빈 스프레드시트 를 클릭합니다.
나타나는 시트에서 파일 > 가져오기 를 클릭하고 업로드 탭을 클릭하십시오.
포션 상점 스프레드시트 파일을 업로드 창에 끌어옵니다.
스프레드시트 대체 를 선택한 다음 데이터 가져오기 를 선택합니다.
시트의 AppScript 탭에서 A1 셀의 코드를 복사합니다.
클릭하십시오 확장 > 앱 스크립트 메뉴 및 코드를 Code.gs. 그런 다음 프로젝트를 저장하십시오.
스프레드시트로 돌아가 업데이트 물약 상점 탭을 선택합니다.클릭하십시오 업데이트 스크립트 버튼, 오버플로 메뉴를 클릭하고 스크립트 할당 을 선택합니다.
스크립트 할당 창에서 UpdateScript을 하고 확인 을 클릭하십시오.

API 키 생성

크리에이터 허브 오픈 클라우드 API 키 페이지로 이동하고 API 키 생성 을 클릭하십시오.
다음 정보로 양식을 채우십시오.
- 이름 : PotionShop
- API 시스템 : 유니버스 장소 인스턴스 API 시스템을 추가합니다.포션 상점 경험을 시스템에 추가합니다.경험 작업의 경우 읽기 및 쓰기 액세스를 추가 .
- 승인된 IP 주소 : 0.0.0.0/0을 IP 주소로 추가
- 만료 : 만료 없음
- 클릭 저장 및 키 생성 및 그런 다음 클립보드에 키 복사 .
Google 시트의 소개 탭에 API 키 셀(D2)에 API 키를 붙여넣습니다.

우주와 장소 ID 받기

크리에이터 허브 창작품 페이지로 이동하고, 포션 상점의 경험 타일 위로 마우스를 이동하고, 오버플로 메뉴를 클릭하십시오.
선택 유니버스 ID 복사 및 구글 시트의 소개 탭의 유니버스 ID 셀에 붙여넣습니다(E2).
선택 복사 시작 장소 ID 를 선택하고 Google 시트의 소개 탭에 있는 장소 ID 셀(F2)에 붙여넣습니다.

스크립트 값 업데이트

시트의 업데이트 물약 상점 탭에서 원하는 값을 수정하고 업데이트 스크립트 버튼을 클릭하십시오.
Google 시트가 승인을 요청하면 확인 을 클릭하고 계정이 스크립트를 실행할 수 있도록 허용합니다.
Studio에서 포션 상점을 플레이테스트하여 반영된 변경 사항을 확인하세요.탐색기 창에서 ReplicatedStorage > ItemList 스크립트를 열어 변경 사항을 검사할 수도 있습니다.

이 페이지