API REST 1.2

La API REST de Databricks permite acceder mediante programación a Azure Databricks en lugar de pasar a través de la interfaz de usuario web.

En este artículo se describe la API REST 1.2. La versión más reciente de API REST, así como API REST 2.1 y 2.0, también están disponibles.

Importante

Importante

Para acceder a las API REST de Databricks, es preciso autenticarse.

Casos de uso de la API REST

  • Inicie los trabajos de Apache Spark desencadenados desde los sistemas de producción existentes o desde sistemas de flujo de trabajo.
  • Muestre mediante programación un clúster de un tamaño determinado a una hora fija del día y, a continuación, apáguelo por la noche.

Categorías de la API

  • Contexto de ejecución: cree espacios de nombres variables únicos en los que se pueda llamar a los comandos de Spark.
  • Ejecución del comando: ejecute comandos dentro de un contexto de ejecución específico.

Detalles

  • Esta API REST se ejecuta mediante HTTPS.
  • Para recuperar información, use HTTP GET.
  • Para modificar el estado, use HTTP POST.
  • Para cargar archivos, use multipart/form-data. De lo contrario, use application/json.
  • El tipo de contenido de la respuesta es JSON.
  • La autenticación básica se usa para autenticar al usuario para cada llamada API.
  • Las credenciales de usuario están codificadas en Base64 y se encuentran en el encabezado HTTP para cada llamada API. Por ejemplo, Authorization: Basic YWRtaW46YWRtaW4=. Si usa curl, también puede almacenar las credenciales de usuario en un archivo .netrc.
  • Para más información sobre el uso de la API REST de Databricks, consulte la referencia de la API REST de Databricks.

Introducción

  • Para probar los ejemplos de este artículo, reemplace <databricks-instance> por la dirección URL del área de trabajo de la implementación de Azure Databricks.
  • En los ejemplos siguientes se usa curl y un archivo .netrc. Puede adaptar estos curl ejemplos con una biblioteca HTTP en el lenguaje de programación que prefiera.

Referencia de API

Obtener la lista de clústeres

Método y ruta de acceso:

GET /api/1.2/clusters/list

Ejemplo

Solicitud:

curl --netrc --request GET \
  https://<databricks-instance>/api/1.2/clusters/list

Respuesta:

[
  {
    "id": "1234-567890-span123",
    "name": "MyCluster",
    "status": "Terminated",
    "driverIp": "",
    "jdbcPort": 10000,
    "numWorkers":0
  },
  {
    "..."
  }
]

Esquema de solicitud

Ninguno.

Esquema de respuesta

Matriz de objetos, con cada objeto que representa información sobre un clúster, tal y como se muestra a continuación:

Campo
id

Tipo: string

El Id. del clúster.
name

Tipo: string

Nombre del clúster.
status

Tipo: string

El estado del clúster. Uno de los valores siguientes:

* Error
* Pending
* Reconfiguring
* Restarting
* Running
* Terminated
* Terminating
* Unknown
driverIp

Tipo: string

La dirección IP del controlador.
jdbcPort

Tipo: number

El número de puerto de JDBC.
numWorkers

Tipo: number

Número de trabajos del clúster.

Obtención de información sobre un clúster

Método y ruta de acceso:

GET /api/1.2/clusters/status

Ejemplo

Solicitud:

curl --netrc --get \
  https://<databricks-instance>/api/1.2/clusters/status \
  --data clusterId=1234-567890-span123

Respuesta:

{
  "id": "1234-567890-span123",
  "name": "MyCluster",
  "status": "Terminated",
  "driverIp": "",
  "jdbcPort": 10000,
  "numWorkers": 0
}

Esquema de solicitud

Campo
clusterId

Tipo: string

El Id. del clúster.

Esquema de respuesta

Un objeto que representa información sobre el clúster.

Campo
id

Tipo: string

El Id. del clúster.
name

Tipo: string

Nombre del clúster.
status

Tipo: string

El estado del clúster. Uno de los valores siguientes:

* Error
* Pending
* Reconfiguring
* Restarting
* Running
* Terminated
* Terminating
* Unknown
driverIp

Tipo: string

La dirección IP del controlador.
jdbcPort

Tipo: number

El número de puerto de JDBC.
numWorkers

Tipo: number

Número de trabajos del clúster.

Reinicio de un clúster

Método y ruta de acceso:

POST /api/1.2/clusters/restart

Ejemplo

Solicitud:

curl --netrc --request POST \
  https://<databricks-instance>/api/1.2/clusters/restart \
  --data clusterId=1234-567890-span123

Respuesta:

{
  "id": "1234-567890-span123"
}

Esquema de solicitud

Campo
clusterId

Tipo: string

El id. del clúster que se reiniciará.

Esquema de respuesta

Campo
id

Tipo: string

El Id. del clúster.

Cree un contexto de ejecución

Método y ruta de acceso:

POST /api/1.2/contexts/create

Ejemplo

Solicitud:

curl --netrc --request POST \
  https://<databricks-instance>/api/1.2/contexts/create \
  --data clusterId=1234-567890-span123 \
  --data language=sql

Respuesta:

{
  "id": "1234567890123456789"
}

Esquema de solicitud

Campo
clusterId

Tipo: string

El id. del clúster para el que se creará el contexto.
clusterId

Tipo: string

El lenguaje para el contexto. Uno de los valores siguientes:

* python
* scala
* sql

Esquema de respuesta

Campo
id

Tipo: string

El id. del contexto de ejecución.

Obtener información sobre un contexto de ejecución

Método y ruta de acceso:

GET /api/1.2/contexts/status

Ejemplo

Solicitud:

curl --netrc https://<databricks-instance>/api/1.2/contexts/status?clusterId=1234-567890-span123&contextId=1234567890123456789

Respuesta:

{
  "id": "1234567890123456789",
  "status": "Running"
}

Esquema de solicitud

Campo
clusterId

Tipo: string

El id. del clúster sobre el que se obtiene información de contexto de ejecución.
contextId

Tipo: string

El id. del contexto de ejecución.

Esquema de respuesta

Campo
id

Tipo: string

El id. del contexto de ejecución.
status

Tipo: string

El estado del contexto de ejecución. Uno de los valores siguientes:

* Error
* Pending
* Running

Eliminar un contexto de ejecución

Método y ruta de acceso:

POST /api/1.2/contexts/destroy

Ejemplo

Solicitud:

curl --netrc --request POST \
  https://<databricks-instance>/api/1.2/contexts/destroy \
  --data clusterId=1234-567890-span123 \
  --data contextId=1234567890123456789

Respuesta:

{
  "id": "1234567890123456789"
}

Esquema de solicitud

Campo
clusterId

Tipo: string

El id. del clúster para el que se destruirá el contexto de ejecución.
contextId

Tipo: string

El id. del contexto de ejecución a destruir.

Esquema de respuesta

Campo
id

Tipo: string

El id. del contexto de ejecución.

Ejecute un comando

Método y ruta de acceso:

POST /api/1.2/commands/execute

Ejemplo

Solicitud:

curl --netrc --request POST \
  https://<databricks-instance>/api/1.2/commands/execute \
  --header 'Content-Type: application/json' \
  --data @execute-command.json

execute-command.json:

{
   "clusterId": "1234-567890-span123",
   "contextId": "1234567890123456789",
   "language": "python",
   "command": "print('Hello, World!')"
}

Respuesta:

{
  "id": "1234ab56-7890-1cde-234f-5abcdef67890"
}

Esquema de solicitud

Campo
clusterId

Tipo: string

El id. del clúster en el que se ejecutará el comando.
contextId

Tipo: string

El id. del contexto de ejecución en el que se ejecutará el comando.
idioma

Tipo: string

El lenguaje del comando.
command

Tipo: string

La cadena de comando que se ejecutará.

Especifique un comando o
un commandFile.
commandFile

Tipo: string

La ruta de acceso a un archivo que contiene el comando que se ejecutará.

Especifique un commandFile o
un comando.
options

Tipo: string

Asignación opcional de valores usados de bajada. Por ejemplo, una invalidación displayRowLimit (usada en pruebas).

Esquema de respuesta

Campo
id

Tipo: string

Id. del comando.

Obtener información sobre un comando

Método y ruta de acceso:

GET /api/1.2/commands/status

Ejemplo

Solicitud:

curl --netrc --get \
  https://<databricks-instance>/api/1.2/commands/status \
  --data clusterId=1234-567890-span123 \
  --data contextId=1234567890123456789 \
  --data commandId=1234ab56-7890-1cde-234f-5abcdef67890

Respuesta:

{
  "id": "1234ab56-7890-1cde-234f-5abcdef67890",
  "status": "Finished",
  "results": {
    "resultType": "text",
    "data": "Hello, World!"
  }
}

Esquema de solicitud

Campo
clusterId

Tipo: string

El id. del clúster sobre el que se obtiene la información del comando.
contextId

Tipo: string

El id. del contexto de ejecución asociado al comando.
commandId

Tipo: string

El id. del comando sobre el que se obtiene información.

Esquema de respuesta

Campo
id

Tipo: string

Id. del comando.
status

Tipo: string

El estado del comando. Uno de los valores siguientes:

* Cancelled
* Cancelling
* Error
* Finished
* Queued
* Running
results

Tipo: object

Los resultados del comando.

* resultType: El tipo de resultado. Tipo: string Uno de los valores siguientes:

* error
* image
* images
* table
* text

Para error:

* cause: La causa del error. Tipo: string

Para image:

* fileName: El nombre de archivo de la imagen. Tipo: string

Para images:

* fileNames: Los nombres de archivo de las imágenes. Tipo: array de string

Para table:

* data: Los datos de la tabla. Tipo: array de array de any

* schema: El esquema de tabla. Tipo: array de array de (string, any)

* truncated: true si se devuelven resultados parciales. Tipo: true/false

* isJsonSchema: true si se devuelve un esquema JSON en lugar de una representación de cadena del tipo Hive. Tipo: true/false

Para text:

* data: El texto. Tipo: string

Cancelación de un comando

Método y ruta de acceso:

POST/api/1.2/commands/cancel

Ejemplo

Solicitud:

curl --netrc --request POST \
  https://<databricks-instance>/api/1.2/commands/cancel \
  --data clusterId=1234-567890-span123 \
  --data contextId=1234567890123456789 \
  --data commandId=1234ab56-7890-1cde-234f-5abcdef67890

Respuesta:

{
  "id": "1234ab56-7890-1cde-234f-5abcdef67890"
}

Esquema de solicitud

Campo
clusterId

Tipo: string

El id. del clúster asociado al comando que se va a cancelar.
contextId

Tipo: string

El id. del contexto de ejecución asociado al comando que se va a cancelar.
commandId

Tipo: string

El id. del comando que se va a cancelar.

Esquema de respuesta

Campo
id

Tipo: string

Id. del comando.

Obtener la lista de bibliotecas para un clúster

Importante

Esta operación está en desuso. En su lugar, use la operación Estado del clúster en Libraries API.

Método y ruta de acceso:

GET /api/1.2/libraries/list

Ejemplo

Solicitud:

curl --netrc --get \
  https://<databricks-instance>/api/1.2/libraries/list \
  --data clusterId=1234-567890-span123

Esquema de solicitud

Campo
clusterId

Tipo: string

El Id. del clúster.

Esquema de respuesta

Un matriz de objetos, con cada objeto que representa información sobre una librería, tal y como se muestra a continuación:

Campo
name

Tipo: string

El nombre de la biblioteca.
status

Tipo: string

El estado de la biblioteca. Uno de los valores siguientes:

* LibraryError
* LibraryLoaded
* LibraryPending

Cargar una biblioteca a un clúster

Importante

Esta operación está en desuso. En su lugar, use la operación Install en Libraries API.

Método y ruta de acceso:

POST /api/1.2/libraries/upload

Esquema de solicitud

Campo
clusterId

Tipo: string

El id. del clúster en el que se cargará la biblioteca.
name

Tipo: string

El nombre de la biblioteca.
idioma

Tipo: string

El lenguaje de la biblioteca.
uri

Tipo: string

El URI de la biblioteca.

El esquema puede ser file, http o
https.

Esquema de respuesta

Información sobre la biblioteca cargada.

Campo
idioma

Tipo: string

El lenguaje de la biblioteca.
uri

Tipo: string

El URI de la biblioteca.

Ejemplos adicionales

En los siguientes ejemplos adicionales encontrará varios comandos que también puede usar con curl o adaptarlo con una biblioteca HTTP en el lenguaje de programación que prefiera.

Crear un contexto de ejecución

Crear un contexto de ejecución en un clúster especificado para un lenguaje de programación determinado:

curl --netrc --request POST \
  https://<databricks-instance>/api/1.2/contexts/create \
  --header 'Content-Type: application/json' \
  --data '{ "language": "scala", "clusterId": "1234-567890-span123" }'

Obtener información sobre el contexto de ejecución:

curl --netrc --get \
  https://<databricks-instance>/api/1.2/contexts/status \
  --data 'clusterId=1234-567890-span123&contextId=1234567890123456789'

Eliminar el contexto de ejecución:

curl --netrc --request POST \
  https://<databricks-instance>/api/1.2/contexts/destroy \
  --header 'Content-Type: application/json' \
  --data '{ "contextId": "1234567890123456789", "clusterId": "1234-567890-span123" }'

Ejecución de un comando

Limitaciones conocidas: la ejecución de comandos no admite %run.

Ejecutar una cadena de comando:

curl --netrc --request POST \
  https://<databricks-instance>/api/1.2/commands/execute \
  --header 'Content-Type: application/json' \
  --data '{ "language": "scala", "clusterId": "1234-567890-span123", "contextId": "1234567890123456789", "command": "sc.parallelize(1 to 10).collect" }'

Ejecutar un archivo:

curl --netrc --request POST \
  https://<databricks-instance>/api/1.2/commands/execute \
  --header 'Content-Type: multipart/form-data' \
  --form language=python \
  --form clusterId=1234-567890-span123 \
  --form contextId=1234567890123456789 \
  --form command=@myfile.py

Mostrar el estado y el resultado del comando:

curl --netrc --get \
  https://<databricks-instance>/api/1.2/commands/status \
  --data 'clusterId=1234-567890-span123&contextId=1234567890123456789&commandId=1234ab56-7890-1cde-234f-5abcdef67890'

Cancelar el comando:

curl --netrc --request POST \
  https://<databricks-instance>/api/1.2/commands/cancel \
  --data 'clusterId=1234-567890-span123&contextId=1234567890123456789&commandId=1234ab56-7890-1cde-234f-5abcdef67890' \

Carga y ejecución de un archivo JAR de Spark

Carga de un JAR

Usar la API REST 2.0 (la más reciente) para cargar un archivo JAR y anexarlo a un clúster.

Ejecución de un archivo JAR

  1. Cree un contexto de ejecución.

    curl --netrc --request POST \
      https://<databricks-instance>/api/1.2/contexts/create \
      --data "language=scala&clusterId=1234-567890-span123"
    
    {
      "id": "1234567890123456789"
    }
    
  2. Ejecute un comando que use el archivo JAR.

    curl --netrc --request POST \
      https://<databricks-instance>/api/1.2/commands/execute \
      --data 'language=scala&clusterId=1234-567890-span123&contextId=1234567890123456789&command=println(com.databricks.apps.logs.chapter1.LogAnalyzer.processLogFile(sc,null,"dbfs:/somefile.log"))'
    
    {
      "id": "1234ab56-7890-1cde-234f-5abcdef67890"
    }
    
  3. Compruebe el estado del comando. Es posible que no se devuelva inmediatamente si se ejecuta un trabajo de Spark de larga duración.

    curl --netrc 'https://<databricks-instance>/api/1.2/commands/status?clusterId=1234-567890-span123&contextId=1234567890123456789&commandId=1234ab56-7890-1cde-234f-5abcdef67890'
    
    {
       "id": "1234ab56-7890-1cde-234f-5abcdef67890",
       "results": {
         "data": "Content Size Avg: 1234, Min: 1234, Max: 1234",
         "resultType": "text"
       },
       "status": "Finished"
    }
    

    Los valores de resultType permitidos son:

    • error
    • image
    • images
    • table
    • text