Partilhar via

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

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

Comece a utilizar a API Livy para Engenharia de Dados em Fabric, criando um Lakehouse; autenticando com um token Microsoft Entra; descobrir o endpoint da API Livy; submeter trabalhos em lote ou sessões a partir de um cliente remoto para a computação Fabric Spark; e monitorizar os resultados.

Pré-requisitos

Escolhendo um cliente de API REST

Você pode usar várias linguagens de programação ou clientes GUI para interagir com pontos de extremidade da API REST. Neste artigo, usamos Visual Studio Code. O Visual Studio Code precisa ser configurado com Jupyter Notebooks, PySpark e a Microsoft Authentication Library (MSAL) para Python

Como autorizar as solicitações da API Livy com um Entra SPN Token

Para trabalhar com as Fabric APIs, incluindo a Livy API, é necessário primeiro criar uma aplicação Microsoft Entra, gerar uma credencial secreta e utilizá-la no seu código. Seu aplicativo precisa ser registrado e configurado adequadamente para executar chamadas de API no Fabric. Para obter mais informações, consulte Adicionar e gerenciar credenciais de aplicativo no Microsoft Entra ID

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

Captura de ecrã a mostrar o registo da aplicação Entra e a adicionar um segredo do cliente.

  1. 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. Você também precisará do ID do aplicativo (cliente) e do diretório (ID do locatário), além do segredo em seu código.

  2. Em seguida, precisamos adicionar o segredo do cliente ao nosso espaço de trabalho.

    Captura de tela mostrando as configurações do Lakehouse para gerenciar opções de acesso.

  3. Procure o segredo do cliente Entra, adicione esse segredo ao espaço de trabalho e verifique se o segredo recém-adicionado tem permissões de administrador.

    Captura de tela mostrando a adição da nova entidade de serviço SPN ao espaço de trabalho.

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

Para trabalhar com APIs de malha, 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 no Fabric. Para obter mais informações, consulte Registrar um aplicativo com a plataforma de identidade da Microsoft.

Há muitas permissões de escopo do Microsoft Entra necessárias para executar trabalhos do Livy. Este exemplo usa código Spark simples + acesso ao armazenamento + SQL:

  • Código.AccessAzureDataExplorer.All

  • Code.AccessAzureDataLake.All

  • Code.AccessAzureKeyvault.All

  • Código.AccessFabric.All

  • Code.AccessStorage.All

  • Item.ReadWrite.All

  • Lakehouse.Execute.Todos

  • Workspace.ReadWrite.All

    Captura de tela mostrando as permissões da API Livy no centro de administração do Microsoft Entra.

Nota

Durante a visualização pública, esses escopos podem mudar à medida que adicionamos alguns escopos mais granulares. Quando essas alterações de escopo acontecem, seu aplicativo Livy pode quebrar. Verifique esta lista, pois ela será atualizada com os escopos adicionais.

Alguns clientes querem permissões mais granulares do que a lista anterior. Você pode remover Item.ReadWrite.All e substituir por estas permissões de escopo mais granulares:

  • Código.AccessAzureDataExplorer.All
  • Code.AccessAzureDataLake.All
  • Code.AccessAzureKeyvault.All
  • Código.AccessFabric.All
  • Code.AccessStorage.All
  • Lakehouse.Execute.Todos
  • Lakehouse.ReadWrite.Tudo
  • Workspace.ReadWrite.All
  • Notebook.ReadWrite.All
  • SparkJobDefinition.ReadWrite.All
  • MLModel.ReadWrite.All
  • MLExperiment.ReadWrite.All
  • Dataset.ReadWrite.All

Quando registar a sua aplicação, irá precisar tanto do ID da Aplicação (cliente) como do ID do Diretório (inquilino).

Captura de ecrã mostrando a visão geral da aplicação Livy API no centro de administração do Microsoft Entra.

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.

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.

Captura de tela mostrando os pontos de extremidade da API Livy nas configurações do Lakehouse.

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.

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.

Integração com ambientes de malha

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

Para usar um ambiente de malha em uma sessão do Livy Spark, basta atualizar o json para incluir essa carga.

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

Para usar um Fabric Environment numa sessão em lote do Livy Spark, basta atualizar o payload JSON conforme ilustrado abaixo.

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

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.

Captura de tela mostrando envios anteriores da API Livy no hub de monitoramento.

Conteúdos relacionados

  • Last updated on