Partager via

Gérer l’environnement via des API publiques

  • Article

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.

Important

Cette fonctionnalité est en version préliminaire.

Résumé des API d’environnement disponibles

API Description Catégorie
Créer l’environnement Créer un environnement dans l’espace de travail. Général
Obtenir l’environnement Obtenir les métadonnées d’un environnement. La réponse inclut l’état de l’environnement. Général
Mettre à jour l’environnement Mettez à jour les métadonnées d’un environnement, comme le nom et la description. Général
Supprimer un environnement Supprimer un environnement existant. Général
Liste de l'environnement dans l'espace de travail Obtenir la liste des environnements d'un espace de travail. Général
Publier un environnement Déclenchez la publication de l’environnement avec les modifications en attente actuelles. Général
Publier l’annulation Annuler une publication en cours de l’environnement Général
Obtenir le calcul Spark publié Obtenir les configurations de calcul Spark qui sont efficaces. Calcul Spark
Obtenir le calcul Spark intermédiaire Obtenir les configurations de calcul intermédiaire complètes. Les configurations intermédiaires incluent les configurations de calcul publiées et en attente. Calcul Spark
Obtenir des bibliothèques publiées Obtenez la liste de bibliothèques effective. Bibliothèques
Obtenir des bibliothèques intermédiaires Obtenez la liste complète des bibliothèques intermédiaires. Cette liste inclut les bibliothèques publiées et en attente. Bibliothèques
Charger des bibliothèques intermédiaires Ajout d’une bibliothèque personnalisée ou d’une/plusieurs bibliothèques publiques dans l’environnement. Bibliothèques
Supprimer des bibliothèques intermédiaires Supprimez une bibliothèque personnalisée intermédiaire ou toute bibliothèque publique. Bibliothèques

En savoir plus sur les API publiques d’environnement dans les Eléments API - Environnement

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

Cette section vous guide dans plusieurs scénarios courants lors de la gestion de l’environnement. Vous pouvez remplacer le {WORKSPACE_ID} et le {ARTIFACT_ID} dans les exemples suivants par des valeurs appropriées.

Créer un environnement

Vous pouvez créer un environnement vide à l’aide de 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 charger/supprimer 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/supprimer une bibliothèque, vous pouvez utiliser l’API obtenir des bibliothèques publiées pour case activée quelles bibliothèques sont actuellement effectives.

  • Exemple de requête

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

  • 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": "dependencies:\r\n- pip:\r\n  - matplotlib==3.4.3"
}

Chargement des bibliothèques

L’API pour le chargement de la bibliothèque intermédiaire accepte un fichier à la fois. Les types de fichiers pris en charge sont .whl, .jar, .tar.gz, .py et environment.yml pour la bibliothèque publique. Vous pouvez spécifier le fichier via le type de contenu multipart/form-data.

Remarque

  • Pour manipuler la bibliothèque publique plus efficacement, il est vivement recommandé de composer toutes les bibliothèques attendues de PyPI et conda dans un fichier environment.yml.
  • L’API de chargement autorise jusqu’à 200 Mo fichier dans une requête, la bibliothèque qui dépasse cette limite de taille n’est actuellement pas prise en charge dans l’API publique.

  • Exemples de demandes

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

Suppression des bibliothèques

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

Remarque

  • Si vous spécifiez environment.yml comme fichier à supprimer, vous supprimez toutes les bibliothèques publiques.
  • Si vous souhaitez supprimer un sous-ensemble de bibliothèque publique existante, utilisez plutôt la bibliothèque de chargement et chargez un environment.yml qui contient uniquement les bibliothèques attendues. L’environment.yml chargé remplace entièrement la section de bibliothèque publique existante.

  • Exemples de demandes

    DELETE https://api.fabric.microsoft.com/v1/workspaces/{{WORKSPACE_ID}}/environments/{{ARTIFACT_ID}}/staging/libraries?libraryToDelete=fuzzywuzzy-0.18.0-py2.py3-none-any.whl

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, vous pouvez utiliser l’API de calcul Spark publiée pour case activée quelles configurations de calcul Spark sont actuellement efficaces.

  • Exemple de requête

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

  • Exemple de réponse

    {
    "instancePool": {
        "name": "Starter Pool",
        "type": "Workspace"
    },
    "driverCores": 4,
    "driverMemory": "56g",
    "executorCores": 4,
    "executorMemory": "56g",
    "dynamicExecutorAllocation": {
        "enabled": false,
        "minExecutors": 1,
        "maxExecutors": 1
    },
    "sparkProperties": {
        "spark.acls.enable": "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/supprimer des propriétés Spark via 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 via l’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, vous devez spécifier la valeur comme null avec la clé que vous souhaitez supprimer, comme indiqué dans l’exemple suivant.

  • Exemple de requête

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

{
    "instancePool": {
        "name": "Starter Pool",
        "type": "Workspace"
    },
    "driverCores": 4,
    "driverMemory": "56g",
    "executorCores": 4,
    "executorMemory": "56g",
    "dynamicExecutorAllocation": {
        "enabled": false,
        "minExecutors": 1,
        "maxExecutors": 1
    },
    "sparkProperties": {
        "spark.acls.enable": null
    },
    "runtimeVersion": "1.2"
}

Apporter les modifications effectives

À l’aide des ensembles d’API suivants pour publier les modifications.

Préparer une publication

L’environnement peut accepter une publication à la fois. Avant de publier votre environnement, vous pouvez valider l’état de l’environnement et avoir une révision finale des modifications intermédiaires. Une fois l’environnement publié avec succès, toutes les configurations dans l’état intermédiaire deviennent effectives.

  • Étape 1 : obtenir 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 indiquer clairement l’état de l’environnement. Assurez-vous qu’il n’existe aucune publication en cours avant de passer à l’étape suivante.

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

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

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

Déclencher la publication de l’environnement

Les modifications que vous avez apportées pour les bibliothèques intermédiaires et le calcul Spark sont mises en cache, mais nécessitent l’efficacité de la publication. Suivez l’exemple suivant pour déclencher la publication.

  • Exemple de requête

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

  • Exemple de réponse

    {
    "publishDetails":
    {
        "state": "Running",
        "targetVersion": "46838a80-5450-4414-bea0-40fb6f3e0c0d",
        "startTime": "2024-03-29T14:17:09.0697022Z",
        "componentPublishInfo": {
            "sparkLibraries": {
                "state": "Running"
            },
            "sparkSettings": {
                "state": "Running"
            }
        }
    }
}

Pendant la 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