Azure Databricks REST API

Esta página descreve a API Azure Databricks REST, como a chamar e algumas boas práticas.

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

Observação

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

APIs REST de Área de trabalho vs Conta

O Azure Databricks fornece dois conjuntos de APIs REST. As APIs do espaço de trabalho gerem recursos dentro de um único espaço de trabalho, como clusters, tarefas, notebooks e objetos do Unity Catalog, e são chamadas utilizando o URL do seu espaço de trabalho como anfitrião. As APIs de Conta gerem recursos a nível da conta, como o provisionamento de utilizadores e grupos, criação de espaços de trabalho, configuração de rede e faturação, e definições do Unity Catalog ao nível da conta, e chama-as usando o URL de login da consola da conta e o ID da conta.

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

Chamar uma API REST

Uma chamada REST API Databricks inclui os seguintes componentes:

  • Consoante se trate de um endpoint de espaço de trabalho 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, por exemplo, um token OAuth do Databricks.
  • Qualquer carga útil do pedido ou parâmetros de consulta do pedido que sejam suportados pela operação da API REST, como o ID de um cluster.

Para informações sobre como estruturar um pedido de API REST e como analisar as cargas de resposta para a sua ferramenta de programação preferida, consulte a documentação do seu fornecedor.

Exemplo 1: Obter clusters

O exemplo seguinte chama o endpoint Cluster, List para devolver uma lista de clusters disponíveis. Assume que a DATABRICKS_HOST variável de ambiente está definida para o URL do seu espaço de trabalho Databricks e DATABRICKS_TOKEN está definida para um token 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: Executar um trabalho

O exemplo seguinte chama o endpoint Job, Run Now para desencadear um ensaio geral de um trabalho existente. Assume que a DATABRICKS_HOST variável de ambiente está definida para o URL do seu espaço de trabalho Databricks e DATABRICKS_TOKEN está definida para um token 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 utilizadores da conta

O exemplo seguinte chama o endpoint Account User, List para devolver utilizadores na conta Databricks identificada 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())

Melhores práticas

As secções seguintes descrevem algumas melhores práticas de desempenho à medida que os dados no seu espaço de trabalho crescem.

Paginação LIST das respostas da API

LIST As APIs devolvem 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 no seu pedido. Isto permite ao servidor escolher um tamanho de página apropriado, o que é mais eficiente do que pedir um número fixo de resultados por página.
  • Leia o next_page_token campo de cada resposta. Para pedir a página seguinte, passe o seu valor no page_token parâmetro de consulta do seu próximo pedido.
  • Repita até que uma resposta omita o next_page_token ou o retorne com um valor vazio. Essa resposta é a última página.
  • Não incluas page_token no primeiro pedido. Adiciona-o apenas para pedidos de seguimento.

O exemplo seguinte utiliza este padrão para recuperar todas as tabelas de um esquema a partir do endpoint Unity Catalog Table, List. O mesmo ciclo funciona para qualquer LIST API. Apenas o endpoint e o nome do campo do array na resposta mudam. Por exemplo, o endpoint Grants devolve resultados num 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 com limite de taxa

Databricks impõe limites à taxa das chamadas à API REST para manter os espaços de trabalho responsivos sob carga intensa. São aplicados limites por endpoint e por workspace para suportar uma utilização e disponibilidade justas. Um pedido que exceda o limite de taxa devolve uma resposta HTTP 429 Too Many Requests .

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

  • Recuo 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 um pedido não tente indefinidamente.
  • Jitter: Adicionar um pequeno intervalo aleatório a cada período de espera. O jitter dispersa as tentativas de vários clientes para que não tentem todos ao mesmo tempo e causem surtos 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 de cliente HTTP pode aplicar este comportamento de repetição por si só. Para obter contexto sobre o algoritmo, veja Recuo exponencial e jitter.

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

Reduzir os campos de resposta para melhorar o desempenho

Algumas LIST APIs devolvem campos que são caros de calcular ou que tornam as respostas grandes. Quando não precisares destes campos, usa os parâmetros de pedido que os omitam para reduzir o tamanho da resposta e melhorar a latência.

Por exemplo, a API Unity Catalog Tables 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 estiver a listar tabelas apenas para obter os nomes delas, definir ambos os parâmetros devolve uma resposta menor e lista tabelas mais rapidamente. Verifique a referência da API REST para os parâmetros de corte de campos que cada endpoint suporta.

Recursos adicionais

  • Last updated on