Chamar APIs REST diretamente a partir do código do agente

Utilize o endpoint proxy de ligações do Unity Catalog com o SDK de cliente do serviço externo para chamar diretamente as APIs REST a partir do código do agente. Direcione a URL base do SDK para o endpoint do proxy e use o seu token Azure Databricks como chave de API. O Azure Databricks autentica o pedido e injeta automaticamente as credenciais do serviço externo a partir da ligação ao Unity Catalog. O teu código não lida diretamente com os tokens do serviço externo.

Requisitos

• Python 3.12 e início de sessão no espaço de trabalho.
• Uma ligação HTTP do Unity Catalog para o serviço externo. O endpoint proxy utiliza esta ligação para autenticar e injetar as credenciais do serviço.
• USE CONNECTION no objeto de ligação.

OpenAI

Uso DatabricksOpenAI para encaminhar chamadas para OpenAI externo através do proxy de ligações do Unity Catalog. Primeiro, crie uma ligação HTTP ao Unity Catalog usando a sua chave API OpenAI armazenada como segredo Databricks:

CREATE CONNECTION openai_connection TYPE HTTP
OPTIONS (
  host 'https://api.openai.com',
  base_path '/v1',
  bearer_token secret ('<secret-scope>', '<secret-key>')
);

Depois instala o pacote databricks-openai e usa a URL do proxy e o cliente de espaço de trabalho no código do seu agente.

pip install --upgrade databricks-openai

from databricks_openai import DatabricksOpenAI
from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

client = DatabricksOpenAI(
    workspace_client=w,
    base_url=f"{w.config.host}/api/2.0/unity-catalog/connections/openai_connection/proxy/",
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(response.choices[0].message.content)

Slack

Configure o Slack SDK para fazer o encaminhamento através do proxy de conexões do Unity Catalog. Crie uma ligação HTTP do Unity Catalog com o host /api e o caminho base https://slack.com, depois use a URL do proxy como URL base do SDK. Nomeie a ligação slack_connection e configure as credenciais do fornecedor de serviços para a sua aplicação Slack.

Instale as bibliotecas:

pip install --upgrade slack-sdk databricks-sdk

Substitui <channel-id> por um canal onde a tua aplicação Slack possa publicar. Executar este exemplo envia uma mensagem:

from slack_sdk import WebClient
from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

client = WebClient(
    token=w.config.authenticate()["Authorization"].split(" ")[1],
    base_url=f"{w.config.host}/api/2.0/unity-catalog/connections/slack_connection/proxy/",
)

result = client.chat_postMessage(channel="<channel-id>", text="Hello from Databricks!")
print(result["message"]["text"])

HTTP genérico

Para serviços sem SDK dedicado, use a requests biblioteca com o URL proxy diretamente. Substitua o nome da ligação, o caminho do recurso e o corpo JSON pelos valores da sua API.

pip install --upgrade requests databricks-sdk

import requests
from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

response = requests.post(
    f"{w.config.host}/api/2.0/unity-catalog/connections/my_connection/proxy/api/v1/resource",
    headers={
        **w.config.authenticate(),
        "Content-Type": "application/json",
    },
    json={"key": "value"},
    timeout=30,
)
response.raise_for_status()
print(response.text)

Para detalhes sobre o endpoint proxy, métodos de autenticação suportados e configuração de ligação, consulte Encaminhar pedidos através do proxy de ligação HTTP.

Envolver http_request() numa função do Unity Catalog (legado)

Também pode criar uma função do Catálogo do Unity que encapsula http_request() para chamar serviços externos, o que é útil para definições de ferramentas baseadas em SQL. A função utiliza a mesma ligação HTTP do Unity Catalog que a utilizada pela abordagem de proxy, indicada pelo nome no parâmetro conn.

O exemplo seguinte usa o slack_connection acima, cujo caminho base é /api. Substitua <channel-id> pelo ID do canal do Slack. A função envia uma mensagem quando é invocada:

CREATE OR REPLACE FUNCTION main.default.slack_post_message(
  text STRING COMMENT 'message content'
)
RETURNS STRING
COMMENT 'Sends a Slack message by passing in the message and returns the response received from the external service.'
RETURN (http_request(
  conn => 'slack_connection',
  method => 'POST',
  path => '/chat.postMessage',
  json => to_json(named_struct(
    'channel', '<channel-id>',
    'text', text
  ))
)).text;

Veja CREATE FUNCTION (SQL, Python, Scala e Java).