Condividi tramite

Gestire l'ambiente tramite API pubbliche

  • Articolo

L'API REST di Microsoft Fabric fornisce un endpoint servizio per le operazioni di creazione, lettura, aggiornamento ed eliminazione (CRUD) di un elemento di Fabric. Questo articolo descrive le API REST dell'ambiente disponibili e il relativo utilizzo.

Importante

Questa funzionalità è in anteprima.

Riepilogo delle API dell'ambiente disponibili

API Descrizione Categoria
Creare un ambiente Creare un nuovo ambiente nell'area di lavoro. Generali
Ottenere l'ambiente Ottenere i metadati di un ambiente. La risposta include lo stato dell'ambiente. Generali
Aggiornamento dell'ambiente Aggiornare i metadati di un ambiente, come il nome e la descrizione. Generali
Elimina ambiente Eliminare un ambiente esistente. Generali
Elencare l'ambiente nell'area di lavoro Ottenere l'elenco di tutti gli ambienti in un'area di lavoro. Generali
Pubblicare l'ambiente Attivare la pubblicazione dell'ambiente con le modifiche attuali in sospeso. Generali
Pubblicare l'annullamento Annullare una pubblicazione in corso dell'ambiente Generali
Ottenere l'ambiente di calcolo Spark pubblicato Ottenere le configurazioni di calcolo Spark valide. Calcolo di Spark
Ottenere l'ambiente di calcolo Spark di gestione temporanea Ottenere le configurazioni di calcolo complete di gestione temporanea. Le configurazioni di gestione temporanea includono le configurazioni di calcolo pubblicate e in sospeso. Calcolo di Spark
Ottenere librerie pubblicate Ottenere l'elenco di librerie che è efficace. Librerie
Ottenere le librerie di gestione temporanea Ottenere l'elenco completo delle librerie di gestione temporanea. Questo elenco include le librerie pubblicate e in sospeso. Librerie
Caricare le librerie di gestione temporanea Aggiungere una libreria personalizzata o una o più librerie pubbliche nell'ambiente. Librerie
Eliminare le librerie di gestione temporanea Eliminare una libreria personalizzata di gestione temporanea o tutta la libreria pubblica. Librerie

Altre informazioni sulle API pubbliche dell'ambiente nelle API degli elementi – Ambiente

Casi d'uso dell'API pubblica dell'ambiente

Questa sezione illustra diversi scenari comuni durante la gestione dell'ambiente. È possibile sostituire {WORKSPACE_ID} e {ARTIFACT_ID} negli esempi seguenti con valori appropriati.

Creazione di un nuovo ambiente

È possibile creare un nuovo ambiente vuoto usando l'API seguente.

  • Esempio di richiesta

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

{
    "displayName": "Environment_1",
    "description": "An environment description"
}

Gestire le librerie di gestione temporanea

È possibile usare l'opzione Carica/Elimina le API delle librerie di gestione temporanea per gestire la sezione delle librerie nell'ambiente

Controllare le librerie pubblicate per l'ambiente

Prima di aggiungere/eliminare la libreria, è possibile usare l'API Ottieni librerie pubblicate per verificare quali librerie sono attualmente valide.

  • Esempio di richiesta

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

  • Risposta di esempio

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

Caricamento delle librerie

L'API per il caricamento della libreria di gestione temporanea accetta un file alla volta. I tipi di file supportati sono .whl, .jar, .tar.gz, .py e environment.yml per la libreria pubblica. È possibile specificare il file tramite il tipo di contenuto multiparte/dati di modulo.

Nota

  • Per manipolare la libreria pubblica in modo più efficiente, è consigliabile comporre tutte le librerie previste da PyPI e conda in un file environment.yml .
  • L'API di caricamento consente file fino a 200 MB in una richiesta; la libreria che supera questo limite di dimensioni non è attualmente supportata nell'API pubblica.

  • Richieste di esempio

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

Eliminazione delle librerie

Specificando il nome completo del file di libreria con il suffisso di tipo, è possibile eliminare una libreria alla volta.

Nota

  • Se si specifica environment.yml come file da eliminare, verranno rimosse tutte le librerie pubbliche.
  • Se si desidera rimuovere un sottoinsieme di librerie pubbliche esistente, usare invece l'opzione Carica libreria e caricare un file environment.yml che contiene solo le librerie previste. Il file environment.yml caricato sostituisce completamente la sezione della libreria pubblica esistente.

  • Richieste di esempio

    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

Gestire l'ambiente di calcolo Spark per la gestione temporanea

È possibile usare il calcolo Spark di gestione temporanea degli aggiornamenti per gestire il calcolo Spark.

Verificare l'ambiente di calcolo Spark pubblicato

Prima di modificare le configurazioni per l'ambiente, è possibile usare l'API di calcolo Spark pubblicata per verificare quali configurazioni di calcolo Spark sono attualmente efficaci.

  • Esempio di richiesta

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

  • Risposta di esempio

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

Aggiornare le configurazioni di calcolo

È possibile aggiornare il runtime di Spark, passare a un altro pool, perfezionare la configurazione di calcolo e aggiungere/rimuovere proprietà Spark modificando il corpo della richiesta di questa API.

È possibile cambiare il pool collegato specificando il nome del pool e il pool. Specificare il nome del pool come Starter Pool per far tornare il pool alle impostazioni predefinite. Per ottenere l'elenco completo dei pool personalizzati disponibili dell'area di lavoro in base all'API REST, vedere Pool personalizzati – Elencare pool personalizzati dell'area di lavoro

Se si vuole rimuovere una proprietà Spark esistente, è necessario specificare il valore come null con la chiave da rimuovere, come illustrato nell'esempio seguente.

  • Esempio di richiesta

    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"
}

Rendere effettive le modifiche

Usare i seguenti insiemi di API per pubblicare le modifiche.

Prepararsi per una pubblicazione

L'ambiente può accettare una pubblicazione alla volta. Prima di pubblicare l'ambiente, è possibile convalidare lo stato dell'ambiente e avere una revisione finale delle modifiche di gestione temporanea. Dopo la pubblicazione riuscita dell'ambiente, tutte le configurazioni nello stato di gestione temporanea diventano effettive.

  • Passaggio 1: Ottenere i metadati dell'ambiente

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

    Nel corpo della risposta, è possibile indicare chiaramente lo stato dell'ambiente. Assicurarsi che non vi sia alcuna pubblicazione in corso prima di svolgere il passaggio successivo.

  • Passaggio 2: Ottenere le librerie di gestione temporanea/calcolo Spark per avere una revisione 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

Attivare la pubblicazione dell'ambiente

Le modifiche apportate per le librerie di gestione temporanea e il calcolo Spark vengono memorizzate nella cache, ma richiedono che la pubblicazione diventi effettiva. Seguire l'esempio riportato sotto per attivare la pubblicazione.

  • Esempio di richiesta

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

  • Risposta di esempio

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

Durante la pubblicazione, è anche possibile chiamare l'API seguente per annullarla.

  • Esempio di richiesta

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

Contenuto correlato