Condividi tramite

Gestire l'ambiente tramite API pubbliche

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.

Migrare le API dell'ambiente alla loro versione GA stabile

Importante

  • La versione GA include aggiornamenti nel contratto di richiesta/risposta delle API esistenti, deprecazioni delle API e nuove API. I dettagli sono disponibili nelle sezioni seguenti.
  • Viene introdotto un nuovo parametro beta di query per facilitare la transizione delle modifiche del contratto di richiesta/risposta. Il beta parametro di query viene impostato per impostazione predefinita fino al True31 marzo 2026, rendendo ancora disponibili i contratti di anteprima. Impostare il valore su False per iniziare a usare la versione release stabile dei contratti.
  • Preview Il parametro di query è stato sostituito da beta. Per la compatibilità con le versioni precedenti, l'anteprima è ancora supportata e si comporta come beta.
  • Le API da deprecare continueranno a essere supportate fino al 31 marzo 2026. Per favore, usare le API appena introdotte per sostituirle il prima possibile.

API con aggiornamento del contratto di richiesta/risposta

Categoria API (Interfaccia di Programmazione delle Applicazioni) Descrizione Note Versione di anteprima Swagger Versione di rilascio di Swagger
Operazione dell'elemento Ambiente di pubblicazione Attivare l'operazione di pubblicazione dell'ambiente con le modifiche attualmente in sospeso. Aggiornamento nel contratto di risposta. Ambiente di pubblicazione (anteprima) Ambiente di pubblicazione
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 nel contratto di risposta. Elencare le librerie di staging (anteprima) Elenchi le librerie di staging
Allestimento Elencare le risorse di calcolo Spark di staging Ottieni le configurazioni di calcolo complete di staging. Le configurazioni di gestione temporanea includono le configurazioni di calcolo pubblicate e in sospeso. Aggiornamento nel contratto di risposta. Elencare il calcolo Spark di staging (anteprima) Elencare l'ambiente di calcolo di staging Spark
Allestimento Aggiornare il calcolo Spark Aggiornare le configurazioni di calcolo e le proprietà Spark per un ambiente. Aggiornamento dei contratti di richiesta e risposta. Aggiornare il calcolo Spark (anteprima) Aggiornare il calcolo Spark
Pubblicato Elencare le librerie pubblicate Ricavare le librerie che sono pubblicate ed efficaci nelle sessioni di Spark. Aggiornamento nel contratto di risposta. Elencare le raccolte pubblicate (anteprima) Elencare le librerie pubblicate
Pubblicato Elencare le risorse di calcolo Spark pubblicate Ottieni le configurazioni di calcolo Spark e le proprietà Spark pubblicate e attive nelle sessioni Spark. Aggiornamento nel contratto di risposta. Elencare le raccolte pubblicate (anteprima) Elencare le librerie pubblicate

Il parametro di beta è impostato per impostazione predefinita a True fino al 31 marzo 2026, ovvero il sistema considera il parametro come True se la richiesta viene inviata senza specificare questo parametro fino alla data di eliminazione. È consigliabile eseguire la migrazione delle implementazioni alla versione stabile impostando in modo esplicito il beta parametro su False appena possibile.

Uso dell'API List staging libraries come esempio, che include un aggiornamento nella risposta dell'API.

  • Quando si invia la richiesta con il parametro beta impostato a True

    Richiesta di esempio: 

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

    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": "name: sample-environment\ndependencies:\n  - fuzzywuzzy==0.0.1\n  - matplotlib==0.0.1"
}

  • Quando si invia la richiesta con il parametro preview impostato a False

    Richiesta di esempio: 

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

    Risposta di esempio:

    {
  "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 da deprecare

Importante

  • Le API da deprecare continueranno a essere supportate fino al 31 marzo 2026. È consigliabile usare le API appena introdotte per sostituire le implementazioni il prima possibile.
Categoria API (Interfaccia di Programmazione delle Applicazioni) Descrizione Nota
Allestimento Caricare le librerie di staging Aggiungere una libreria personalizzata o una o più librerie pubbliche nell'ambiente. Il supporto è garantito fino al 31 marzo 2026, utilizzare le API appena introdotte Import external libraries/Upload custom library per la sostituzione.
Allestimento Eliminare le librerie di staging Eliminare una libreria di staging personalizzata o tutte le librerie pubbliche. Il supporto è garantito fino al 31 marzo 2026, utilizzare le API appena introdotte Remove external library/Delete custom library per la sostituzione.

Di seguito sono riportati alcuni esempi che illustrano gli scenari durante la gestione delle librerie di staging.

  • Aggiungere le librerie pubbliche nell'ambiente

    In precedenza, è possibile usare l'API Upload staging libraries per caricare il file YAML aggiornato e ora è possibile usare l'API Import external libraries per importare il file YAML aggiornato.

  • Eliminare una libreria pubblica nell'ambiente

    In precedenza, è possibile usare l'API Upload staging libraries per caricare il file YAML aggiornato e ora è possibile usare l'API Remove external library per rimuoverlo.

  • Elimina tutte le librerie pubbliche nel tuo ambiente

    In precedenza, è possibile usare l'API Delete staging libraries per eliminare tutte le librerie pubbliche e ora è possibile usare Remove external library l'API per rimuovere le librerie pubbliche una alla volta o usare Import external libraries per caricare un file YAML vuoto per ottenere le stesse funzionalità.

Nuove API

Categoria API (Interfaccia di Programmazione delle Applicazioni) Descrizione Nota
Operazione dell'elemento Creare un ambiente con definizione Creare un nuovo ambiente con definizione. Nuova API.
Operazione dell'elemento Ottenere la definizione dell'ambiente Ottenere la definizione di un ambiente. Nuova API.
Operazione dell'elemento Aggiornare la definizione dell'ambiente Aggiornare la definizione di un ambiente. Nuova API.
Allestimento Importare librerie esterne Caricare librerie esterne come file environment.yml nell'ambiente. Esegue l'override dell'elenco di librerie esterne esistenti in un ambiente. Nuova API.
Allestimento Esportare librerie esterne Ottenere le librerie esterne complete come file di 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.
Pubblicato Esportare librerie esterne Recuperare le librerie esterne pubblicate come file environment.yml. Nuova API.

API senza aggiornamento

Categoria API (Interfaccia di Programmazione delle Applicazioni) Descrizione
Operazione dell'elemento Creare un ambiente Creare un nuovo ambiente vuoto nell'area di lavoro.
Operazione dell'elemento Recupera ambiente Ottenere i metadati di un ambiente. La risposta include lo stato dell'ambiente.
Operazione dell'elemento Eliminare l'ambiente Eliminare un ambiente esistente.
Operazione dell'elemento Elencare l'ambiente Ottenere l'elenco di ambienti in un'area di lavoro.
Operazione dell'elemento Aggiornare l'ambiente Aggiornare i metadati di un ambiente, come il nome e la descrizione.
Operazione dell'elemento Annullare l'ambiente di pubblicazione Annullare un'operazione di pubblicazione in corso dell'ambiente.

Per altre informazioni sulle API pubbliche dell'ambiente, vedere API degli elementi - Ambiente.

Casi d'uso dell'API pubblica dell'ambiente

Importante

Questa sezione viene illustrata con la versione stabile delle API.

Questa sezione illustra come usare le API per ottenere scenari specifici durante la gestione dell'ambiente. È possibile sostituire le {WORKSPACE_ID} proprietà e {ARTIFACT_ID} negli esempi seguenti con i valori appropriati.

Creazione di un nuovo ambiente

Per creare un nuovo ambiente vuoto, usare 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 le API di caricamento ed eliminazione delle librerie di staging per gestire la sezione della libreria nell'ambiente.

Controllare le librerie pubblicate per l'ambiente

Prima di aggiungere o eliminare una libreria, usare l'API Recupera 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?beta=False

  • Risposta di esempio

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

Importare librerie pubbliche o caricare una libreria personalizzata

È possibile usare Importa librerie esterne e Caricare API di libreria personalizzate per aggiungere nuove librerie pubbliche/personalizzate all'ambiente. L'API importa librerie esterne accetta environment.yml file mentre i tipi di file supportati sono .whl, .jar, .tar.gz, .py per caricare l'API della libreria personalizzata.

Nota

Per modificare 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 fino a un file da 200 MB in una richiesta. Una libreria che supera questo limite di dimensioni non è attualmente supportata nelle API pubbliche.

  • Richieste di esempio

    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

Eliminare la libreria personalizzata

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

Nota

Se si vuole rimuovere un subset delle librerie pubbliche esistenti o tutte, importare un file YAML aggiornato tramite Import public libraries l'API.

  • Richieste di esempio

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

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, 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?beta=False

  • 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 configurazioni di calcolo

È possibile aggiornare il runtime di Spark, passare a un altro pool, perfezionare la configurazione di calcolo e aggiungere o 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 tramite l'API REST, vedere Pool personalizzati - Elenca pool personalizzati dell'area di lavoro.

Se si vuole rimuovere una proprietà Spark esistente, specificare il valore come null con la chiave da rimuovere.

  • Esempio di richiesta

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

Rendere effettive le modifiche

Usare i set di API seguenti per pubblicare le modifiche.

Preparare un'operazione di pubblicazione

L'ambiente può accettare un'operazione di pubblicazione alla volta. Prima di pubblicare l'ambiente, verificare lo stato dell'ambiente e fare una revisione finale delle modifiche in fase 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 in corso alcuna operazione di pubblicazione prima di passare al passaggio successivo.

  • Passaggio 2: Preparare le librerie di staging/il calcolo Spark per una revisione 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

Attivare l'operazione di pubblicazione dell'ambiente

Le modifiche apportate per le librerie di staging e le risorse di calcolo Spark vengono memorizzate nella cache, ma richiedono che la pubblicazione diventi effettiva. Usare l'esempio successivo per attivare l'operazione di pubblicazione. La risposta segue il modello LRO (Long Running Operations) e potrebbe essere restituito il codice di risposta HTTP 202.

  • Esempio di richiesta

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

  • 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: 120

Durante l'operazione di 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

  • Last updated on