Condividi tramite

Usare l'API Livy per inviare ed eseguire processi di sessione Spark con credenziali utente

Si applica a:✅ Ingegneria dei dati e data science di Fabric

Iniziare a usare l'API Livy per Fabric Data Engineering creando un Lakehouse; autenticazione con un token di Microsoft Entra, individuare l'endpoint dell'API Livy, inviare processi batch o di sessione da un client remoto al calcolo di Fabric Spark e monitorare i risultati.

Prerequisiti

Scelta di un client API REST

È possibile usare vari linguaggi di programmazione o client GUI per interagire con gli endpoint dell'API REST. In questo articolo viene usato Visual Studio Code. Visual Studio Code deve essere configurato con Jupyter Notebooks, PySpark e Microsoft Authentication Library (MSAL) per Python

Come autorizzare le richieste dell'API Livy

Per usare l'API Livy, è necessario autenticare le richieste usando Microsoft Entra ID. Sono disponibili due metodi di autorizzazione:

  • Entra SPN Token (principal del servizio): l'applicazione esegue l'autenticazione come sé stessa usando credenziali come un segreto del client o un certificato. Questo metodo è adatto per processi automatizzati e servizi in background in cui non è necessaria alcuna interazione dell'utente.

  • Entra app token (Delegato): l'applicazione agisce per conto di un utente registrato. Questo metodo è adatto quando si vuole che l'applicazione acceda alle risorse con le autorizzazioni dell'utente autenticato.

Scegliere il metodo di autorizzazione più adatto allo scenario e seguire la sezione corrispondente di seguito.

Come autorizzare le richieste dell'API Livy con un token SPN Entra

Per usare le API di Infrastruttura, inclusa l'API Livy, è prima necessario creare un'applicazione Microsoft Entra e creare un segreto e usarlo nel codice. L'applicazione deve essere opportunamente registrata e configurata per eseguire chiamate API su Fabric. Per altre informazioni, vedere Aggiungere e gestire le credenziali dell'applicazione in Microsoft Entra ID

Dopo aver creato la registrazione dell'app, crea un "client secret".

Screenshot che mostra la registrazione dell'app Entra e l'aggiunta di un segreto client.

  1. Quando si crea il segreto del client, assicurarsi di copiare il valore. Questa operazione è necessaria più avanti nel codice e il segreto non può essere più visualizzato. Sono necessari anche l'ID applicazione (client) e l'ID directory (tenant) oltre al segreto nel codice.

  2. Successivamente, aggiungere l'entità servizio alla tua area di lavoro.

    Screenshot che mostra le opzioni di gestione dell'accesso nelle impostazioni del Lakehouse.

  3. Cercare l'applicazione Entra usando l'ID applicazione (client) o il nome, aggiungerlo all'area di lavoro e assicurarsi che il principale del servizio disponga delle autorizzazioni di Collaboratore.

    Screenshot che mostra l'aggiunta della nuova entità di servizio SPN all'area di lavoro.

Come autorizzare le richieste api Livy con un token dell'app Entra

Per usare le API di Infrastruttura, inclusa l'API Livy, è prima necessario creare un'applicazione Microsoft Entra e ottenere un token. L'applicazione deve essere opportunamente registrata e configurata per eseguire chiamate API su Fabric. Per altre informazioni, vedere Registrare un'applicazione con Microsoft Identity Platform.

Per eseguire i processi Livy sono necessarie molte autorizzazioni di ambito Microsoft Entra. Questo esempio usa codice Spark semplice e accesso all'archiviazione + SQL:

  • Code.AccessAzureDataExplorer.All

  • Code.AccessAzureDataLake.All

  • Code.AccessAzureKeyvault.All

  • Code.AccessFabric.All

  • Code.AccessStorage.All

  • Elemento.LeggiScrivi.Tutto

  • Lakehouse.Execute.All

  • SpazioDiLavoro.LetturaScrittura.Tutti

    Screenshot che mostra le autorizzazioni dell'API Livy nell'interfaccia di amministrazione Microsoft Entra.

Nota

Durante l'anteprima pubblica questi ambiti possono cambiare man mano che si aggiungono altri ambiti granulari. Quando si verificano modifiche all'ambito, la tua app Livy potrebbe smettere di funzionare. Controllare questo elenco perché verrà aggiornato con gli ambiti aggiuntivi.

Alcuni clienti vogliono autorizzazioni più granulari rispetto all'elenco precedente. È possibile rimuovere Item.ReadWrite.All e sostituire con queste autorizzazioni di ambito più granulari:

  • Code.AccessAzureDataExplorer.All
  • Code.AccessAzureDataLake.All
  • Code.AccessAzureKeyvault.All
  • Code.AccessFabric.All
  • Code.AccessStorage.All
  • Lakehouse.Execute.All
  • Lakehouse.ReadWrite.All
  • SpazioDiLavoro.LetturaScrittura.Tutti
  • Notebook.ReadWrite.All
  • SparkJobDefinition.ReadWrite.All
  • MLModel.ReadWrite.All
  • MLExperiment.ReadWrite.All
  • Dataset.ReadWrite.All

Quando si registra l'applicazione, saranno necessari sia l'ID applicazione (client) che l'ID directory (tenant).

Screenshot che mostra la panoramica dell'app per le API Livy nell'interfaccia di amministrazione Microsoft Entra.

L'utente autenticato che chiama l'API Livy deve essere un membro dell'area di lavoro in cui si trovano sia l'API che gli elementi dell'origine dati con un ruolo Collaboratore. Per altre informazioni, vedere Concedere agli utenti l'accesso alle aree di lavoro.

Come individuare l'endpoint dell'API Livy fabric

Per accedere all'endpoint Livy è necessario un artefatto Lakehouse. Dopo aver creato Lakehouse, l'endpoint dell'API Livy può trovarsi all'interno del pannello delle impostazioni.

Screenshot che mostra gli endpoint dell'API Livy nelle impostazioni di Lakehouse.

L'endpoint dell'API Livy seguirà questo modello:

https://api.fabric.microsoft.com/v1/workspaces/><ws_id>/lakehouses/<lakehouse_id>/livyapi/versions/2023-12-01/

L'URL viene aggiunta con <sessioni> o <batch> a seconda di ciò che si sceglie.

Scaricare i file Swagger dell'API Livy

I file Swagger completi per l'API Livy sono disponibili qui.

Inviare processi api Livy

Ora che la configurazione dell'API Livy è stata completata, è possibile scegliere di inviare processi batch o di sessione.

Integrazione con gli ambienti di Fabric

Per impostazione predefinita, questa sessione dell'API Livy viene eseguita nel pool di avvio predefinito per l'area di lavoro. In alternativa, è possibile usare gli ambienti di infrastruttura Creare, configurare e usare un ambiente in Microsoft Fabric per personalizzare il pool di Spark usato dalla sessione API Livy per questi processi Spark.

Per utilizzare un ambiente Fabric in una sessione Livy Spark, basta aggiornare il JSON per includere questo payload.

create_livy_session = requests.post(livy_base_url, headers = headers, json={
    "conf" : {
        "spark.fabric.environmentDetails" : "{\"id\" : \""EnvironmentID""}"}
    }
)

Per usare un ambiente Fabric in una sessione batch di Livy Spark, è sufficiente aggiornare il payload JSON come illustrato di seguito.

payload_data = {
"name":"livybatchdemo_with"+ newlakehouseName,
"file":"abfss://YourABFSPathToYourPayload.py", 
"conf": {
    "spark.targetLakehouse": "Fabric_LakehouseID",
    "spark.fabric.environmentDetails" : "{\"id\" : \""EnvironmentID"\"}"  # Replace "EnvironmentID" with your environment ID, or remove this line to use starter pools instead of an environment
    }
}

Come monitorare la cronologia delle richieste

È possibile usare l'hub di monitoraggio per visualizzare gli invii precedenti dell'API Livy ed eseguire il debug di eventuali errori di invio.

Screenshot che mostra gli invii precedenti dell'API Livy nell'hub di monitoraggio.

Contenuto correlato

  • Last updated on