Instances moteur | Documentation - Hub Création Roblox

Les API ouvertes du moteur vous permettent de gérer Instance objets dans vos expériences Roblox à partir du web.

Restrictions bêta

Ces API sont actuellement en bêta et ont les restrictions suivantes :

Vous ne pouvez lire et mettre à jour que Script, LocalScript, et ModuleScript objets.
Vous ne pouvez pas mettre à jour les scripts qui sont actuellement ouverts dans Roblox Studio.
Vous ne pouvez pas mettre à jour les scripts qui font partie d'un package .
Vous ne pouvez utiliser que l'authentification API clé. Créez un clé API avec place-instances-univers ajouté comme système d'API.

Vous devez spécifier les expériences que vous souhaitez que la clé ait l'accès à ainsi que les scopes de permission de lecture et d'écriture souhaités.
Vous devez avoir une session collaborative activée pour l'expérience que vous souhaitez accès.
Les demandes de corps, telles que Mettre à jour l'instance, sont limitées à 200 KB.

Enfants

Listez tous les enfants d'une instance spécifique en spécifiant un ID d'instance et en appelant la méthode List Instances Children.

La première fois que vous utilisez ces méthodes, spécifiez root pour l'ID de l'instance. Après avoir reçu la liste des enfants de niveau supérieur et leurs ID, vous pouvez effectuer des appels supplémentaires pour trouver des instances plus profondes dans la hiérarchie d'instance de votre emplacement.


import requests

# Générer à https://create.roblox.com/ashboard/credentials
apiKey = "<API_KEY>"
# Trouvez-le à https://create.roblox.com/dashboards/creations dans le menu déroulant d'une pavéd'expérience
universeId = "<UNIVERSE_ID>"
# Trouvez l'ID de lieu de départ à https://create.roblox.com/dashboards/creations dans le menu déroulant d'une pavéd'expérience
placeId = "<PLACE_ID>"
# L'ID par défaut pour le racine de tout modèlisationde données
instanceId = "root"

# Demander le header
apiKeyHeaderKey = "x-api-key"
# URL de fin de la liste des enfants
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)

# Analysez le chemin de l'objet d'opération pour obtenir plus tard la ressource d'instance. Voir la section Polling for Results pour plus d'informations.
operationPath = response.json()['path']

Au lieu de simplement lister les enfants, la réponse inclut un Operation objet avec un autre端口. Poll this endpoint pour récupérer la liste complète des enfants. Un code plus complet se voit comme ceci :


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)
# Analysez le chemin de l'objet d'opération à utiliser dans le vote pour la ressource de l'instance.
operationPath = response.json()['path']
response = PollForResults(operationPath)
print("Response:", response.status_code, response.text)

La réponse finale ressemblera peut-être à ceci :


{
  "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": {}
        }
      },

      ...

    ]
  }
}

Vous pouvez alors itérer sur le JSON pour trouver un ID d'instance spécifique :


instances = response.json()['response']['instances']
replicatedStorageId = ""
for i in instances:
  if i['engineInstance']['Name'] == "ReplicatedStorage":
    replicatedStorageId = i['engineInstance']['Id']

if replicatedStorageId:
  # Vous avez maintenant un ID d'instance et vous pouvez le obtenir ou le mettre à jour.
else:
  # The name wasn't found.

Les scripts contiennent certaines informations supplémentaires dans l'objet Details, telles que le taperscript, la source et si ils sont activés.

Obtenir une instance

Cette méthode renvoie une seule instance.


import requests

# Générer à https://create.roblox.com/ashboard/credentials
apiKey = "<API_KEY>"
# Trouvez-le à https://create.roblox.com/dashboards/creations dans le menu déroulant d'une pavéd'expérience
universeId = "<UNIVERSE_ID>"
# Trouvez l'ID de lieu de départ à https://create.roblox.com/dashboards/creations dans le menu déroulant d'une pavéd'expérience
placeId = "<PLACE_ID>"
# L'ID par défaut pour le racine de tout modèlisationde données
instanceId = "<INSTANCE_ID>"

# Demander le header
apiKeyHeaderKey = "x-api-key"
# URL de fin de la ligne pour la méthode Get Instance
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)

# Analysez le chemin de l'objet d'opération à partir de la réponse. Voir la section Polling for Results pour plus d'informations.
operationPath = response.json()['path']

Comme la méthode List Instanti Children, la réponse inclut un Operation objet que vous polluez pour récupérer l'instance réelle. Voir Polling for Results pour plus d'informations.

Mise à jour des instances

Après avoir obtenu l'ID d'instance approprié, vous pouvez le mettre à jour. Poll for results après avoir fait la demande de mise à jour initiale.


import json
import requests

# Générer à https://create.roblox.com/ashboard/credentials
apiKey = "<API_KEY>"
# Trouvez-le à https://create.roblox.com/dashboards/creations dans le menu déroulant d'une pavéd'expérience
universeId = "<UNIVERSE_ID>"
# Trouvez l'ID de lieu de départ à https://create.roblox.com/dashboards/creations dans le menu déroulant d'une pavéd'expérience
placeId = "<PLACE_ID>"
instanceId = "<INSTANCE_ID>"
instanceType = ""
propertyName = ""
propertyValue = ""

# Demander le header
apiKeyHeaderKey = "x-api-key"
contentTypeHeaderKey = "Content-type"
contentTypeHeaderValue = "application/json"
# URL de fin de la zone de saisie pour la méthode Mise à jour de la zone
updateInstanceUrl = "https://apis.roblox.com/cloud/v2/universes/%s/places/%s/instances/%s"
# Clé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)

# Analysez le chemin de l'objet d'opération à partir de la réponse. Récupérez les résultats pour exécuter
# la mise à jour.
operationPath = response.json()['path']

Si vous recevez un TypeError lors de l'essayer de mettre à jour un script, vérifiez que le script n'est pas ouvert dans Roblox Studio. Si c'est le cas, fermez son onglet Script Editor. Vous pouvez également vérifier la sortie Studio pour plus d'erreurs, telles que Engine_OC_API: Processing Error - Live scripting session is active .

Pollinisation pour les résultats

Tous les méthodes actuels d'instance retournent un objet Operation à la place de la ressource que vous avez demandée. Cet objet vous permet d'exécuter l'opération d'origine en asynchrone. Utilisez le chemin de l'objet Operation dans la réponse initiale pour polluer quand la ressource est prête.

Vous pouvez utiliser une variété de stratégies de vote, telles que l'utilisation d'un backoff exponentiel ou d'un délai fixe entre les demandes. L'exemple suivant vote toutes les cinq secondes, jusqu'à 10 fois.


import requests
import time

# Générer à https://create.roblox.com/ashboard/credentials
apiKey = "<API_KEY>"
# Utilisez le chemin d'opération de votre demandeinitiale
# Prend la forme d'un « univers / <UNIVERSE_ID / lieux / <PLACE_ID / instances / <INSTANCE_ID>/opérations/ <OPERATION_ID> »
operationPath = "<OPERATION_PATH>"

# Constantes de pollinisation
numberOfRetries = 10
retryPollingCadence = 5

# Demander le header
apiKeyHeaderKey = "x-api-key"
# URL de fin de la longue opération de récupération
getOperationUrl = "https://apis.roblox.com/cloud/v2/%s"
# Clé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)

Démo de la boutique de potions

La démonstration de Google Sheets de la boutique de potions vous montre comment mettre à jour le script d'une expérience à partir du web. La démonstration comprend les éléments suivre:

Un lieu non verrouillé avec une interface utilisateur de démonstration qui affiche diverses potions et leurs prix.
Un fichier .ods que vous importez dans Google Sheets. Ce tableau de bord vous permet de spécifier et de mettre à jour les valeurs pour les propriétés dans l'expérience.
Code pour un script Google Apps qui lit les données de la feuille Google et met à jour le script ReplicatedStorage > ItemList dans l'expérience de la boutique de potions.

Configurer la démo

Allez sur la page Boutique de potions démo. Cliquez sur le menu déroulant et puis Éditer dans le studio . Studio s'ouvre avec une copie du emplacement.
Cliquez sur Fichier → Enregistrer dans Roblox et remplissez les informations nécessaires pour sauvegarder la boutique de potions par défaut. Testez l'expérience. Vous devriez voir l'interface utilisateur pour la boutique de potions. Notez le nom, le coût et les couleurs des potions. Vous les changerez plus tard en utilisant Open Cloud!

Configurer la feuille

Téléchargez le fichier de feuille de calcul de la boutique de potions.
Allez à Google Sheets et cliquez sur Spreadsheets vierges .
Dans la feuille qui apparaît, cliquez sur Fichier > Importer et cliquez sur l'onglet Télécharger .
Faites glisser le fichier de feuille de calcul de la boutique de potions dans la fenêtre de téléchargement.
Choisissez remplacer le feuille de calcul et puis importer les données .
Dans l'onglet AppScript de la feuille, copiez le code dans la cellule A1.
Cliquez sur le menu Extensions > Apps Script et copiez le code dans le Code.gs fichier. Ensuite, enregistrez le projet.
De retour dans la feuille de calcul, sélectionnez l'onglet Mise à jour de la boutique de potions. Cliquez sur le bouton Mettre à jour le script, cliquez sur le menu déroulant et sélectionnez Assigner le script.
Dans la fenêtre Assigner le script , entrez UpdateScript et cliquez sur OK .

Créer une Clé API

Allez sur la page clés de l'API du créateur ouvertes dans le cloud et cliquez sur Créer une clé API .
Remplissez le formulaire avec les informations suivantes.
- Nom. : PotionShop
- API System : Ajoutez le système d'API. Ajoutez votre expérience de boutique de potions au système. Pour Opérations d'expérience , ajoutez l'accès de lecture et d'écriture.
- Adresses IP acceptées : Ajouter 0.0.0.0/0 comme adresse IP
- Expiration : Aucune expiration
- Cliquez sur Enregistrer et générer une clé et puis Copier la clé dans le presse-papiers .
Collez la clé API dans la cellule clé API (D2) sur l'onglet Intro de votre feuille Google.

Obtention de l'ID de l'univers et de la place

Allez sur la page Créations du hub du créateur, passez la souris sur la case d'expérience de la pavéde potions et cliquez sur le menu déroulant.
Sélectionnez Copier l'ID du monde et collez-le dans la Cellule ID du monde (E2) sur l'onglet Intro de votre feuille Google.
Sélectionnez Copier l'identifiant du lieu de départ et collez-le dans la celle ID de lieu (F2) sur l'onglet Intro de votre feuille Google.

Mise à jour des valeurs du script

Dans l'boutique de potions de mise à jour onglet de la feuille, modifiez n'importe quelle valeur que vous souhaitez et cliquez sur le bouton Mettre à jour le script.
Si Google Sheets vous demande d'autoriser, cliquez sur OK et autorisez votre compte à exécuter le script.
Dans Studio, testez la boutique de potions pour voir les changements réflétés. À partir de la fenêtre Explorer , vous pouvez également ouvrir le script ReplicatedStorage > ItemList pour inspecter les changements.