Adicionar um recurso de UDF (função definida pelo usuário) a um aplicativo do Databricks

Adicione user-defined functions (UDFs) registrados no Catálogo do Unity como recursos do Databricks Apps para permitir que seu aplicativo execute funções de SQL e Python registradas. As UDFs fornecem lógica de negócios reutilizável, transformações de dados e operações personalizadas que podem ser compartilhadas em toda a sua organização com governança centralizada.

Requisitos de privilégio

Para executar uma UDF, o principal de serviço do aplicativo deve ter o USE CATALOG privilégio no catálogo pai, o USE SCHEMA privilégio no esquema pai e o EXECUTE privilégio na função. Quando você adiciona o recurso UDF, Azure Databricks concede automaticamente esses privilégios à entidade de serviço do aplicativo.

Para que essa concessão automática seja bem-sucedida, um dos seguintes deve ser verdadeiro para cada privilégio:

• Para USE CATALOG: ou todos os usuários da conta têm o USE CATALOG privilégio no catálogo, ou você tem o MANAGE privilégio no catálogo.
• Para USE SCHEMA: Ou todos os usuários da conta possuem o privilégio USE SCHEMA no esquema, ou você possui o privilégio MANAGE no esquema.
• Para EXECUTE: ou todos os usuários da conta têm o privilégio EXECUTE na função, ou você tem o privilégio MANAGE na função.

Consulte a referência de privilégios do Catálogo do Unity.

Adicionar um recurso de UDF (função definida pelo usuário)

Antes de adicionar um UDF como um recurso, examine os pré-requisitos do recurso de aplicativo.

1. Na seção Recursos do aplicativo ao criar ou editar um aplicativo, clique em + Adicionar> de recurso.
2. Escolha uma Função Definida pelo Usuário (UDF) nas funções disponíveis em seu ambiente de trabalho. A função já deve estar registrada no Catálogo do Unity.
3. Selecione o nível de permissão do aplicativo:
   • Pode executar: Concede a permissão do aplicativo para executar a UDF com os parâmetros fornecidos. Corresponde ao privilégio EXECUTE.
4. (Opcional) Especifique uma chave de recurso personalizada, que é como você faz referência à UDF na configuração do aplicativo. A chave padrão é function.

Variáveis de ambiente

Quando você implanta um aplicativo com um recurso UDF, Azure Databricks expõe o nome completo de três níveis por meio de variáveis de ambiente que você pode referenciar usando o campo valueFrom.

Configuração de exemplo:

env:
  - name: UC_FUNCTION_NAME
    valueFrom: function # Use your custom resource key if different

Usando a função em seu aplicativo:

import os
from databricks.sdk import WorkspaceClient

# Access the function name
function_name = os.getenv("UC_FUNCTION_NAME")

# Initialize workspace client
w = WorkspaceClient()

# Execute the function via SQL
result = w.statement_execution.execute_statement(
    warehouse_id="your_warehouse_id",
    statement=f"SELECT {function_name}('parameter_value')"
)

# Process the result
print(f"Function result: {result}")

Para obter mais informações, consulte Usar variáveis de ambiente para acessar recursos.

Remover um recurso de UDF (função definida pelo usuário)

Quando você remove um recurso UDF de um aplicativo, o principal de serviço do aplicativo perde o acesso à função. A UDF em si permanece inalterada e continua disponível para outros usuários e aplicativos que têm permissões apropriadas.

Práticas recomendadas

Considere o seguinte quando você trabalha com recursos da UDF:

• Verifique se as UDFs estão bem documentadas com descrições de parâmetro claras e tipos de retorno.
• Manipule erros de UDF de forma elegante no código do aplicativo, incluindo validação de parâmetros e tratamento de exceção.
• Teste o comportamento da UDF no contexto do aplicativo antes da implantação para verificar os resultados esperados.
• Considere as dependências da UDF em tabelas ou fontes de dados subjacentes ao planejar permissões de aplicativo.