Use a API do Livy para enviar e executar trabalhos de sessão do Spark com credenciais de usuário

Aplica-se a: ✅ Fabric Engenharia de Dados e Ciência de Dados

A API do Fabric Livy permite-lhe submeter trabalhos em lote e sessão do Spark diretamente de um cliente remoto para o Fabric Spark compute, sem usar o portal Fabric. Neste artigo, cria um Lakehouse, autentica-se com um token Microsoft Entra, descobre o endpoint da API do Livy e submete e monitoriza um trabalho de sessão do Spark.

Pré-requisitos

• Fabric Premium ou Capacidade de Teste com um Lakehouse

• Ativar a definição de administrador de inquilinos para a API do Livy

• Um cliente remoto, como Visual Studio Code, com suporte para notebooks Jupyter, PySpark e Biblioteca de Autenticação da Microsoft (MSAL) para Python

• Ou um token de aplicação Microsoft Entra. Registar uma candidatura no plataforma de identidades da Microsoft

• Ou um token Microsoft Entra SPN (Service Principal). Adicione e gere credenciais de aplicação em Microsoft Entra ID

Escolha um cliente API REST

Pode interagir com a API do Livy a partir de qualquer cliente que suporte pedidos HTTP, incluindo ferramentas como o curl ou qualquer linguagem com uma biblioteca HTTP. Os exemplos neste artigo usam Visual Studio Code com Jupyter Notebooks, PySpark, e o Biblioteca de Autenticação da Microsoft (MSAL) para Python.

Como autorizar os pedidos da API do Livy

Para usar a API do Livy, precisa de autenticar os seus pedidos usando o Microsoft Entra ID. Existem dois métodos de autorização disponíveis:

• Entra SPN Token (Principal de Serviço): A aplicação autentica-se por si mesma usando credenciais, como um segredo de aplicação ou certificado. Este método é adequado para processos automatizados e serviços em segundo plano onde não é necessária interação do utilizador.

• Token da aplicação Entra (Delegado): A aplicação atua em nome de um utilizador iniciado. Este método é adequado quando se quer que a aplicação aceda a recursos com as permissões do utilizador autenticado.

Escolha o método de autorização que melhor se adapte ao seu cenário e siga a secção correspondente abaixo.

Como autorizar os pedidos da API Livy com um Microsoft Entra SPN Token

Para trabalhar com APIs do Fabric, incluindo a API do Livy, primeiro precisa de criar uma aplicação Microsoft Entra, criar um segredo e usar esse segredo no seu código. A sua aplicação precisa de estar registada e configurada adequadamente para realizar chamadas de API contra o Fabric. Para mais informações, consulte Adicionar e gerir credenciais de aplicação em Microsoft Entra ID

1. Depois de criar o registro do aplicativo, crie um segredo do cliente.

   

2. Ao criar o segredo do cliente, certifique-se de copiar o valor. Você precisa disso mais tarde no código, e o segredo não pode ser visto novamente. Também precisas do ID da Aplicação (cliente) e do Diretório (ID do inquilino), além do segredo no teu código.

3. De seguida, adicione o principal de serviço ao seu espaço de trabalho.

   

4. Pesquise a aplicação Microsoft Entra usando o ID ou nome da Aplicação (cliente), adicione-a ao espaço de trabalho e certifique-se de que o principal do serviço tem permissões de Contribuidor.

   

Como autorizar as solicitações da API Livy com um token de aplicativo Entra

Para trabalhar com APIs Fabric, incluindo a API Livy, é necessário primeiro criar uma aplicação Microsoft Entra e obter um token. A sua aplicação precisa de estar registada e configurada adequadamente para realizar chamadas de API contra o Fabric. Para mais informações, consulte Registe uma candidatura no plataforma de identidades da Microsoft.

São necessárias as seguintes permissões para o âmbito do Microsoft Entra para executar trabalhos da API do Livy:

Osciloscópios obrigatórios

Código Opcional: Âmbitos

Adicione estes escopos apenas se os seus trabalhos Spark precisarem de aceder aos serviços correspondentes do Azure em tempo de execução.

Quando regista a sua candidatura, precisa tanto do ID da Aplicação (cliente) como do ID do Diretório (inquilino).

O usuário autenticado que chama a API Livy precisa ser um membro do espaço de trabalho onde os itens da API e da fonte de dados estão localizados com uma função de Colaborador. Para obter mais informações, consulte Conceder aos usuários acesso a espaços de trabalho.

Compreender os escopos do Code.* para a API do Livy

Quando os seus trabalhos Spark são executados através da API do Livy, os Code.* scopes controlam quais serviços externos o Spark Runtime pode aceder em nome do utilizador autenticado. São necessárias duas; Os restantes são opcionais dependendo da tua carga de trabalho.

Códigos obrigatórios.*

Code Opcionais.* contextos

Adicione estes escopos apenas se os seus trabalhos Spark precisarem de aceder aos serviços correspondentes do Azure em tempo de execução.

Como descobrir o endpoint da API do Fabric Livy

É necessário um artefato Lakehouse para aceder ao endpoint Livy. Depois que o Lakehouse é criado, o endpoint da API Livy pode ser localizado dentro do painel de configurações.

O ponto de extremidade da API Livy seguiria este padrão:

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

A URL é anexada com <sessões> ou <lotes>, dependendo do que escolheres.

Baixe os arquivos do Livy API Swagger

Os ficheiros Swagger completos para a API Livy estão disponíveis aqui.

• Livy API Swagger JSON
• Livy API Swagger YAML

Sessões de alta concorrência

O suporte para alta concorrência (HC) permite a execução simultânea do Spark ao permitir que os clientes adquiram múltiplos contextos de execução independentes, chamados sessões de alta concorrência.

Cada sessão HC representa um contexto lógico de execução que corresponde a um Spark REPL (Read-Eval-Print Loop). As instruções Spark submetidas em diferentes sessões HC podem ser executadas em simultâneo.

Isto permite:

• Execução paralela entre sessões HC
• Utilização previsível de recursos
• Isolamento entre pedidos concorrentes
• Menor overhead comparado com criar uma nova sessão por pedido

Usar uma única sessão para todos os pedidos faz com que as instruções sejam executadas sequencialmente. Criar uma nova sessão para cada pedido introduz sobrecarga desnecessária e subutilização de recursos.

Para um guia passo a passo com código de exemplo, veja Inicie com a API Livy para Sessões de Elevada Concorrência no Fabric. Para uma visão conceptual, consulte Suporte a alta concorrência na Fabric Livy API.

Enviar trabalhos da API Livy

Agora que a configuração da API do Livy está concluída, você pode optar por enviar trabalhos em lote ou de sessão.

• Enviar trabalhos de sessão usando a API Livy
• Enviar trabalhos em lote usando a API do Livy

Integração com ambientes Fabric

Por padrão, essa sessão da API Livy é executada no pool inicial padrão para o espaço de trabalho. Alternativamente, podes usar Fabric Ambientes Criar, configurar e usar um ambiente em Microsoft Fabric para personalizar o pool Spark que a sessão da API do Livy usa para estes trabalhos do Spark.

Para usar um Ambiente Fabric numa sessão Livy Spark, atualize o json para incluir esta carga útil.

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

Para usar um Ambiente Fabric numa sessão batch do Livy Spark, atualize o payload json como mostrado aqui:

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

Como monitorar o histórico de solicitações

Você pode usar o Hub de Monitoramento para ver seus envios anteriores da API Livy e depurar quaisquer erros de envios.

Conteúdos relacionados

• Documentação da API REST do Apache Livy
• Comece com as definições de administração para a sua capacidade de Fabric
• Definições de administração do espaço de trabalho Apache Spark em Microsoft Fabric
• Registar uma candidatura no plataforma de identidades da Microsoft
• Visão geral de permissão e consentimento do Microsoft Entra
• Fabric REST API Scopes
• Visão geral do monitoramento do Apache Spark
• Detalhes da aplicação Apache Spark