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:

  • Leia o next_page_token campo de cada resposta. Para pedir a página seguinte, passe o seu valor no parâmetro de consulta page_token do seu próximo pedido e mantenha todos os outros parâmetros de pedido iguais.
  • Repita até que uma resposta omita o next_page_token ou o retorne com um valor vazio. Essa resposta é a última página. Continue a solicitar páginas mesmo que uma página não contenha resultados.
  • Não incluas page_token no primeiro pedido. Adiciona-o apenas para pedidos de seguimento.

O parâmetro que controla o tamanho da página varia consoante a API. Por exemplo, algumas APIs usam max_results, outras usam page_size, e outras usam limit. Verifique a referência da API REST para os parâmetros que cada endpoint suporta.

Observação

Algumas APIs antigas do Unity Catalog LIST só devolvem resultados de forma paginada quando especifica max_results. Defina max_results=0 para permitir que o servidor escolha o tamanho da página, ou defina um valor positivo para pedir um tamanho de página. Para mais informações, consulte Paginar operações da API REST do Catálogo Unity.

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

  • Última atualização a