Desenvolver aplicativos da Databricks

info

Visualização

O Databricks Apps está em visualização pública.

nota

Para implantar e executar aplicativos em seu Databricks workspace, o senhor deve garantir que o firewall não bloqueie o domínio *.databricksapps.com.

Este artigo contém detalhes sobre a criação de dados e aplicativos AI com o Databricks Apps, incluindo como criar e editar aplicativos na interface do usuário, como usar os recursos da plataforma Databricks, como SQL warehouse, secrets e Databricks Jobs, práticas recomendadas para o desenvolvimento de aplicativos e informações importantes para o desenvolvimento de aplicativos usando estruturas compatíveis.

Como faço para criar um aplicativo na interface do usuário de aplicativos da Databricks?

1. Na barra lateral, clique em Novo e selecione Aplicativo no menu.

2. O senhor pode começar com um aplicativo de exemplo completo e pré-construído ou usar seu código-fonte e artefatos.

   • Para começar com um aplicativo de exemplo, selecione o padrão , clique em tab para sua estrutura preferida e selecione na lista de aplicativos.
   • Para criar um aplicativo usando seu código, selecione Personalizado .

   

3. Clique em Avançar .

4. No campo Nome do aplicativo , insira um nome para o aplicativo e, opcionalmente, insira uma descrição.

nota

• O nome atribuído a um aplicativo Databricks não pode ser alterado após a criação do aplicativo, e qualquer usuário com acesso a um Databricks workspace pode ver os nomes e o histórico de implantação de todos os aplicativos Databricks no workspace. Além disso, o nome do aplicativo é incluído nos registros gravados nas tabelas do sistema. Devido a essa visibilidade, o senhor não deve incluir informações confidenciais ao nomear seus aplicativos Databricks.

• O nome deve ser exclusivo no site Databricks workspace que hospeda o aplicativo e deve conter apenas letras minúsculas, números e hífens.

Se você selecionou Personalizado , clique em Criar aplicativo . Se o senhor selecionou o padrão , configure o recurso necessário e clique em Create and implantado app . Consulte Atribuir recurso da plataforma Databricks a um aplicativo Databricks.

A página de detalhes do aplicativo é exibida depois que o senhor clica em Criar e implantar aplicativo ou Criar aplicativo . Se o senhor selecionou o padrão , o Databricks Apps cria seu aplicativo e, em seguida, implanta o aplicativo, incluindo o código de exemplo do padrão e a configuração necessária para o aplicativo. A página de detalhes do aplicativo mostra:

• O status da criação e implantação do aplicativo.
• As etapas que o senhor pode usar para continuar o desenvolvimento do aplicativo localmente, incluindo a cópia dos artefatos do aplicativo para o seu ambiente local e a sincronização das alterações locais com o site Databricks workspace.

Se o senhor selecionou Personalizado , a Databricks Apps cria o aplicativo. Como é necessário adicionar o código e os artefatos do aplicativo, o aplicativo deve ser implantado como uma etapa separada. A página de detalhes do aplicativo mostra:

• O status da criação do aplicativo.
• As etapas para sincronizar o código e os artefatos do aplicativo do seu ambiente de desenvolvimento local com o Databricks workspace e implantar o aplicativo.

Para saber como configurar um ambiente de desenvolvimento local, criar ou atualizar o código e a configuração de seu aplicativo localmente e sincronizar e implantar o aplicativo em seu Databricks workspace, consulte Get começar with Databricks Apps. 5. Se o senhor selecionou o padrão e deseja copiar os artefatos do aplicativo do site workspace para o ambiente de desenvolvimento local, poderá usar o site Databricks CLI:

Bash

databricks workspace export-dir <workspace-path> <target-path>

Substituir:

• <workspace-path> com o caminho para o diretório de arquivos workspace que contém o código e os artefatos do seu aplicativo.
• <target-path> com um caminho em seu ambiente local para copiar os arquivos.

Atribua o recurso da plataforma Databricks a um aplicativo Databricks

nota

Para usar o Databricks SQL, a entidade de serviço precisa ter acesso a um SQL warehouse e a todas as tabelas acessadas por consultas.

Para usar os recursos da plataforma Databricks, como Databricks SQL, Databricks Jobs, Mosaic AI Model Serving e Databricks secrets, adicione esses recursos ao seu aplicativo como recurso. O senhor pode adicionar recurso ao criar ou editar um aplicativo.

1. No cartão Criar novo aplicativo ou Editar aplicativo , clique em Configurações avançadas > + Adicionar recurso e selecione o tipo de recurso.

   

2. Dependendo do tipo de recurso, preencha os campos necessários para configurar o recurso, inclusive o campo recurso key . Esse key é usado posteriormente para fazer referência ao recurso.

3. Clique em Salvar .

4. Adicione uma entrada para o recurso no arquivo de configuração app.yaml usando o recurso SQL warehouse key. Como isso faz referência à origem do valor do parâmetro e não ao valor real, use valueFrom em vez de value.

   YAML

   env:
     - name: 'DATABRICKS_WAREHOUSE_ID'
       valueFrom: 'sql-warehouse'

5. Para fazer referência ao recurso no código do aplicativo, use o valor do campo name (DATABRICKS_WAREHOUSE_ID neste exemplo) para fazer referência ao valor configurado em key.

   Python

   import os
   
   os.getenv('DATABRICKS_WAREHOUSE_ID')

Para ver mais exemplos de uso de recurso com aplicativos, incluindo SQL warehouse e servindo modelo de endpoint, consulte os exemplos de padrão quando o senhor cria um aplicativo e Melhores práticas: Use segredos para armazenar informações confidenciais em um aplicativo Databricks.

Veja os detalhes de um aplicativo Databricks

Para view a página de detalhes de um aplicativo Databricks:

1. Clique em Calcular na barra lateral.
2. Vá para Apps tab.
3. Na coluna Nome , clique no nome do aplicativo.
4. A Visão geral tab é exibida com detalhes sobre o aplicativo, incluindo o status, o local de implantação e qualquer recurso associado.
   • Para acessar o histórico de implementação do aplicativo, vá para Deployments tab.
   • Para acessar view o logs do aplicativo, vá para os registros tab.
   • Para view o ambiente de tempo de execução do aplicativo, incluindo a variável de ambiente e o pacote instalado, acesse Environment tab.

Configurar permissões para seu aplicativo Databricks

Para gerenciar as permissões do aplicativo, o senhor deve ter a permissão CAN MANAGE ou IS OWNER. Para acessar o aplicativo, o usuário deve ter permissões CAN_USE ou CAN_MANAGE no aplicativo. A menos que um usuário precise da permissão CAN_MANAGE em um aplicativo, a Databricks recomenda atribuir apenas a permissão CAN_USE.

1. Na página de detalhes do aplicativo, clique em Permissões .
2. Em Permissions Settings (Configurações de permissões ), selecione o menu suspenso Select User, Group or entidade de serviço e, em seguida, selecione um usuário, grupo, entidade de serviço ou todos os usuários do site workspace.
3. Selecione uma permissão no dropdown de permissões.
4. Clique em Adicionar e, em seguida, clique em Salvar .

Usando o modelo de autorização do Databricks Apps

O modelo de autorização do Databricks Apps usa o protocolo OAuth 2.0 e inclui as permissões atribuídas a um aplicativo e aquelas atribuídas ao usuário que acessa o aplicativo. As permissões de um aplicativo são determinadas por uma Databricks entidade de serviço atribuída ao aplicativo, e as permissões do usuário são determinadas por tokens de usuário atribuídos a um usuário de login workspace. Esse modelo permite que o senhor controle e separe o recurso que seu aplicativo pode acessar e o recurso que o usuário do aplicativo pode acessar.

A seguir, uma visão geral de como as permissões de aplicativos e usuários são gerenciadas.

• Para acessar um aplicativo, o usuário deve ter permissões CAN_USE ou CAN_MANAGE no aplicativo. Para gerenciar as permissões de um aplicativo, inclusive o acesso ao aplicativo, o senhor deve ter a permissão CAN MANAGE ou IS OWNER. Para saber mais sobre como atribuir permissões a um aplicativo, consulte Configurar permissões para seu aplicativo Databricks.

• Quando um aplicativo é criado, o Databricks Apps cria automaticamente uma entidade de serviço da Databricks e atribui essa entidade de serviço ao aplicativo. A entidade de serviço de um aplicativo é exclusiva e associada somente a esse aplicativo. A entidade de serviço tem acesso apenas ao site workspace no qual o aplicativo foi criado e é usado para autenticar e autorizar o acesso a recursos no site workspace, como o armazém SQL, o endpoint do modelo de serviço ou objetos seguros no site Unity Catalog.

  O nome da entidade de serviço pode ser encontrado na página de autorização tab quando o senhor acessar view os detalhes de um aplicativo. A entidade de serviço inclui o nome do aplicativo. Por exemplo, para um aplicativo chamado my-hello-world-app,, o nome da entidade de serviço pode ser app-22ixod my-hello-world-app.

• Além de acessar o recurso em um Databricks workspace usando as permissões atribuídas à entidade de serviço do aplicativo, o senhor pode usar a autorização no local do usuário para garantir que seu aplicativo interaja com o recurso usando as permissões atribuídas ao usuário do aplicativo. Utilize a autorização por parte do usuário quando o acesso a um recurso, como tabelas de gerenciamento de UC ou endpoint de modelo de serviço, deve ser restrito pelas permissões atribuídas ao usuário.

Para limitações relacionadas à autorização, consulte Limitações.

Adicionar autorização por parte do usuário a um aplicativo Databricks

Para adicionar autorização em nome do usuário a um aplicativo, você define escopos como parte da configuração do aplicativo. Um escopo limita o que seu aplicativo pode fazer ao acessar o recurso com a identidade do usuário. Se o senhor não selecionar nenhum escopo, o acesso ao seu aplicativo será limitado com base no seguinte conjunto de default escopos que são automaticamente atribuídos ao aplicativo. Esses escopos permitem que o seu aplicativo recupere informações sobre os usuários do aplicativo e são necessários para oferecer suporte à autorização no local do usuário em seus aplicativos. Você adiciona escopos adicionais ao criar ou editar seu aplicativo.

• iam.access-control:read
• iam.current-user:read

A Databricks recomenda seguir o princípio do menor privilégio e adicionar apenas os escopos exigidos pelo seu aplicativo.

Os usuários devem conceder consentimento antes de usar um aplicativo configurado para autorização em nome do usuário. Quando os usuários acessam o aplicativo pela primeira vez, eles são direcionados para uma página de consentimento do usuário que lista os escopos e as descrições de acesso solicitados pelo aplicativo. Depois de autorizar o aplicativo, o usuário pode continuar a usá-lo. Os usuários autorizam um aplicativo somente uma vez, a menos que haja uma alteração nos escopos do aplicativo.

O senhor pode adicionar escopos a um aplicativo e habilitar a autorização em nome do usuário ao criar ou editar o aplicativo na UI do Databricks Apps:

1. No cartão Instalar aplicativo ou Editar aplicativo , clique em Configurações avançadas .
2. Na seção User authorized API scopes (Escopos de API autorizados pelo usuário ), selecione os escopos a serem atribuídos ao aplicativo.
3. Clique em Instalar aplicativo ou Salvar .

Como posso determinar qual identidade usar ao acessar um recurso?

Ao implementar seu aplicativo, o senhor deve decidir qual identidade usar ao acessar um recurso. Databricks recomenda o uso da identidade do usuário para acessar recursos que são usados para implementar os requisitos funcionais do aplicativo. Caso contrário, o recurso que o aplicativo requer para funcionar deve usar a identidade do aplicativo.

Use a identidade do aplicativo para:

• Conecte-se a um data warehouse para ler ou gravar dados ou metadados específicos do aplicativo.
• registro do aplicativo em uma tabela ou volume gerenciado pelo Unity Catalog.

Use a identidade do usuário para:

• Consultar dados no Unity Catalog - gerenciar objetos.
• Conecte-se a um modelo de serviço endpoint.

Acesse identidades de aplicativos e usuários em seu código

Os valores da entidade de serviço de um aplicativo estão disponíveis na seguinte variável de ambiente:

Variável	Descrição
DATABRICKS_CLIENT_ID	O ID do cliente para a entidade de serviço Databricks atribuída ao aplicativo.
DATABRICKS_CLIENT_SECRET	O segredo do OAuth para a entidade de serviço Databricks atribuída ao aplicativo.

Para ler esses valores em seu aplicativo:

Python

import os

client_id = os.getenv('DATABRICKS_CLIENT_ID')
client_secret = os.getenv('DATABRICKS_CLIENT_SECRET')

As informações do usuário, incluindo os tokens de acesso do usuário, estão nos cabeçalhos HTTP passados para um aplicativo. A recuperação de valores dos cabeçalhos HTTP varia de acordo com a estrutura. A seguir, exemplos de como obter os tokens de acesso de um usuário em várias estruturas populares:

Streamlit

Python

import streamlit as st
user_access_token = st.context.headers.get('X-Forwarded-Access-Token')

Gradio

Python

from fastapi import Request
import gradio as gr

request: Request = gr.Request().get("request")
user_access_token = dict(request.headers).get('X-Forwarded-Access-Token')

Dash and Flask

Python

from flask import request

headers = request.headers
user_token = headers.get('X-Forwarded-Access-Token')

Shiny

Python

user_token = session.http_conn.headers.get('X-Forwarded-Access-Token', None)

Como manter o estado do seu aplicativo Databricks

Qualquer estado que seu aplicativo mantenha na memória é perdido quando ele é reiniciado. Se seu aplicativo exigir a manutenção do estado entre as reinicializações, armazene o estado externamente. Por exemplo, seu aplicativo pode usar Databricks SQLworkspace arquivos ou Unity Catalog volumes para manter o estado.

Registro em log do seu aplicativo Databricks

nota

Para view fazer login na UI do Databricks Apps ou com o URL do aplicativo, seu aplicativo deve log para stdout e stderr.

Para view a saída padrão e o erro padrão de um aplicativo, na página de detalhes do aplicativo, clique em logs tab. Veja os detalhes de um aplicativo Databricks.

O senhor também pode acessar view a saída padrão e o erro padrão logs no link <appurl>/logz. Por exemplo, se o URL do seu aplicativo for https://my-app-1234567890.my-instance.databricksapps.com, o senhor poderá acessar view o logs em https://my-app-1234567890.my-instance.databricksapps.com/logz. Para encontrar o URL do aplicativo, acesse a página de detalhes do aplicativo.

Especificando dependências de biblioteca para seu aplicativo Databricks

Se o seu aplicativo exigir Python biblioteca diferente do pacote instalado automaticamente com a implantação, use um arquivo requirements.txt para definir essa biblioteca. Se um pacote em seu arquivo requirements.txt duplicar um dos pacotes instalados automaticamente, a versão em seu requirements.txt substituirá o pacote instalado automaticamente.

Para obter a lista de pacotes e versões instalados como parte da implantação do aplicativo, consulte Python biblioteca instalada.

Quais cabeçalhos HTTP são passados para os aplicativos da Databricks?

Os seguintes cabeçalhos X-Forwarded-* são transmitidos do proxy reverso do Databricks Apps para os aplicativos:

cabeçalho	Descrição
X-Forwarded-Host	O host ou domínio original solicitado pelo cliente.
X-Forwarded-Preferred-Username	O nome de usuário fornecido pelo IdP.
X-Forwarded-User	O identificador de usuário fornecido pelo IdP.
X-Forwarded-Email	O usuário email fornecido pelo IdP.
X-Real-Ip	O endereço IP do cliente que fez a solicitação original.
X-Request-Id	O UUID da solicitação.

Quais estruturas são compatíveis com o Databricks Apps?

O senhor pode usar a maioria das estruturas Python para desenvolver seus aplicativos. Para ver exemplos de uso de estruturas específicas, incluindo Dash, Gradio e Streamlit, selecione na biblioteca de aplicativos padrão ao criar um novo aplicativo na interface do usuário. Consulte Como faço para criar um aplicativo na interface do usuário de aplicativos da Databricks?

Para as variáveis específicas do Streamlit que são definidas no ambiente de tempo de execução do Databricks Apps, consulte variável de ambiente padrão para o Streamlit.

Melhores práticas: Use segredos para armazenar informações confidenciais em um aplicativo Databricks

Databricks recomenda o uso de segredos para armazenar informações confidenciais, como credenciais de autenticação. Para saber mais sobre como usar segredos, consulte gerenciar segredos.

Para usar um segredo com seu aplicativo:

1. Configure o segredo como um recurso de aplicativo.

   

2. Adicione uma entrada para o segredo no arquivo de configuração app.yaml do aplicativo.

   YAML

   env:
     - name: 'API_TOKEN'
       valueFrom: 'api-token-value'

3. Para fazer referência ao segredo no código do aplicativo, use o valor do campo name (API_TOKEN neste exemplo) para se referir ao valor configurado em key.

Python

token = os.getenv('API_TOKEN')

Melhores práticas: Usar Databricks recurso para processamento de dados

Databricks O Apps compute foi projetado para atender à UI. Para garantir que seus aplicativos possam suportar com eficiência vários usuários, o senhor deve usar o recurso Databricks para realizar qualquer coisa que não seja um simples processamento de dados. Por exemplo, use Databricks SQL para processamento de consultas e armazenamento de conjunto de dados, Databricks Job para processamento de dados ou servindo modelo para consultar modelos AI.

Prática recomendada: siga as melhores práticas de codificação segura

A Databricks recomenda seguir práticas de codificação seguras ao desenvolver seus aplicativos, incluindo a parametrização de consultas para evitar ataques de injeção de SQL. Consulte a API de execução de instruções.

Diretrizes importantes para a implementação de aplicativos da Databricks

• Os aplicativos do Databricks enviam um sinal SIGKILL 15 segundos após um SIGTERM, portanto, os aplicativos devem ser encerrados graciosamente no máximo 15 segundos após o recebimento do sinal SIGTERM. Se um aplicativo não sair após 15 segundos, um sinal SIGKILL será enviado para encerrar o processo e todos os processos secundários.
• Como os aplicativos Databricks são executados como um usuário de sistema não privilegiado, eles não podem executar operações que exijam execução em um contexto de segurança privilegiado, como operações que exijam permissões de usuário root.
• As solicitações são encaminhadas por um proxy reverso, portanto, os aplicativos não devem depender das origens das solicitações. O ambiente do Databricks Apps define os parâmetros de configuração necessários para as estruturas compatíveis.
• Como a estrutura do aplicativo Databricks gerencia conexões TLS (Transport Layer Security), seus aplicativos não devem executar nenhuma conexão TLS ou operações de handshake.
• Seus aplicativos devem ser implementados para lidar com solicitações no formato de texto não criptografado (H2C) HTTP/2.
• Os aplicativos Databricks devem hospedar servidores HTTP em 0.0.0.0 e usar o número da porta especificado na variável de ambiente DATABRICKS_APP_PORT. Ver variável de ambiente.