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

Aplicável a:✅ Fabric Data Engineering and Data Science

A API Livy do Fabric permite enviar trabalhos de lote e sessão do Spark de um cliente remoto diretamente para a computação Spark do Fabric, sem usar o portal Fabric. Neste artigo, você cria um Lakehouse, autentica com um token Microsoft Entra, descobre o endpoint da API Livy e envia e monitora um trabalho de sessão do Spark.

Pré-requisitos

• Capacidade Premium ou de Avaliação do Fabric com um Lakehouse

• Habilitar a configuração de administrador de locatário para a API livy

• Um cliente remoto, como Visual Studio Code com suporte ao Jupyter Notebook, PySpark e Biblioteca do Microsoft Authenticator (MSAL) para Python

• Um token de aplicativo Microsoft Entra. Registre um aplicativo na plataforma de identidade da Microsoft

• Ou um token Microsoft Entra SPN (Principal de Serviço). Adicionar e gerenciar credenciais de aplicativo no Microsoft Entra ID

Escolher um cliente da API REST

Você pode interagir com a API livy de qualquer cliente que dê suporte a solicitações HTTP, incluindo ferramentas como curl ou qualquer idioma com uma biblioteca HTTP. Os exemplos neste artigo usam Visual Studio Code com Jupyter Notebooks, PySpark e o Biblioteca do Microsoft Authenticator (MSAL) para Python.

Como autorizar as solicitações da API do Livy

Para usar a API livy, você precisa autenticar suas solicitações usando Microsoft Entra ID. Há dois métodos de autorização disponíveis:

• Entra SPN Token (Entidade de Serviço): o aplicativo autentica a si mesmo usando suas credenciais, como um segredo de cliente ou um certificado. Esse método é adequado para processos automatizados e serviços em segundo plano em que nenhuma interação do usuário é necessária.

• Token do aplicativo Entra (Delegado): o aplicativo atua em nome de um usuário conectado. Esse método é adequado quando você deseja que o aplicativo acesse recursos com as permissões do usuário autenticado.

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

Como autorizar as solicitações da API livy com um token SPN Microsoft Entra

Para trabalhar com APIs de Fabric, incluindo a API livy, primeiro você precisa criar um aplicativo Microsoft Entra e criar um segredo e usar esse segredo em seu código. Seu aplicativo precisa ser registrado e configurado adequadamente para executar chamadas de API em Fabric. Para obter mais informações, consulte Add e gerenciar credenciais de aplicativo no Microsoft Entra ID

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

   

2. Ao criar o segredo do cliente, copie o valor. Você precisa disso mais tarde no código e o segredo não pode ser visto novamente. Você também precisa da ID do aplicativo (cliente) e do diretório (ID do locatário) além do segredo em seu código.

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

   

4. Pesquise pelo aplicativo Microsoft Entra usando a ID ou o nome do aplicativo (cliente), adicione-o ao espaço de trabalho e verifique se a entidade de serviço tem permissões de Colaborador.

   

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

Para trabalhar com APIs de Fabric, incluindo a API livy, primeiro você precisa criar um aplicativo Microsoft Entra e obter um token. Seu aplicativo precisa ser registrado e configurado adequadamente para executar chamadas de API em Fabric. Para obter mais informações, consulte Registrar um aplicativo na plataforma de identidade da Microsoft.

As seguintes permissões de escopo de Microsoft Entra são necessárias para executar trabalhos da API livy:

Escopos necessários

Escopos opcionais do Code.*

Adicione esses escopos somente se os trabalhos do Spark precisarem acessar os serviços de Azure correspondentes em runtime.

Ao registrar sua aplicação, você precisa do ID da Aplicação (cliente) e do ID do Diretório (inquilino).

A pessoa autenticada chamando a API do Livy precisa ser um membro do workspace onde tanto a API quanto os itens da fonte de dados estão localizados com um papel de Contribuidor. Para obter mais informações, consulte Conceder aos usuários acesso a espaços de trabalho.

Noções básicas sobre escopos code.* para a API Livy

Quando seus trabalhos do Spark são executados por meio da API livy, os Code.* escopos controlam quais serviços externos o Spark Runtime pode acessar em nome do usuário autenticado. Dois são necessários; o restante é opcional dependendo da carga de trabalho.

Escopos de Code.* necessários

Escopos opcionais do Code.*

Adicione esses escopos somente se os trabalhos do Spark precisarem acessar os serviços de Azure correspondentes em runtime.

Como encontrar o endpoint da API do Fabric Livy

Um artefato Lakehouse é necessário para acessar o endpoint Livy. Assim que o Lakehouse é criado, o endpoint da API Livy pode ser localizado no painel de configurações.

O ponto de extremidade da API do Livy seguiria esse 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 você escolher.

Baixar os arquivos Swagger da API Livy

Os arquivos completos do Swagger para a API livy estão disponíveis aqui.

• Swagger da API do Livy – JSON
• Swagger da API do Livy – YAML

Sessões de alta simultaneidade

O suporte a HC (alta simultaneidade) permite a execução simultânea do Spark, permitindo que os clientes adquiram vários contextos de execução independentes, chamados de sessões de alta simultaneidade.

Cada sessão de HC representa um contexto de execução lógica mapeado para um REPL do Spark (Loop de Leitura-Avaliação-Impressão). Instruções spark enviadas em diferentes sessões de HC podem ser executadas simultaneamente.

Permite:

• Execução paralela entre sessões de HC
• Uso previsível de recursos
• Isolamento entre solicitações simultâneas
• Menor sobrecarga em comparação com a criação de uma nova sessão por solicitação

Usar uma única sessão para todas as solicitações faz com que as instruções são executadas sequencialmente. A criação de uma nova sessão para cada solicitação introduz sobrecarga desnecessária e subutilização de recursos.

Para obter um passo a passo com o código de exemplo, consulte Comece com a API Livy para sessões de Alta Concurrency do Fabric. Para obter uma visão geral conceitual, consulte Suporte a alta simultaneidade na Fabric Livy API.

Enviar trabalhos para a API do Livy

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

• Enviar trabalhos de Sessão usando a API do Livy
• Enviar trabalhos em Lote usando a API do Livy

Integração com ambientes de Fabric

Por padrão, essa sessão da API livy é executada no pool inicial padrão do workspace. Como alternativa, você pode usar ambientes Fabric Criar, configurar e usar um ambiente no Microsoft Fabric para personalizar o pool do Spark que a sessão da API livy usa para esses trabalhos do Spark.

Para usar um ambiente Fabric em uma sessão do Livy Spark, atualize o JSON para incluir este payload.

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

Para usar um ambiente Fabric em uma sessão em lotes 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 do Livy e depurar quaisquer erros de envios.

Conteúdo relacionado

• Documentação API REST Apache Livy
• Comece com as configurações do administrador para sua Capacidade do Fabric
• configurações de administração do workspace Apache Spark no Microsoft Fabric
• Registre um aplicativo na plataforma de identidade da Microsoft
• Microsoft Entra visão geral de permissão e consentimento
• Escopos da API REST Fabric
• Visão geral do monitoramento do Apache Spark
• Detalhes do aplicativo Apache Spark