Gérer l’environnement via des API publiques

L’API REST Microsoft Fabric fournit un point de terminaison de service pour les opérations de création, de lecture, de mise à jour et de suppression d’un élément Fabric. Cet article décrit les API REST disponibles pour l'environnement et leur utilisation.

Migrer les API d’environnement vers leur version stable en disponibilité générale

Mises à jour des contrats de demande/réponse des APIs

Le beta paramètre est défini par défaut True jusqu’au 31 mars 2026, c’est-à-dire que le système considère le paramètre comme True si la demande envoie sans spécifier ce paramètre jusqu’à la date de dépréciation. Nous vous recommandons vivement de migrer vos implémentations vers la version stable en définissant explicitement le paramètre beta à False dès que possible.

En utilisant l’API List staging libraries comme exemple, dont la réponse a été mise à jour.

• Lors de l’envoi de la requête avec le paramètre beta comme True

  Exemple de demande :

  GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/environments/{environmentId}/libraries?beta=True
  

  Exemple de réponse :

  {
    "customLibraries": {
      "wheelFiles": [
        "samplewheel-0.18.0-py2.py3-none-any.whl"
      ],
      "pyFiles": [
        "samplepython.py"
      ],
      "jarFiles": [
        "samplejar.jar"
      ],
      "rTarFiles": [
        "sampleR.tar.gz"
      ]
    },
    "environmentYml": "name: sample-environment\ndependencies:\n  - fuzzywuzzy==0.0.1\n  - matplotlib==0.0.1"
  }
  

• Lors de l’envoi de la requête avec le paramètre preview comme False

  Exemple de demande :

    GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/environments/{environmentId}/libraries?beta=False
  

  Exemple de réponse :

  {
    "libraries": [
      {
        "name": "samplewheel-0.18.0-py2.py3-none-any.whl",
        "libraryType": "Custom"
      },
      {
        "name": "fuzzywuzzy",
        "libraryType": "External",
        "version": "0.0.1"
      }
    ],
    "continuationToken": "null",
    "continuationUri": "null"
  }
  

API à déprécier

Ci-dessous, quelques exemples illustrent les scénarios pour la gestion des bibliothèques de staging.

• Ajouter les bibliothèques publiques dans votre environnement

  Auparavant, vous pouvez utiliser Upload staging libraries l’API pour charger le fichier YAML mis à jour, et maintenant vous pouvez utiliser Import external libraries l’API pour importer le fichier YAML mis à jour.

• Supprimer une bibliothèque publique dans votre environnement

  Auparavant, vous pouvez utiliser Upload staging libraries l’API pour charger le fichier YAML mis à jour, et maintenant vous pouvez utiliser l’API Remove external library pour la supprimer.

• Supprimer toutes les bibliothèques publiques dans votre environnement

  Auparavant, vous pouvez utiliser Delete staging libraries l’API pour supprimer toutes les bibliothèques publiques, et maintenant vous pouvez utiliser Remove external library l’API pour supprimer les bibliothèques publiques une par une ou pour Import external libraries charger un fichier YAML vide pour obtenir les mêmes fonctionnalités.

Nouvelles API

API sans mise à jour

Pour en savoir plus sur les API publiques de l’environnement, consultez API d’élément - Environnement.

Cas d’utilisation de l’API publique d’environnement

Cette section montre comment utiliser les API pour obtenir des scénarios spécifiques lors de la gestion de l’environnement. Vous pouvez remplacer les propriétés {WORKSPACE_ID} et {ARTIFACT_ID} dans les exemples suivants par des valeurs appropriées.

Créer un nouvel environnement

Pour créer un environnement vide, utilisez l’API suivante.

• Exemple de requête

  POST https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments
  
  {
      "displayName": "Environment_1",
      "description": "An environment description"
  }
  

Gérer les bibliothèques intermédiaires

Vous pouvez utiliser les API de chargement et de suppression des bibliothèques intermédiaires pour gérer la section bibliothèque dans l’environnement.

Vérifier les bibliothèques publiées pour l’environnement

Avant d’ajouter ou de supprimer une bibliothèque, utilisez l’API Get Published Libraries pour vérifier quelles bibliothèques sont actuellement effectives.

• Exemple de requête

  GET https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/libraries?beta=False
  

• Exemple de réponse

  {
    "libraries": [
      {
        "name": "samplewheel-0.18.0-py2.py3-none-any.whl",
        "libraryType": "Custom"
      },
      {
        "name": "fuzzywuzzy",
        "libraryType": "External",
        "version": "0.0.1"
      }
    ],
    "continuationToken": "null",
    "continuationUri": "null"
  }
  

Importer des bibliothèques publiques ou charger une bibliothèque personnalisée

Vous pouvez utiliser Importer des bibliothèques externes et charger des API de bibliothèque personnalisées pour ajouter de nouvelles bibliothèques publiques/personnalisées à votre environnement. L’API importer des bibliothèques externes accepte environment.yml fichier tandis que les types de fichiers pris en charge sont .whl, .jar, .tar.gz, .py pour charger l’API de bibliothèque personnalisée.

• Exemples de demandes

  POST https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/staging/libraries/importExternalLibraries
  

  POST https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/staging/libraries/samplelibrary.jar
  

Supprimer la bibliothèque personnalisée

En spécifiant le nom de fichier de bibliothèque complet avec le suffixe de type, vous pouvez supprimer une bibliothèque personnalisée à la fois.

• Exemples de demandes

  DELETE https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/staging/libraries/samplelibrary.jar
  

Gérer le calcul Spark intermédiaire

Vous pouvez utiliser le calcul Spark intermédiaire de mise à jour pour gérer le calcul Spark.

Vérifier le calcul Spark publié pour l’environnement

Avant de modifier les configurations de l’environnement, utilisez l’API Get Published Spark Compute pour vérifier quelles configurations de calcul Spark sont actuellement effectives.

• Exemple de requête

  GET https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/sparkcompute?beta=False
  

• Exemple de réponse

  {
    "instancePool": {
      "name": "MyWorkspacePool",
      "type": "Workspace",
      "id": "78942136-106c-4f3e-80fc-7ff4eae11603"
    },
    "driverCores": 4,
    "driverMemory": "56g",
    "executorCores": 4,
    "executorMemory": "56g",
    "dynamicExecutorAllocation": {
      "enabled": false,
      "minExecutors": 1,
      "maxExecutors": 1
    },
    "sparkProperties": [
      {
        "key": "spark.acls.enable",
        "value": "false"
      }
    ],
    "runtimeVersion": "1.2"
  }
  

Mettre à jour les configurations de calcul

Vous pouvez mettre à jour le runtime Spark, basculer vers un autre pool, affiner la configuration du calcul et ajouter ou supprimer des propriétés Spark par le biais de la modification du corps de la requête de cette API.

Vous pouvez changer le pool attaché en spécifiant le nom du pool et le pool. Spécifiez le nom de pool Starter Pool pour basculer le pool vers les paramètres par défaut. Pour obtenir la liste complète des pools personnalisés disponibles de l’espace de travail par API REST, consultez Pools personnalisés - Répertorier les pools personnalisés de l’espace de travail.

Si vous souhaitez supprimer une propriété Spark existante, spécifiez la valeur comme null avec la clé que vous souhaitez supprimer.

• Exemple de requête

  PATCH https://api.fabric.microsoft.com/v1/workspaces/f089354e-8366-4e18-aea3-4cb4a3a50b48/environments/707cfd07-cbf1-41da-aad7-dd157ddb8c11/staging/sparkcompute?beta=False
  
  {
    "instancePool": {
      "name": "MyWorkspacePool",
      "type": "Workspace"
    },
    "driverCores": 4,
    "driverMemory": "56g",
    "executorCores": 4,
    "executorMemory": "56g",
    "dynamicExecutorAllocation": {
      "enabled": false,
      "minExecutors": 1,
      "maxExecutors": 1
    },
    "sparkProperties": [
      {
        "key": "spark.acls.enable",
        "value": "false"
      },
      {
        "key": "spark.admin.acls",
        "value": null
      }
    ],
    "runtimeVersion": "1.2"
  }
  

Apporter les modifications effectives

Utilisez les ensembles d’API suivants pour publier les modifications.

Préparer une opération de publication

L’environnement peut accepter une opération de publication à la fois. Avant de publier votre environnement, validez l’état de l’environnement et passez en revue les modifications intermédiaires. Une fois l’environnement publié, toutes les configurations dans l’état intermédiaire deviennent effectives.

• Étape 1 : Obtenez les métadonnées de l’environnement.

  GET https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/
  

  Dans le corps de la réponse, vous pouvez clairement indiquer l’état de l’environnement. Vérifiez qu’aucune opération de publication n’est en cours avant de passer à l’étape suivante.

• Étape 2 : Obtenir les bibliothèques intermédiaires/calcul Spark pour réaliser une révision finale.

  GET https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/staging/libraries?beta=False
  
  GET https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/staging/sparkcompute?beta=False
  

Déclencher l’opération de publication de l’environnement

Les modifications que vous avez apportées aux bibliothèques de préproduction et au calcul Spark sont mises en cache, mais elles doivent être publiées pour prendre effet. Utilisez l’exemple suivant pour déclencher l’opération de publication. La réponse suit le modèle DRO (Long Running Operations) et le code de réponse HTTP 202 peuvent être retournés.

• Exemple de requête

  POST https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/staging/publish?beta=False
  

• Exemple de réponse

  Location: https://api.fabric.microsoft.com/v1/operations/abcdef00-9d7e-469a-abf1-fca847a0ea69
  x-ms-operation-id: abcdef00-9d7e-469a-abf1-fca847a0ea69
  Retry-After: 120  
  

Pendant l’opération de publication, vous pouvez également appeler l’API suivante pour l’annuler.

• Exemple de requête

  POST https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/staging/cancelPublish
  

Contenu connexe

• Créer, configurer et utiliser un environnement dans Fabric
• API des éléments - Environnement