Pular para o conteúdo principal
Última atualização em

API REST do Databricks

Esta página descreve a API REST do Databricks, como chamá-la e algumas práticas recomendadas.

Para obter a referência completa da API REST do Databricks, consulte a referência da API REST do Databricks.

nota

Com exceção de cenários avançados, o Databricks recomenda usar os SDKs do Databricks ou a CLI do Databricks em vez da API REST do Databricks para gerenciar objetos do Databricks programaticamente.

APIs REST de Workspace vs. account​

O Databricks fornece dois conjuntos de APIs REST. As APIs de workspaces gerenciam recursos dentro de um único workspace, como clusters, jobs, notebooks e objetos do Unity Catalog, e você as chama usando sua URL do workspace como host. As APIs de contas gerenciam recursos de toda a conta, como provisionamento de usuários e grupos, criação de workspace, configuração de rede e faturamento, e configurações do Unity Catalog em nível de conta, e você as chama usando sua URL de login do console da conta e ID da conta.

Para as operações disponíveis em cada conjunto, consulte a referência da API de Workspace e a referência da API de account.

Chamar uma API REST​

Uma chamada de API REST do Databricks inclui os seguintes componentes:

  • Dependendo se é um endpoint de workspace ou de conta, ou:

  • O tipo de operação da API REST, como GET, POST, PATCH ou DELETE.

  • O caminho da operação da API REST, como /api/2.0/clusters/get.

  • Informações de autenticação do Databricks, como um token OAuth do Databricks.

  • Qualquer payload de solicitação ou parâmetros de query de solicitação que sejam suportados pela operação da API REST, como o ID de um cluster.

Para obter informações sobre como estruturar uma solicitação de API REST e como analisar payloads de resposta para sua ferramenta de desenvolvedor preferida, consulte a documentação do seu provedor.

Exemplo 1: Obter clusters​

O exemplo a seguir chama o endpoint Cluster, List para retornar uma lista de clusters disponíveis. Ele pressupõe que a variável de ambiente DATABRICKS_HOST esteja definida como a URL do seu workspace do Databricks e DATABRICKS_TOKEN esteja definida como um token do Databricks.

Bash
curl -X GET "$DATABRICKS_HOST/api/2.0/clusters/list" \
  -H "Authorization: Bearer $DATABRICKS_TOKEN"
Python
import requests
import os

headers = {"Authorization": f"Bearer {os.getenv('DATABRICKS_TOKEN')}"}
response = requests.get(f"{os.getenv('DATABRICKS_HOST')}/api/2.0/clusters/list", headers=headers)

print(response.json())

Exemplo 2: Executar um job​

O exemplo a seguir chama o Endpoint Job, Run Now para Trigger uma execução de teste de um Job existente. Ele pressupõe que a variável de ambiente DATABRICKS_HOST esteja definida como a URL do seu workspace do Databricks e DATABRICKS_TOKEN esteja definida como um token do Databricks.

Bash
curl -X POST "$DATABRICKS_HOST/api/2.1/jobs/run-now" \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "job_id": 45678,
    "notebook_params": {
      "dry_run": "true",
      "start_date": "2026-08-27"
    }
  }'
Python
import requests
import os

url = f"{os.getenv('DATABRICKS_HOST')}/api/2.1/jobs/run-now"
headers = {
    "Authorization": f"Bearer {os.getenv('DATABRICKS_TOKEN')}",
    "Content-Type": "application/json"
}
payload = {
    "job_id": 45678,
    "notebook_params": {"dry_run": "true", "start_date": "2026-08-27"}
}

response = requests.post(url, headers=headers, json=payload)
print(f"Run ID: {response.json().get('run_id')}")

Exemplo 3: Retornar usuários da account​

O exemplo a seguir chama o endpoint List de usuários da conta para retornar usuários na conta Databricks identificada por <account_id>:

Bash
curl -X GET '<databricks-account-login-url>/api/2.0/identity/accounts/<account_id>/users' \
  --header "Authorization: Bearer $OAUTH_TOKEN"
Python
import requests
import os

url = "<databricks-account-login-url>/api/2.0/identity/accounts/<account_id>/users"
headers = {"Authorization": f"Bearer {os.getenv('OAUTH_TOKEN')}"}

response = requests.get(url, headers=headers)
print(response.json())

Práticas recomendadas​

As seções a seguir descrevem algumas boas práticas de desempenho à medida que os dados em seu workspace aumentam.

Paginando respostas da API LIST​

As APIs LIST retornam resultados em páginas em vez de uma única resposta grande. Para recuperar um conjunto completo de resultados, solicite a primeira página e, em seguida, use o token na resposta para solicitar cada página subsequente até que nenhum token seja retornado.

Para navegar por um conjunto completo de resultados:

  • Defina max_results=0 em sua solicitação. Isso permite que o servidor escolha um tamanho de página apropriado, o que é mais eficiente do que solicitar um número fixo de resultados por página.
  • Leia o campo next_page_token de cada resposta. Para solicitar a próxima página, passe seu valor no parâmetro de query page_token da sua próxima solicitação.
  • Repita até que uma resposta omita next_page_token ou a retorne como um valor vazio. Essa resposta é a última página.
  • Não inclua page_token na primeira solicitação. Adicione-o apenas para solicitações de acompanhamento.

O exemplo a seguir usa esse padrão para recuperar todas as tabelas em um esquema do endpoint de listagem de tabelas do Unity Catalog. O mesmo loop funciona para qualquer API LIST. Apenas o endpoint e o nome do campo de array na resposta mudam. Por exemplo, o endpoint Grants retorna resultados em um array privilege_assignments em vez de tables.

Python
import requests

base_url = "https://example.cloud.databricks.com"  # No trailing slash
bearer_token = "<your-personal-access-token>"
catalog_name = "main"
schema_name = "default"


def list_tables(base_url, bearer_token, catalog_name, schema_name):
    endpoint = f"{base_url}/api/2.1/unity-catalog/tables"
    headers = {"Authorization": f"Bearer {bearer_token}"}
    params = {
        "catalog_name": catalog_name,
        "schema_name": schema_name,
        "max_results": 0,  # Let the server choose the page size.
    }

    tables = []
    while True:
        response = requests.get(endpoint, headers=headers, params=params)
        response.raise_for_status()
        body = response.json()

        tables.extend(body.get("tables", []))

        # Stop when the response no longer includes a page token.
        page_token = body.get("next_page_token")
        if not page_token:
            break
        params["page_token"] = page_token

    return tables

Lidar com respostas de limite de taxa 429​

O Databricks impõe limites de taxa em chamadas de API REST para manter os workspaces responsivos sob carga pesada. Os limites são aplicados por endpoint e por workspace para oferecer suporte ao uso justo e à disponibilidade. Uma solicitação que excede o limite de taxa retorna uma resposta HTTP 429 Too Many Requests.

Trate as respostas 429 adequadamente, tentando novamente com backoff exponencial e jitter:

  • Recuo exponencial : após um 429, aguarde antes de tentar novamente e dobre o tempo de espera após cada 429 subsequente. Defina um tempo máximo de espera e um número máximo de novas tentativas para que uma solicitação não tente novamente indefinidamente.
  • Jitter : adicione uma pequena quantidade aleatória de tempo a cada espera. O jitter distribui as novas tentativas de vários clientes para que eles não tentem novamente no mesmo momento e causem picos repetidos de tráfego.
  • Se uma resposta incluir um cabeçalho Retry-After, aguarde pelo menos esse tempo antes de tentar novamente.

A maioria das bibliotecas de cliente HTTP pode aplicar esse comportamento de repetição para você. Para obter informações básicas sobre o algoritmo, consulte Exponential backoff and jitter.

Para os limites de taxa que se aplicam a APIs específicas, consulte os limites de taxa de API em API rate limits.

Cortar campos de resposta para desempenho​

Algumas APIs LIST retornam campos que são caros para compute ou que tornam as respostas grandes. Quando você não precisar desses campos, use os parâmetros de solicitação que os omitem para reduzir o tamanho da resposta e melhorar a latência.

Por exemplo, a API de tabelas do Unity Catalog é compatível com os seguintes parâmetros:

  • omit_properties=true: Omitir o campo properties de cada tabela na resposta.
  • omit_columns=true: Omitir o campo columns de cada tabela na resposta.

Se você estiver listando tabelas apenas para recuperar seus nomes, definir ambos os parâmetros retornará uma resposta menor e listará as tabelas mais rapidamente. Verifique a referência da API REST para os parâmetros de corte de campo que cada endpoint suporta.

Outros recursos​

Nesta página