Gestire l'ambiente tramite API pubbliche

2025-04-01

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

La nuova versione include nuove API, deprecazione delle API e modifiche del contratto di risposta/richiesta API. La tabella riportata nella sezione seguente riepiloga tutte le modifiche all'API.

Riepilogo delle API dell'ambiente

Categoria	API (Interfaccia di Programmazione delle Applicazioni)	Descrizione	Nota
Operazione dell'elemento	Creare un ambiente	Creare un nuovo ambiente vuoto nell'area di lavoro.	Nessuna modifica
Operazione dell'elemento	Creare un ambiente con definizione	Creare un nuovo ambiente con Definizione.	nuova API
Operazione dell'elemento	Elimina ambiente	Eliminare un ambiente esistente.	Nessuna modifica
Operazione dell'elemento	Elencare l'ambiente	Ottenere l'elenco di tutti gli ambienti in un'area di lavoro.	Nessuna modifica
Operazione dell'elemento	Acquisire l'ambiente	Ottenere i metadati di un ambiente. La risposta include lo stato dell'ambiente.	aggiornamento del contratto di risposta
Operazione dell'elemento	Ottenere la definizione dell'ambiente	Ottenere la definizione di un ambiente.	nuova API
Operazione dell'elemento	Aggiornamento dell'ambiente	Aggiornare i metadati di un ambiente, come il nome e la descrizione.	Nessuna modifica
Operazione dell'elemento	Aggiornare la definizione dell'ambiente	Aggiornare la definizione di un ambiente.	nuova API
Operazione dell'elemento	Ambiente di pubblicazione	Innescare la pubblicazione dell'ambiente con le modifiche in sospeso attuali.	aggiornamento del contratto di risposta
Operazione dell'elemento	Annullare l'ambiente di pubblicazione	Annullare una pubblicazione attualmente in corso dell'ambiente	Nessuna modifica
Allestimento	Elencare le librerie di staging	Ottenere l'elenco completo delle librerie di gestione temporanea. Questo elenco include le librerie pubblicate e in attesa di pubblicazione.	aggiornamento del contratto di risposta
Allestimento	Importare librerie esterne	Caricare librerie esterne come file environment.yml nell'ambiente. Sostituisce l'elenco delle librerie esterne esistenti nell'ambiente.	nuova API
Allestimento	Esportare librerie esterne	Ottieni le librerie esterne complete in un file environment.yml.	nuova API
Allestimento	Rimuovere la libreria esterna	Eliminare una libreria esterna da un ambiente. Questa API accetta una libreria alla volta	nuova API
Allestimento	Caricare una libreria personalizzata	Caricare un pacchetto personalizzato nell'ambiente. Questa API consente il caricamento di un file alla volta. I formati di file supportati sono .jar, .py, whl e .tar.gz.	nuova API
Allestimento	Eliminare una libreria personalizzata	Eliminare un pacchetto personalizzato dall'ambiente. Inserire il nome completo del pacchetto personalizzato con l'estensione nella richiesta API per rimuoverlo.	nuova API
Allestimento	Caricare le librerie di staging	Aggiungere una libreria personalizzata o una o più librerie pubbliche nell'ambiente.	Da non utilizzare
Allestimento	Eliminare le librerie dell'ambiente di staging	Eliminare una libreria personalizzata di gestione temporanea o tutta la libreria pubblica.	Da non utilizzare
Allestimento	Elenca le impostazioni di staging di Spark	Ottieni le configurazioni di calcolo complete di staging. Le configurazioni di gestione temporanea includono le configurazioni di calcolo pubblicate e in sospeso.	aggiornamento del contratto di risposta
Allestimento	Aggiornare le impostazioni di Spark	Aggiornare le configurazioni di calcolo e le proprietà spark per un ambiente	aggiornamento del contratto di richiesta e risposta
Pubblicato	Elencare le librerie pubblicate	Ricavare le librerie che sono pubblicate ed efficaci nelle sessioni di Spark.	aggiornamento del contratto di risposta
Pubblicato	Elenca l'impostazione Spark pubblicata	Ottieni le configurazioni di calcolo Spark e le proprietà Spark pubblicate e attive nelle sessioni Spark.	aggiornamento del contratto di risposta
Pubblicato	Esportare librerie esterne	Ottieni le librerie esterne pubblicate come file environment.yml.	nuova API

Scopri di più sulle API pubbliche esistenti per l'ambiente nelle API degli elementi - Ambiente

Dettagli dell'aggiornamento dell'API pubblica dell'ambiente

Questa sezione descrive gli aggiornamenti futuri per le API esistenti.

Ottieni l'ambiente

Nella risposta dell'API Get Environment, 'startTime' diventerà 'startDateTime' e 'endTime' diventerà 'endDateTime'. Rappresentano l'ora di inizio/fine dell'operazione di pubblicazione.

Nota

'startTime' e 'endTime' utilizzano il formato data e ora, mentre 'startDateTime' e 'endDateTime' saranno in formato Stringa, che è in UTC e segue il formato YYYY-MM-DDTHH:mm:ssZ.

Interfaccia

GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/environments/{environmentId}

Risposta di esempio originale

{
  "displayName": "Environment_1",
  "description": "An Environment description",
  "type": "Environment",
  "workspaceId": "cfafbeb1-8037-4d0c-896e-a46fb27ff229",
  "id": "5b218778-e7a5-4d73-8187-f10824047715",
  "properties": {
    "publishDetails": {
      "state": "Success",
      "targetVersion": "46838a80-5450-4414-bea0-40fb6f3e0c0d",
      "startTime": "2024-03-29T14:17:09.0697022Z",
      "endTime": "2024-03-29T14:48:09.0697022Z",
      "componentPublishInfo": {
        "sparkLibraries": {
          "state": "Success"
        },
        "sparkSettings": {
          "state": "Success"
        }
      }
    }
  }
}

Nuova risposta di esempio

{
  "displayName": "Environment_1",
  "description": "An Environment description",
  "type": "Environment",
  "workspaceId": "cfafbeb1-8037-4d0c-896e-a46fb27ff229",
  "id": "5b218778-e7a5-4d73-8187-f10824047715",
  "properties": {
    "publishDetails": {
      "state": "Success",
      "targetVersion": "46838a80-5450-4414-bea0-40fb6f3e0c0d",
      "startDateTime": "2024-03-29T14:17:09Z",
      "endDateTime": "2024-03-29T14:48:09Z",
      "componentPublishInfo": {
        "sparkLibraries": {
          "state": "Success"
        },
        "sparkSettings": {
          "state": "Success"
        }
      }
    }
  }
}

Ambiente di pubblicazione

L'API dell'ambiente di pubblicazione supporterà le operazioni a esecuzione prolungata a partire dal rilascio, il contratto della risposta cambierà. L'endpoint rimane invariato per l'invio di richieste.

Interfaccia

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

Risposta di esempio originale

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

Nuova risposta di esempio


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

Elenca le librerie di staging e quelle pubblicate

Queste due API possono ottenere l'elenco completo delle librerie di staging e di quelle pubblicate dell'ambiente. Gli endpoint rimangono invariati per l'invio di richieste, mentre le librerie verranno restituite con una struttura diversa.

Interfacce

Ottenere le librerie di gestione temporanea

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

Ottenere librerie pubblicate

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

Risposta di esempio originale


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

Nuova risposta di esempio

{
  "libraries": [
    {
      "name": "samplewheel-0.18.0-py2.py3-none-any.whl",
      "libraryType": "Custom"
    },
    {
      "name": "samplepython.py",
      "libraryType": "Custom"
    },
    {
      "name": "samplejar.jar",
      "libraryType": "Custom"
    },
    {
      "name": "sampleR.tar.gz",
      "libraryType": "Custom"
    },
    {
      "name": "fuzzywuzzy",
      "libraryType": "External",
      "version": "0.0.1"
    },
    {
      "name": "matplotlib",
      "libraryType": "External",
      "version": "0.0.1"
    }
  ],
  "continuationToken": "null",
  "continuationUri": "null"
}

Elenco delle impostazioni di Spark di staging/pubblicate

Queste due API possono ottenere le configurazioni di calcolo e le proprietà di calcolo Spark dell'ambiente. Gli endpoint rimangono invariati per l'invio di richieste, mentre le configurazioni verranno restituite con una struttura diversa. Le proprietà di Spark verranno modificate in un elenco.

Interfacce

Ottenere le impostazioni Spark di staging

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

Ottenere le impostazioni di Spark pubblicate

GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/environments/{environmentId}/sparkcompute

Risposta di esempio originale

{
  "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": {
    "spark.acls.enable": "false"
  },
  "runtimeVersion": "1.2"
}

Nuova risposta di esempio

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

Aggiornare le impostazioni di Spark

Questa API è destinata all'aggiornamento del calcolo e delle proprietà Spark di un ambiente, il contratto della proprietà Spark nella richiesta e nella risposta verrà aggiornato una volta che la versione verrà rilasciata.

Richiesta di esempio originale

PATCH https://api.fabric.microsoft.com/v1/workspaces/f089354e-8366-4e18-aea3-4cb4a3a50b48/environments/707cfd07-cbf1-41da-aad7-dd157ddb8c11/staging/sparkcompute

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

Nuova richiesta di esempio

PATCH https://api.fabric.microsoft.com/v1/workspaces/f089354e-8366-4e18-aea3-4cb4a3a50b48/environments/707cfd07-cbf1-41da-aad7-dd157ddb8c11/staging/sparkcompute

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

Risposta di esempio originale

{
  "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": {
    "spark.acls.enable": "false"
  },
  "runtimeVersion": "1.2"
}

Nuova risposta di esempio

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

Casi d'uso dell'API pubblica dell'ambiente

Importante

Le nuove API e le modifiche del contratto non sono incluse in questa sezione.

Questa sezione illustra come usare le API attualmente disponibili per raggiungere obiettivi specifici. È 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 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 multiparte/dati di modulo.

Nota

Per gestire la libreria pubblica in modo più efficiente, si consiglia vivamente di comporre tutte le librerie previste da PyPI e conda in un file 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 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 staging per il calcolo Spark

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

Verificare il calcolo Spark pubblicato per l'ambiente

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 sia il nome del pool che il pool stesso. 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 ci sia una pubblicazione in corso prima di passare al passaggio successivo.

Passaggio 2: Ottenere le librerie di messa in scena/calcolo Spark per 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 alle librerie di staging e al calcolo Spark sono memorizzate nella cache, ma necessitano di essere pubblicate per diventare effettive. 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

Condividi tramite

Gestire l'ambiente tramite API pubbliche

Riepilogo delle API dell'ambiente

Dettagli dell'aggiornamento dell'API pubblica dell'ambiente

Ottieni l'ambiente

Ambiente di pubblicazione

Elenca le librerie di staging e quelle pubblicate

Elenco delle impostazioni di Spark di staging/pubblicate

Aggiornare le impostazioni di Spark

Casi d'uso dell'API pubblica dell'ambiente

Creazione di un nuovo ambiente

Gestire le librerie di gestione temporanea

Controllare le librerie pubblicate per l'ambiente

Caricamento delle librerie

Eliminazione delle librerie

Gestire l'ambiente di staging per il calcolo Spark

Verificare il calcolo Spark pubblicato per l'ambiente

Aggiornare le configurazioni di calcolo

Rendere effettive le modifiche

Prepararsi per una pubblicazione

Attivare la pubblicazione dell'ambiente

Contenuto correlato

Commenti e suggerimenti

Risorse aggiuntive