Instances de moteur

Les API ouvertes du moteur du cloud vous permettent de gérer Instance des objets dans vos expériences Roblox depuis le web.

Restrictions bêta

Ces API sont actuellement en version 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 actuellement ouverts dans Roblox Studio.
Vous ne pouvez pas mettre à jour les scripts faisant partie d'un paquet.
Vous ne pouvez utiliser l'authentification de clé API que. Créez une clé API avec l'univers-place-instances ajoutée en tant que système API.

Vous devez spécifier les expériences auxquelles vous voulez que la clé ait 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 pour mettre à jour l'instance, sont limitées à 200 KB.

Lister les enfants

Listez tous les enfants d'une instance spécifique en spécifiant une ID d'instance et en appelant la méthode Liste des enfants d'instance.

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 premier niveau et leurs ID, vous pouvez effectuer des appels supplémentaires pour trouver des instances plus profondes dans la hiérarchie des instances de votre emplacement.


import requests

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

# En-tête de requête
apiKeyHeaderKey = "x-api-key"
# URL d'extrémité pour la méthode List Children
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 Opération pour obtenir plus tard la ressource Instance. Voir la section Polling for Results pour plus d'informations.
operationPath = response.json()['path']

Plutôt que d'énumérer simplement les enfants, la réponse inclut un objet Operation avec un point d'extrémité différent. Poll cette extrémité pour récupérer de manière asynchrone la liste réelle des enfants.Un échantillon de code plus complet ressemble à 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 Opération à utiliser lors du vote pour la ressource d'instance.
operationPath = response.json()['path']
response = PollForResults(operationPath)
print("Response:", response.status_code, response.text)

La réponse finale pourrait ressembler à 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 ensuite 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 disposez désormais d'un ID d'instance et pouvez le récupérer 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 elles sont activées.

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 à https://create.roblox.com/ashboard/creations dans le menu débordant d'une pavéd'expérience
universeId = "<UNIVERSE_ID>"
# Trouvez l'ID du lieu de départ à https://create.roblox.com/dashboard/creations dans le menu débordant d'une pavéd'expérience
placeId = "<PLACE_ID>"
# L'ID par défaut pour la racine du modèlisationde données de n'importe quel emplacement
instanceId = "<INSTANCE_ID>"

# En-tête de requête
apiKeyHeaderKey = "x-api-key"
# URL d'extrémité pour la méthode GetInstance
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 Opération à partir de la réponse. Voir la section Polling for Results pour plus d'informations.
operationPath = response.json()['path']

Tout comme la méthode List Instance Children, la réponse inclut un objet Operation que vous interrogez pour récupérer l'instance réelle.Voir enquête pour les résultats pour plus d'informations.

Mettre à jour les instances

Une fois que vous avez obtenu l'ID d'instance approprié, vous pouvez le mettre à jour. Poll pour les résultats 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 à https://create.roblox.com/ashboard/creations dans le menu débordant d'une pavéd'expérience
universeId = "<UNIVERSE_ID>"
# Trouvez l'ID du lieu de départ à https://create.roblox.com/dashboard/creations dans le menu débordant d'une pavéd'expérience
placeId = "<PLACE_ID>"
instanceId = "<INSTANCE_ID>"
instanceType = ""
propertyName = ""
propertyValue = ""

# En-tête de requête
apiKeyHeaderKey = "x-api-key"
contentTypeHeaderKey = "Content-type"
contentTypeHeaderValue = "application/json"
# URL d'extrémité pour la méthode Update Instance
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. Poll pour les résultats à effectuer
# la mise à jour.
operationPath = response.json()['path']

Si vous recevez un TypeError lors de la tentative de mise à jour d'un script, vérifiez que le script n'est pas ouvert dans Roblox Studio.Si c'est le cas, fermez l'onglet Éditeur de scripts.Vous pouvez également vérifier la sortie du studio pour d'autres erreurs, telles que Engine_OC_API: Processing Error - Live scripting session is active .

Sondage pour les résultats

Toutes les méthodes actuelles de Instance retournent un objet Operation au lieu de la ressource que vous avez demandée.Cet objet vous permet d'effectuer de manière asynchrone l'opération originale.Utilisez le chemin de l'objet Operation (inclus dans la réponse initiale) pour voter quand la ressource est prête.

Vous pouvez utiliser une variété de stratégies de vote, telles que l'utilisation d'un recul exponentiel ou d'un délai fixe entre les demandes.L'exemple suivant effectue des sondages 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 demande initiale
# Prend la forme de "universes/<UNIVERSE_ID>/places/<PLACE_ID>/instances/<INSTANCE_ID>/operations/<OPERATION_ID>"
operationPath = "<OPERATION_PATH>"

# Constantes de vote
numberOfRetries = 10
retryPollingCadence = 5

# En-tête de requête
apiKeyHeaderKey = "x-api-key"
# URL d'extrémité pour le polling d'opération de longue durée
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 la boutique de potions Google Sheets vous montre comment mettre à jour le script d'une expérience à partir du web. La démonstration se compose du suivre:

Un endroit non verrouillé avec une interface utilisateur mock 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 des valeurs pour les propriétés dans l'expérience.
Code pour un script Google Apps qui lit des données de la feuille Google et met à jour le script ReplicatedStorage > ItemList dans l'expérience du magasin de potions.

Configurer la démo

Aller à la page Démo de la boutique de potions Découvrir.Cliquez sur le menu débordant, puis Éditer dans Studio .Studio s'ouvre avec une copie de l'emplacement.
Cliquez sur Fichier → Enregistrer dans Roblox et remplissez les informations nécessaires pour enregistrer la démo de la boutique de potions comme lieu par défaut pour votre expérience.Testez l'expérience.Vous devriez voir l'interface utilisateur pour la démo du magasin de potions.Prenez note du nom, du coût et des couleurs des potions.Vous les changerez plus tard en utilisant Open Cloud !

Configurer la feuille

Télécharger le fichier de feuille de calcul de la boutique de potions.
Allez dans feuilles Google et cliquez sur feuille de calcul vide .
Dans la feuille qui apparaît, cliquez sur Fichier > Importer et cliquez sur l'onglet Téléchargement .
Faites glisser le fichier de feuille de calcul de la boutique de potions dans la fenêtre de téléchargement.
Choisissez remplacer la feuille de calcul 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 collez le code dans le fichier Code.gs. 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 Mise à jour du script , cliquez sur le menu de surcharge, et sélectionnez Attribuer le script .
Dans la fenêtre Attribuer le script , entrez UpdateScript et cliquez sur OK .

Créer une clé API

Accédez à la page Créateur Hub Open Cloud API Keys et cliquez sur Créer clé API .
Remplissez le formulaire avec les informations suivantes.
- Nom : PotionShop
- Système API : Ajoutez le système API univers-place-instances .Ajoutez votre expérience de boutique de potions au système.Pour opérations d'expérience , ajoutez l'accès lecture/écriture.
- Adresses IP acceptées : Ajouter 0.0.0.0/0 comme adresse IP
- Expiration : Pas d'expiration
- Cliquez sur Enregistrer et générer la clé 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.

Obtenir l'univers et l'ID de lieu

Accédez à la page créations du hub créateur, survolez la case d'expérience du magasin de potions, et cliquez sur le menu pavé.
Sélectionnez Copier l'ID de l'univers et collez-le dans la cellule ID de l'univers (E2) sur l'onglet Intro de votre feuille Google.
Sélectionnez Copier l'ID du lieu de départ et collez-le dans la cellule ID du lieu (F2) sur l'onglet Intro de votre feuille Google.

Mettre à jour les valeurs du script

Dans l'onglet Mise à jour de la boutique de potions de la feuille, modifiez toutes les valeurs que vous souhaitez et cliquez sur le bouton Mise à jour du script .
Si Google Sheets vous demande l'autorisation, cliquez sur OK et permettez à votre compte d'exécuter le script.
Dans Studio, testez le magasin de potions pour voir toute modification reflétée.De la fenêtre Explorateur , vous pouvez également ouvrir le script ReplicatedStorage > ItemList pour inspecter les modifications.

Sur cette page