Use o Genie Everywhere com OAuth empresarial

Introdução

A democratização dos dados começa com o acesso fácil e seguro às percepções. Com o Databricks Genie, os usuários agora podem conversar com seus dados diretamente das ferramentas que já usam: Teams, Slack, Confluence ou aplicativos web personalizados. Seja usando nossas integrações nativas do Copilot Studio/Foundry ou desenvolvendo com as APIs/SDK do Genie Conversation, o Genie agora pode trazer a analítica de linguagem natural para os fluxos de trabalho diários. Nos bastidores, o OAuth pode ser aplicado para autenticar cada usuário com segurança e aplicar permissões de acesso a dados.

Anteriormente, vimos clientes como The AA e Casas Bahia criarem de forma independente suas próprias integrações do Genie no Microsoft Teams e em aplicativos internos. Nosso robusto conjunto de extensibilidade agora torna essa experiência mais fácil, mais rápida e mais escalável.

Neste blog, vamos apresentar duas maneiras comuns de implementar o Genie com OAuth empresarial em toda a sua organização:

• Leve o Genie para o Microsoft Teams com nossa integração do Copilot Studio
• Incorpore o Genie em seus aplicativos da web personalizados com as APIs Genie Conversation

Adicione o Genie ao Microsoft Teams

Perguntas pontuais sobre dados surgem o tempo todo durante as conversas em grupo. Com a integração nativa do Databricks Genie com o Copilot Studio, seus usuários agora podem obter respostas no momento em que as perguntas surgem, diretamente no Microsoft Teams. Para aproveitar esta integração, siga os passos abaixo:

Pré-requisitos

• Garanta que você tenha um espaço do Genie de destino com curadoria de acordo com nossas melhores práticas para oferecer a mais alta qualidade.
• Os usuários finais/Service Principals devem ter acesso ao Genie space de destino (pelo menos CAN VIEW), privilégios SELECT nos dados do Unity Catalog do espaço e permissão CAN USE na SQL compute do espaço. Os usuários finais podem, opcionalmente, receber a qualificação Consumer Access para uma experiência simplificada de “somente leitura”.

Etapa 1: Conectar o Azure Databricks ao Power Platform

O primeiro passo para habilitar o Genie no Microsoft Teams é conectar o Azure Databricks à Power Platform (documentação). No seu Microsoft Power Apps, clique em Conexões e selecione Azure Databricks ou Databricks se você usa AWS/GCP. Configure os seguintes campos:

• Para garantir que cada usuário final se autentique no Databricks com sua própria identidade, selecione OAuth como o Tipo de Autenticação.
• Para o hostname do servidor e o Caminho HTTP, acesse o workspace onde está o seu Genie space de destino. Selecione um SQL warehouse e abra os Detalhes da conexão para recuperar essa informação (não precisa ser o mesmo SQL warehouse que está anexado ao seu espaço do Genie).

Etapa 2: Conecte os Genie spaces ao seu agente do Copilot Studio

Em seguida, você conectará seu Genie space ao Copilot Studio (documentação). Nossa integração cuida de toda a lógica de API e MCP para que a conexão possa ser feita em apenas alguns cliques.

No Copilot Studio, clique em Agents. Selecione “Create blank agent” para criar um novo agente independente para um espaço do Genie. Se quiser trazer o Genie para uma estrutura de agente existente, você também pode escolher um agente existente do Copilot Studio para adicionar seu Genie space.

No seu novo agente, clique em 'Ferramentas' e depois em “Adicionar uma ferramenta”. Selecione o Azure Databricks Genie (ou o Databricks Genie para AWS/GCP) na seção MCP.

Agora, você pode selecionar o Genie space desejado e configurar os detalhes da conexão:

• Credenciais a serem usadas: Selecione “Credenciais de usuário final” para garantir que cada usuário do aplicativo fará login com sua própria identidade e permissões de acesso a dados. Isso garante que, se um usuário do aplicativo não tiver acesso ao Genie space ou às tabelas, ele não conseguirá recuperar percepções de dados do Genie.
• Selecione “Credenciais fornecidas pelo criador” se você quiser que os usuários finais se autentiquem usando uma única identidade compartilhada (um service principal — recomendado — ou sua própria identidade).
• IMPORTANTE: certifique-se de que seu espaço do Genie de destino tenha um título e uma descrição claros que descrevam seu contexto, seus principais conceitos e suas limitações. Isso ajudará seu agente do Copilot Studio a orquestrar solicitações de forma eficaz.

Passo 3: Habilitar o compartilhamento de parâmetros de conexão

Ao escolher “Credenciais do usuário final”, cada pessoa deve fazer login no Databricks com a própria conta. Para simplificar, sugerimos o compartilhamento dos parâmetros de Conexão (conforme descrito na documentação da Microsoft), para que os usuários não precisem fornecer essas informações por conta própria. Na prática, isso significa simplesmente fornecer o hostname do servidor e o caminho HTTP, o que garante que a autenticação seja feita no workspace exato do Databricks vinculado ao Genie space conectado em seu agente do Copilot Studio.

• Abra a página de Configurações do seu Agente do Copilot Studio.
• Abra as Configurações de Conexão e verifique se o Azure Databricks exibe o status Conectado.
  
• Em seguida, clique em Ver detalhes e conceda permissão para compartilhar parâmetros na tab Parâmetros de conexão.
  

Passo 4: leve seu agente para o Teams

Agora que você tem um Agente do Copilot Studio conectado ao seu espaço do Genie, você pode publicá-lo no Teams.

• Certifique-se de que seu agente tenha um Nome e uma Descrição claros.
• Também recomendamos:
  • Selecionar um modelo de raciocínio (p. ex., GPT-5 Reasoning, Claude Sonnet 4.5) para polling e uso eficazes do Genie.
  • Adicionar instruções de agente personalizadas para personalizar a experiência (por exemplo, formatação de resposta e preferências de latência).
    
• Depois de revisar seu agente do Copilot Studio, clique em Publicar. Em seguida, em Canais, escolha o Teams como seu canal desejado.
  

Tudo pronto! O Genie agora está ativo no Microsoft Teams, fornecendo percepções de dados governados no momento em que as perguntas surgem.

Para ver como os usuários finais estão utilizando o Genie no Microsoft Teams, consulte nossas histórias de clientes.

Levando o Genie para aplicativos web personalizados

Muitas organizações também querem incorporar o Genie diretamente em seus aplicativos web personalizados, para que os usuários possam fazer perguntas nas ferramentas que já usam — por exemplo, gerentes de loja podem fazer perguntas ad-hoc sobre seu estoque diretamente no terminal de vendas existente. Com as APIs de Conversa do Genie e o Databricks OAuth, isso agora é possível.

Antes de criar uma integração entre seu aplicativo web e o Genie, é importante decidir qual padrão OAuth você usará: User-to-Machine (U2M), Machine-to-Machine (M2M) ou um modelo On-Behalf-Of (OBO). Cada abordagem se alinha a um tipo diferente de caso de uso do aplicativo:

• Usuário-para-Máquina (U2M) - Ideal para quando cada usuário final precisa de acesso a dados governado e personalizado. Neste modelo, um usuário faz login com sua identidade corporativa (por exemplo, SSO), o Genie recebe um token OAuth específico do usuário, e as queries são executadas com as permissões desse usuário. Exemplo de caso de uso: um ventas Copilot em que os representantes de ventas conversam com um único Genie space subjacente e devem ver apenas percepções de dados de seus próprios negócios.
• Máquina a máquina (M2M) – ideal para casos de uso em que todos os usuários devem ter o mesmo acesso aos dados e uma governança mais simples. Este modelo permite que uma entidade de serviço se autentique e emita um token OAuth associado para o Genie, que é então usado para executar consultas sob as permissões da entidade de serviço. Exemplo de caso de uso: um chatbot de “KPIs da empresa” em que qualquer funcionário pode perguntar sobre as métricas de KPI de toda a empresa e receber as mesmas percepções compartilhadas.
• On-Behalf-Of (OBO): ideal para aplicativos que precisam de governança de dados por usuário, mas por trás de um back-end central. Neste modelo, seu aplicativo primeiro se autenticaria no Databricks e, em seguida, chamaria as APIs do Genie “em nome do” usuário final com as permissões de dados dele aplicadas. Exemplo de caso de uso: um portal de analítica financeira onde os usuários conversam com um chatbot unificado que utiliza o Genie, e cada usuário vê apenas os dados para os quais está autorizado.

No restante deste blog, focaremos no primeiro padrão de integração com o Genie: o fluxo OAuth U2M usando o suporte OAuth integrado do Databricks.

OBSERVAÇÃO: o Databricks também oferece suporte à federação de tokens OAuth, que você pode usar para trazer tokens emitidos pelo seu próprio provedor de identidade e combiná-los com qualquer um dos métodos descritos acima para acesso ao Genie.

Pré-requisitos

• Garanta que você tenha um espaço do Genie de destino com curadoria de acordo com nossas melhores práticas para oferecer a mais alta qualidade.
• Os usuários finais/as Service Principal devem ter acesso ao Genie space de destino (pelo menos CAN VIEW), privilégios SELECT sobre os dados do Unity Catalog do espaço e permissão CAN USE na SQL compute do espaço. Os usuários finais podem, opcionalmente, receber a permissão de Acesso de Consumidor para uma experiência otimizada de “somente leitura”.
  

Passo 1: Registrar um aplicativo OAuth

Para conectar com segurança seu aplicativo web personalizado ao Genie, comece registrando-o em sua account do Databricks. Esta etapa permite que o Databricks emita tokens com escopo de usuário com segurança para seu aplicativo nos passos posteriores. Confira a documentação do produto para saber mais.

No Console da conta do Databricks, adicione uma nova conexão OAuth e configure o seguinte:

• Nome do aplicativo: um nome legível por humanos exibido aos usuários durante o login
• URLs de redirecionamento: uma ou mais URLs para as quais o Databricks tem permissão para enviar usuários após a autenticação. Elas devem corresponder exatamente às URLs que seu aplicativo usará nos passos posteriores.
• Escopos de acesso: conceda acesso a todas as APIs (All APIs) para que seu aplicativo possa chamar as APIs do Genie Conversation em nome dos usuários.
  

Após salvar esta conexão, o Databricks gerará o seguinte:

• ID do cliente: identificador público para seu aplicativo
• Segredo do cliente: credencial privada para seu back-end

Armazene estas credenciais com segurança em seu back-end. Elas serão necessárias para trocar códigos de autorização por tokens de acesso e autenticar chamadas para as APIs do Genie Conversation.

Passo 2: Direcionar os usuários para o Databricks para autenticar e conceder acesso

O próximo passo é garantir que seu aplicativo direcione os usuários finais para o Databricks para que eles possam fazer login e aprovar seu aplicativo para se comunicar com o Genie em nome deles. Após um login e uma aprovação bem-sucedidos, o Databricks redirecionará o usuário para seu aplicativo com um código de autorização de curta duração.

Este código de autorização é a prova de que o usuário se autenticou com sucesso no Databricks e que o usuário aprovou o acesso solicitado pelo seu aplicativo. O backend do seu aplicativo usará este código de autorização no próximo passo para obter tokens de acesso.

Para começar, gere valores de PKCE e de estado para cada login para proteger seu aplicativo web:

• Gere um code_verifier e um code_challenge correspondente de acordo com o padrão OAuth PKCE usando a codificação SHA-256 e Base64 URL. Este passo impede que os códigos de autorização sejam roubados e reutilizados (veja exemplos de código na documentação).
• Crie uma string state aleatória e certifique-se de armazená-la em um cookie ou sessão. Isso garante que os códigos de autorização sejam gerados para sessões reais de usuário final.

Em seguida, seu front-end deve construir uma URL de autorização usando o endpoint OAuth do Databricks:

Inclua os seguintes parâmetros de formulário para identificar seu aplicativo para seus usuários:

• <databricks-instance>: Sua instância do Databricks com o nome da instância do workspace (por exemplo, dbc-a1b2345c-d6e7.cloud.databricks.com)
• <client_id>: o ID do cliente do seu aplicativo OAuth registrado n'o passo anterior
• <redirect-url>: a mesma URL de redirecionamento especificada no passo anterior
• <state>: - Qualquer string de texto simples para validar a resposta
• <code-challenge>: desafio de código PKCE derivado do code_verifier

Depois que um usuário entrar em sua account do Databricks, ele será redirecionado para a redirect_url com os parâmetros de query: https://<redirect_url>/oauth/callback?code=<authorization_code>&state=<state>

Seu manipulador de callback deve ler o authorization_code e o state da query string. Verifique se o valor de state corresponde ao que foi armazenado em cookies ou sessões web. Caso não corresponda, descarte o authorization_code. Com o authorization_code retornado, seu aplicativo agora pode trocá-lo por tokens de acesso.

O passo 3: trocar códigos de autorização por tokens e gerenciá-los com segurança

O código de autorização recuperado no passo anterior não pode ser usado para chamar APIs diretamente — ele deve ser trocado por tokens de acesso no seu backend, que são necessários para se comunicar de forma segura com o Genie. Para mais informações, consulte nossa documentação do produto).

Abaixo está um exemplo em Python para trocar códigos de autorização por tokens de acesso e de atualização (veja os detalhes na documentação do SDK do OAuth):

Inclua os seguintes parâmetros:

• <databricks-instance>: sua instância do Databricks com o nome da instânciado workspace
• <client_id>: o ID do cliente do seu aplicativo OAuth registrado n'o passo anterior
• <client_secret>: o segredo do cliente para seu app gerado no passo 1
• <redirect-url>: a mesma URL de redirecionamento especificada n'o Passo 1
• <code-verifier>: o verificador gerado no passo 2

É importante salvar os seguintes valores do objeto result no banco de dados do seu aplicativo:

• access_token: usado para chamar as APIs de conversação do Genie
• refresh_token: usado para obter novos access tokens sem forçar o usuário a fazer login novamente
• expires_in: um tempo de expiração para o access token
• expires_at: um timestamp para quando o access token não for mais válido

Para gerenciar tokens de acesso com segurança, também é importante que seu aplicativo monitore os tempos de expiração e use os refresh tokens para obter novos tokens de acesso quando necessário. O exemplo de código abaixo abstrai a lógica de refresh para sempre retornar um access token de usuário válido:

Passo 4: rotear as solicitações do usuário para as APIs de conversação do Genie

Agora que seu aplicativo tem tokens de acesso do Databricks com escopo de usuário, ele pode enviar prompts para um espaço do Genie em nome do usuário conectado. Recomendamos criar um roteador de API de backend para seu aplicativo web para proteger os access tokens do Databricks do navegador e para centralizar a observabilidade, o tratamento de erros e a limitação de taxa. Os exemplos de código abaixo aproveitam o FastAPI e o SDK do Genie para uma lógica mais simples.

• Primeiro, use o token de acesso do usuário para criar um WorkspaceClient com escopo. Este WorkspaceClient poderá então chamar o SDK do Genie. Exemplos de código

• Em seguida, exponha os endpoints HTTP pertencentes ao aplicativo que se traduzem em chamadas do SDK do Genie no back-end. Isso garante que todas as chamadas do SDK do Genie sejam feitas em seu servidor e que os access tokens nunca sejam enviados para o navegador.
  • Por exemplo, é assim que se cria um endpoint HTTP para iniciar uma nova conversa com o Genie:

• Continue adicionando outros roteadores de API para as ações do Genie que você quer que seu aplicativo suporte. As funções essenciais a serem incluídas são:
  • Enviar mensagem de acompanhamento - para mensagens de acompanhamento de uma conversa existente
    • create_message_and_wait(space_id: str, conversation_id: str, content: str, timeout: datetime.timedelta = 0:20:00) → GenieMessage
  • Recuperar resultados da consulta - recupera resultados SQL se a mensagem tiver um anexo de consulta
    • get_message_attachment_query_result(space_id: str, conversation_id: str, message_id: str, attachment_id: str) → GenieGetMessageQueryResultResponse
  • Obter mensagem - recuperar status e resultados de uma mensagem específica
    • get_message(space_id: str, conversation_id: str, message_id: str) → GenieMessage
  • Listar mensagens em uma conversa - para listar todas as mensagens anteriores em uma conversa
    • list_conversation_messages(space_id: str, conversation_id: str [, page_size: Optional[int], page_token: Optional[str]]) → GenieListConversationMessagesResponse
  • Consulte a documentação do SDK do Genie para ver todas as funções disponíveis.

Após esses os passos, seu aplicativo web personalizado será integrado com segurança ao Genie, permitindo que os usuários façam perguntas em linguagem natural e recuperem percepções governadas diretamente nas ferramentas que já usam.

Acessar o Genie Everywhere

O Genie foi projetado para atender aos usuários onde quer que eles trabalhem. Neste blog, abordamos como as organizações incorporam com segurança os recursos de analítica conversacional do Genie no Microsoft Teams e em aplicativos personalizados com autenticação OAuth.

Ao levar o Genie a todos os lugares onde suas equipes fazem perguntas, você encurta o caminho da pergunta à percepção — e da percepção à ação. Comece a criar espaços do Genie e a levá-los para seus usuários hoje mesmo. Como sempre, entre em contato com as equipes da sua conta da Databricks para tirar dúvidas e enviar feedback.

(Esta publicação no blog foi traduzida utilizando ferramentas baseadas em inteligência artificial) Publicação original