Condividi tramite

Gestire l'ambiente tramite LE API pubbliche

  • Articolo

L'API REST di Microsoft Fabric fornisce un endpoint di servizio per le operazioni CRUD (Create, Read, Update, Delete) di un elemento fabric. Questo articolo descrive le API REST dell'ambiente disponibili e il relativo utilizzo.

Importante

Questa funzionalità è disponibile 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
Aggiornare l'ambiente Aggiornare i metadati di un ambiente, ad esempio nome e descrizione. Generali
Elimina ambiente Eliminare un ambiente esistente. Generali
Elencare l'ambiente nell'area di lavoro Ottenere l'elenco di ambienti in un'area di lavoro. Generali
Ambiente di pubblicazione Attivare la pubblicazione dell'ambiente con le modifiche correnti 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 Spark
Ottenere l'ambiente di calcolo Spark di staging Ottenere le configurazioni di calcolo di staging complete. Le configurazioni di staging includono le configurazioni di calcolo pubblicate e in sospeso. Calcolo Spark
Ottenere librerie pubblicate Ottenere l'elenco di librerie efficace. Librerie
Ottenere le librerie di staging Ottenere l'elenco completo delle librerie di staging. Questo elenco include le librerie pubblicate e in sospeso. Librerie
Caricare le librerie di staging Aggiunta di una libreria personalizzata o di una o più librerie pubbliche nell'ambiente. Librerie
Eliminare le librerie di staging Eliminare una libreria personalizzata di staging 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 i 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 staging

È possibile usare le API di caricamento/eliminazione delle librerie di staging per gestire la sezione della libreria nell'ambiente

Controllare le librerie pubblicate per l'ambiente

Prima di aggiungere/eliminare la libreria, è possibile usare l'API get published libraries 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 staging 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 multipart/form-data.

Nota

  • Per modificare la libreria pubblica in modo più efficiente, è consigliabile comporre tutte le librerie previste da PyPI e conda in un file di environment.yml .
  • L'API di caricamento consente fino a 200 MB di file 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 subset di libreria pubblica esistente, usare invece la libreria di caricamento e caricare un environment.yml che contiene solo le librerie previste. Il 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 di staging

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

Controllare 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 valide.

  • 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 e il pool del pool. Specificare il nome del pool come Starter Pool per impostare le impostazioni predefinite del pool. 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

Uso dei set di API seguenti per pubblicare le modifiche.

Preparare 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 staging. Dopo la pubblicazione 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 sia disponibile alcuna pubblicazione in corso prima di passare al passaggio successivo.

  • Passaggio 2: ottenere le librerie di staging/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 in per le librerie di staging e il calcolo Spark vengono memorizzate nella cache, ma richiedono che la pubblicazione diventi effettiva. Seguire l'esempio seguente 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