Azure Databricks REST API

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

Para referência completa da API REST do Databricks, veja referência à API REST do Databricks.

Observação

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

APIs REST de Workspace vs Conta

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

Para as operações disponíveis em cada conjunto, veja a referência da API do workspace e a referência da API da conta.

Chamar uma API REST

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

  • Dependendo de se tratar de um endpoint de workspace ou de conta, uma das seguintes opções:
  • O tipo de operação da API REST, como GET, POST, PATCH, ou DELETE.
  • O caminho de 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 corpo da solicitação ou parâmetro de consulta da solicitação compatível com a operação da API REST, como o ID de um cluster.

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

Exemplo 1: Obtenha clusters

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

curl -X GET "$DATABRICKS_HOST/api/2.0/clusters/list" \
  -H "Authorization: Bearer $DATABRICKS_TOKEN"

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: Execute um trabalho

O exemplo a seguir faz uma chamada ao endpoint Job, Run Now para disparar uma execução de teste de um job existente. Pressupõe-se que a variável de ambiente DATABRICKS_HOST esteja definida como a URL do seu espaço de trabalho do Databricks e que DATABRICKS_TOKEN esteja definida como um token do Databricks.

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"
    }
  }'

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 conta

O exemplo a seguir chama o endpoint Account User, List para retornar usuários na conta Databricks identificados por <account_id>:

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

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 melhores práticas de desempenho à medida que os dados no seu espaço de trabalho crescem.

Paginar LIST as respostas da API

LIST APIs 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 depois use o token na resposta para solicitar cada página subsequente até que nenhum token seja devolvido.

Para folhear um conjunto completo de resultados:

  • Defina max_results=0 na 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 next_page_token campo de cada resposta. Para solicitar a próxima página, passe seu valor no page_token parâmetro de consulta da sua próxima solicitação.
  • Repita até que uma resposta a omita next_page_token ou retorne como valor vazio. Essa resposta é a última página.
  • Não inclua page_token na primeira solicitação. Adicione isso apenas para solicitações de acompanhamento.

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

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 429 respostas de limite de taxa

O Databricks aplica limites de taxa nas chamadas de API REST para manter os workspaces responsivos sob carga pesada. Limites são aplicados por endpoint e por workspace para suportar uso e disponibilidade justos. Uma solicitação que exceda o limite de taxa retorna uma resposta HTTP 429 Too Many Requests .

Gerencie 429 as respostas com elegância, tentando novamente com um recuo exponencial e tremores:

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

A maioria das bibliotecas cliente HTTP pode aplicar esse comportamento de nova tentativa para você. Para obter contexto sobre o algoritmo, consulte backoff exponencial e jitter.

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

Reduza os campos de resposta para melhorar o desempenho

Algumas APIs LIST retornam campos que são custosos de calcular ou que aumentam muito o tamanho das respostas. Quando você não precisar desses campos, use os parâmetros de requisição que os omitam para reduzir o tamanho da resposta e melhorar a latência.

Por exemplo, a API de Tabelas de Catálogo Unity suporta os seguintes parâmetros:

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

Se você está listando tabelas apenas para recuperar os nomes delas, definir ambos os parâmetros retorna uma resposta menor e lista tabelas mais rápido. Verifique a referência da API REST para os parâmetros de corte de campo que cada endpoint suporta.

Recursos adicionais

  • Last updated on