Instances du moteur | Documentation

Les API Open Cloud du moteur vous permettent de gérer les objets Instance dans vos jeux Roblox depuis le web.

Restrictions bêta

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

Vous pouvez uniquement lire et mettre à jour les objets Script, LocalScript et ModuleScript.
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 par clé API. Créez une clé API avec universe-place-instances ajoutée en tant que système API.

Vous devez spécifier les jeux auxquels vous souhaitez que la clé ait accès ainsi que les autorisations de lecture et d'écriture souhaitées.
Vous devez avoir une session collaborative activée pour le jeu auquel vous souhaitez accéder.
Les corps des requêtes, comme pour Mettre à jour une instance, sont limités à 200 Ko.

Lister les enfants

Listez tous les enfants d'une instance spécifique en spécifiant un ID d'instance et en appelant la méthode Lister les enfants de l'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 faire des appels supplémentaires pour trouver des instances plus profondément dans l'arborescence des instances de votre lieu.


import requests

# Généré sur https://create.roblox.com/dashboard/credentials
apiKey = "<API_KEY>"
# Trouvé sur https://create.roblox.com/dashboard/creations dans le menu déroulant d'une tuile de jeu
universeId = "<UNIVERSE_ID>"
# Trouvez l'ID de lieu de départ sur https://create.roblox.com/dashboard/creations dans le menu déroulant d'une tuile de jeu
placeId = "<PLACE_ID>"
# L'ID par défaut pour la racine du modèle de données de n'importe quel lieu
instanceId = "root"

# En-tête de requête
apiKeyHeaderKey = "x-api-key"
# URL de point de terminaison pour la méthode Lister les 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("Résultats de l'opération :", response.status_code, response.text)

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

Plutôt que de simplement lister les enfants, la réponse inclut un objet Operation avec un point de terminaison différent. Interrogez ce point de terminaison pour récupérer de manière asynchrone la liste réelle des enfants. Un exemple 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("Résultats de l'opération :", response.status_code, response.text)
# Analysez le chemin de l'objet Opération pour l'utiliser dans le poll pour la ressource d'instance.
operationPath = response.json()['path']
response = PollForResults(operationPath)
print("Réponse :", 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 particulier :


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 pouvez l'obtenir ou le mettre à jour.
else:
  # Le nom n'a pas été trouvé.

Les scripts contiennent des informations supplémentaires dans l'objet Details, telles que le type de script, la source et s'ils sont activés ou non.

Obtenir une instance

Cette méthode retourne une Instance.


import requests

# Généré sur https://create.roblox.com/dashboard/credentials
apiKey = "<API_KEY>"
# Trouvé sur https://create.roblox.com/dashboard/creations dans le menu déroulant d'une tuile de jeu
universeId = "<UNIVERSE_ID>"
# Trouvez l'ID de lieu de départ sur https://create.roblox.com/dashboard/creations dans le menu déroulant d'une tuile de jeu
placeId = "<PLACE_ID>"
# L'ID par défaut pour la racine du modèle de données de n'importe quel lieu
instanceId = "<INSTANCE_ID>"

# En-tête de requête
apiKeyHeaderKey = "x-api-key"
# URL de point de terminaison pour la méthode Obtenir une 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("Réponse :", 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 Lister les enfants de l'instance, la réponse inclut un objet Operation que vous interrogez pour récupérer l'instance réelle. Voir Poll for results pour plus d'informations.

Mettre à jour les instances

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


import json
import requests

# Généré sur https://create.roblox.com/dashboard/credentials
apiKey = "<API_KEY>"
# Trouvé sur https://create.roblox.com/dashboard/creations dans le menu déroulant d'une tuile de jeu
universeId = "<UNIVERSE_ID>"
# Trouvez l'ID de lieu de départ sur https://create.roblox.com/dashboard/creations dans le menu déroulant d'une tuile de jeu
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 de point de terminaison pour la méthode Mettre à jour l'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("Réponse :", response.status_code, response.text)

# Analysez le chemin de l'objet Opération à partir de la réponse. Interrogez pour obtenir des résultats afin de réaliser
# la mise à jour.
operationPath = response.json()['path']

Si vous recevez une TypeError lorsque vous essayez 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 d'éditeur de script. Vous pouvez également vérifier la sortie du Studio pour des erreurs supplémentaires, telles que Engine_OC_API: Processing Error - Live scripting session is active.

Interroger pour obtenir des résultats

Tous les méthodes actuelles 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 d'origine. Utilisez le chemin de l'objet Operation (inclus dans la réponse initiale) pour interroger quand la ressource est prête.

Vous pouvez utiliser une variété de stratégies de poll, telles que l'utilisation d'un recul exponentiel ou un délai fixe entre les requêtes. L'exemple suivant interroge toutes les cinq secondes, jusqu'à 10 fois.


import requests
import time

# Généré sur https://create.roblox.com/dashboard/credentials
apiKey = "<API_KEY>"
# Utilisez le chemin de l'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 polling
numberOfRetries = 10
retryPollingCadence = 5

# En-tête de requête
apiKeyHeaderKey = "x-api-key"
# URL de point de terminaison 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("Réponse :", response.status_code, response.text)

Démo du magasin de potions

La démo du magasin de potions de Google Sheets vous montre comment mettre à jour un script de jeu depuis le web. La démo se compose de ce qui suit :

Un lieu non copiable avec une interface utilisateur fictive qui affiche diverses potions et leurs prix.
Un fichier .ods que vous importez dans Google Sheets. Ce tableau permet de spécifier et de mettre à jour les valeurs des propriétés dans le jeu.
Le code pour un script Google Apps qui lit les données de la feuille Google et met à jour le script ReplicatedStorage > ItemList dans le jeu Potion Shop.

Configurer la démo

Allez à la Démo du magasin de potions page de découverte. Cliquez sur le menu déroulant, puis Éditer dans Studio. Studio s'ouvre avec une copie du lieu.
Cliquez sur Fichier → Sauvegarder sur Roblox et remplissez les informations nécessaires pour sauvegarder la démo du magasin de potions comme le lieu par défaut pour votre jeu. Testez le jeu. Vous devez voir l'interface utilisateur de la démo du magasin de potions. Notez le nom, le coût et les couleurs des potions. Vous les changerez plus tard à l'aide d'Open Cloud !

Configurer la feuille

Téléchargez le fichier de la feuille de calcul du magasin de potions.
Allez à Google Sheets et cliquez sur Feuille de calcul blanche.
Dans la feuille qui apparaît, cliquez sur Fichier > Importer, et cliquez sur l'onglet Télécharger.
Faites glisser le fichier de la feuille de calcul du magasin 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, sauvegardez le projet.
De retour dans la feuille de calcul, sélectionnez l'onglet Mettre à jour le magasin de potions. Cliquez sur le bouton Mettre à jour le script, cliquez sur le menu déroulant, et sélectionnez Attribuer un script.
Dans la fenêtre Attribuer un script, entrez UpdateScript et cliquez sur OK.

Créer une clé API

Allez à la page Clés API Open Cloud du Creator Hub et cliquez sur Créer une clé API.
Remplissez le formulaire avec les informations suivantes.
- Nom : PotionShop
- Système API : Ajoutez le système API universe-place-instances. Ajoutez votre jeu Potion Shop au système. Pour Opérations d'expérience, ajoutez un accès en lecture et en écriture.
- Adresses IP acceptées : Ajoutez 0.0.0.0/0 en tant qu'adresse IP
- Expiration : Pas d'expiration
- Cliquez sur Sauvegarder & Générer la clé puis sur Copier la clé dans le presse-papiers.
Collez la clé API dans la cellule de clé API (D2) de l'onglet Intro de votre feuille de calcul Google.

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

Allez à la page Créations du Creator Hub, survolez la tuile de jeu du magasin de potions, et cliquez sur le menu déroulant.
Sélectionnez Copier l'ID de l'univers et collez-le dans la cellule ID de l'univers (E2) de l'onglet Intro de votre feuille de calcul Google.
Sélectionnez Copier l'ID de la place de départ et collez-le dans la cellule ID de la place (F2) de l'onglet Intro de votre feuille de calcul Google.

Mettre à jour les valeurs des scripts

Dans l'onglet Mettre à jour le magasin de potions de la feuille, modifiez les valeurs que vous souhaitez et cliquez sur le bouton Mettre à jour le script.
Si Google Sheets vous invite à autoriser, cliquez sur OK et permettez à votre compte d'exécuter le script.
Dans Studio, testez le magasin de potions pour voir les changements reflétés. Depuis la fenêtre Explorateur, vous pouvez également ouvrir le script ReplicatedStorage > ItemList pour inspecter les changements.