크리에이터

엔진 인스턴스

*이 콘텐츠는 AI(베타)를 사용해 번역되었으며, 오류가 있을 수 있습니다. 이 페이지를 영어로 보려면 여기를 클릭하세요.

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

베타 제한 사항

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

  • Script, LocalScript 및 ModuleScript 객체만 읽고 업데이트할 수 있습니다.

  • Roblox Studio에서 현재 열려 있는 스크립트는 업데이트할 수 없습니다.

  • 패키지의 일부인 스크립트는 업데이트할 수 없습니다.

  • API 키 인증만 사용할 수 있습니다. universe-place-instances을 API 시스템으로 추가하여 API 키를 생성하십시오.

    키가 액세스할 게임과 원하는 읽기 및 쓰기 권한 범위를 지정해야 합니다.

    크리에이터 허브 API 키 화면

  • 액세스하려는 게임에 대해 협업 세션이 활성화되어 있어야 합니다.

  • Update Instance와 같은 요청 본문은 200 KB로 제한됩니다.

자식 목록

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

import requests



# Generate at https://create.roblox.com/dashboard/credentials

apiKey = "<API_KEY>"

# Find at https://create.roblox.com/dashboard/creations in the overflow menu of a game tile

universeId = "<UNIVERSE_ID>"

# Find Start Place ID at https://create.roblox.com/dashboard/creations in the overflow menu of a game tile

placeId = "<PLACE_ID>"

# The default ID for the root of any place's data model

instanceId = "root"



# Request header

apiKeyHeaderKey = "x-api-key"

# Endpoint URL for List Children method

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("작업 결과:", 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("작업 결과:", response.status_code, response.text)

# Operation 객체의 경로를 파싱하여 인스턴스 리소스를 폴링하는 데 사용합니다.

operationPath = response.json()['path']

response = PollForResults(operationPath)

print("응답:", 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



# Generate at https://create.roblox.com/dashboard/credentials

apiKey = "<API_KEY>"

# Find at https://create.roblox.com/dashboard/creations in the overflow menu of a game tile

universeId = "<UNIVERSE_ID>"

# Find Start Place ID at https://create.roblox.com/dashboard/creations in the overflow menu of a game tile

placeId = "<PLACE_ID>"

# The default ID for the root of any place's data model

instanceId = "<INSTANCE_ID>"



# Request header

apiKeyHeaderKey = "x-api-key"

# Endpoint URL for Get Instance method

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.status_code, response.text)



# 응답에서 Operation 객체의 경로를 파싱합니다. 결과를 얻기 위한 폴링 섹션에서 자세한 내용을 확인하십시오.

operationPath = response.json()['path']

List Instance Children 메서드와 마찬가지로 응답에는 실제 인스턴스를 가져오기 위해 폴링하는 Operation 객체가 포함됩니다. 결과를 폴링하는 방법에 대한 더 많은 정보는 여기를 참조하십시오.

인스턴스 업데이트

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

import json

import requests



# Generate at https://create.roblox.com/dashboard/credentials

apiKey = "<API_KEY>"

# Find at https://create.roblox.com/dashboard/creations in the overflow menu of a game tile

universeId = "<UNIVERSE_ID>"

# Find Start Place ID at https://create.roblox.com/dashboard/creations in the overflow menu of a game tile

placeId = "<PLACE_ID>"

instanceId = "<INSTANCE_ID>"

instanceType = ""

propertyName = ""

propertyValue = ""



# Request header

apiKeyHeaderKey = "x-api-key"

contentTypeHeaderKey = "Content-type"

contentTypeHeaderValue = "application/json"

# Endpoint URL for Update Instance method

updateInstanceUrl = "https://apis.roblox.com/cloud/v2/universes/%s/places/%s/instances/%s"

# JSON keys

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.status_code, response.text)



# 응답에서 Operation 객체의 경로를 파싱합니다. 업데이트를 수행하기 위해 결과를 폴링합니다.

operationPath = response.json()['path']

결과 폴링

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

다양한 폴링 전략을 사용할 수 있으며, 예를 들어 기하급수적인 백오프를 사용하거나 요청 사이에 고정된 지연을 사용할 수 있습니다. 다음 예제는 5초마다 최대 10번 폴링합니다.

import requests

import time



# Generate at https://create.roblox.com/dashboard/credentials

apiKey = "<API_KEY>"

# Use the Operation path from your initial request

# Takes the form of "universes/<UNIVERSE_ID>/places/<PLACE_ID>/instances/<INSTANCE_ID>/operations/<OPERATION_ID>"

operationPath = "<OPERATION_PATH>"



# Polling constants

numberOfRetries = 10

retryPollingCadence = 5



# Request header

apiKeyHeaderKey = "x-api-key"

# Endpoint URL for long-running operation polling

getOperationUrl = "https://apis.roblox.com/cloud/v2/%s"

# JSON keys

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.status_code, response.text)

포션 숍 데모

포션 숍 Google Sheets 데모는 웹에서 게임의 스크립트를 업데이트하는 방법을 보여줍니다. 이 데모는 다음으로 구성됩니다:

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

데모 설정

  1. 포션 숍 데모 탐색 페이지로 이동합니다. 오버플로 메뉴를 클릭한 후 Studio에서 편집을 클릭합니다. Studio가 장소의 복사본으로 열립니다.

  2. 파일 → Roblox에 저장을 클릭하고 포션 숍 데모를 기본 장소로 저장하기 위해 필요한 정보를 입력합니다. 게임을 테스트합니다. 포션 숍 데모의 UI를 확인할 수 있어야 합니다. 포션의 이름, 가격 및 색상을 적어두십시오. 나중에 Open Cloud를 사용해 변경할 것입니다!

시트 설정

  1. 다운로드 포션 숍 스프레드시트 파일.
  2. Google Sheets로 이동하고 빈 스프레드시트를 클릭합니다.
  3. 나타나는 시트에서 파일 > 가져오기를 클릭하고 업로드 탭을 클릭합니다.
  4. 포션 숍 스프레드시트 파일을 업로드 창으로 드래그합니다.
  5. 스프레드시트 교체를 선택한 후 데이터 가져오기를 클릭합니다.
  6. 시트의 AppScript 탭에서 A1 셀의 코드를 복사합니다.
  7. 확장 프로그램 > 앱 스크립트 메뉴를 클릭하고 코드를 Code.gs 파일에 붙여넣습니다. 그런 다음 프로젝트를 저장합니다.
  8. 스프레드시트로 돌아가서 Update Potion Shop 탭을 선택합니다. Update Script 버튼을 클릭하고 오버플로 메뉴를 클릭한 후 스크립트 할당을 선택합니다.
  9. 스크립트 할당 창에서 UpdateScript를 입력하고 확인을 클릭합니다.

API 키 생성

  1. Creator Hub Open Cloud API 키 페이지로 이동하여 API 키 생성을 클릭합니다.

  2. 다음 정보를 사용하여 양식을 작성합니다.

    • 이름: PotionShop
    • API 시스템: universe-place-instances API 시스템을 추가합니다. 포션 숍 게임을 시스템에 추가합니다. Experience Operations에 대한 읽기 및 쓰기 접근 권한을 추가합니다.
    • 수락된 IP 주소: 0.0.0.0/0을 IP 주소로 추가합니다.
    • 만료: 만료 없음
    • 저장 및 키 생성을 클릭한 후 클립보드에 키 복사를 클릭합니다.

  3. API 키를 Google Sheet의 Intro 탭에 있는 API 키 셀(D2)에 붙여넣습니다.

유니버스와 장소 ID 얻기

  1. Creator Hub Creations 페이지로 이동하여 포션 숍의 게임 타일 위에 마우스를 올려 오버플로 메뉴를 클릭합니다.
  2. 유니버스 ID 복사를 선택하고 Google Sheet의 Intro 탭에 있는 Universe ID 셀(E2)에 붙여넣습니다.
  3. 시작 장소 ID 복사를 선택하고 Google Sheet의 Intro 탭에 있는 Place ID 셀(F2)에 붙여넣습니다.

스크립트 값 업데이트

  1. 시트의 Update Potion Shop 탭에서 수정하고 싶은 값을 수정한 후 Update Script 버튼을 클릭합니다.
  2. Google Sheets에서 권한을 요청하면 확인을 클릭하고 계정이 스크립트를 실행할 수 있도록 허용합니다.
  3. Studio에서 포션 숍을 플레이 테스트하여 변경 사항이 반영되었는지 확인합니다. 탐색기 창에서 ReplicatedStorage > ItemList 스크립트를 열어 변경 사항을 검사할 수 있습니다.
©2026 Roblox Corporation. Roblox 및 Roblox 로고, 'Powering Imagination'은 미국 및 기타 국가 내 당사의 등록 및 미등록 상표입니다.
약관·개인정보 처리방침·접근성·지원
한국어