API-exempel

Den här artikeln innehåller exempel som visar hur du använder Azure Databricks REST API 2,0.

I följande exempl ersätter du <databricks-instance> med URL för arbetsyta för din Azure Databricks-distribution. <databricks-instance> ska börja med adb-. Använd inte den föråldrade regionala webbadressen som börjar med <azure-region-name>. Den kanske inte fungerar för nya arbetsytor, är mindre tillförlitligt och ger lägre prestanda än webbadresser per arbetsyta.

Autentisering

Om du vill lära dig att autentisera till REST API granskar du autentisering med Azure Databricks personliga åtkomsttoken och autentiserar med Azure Active Directory tokens.

I exemplen i den här artikeln förutsätter vi att du använder Azure Databricks personligaåtkomsttoken. I följande exempel ersätter <your-token> du med din personliga åtkomsttoken. I curl exemplen förutsätter vi att du lagrar Azure DATABRICKS API-autentiseringsuppgifter under . netrc. Python-exemplen använder Bearer -autentisering. Även om exemplen visar lagrings-token i koden, för att använda autentiseringsuppgifter på ett säkert sätt i Azure Databricks, rekommenderar vi att du följer användar handboken för hemlig hantering .

Exempel som använder autentisering med Azure Active Directory tokensfinns i artiklarna i avsnittet.

Hämta en GZipped lista över kluster

curl -n -H "Accept-Encoding: gzip" https://<databricks-instance>/api/2.0/clusters/list > clusters.gz

Ladda upp en stor fil till DBFS

Mängden data som laddas upp av ett enskilt API-anrop får inte överstiga 1 MB. Om du vill överföra en fil som är större än 1 MB till DBFS, använder du strömnings-API: t, som är en kombination av create , addBlock och close .

Här är ett exempel på hur du utför den här åtgärden med python.

import json
import requests
import base64

DOMAIN = '<databricks-instance>'
TOKEN = '<your-token>'
BASE_URL = 'https://%s/api/2.0/dbfs/' % (DOMAIN)

def dbfs_rpc(action, body):
  """ A helper function to make the DBFS API request, request/response is encoded/decoded as JSON """
  response = requests.post(
    BASE_URL + action,
    headers={'Authorization': 'Bearer %s' % TOKEN },
    json=body
  )
  return response.json()

# Create a handle that will be used to add blocks
handle = dbfs_rpc("create", {"path": "/temp/upload_large_file", "overwrite": "true"})['handle']
with open('/a/local/file') as f:
  while True:
    # A block can be at most 1MB
    block = f.read(1 << 20)
    if not block:
        break
    data = base64.standard_b64encode(block)
    dbfs_rpc("add-block", {"handle": handle, "data": data})
# close the handle to finish uploading
dbfs_rpc("close", {"handle": handle})

Skapa ett python 3-kluster (Databricks runtime 5,5 LTS)

Anteckning

Python 3 är standard versionen av python i Databricks Runtime 6,0 och senare.

I följande exempel visas hur du startar ett python 3 -kluster med Databricks-REST API och begär python http-bibliotek:

import requests

DOMAIN = '<databricks-instance>'
TOKEN = '<your-token>'

response = requests.post(
  'https://%s/api/2.0/clusters/create' % (DOMAIN),
  headers={'Authorization': 'Bearer %s' % TOKEN},
  json={
    "cluster_name": "my-cluster",
    "spark_version": "5.5.x-scala2.11",
    "node_type_id": "Standard_D3_v2",
    "spark_env_vars": {
      "PYSPARK_PYTHON": "/databricks/python3/bin/python3",
    }
  }
)

if response.status_code == 200:
  print(response.json()['cluster_id'])
else:
  print("Error launching cluster: %s: %s" % (response.json()["error_code"], response.json()["message"]))

Skapa ett högt samtidighets kluster

I följande exempel visas hur du startar ett kluster med hög samtidighets läge med hjälp av Databricks-REST API:

curl -n -X POST -H 'Content-Type: application/json' -d '{
  "cluster_name": "high-concurrency-cluster",
  "spark_version": "7.3.x-scala2.12",
  "node_type_id": "Standard_D3_v2",
  "spark_conf":{
        "spark.databricks.cluster.profile":"serverless",
        "spark.databricks.repl.allowedLanguages":"sql,python,r"
     },
   "custom_tags":{
        "ResourceClass":"Serverless"
     },
       "autoscale":{
        "min_workers":1,
        "max_workers":2
     },
  "autotermination_minutes":10
}' https://<databricks-instance>/api/2.0/clusters/create

API-exempel för jobb

I det här avsnittet visas hur du skapar python, Spark-överföring och JAR-jobb och kör JAR-jobbet och visar dess utdata.

Skapa ett python-jobb

Det här exemplet visar hur du skapar ett python-jobb. Den använder Apache Spark python Spark PI-uppskattning.

  1. Hämta python-filen som innehåller exemplet och ladda upp den till DBFS (Databricks File System) med hjälp av Databricks CLI.

    dbfs cp pi.py dbfs:/docs/pi.py
    
  2. Skapa jobbet. Följande exempel visar hur du skapar ett jobb med hjälp av Databricks runtime och Databricks ljus.

    Databricks Runtime

    curl -n -X POST -H 'Content-Type: application/json' -d \
    '{
      "name": "SparkPi Python job",
      "new_cluster": {
        "spark_version": "7.3.x-scala2.12",
        "node_type_id": "Standard_D3_v2",
        "num_workers": 2
      },
      "spark_python_task": {
        "python_file": "dbfs:/docs/pi.py",
        "parameters": [
          "10"
        ]
      }
    }' https://<databricks-instance>/api/2.0/jobs/create
    

    Databricks Light

    curl -n -X POST -H 'Content-Type: application/json' -d
    '{
        "name": "SparkPi Python job",
        "new_cluster": {
         "spark_version": "apache-spark-2.4.x-scala2.11",
         "node_type_id": "Standard_D3_v2",
         "num_workers": 2
        },
        "spark_python_task": {
         "python_file": "dbfs:/docs/pi.py",
         "parameters": [
           "10"
         ]
      }
    }' https://<databricks-instance>/api/2.0/jobs/create
    

Skapa ett Spark-Submit -jobb

Det här exemplet visar hur du skapar ett Spark-Submit-jobb. Den använder Apache Spark SparkPi-exempel.

  1. Hämta jar som innehåller exemplet och överför jar till Databricks File System (DBFS) med hjälp av Databricks CLI.

    dbfs cp SparkPi-assembly-0.1.jar dbfs:/docs/sparkpi.jar
    
  2. Skapa jobbet.

    curl -n \
    -X POST -H 'Content-Type: application/json' \
    -d '{
         "name": "SparkPi spark-submit job",
         "new_cluster": {
           "spark_version": "7.3.x-scala2.12",
           "node_type_id": "Standard_DS3_v2",
           "num_workers": 2
           },
        "spark_submit_task": {
           "parameters": [
             "--class",
             "org.apache.spark.examples.SparkPi",
             "dbfs:/docs/sparkpi.jar",
             "10"
          ]
        }
    }' https://<databricks-instance>/api/2.0/jobs/create
    

Skapa och kör ett Spark-Submit-jobb för R -skript

Det här exemplet visar hur du skapar ett Spark-Submit-jobb för att köra R-skript.

  1. Överför R-filen till Databricks File System (DBFS) med hjälp av Databricks CLI.

    dbfs cp your_code.R dbfs:/path/to/your_code.R
    

    Om koden använder Spark, måste den först installera paketet. Databricks Runtime innehåller koden för Spark-källan. Installera Spark-paketet från den lokala katalogen som visas i följande exempel:

    install.packages("/databricks/spark/R/pkg", repos = NULL)
    library(SparkR)
    
    sparkR.session()
    n <- nrow(createDataFrame(iris))
    write.csv(n, "/dbfs/path/to/num_rows.csv")
    

    Databricks Runtime installerar den senaste versionen av sparklyr från CRAN. Om koden använder sparklyr, måste du ange URL: en för Spark-Master i spark_connect . Om du vill skapa en spark-huvud-URL använder du SPARK_LOCAL_IP miljövariabeln för att hämta IP och använder standard porten 7077. Till exempel:

    library(sparklyr)
    
    master <- paste("spark://", Sys.getenv("SPARK_LOCAL_IP"), ":7077", sep="")
    sc <- spark_connect(master)
    iris_tbl <- copy_to(sc, iris)
    write.csv(iris_tbl, "/dbfs/path/to/sparklyr_iris.csv")
    
  2. Skapa jobbet.

    curl -n \
    -X POST -H 'Content-Type: application/json' \
    -d '{
         "name": "R script spark-submit job",
         "new_cluster": {
           "spark_version": "7.3.x-scala2.12",
           "node_type_id": "Standard_DS3_v2",
           "num_workers": 2
           },
        "spark_submit_task": {
           "parameters": [ "dbfs:/path/to/your_code.R" ]
           }
    }' https://<databricks-instance>/api/2.0/jobs/create
    

    Detta returnerar en job-id som du sedan kan använda för att köra jobbet.

  3. Kör jobbet med hjälp av job-id .

    curl -n \
    -X POST -H 'Content-Type: application/json' \
    -d '{ "job_id": <job-id> }' https://<databricks-instance>/api/2.0/jobs/run-now
    

Skapa och köra ett jar -jobb

Det här exemplet visar hur du skapar och kör ett JAR-jobb. Den använder Apache Spark SparkPi-exempel.

  1. Hämta jar som innehåller exemplet.

  2. Överför JAR till din Azure Databricks-instans med hjälp av API: et:

    curl -n \
    -F filedata=@"SparkPi-assembly-0.1.jar" \
    -F path="/docs/sparkpi.jar" \
    -F overwrite=true \
    https://<databricks-instance>/api/2.0/dbfs/put
    

    Ett lyckat anrop returneras {} . Annars visas ett fel meddelande.

  3. Hämta en lista över alla Spark-versioner innan du skapar jobbet.

    curl -n https://<databricks-instance>/api/2.0/clusters/spark-versions
    

    I det här exemplet används 7.3.x-scala2.12. Se versions strängar för körning för mer information om Spark-kluster versioner.

  4. Skapa jobbet. BURKen anges som ett bibliotek och huvud klass namnet refereras till i Spark-JAR-uppgiften.

    curl -n -X POST -H 'Content-Type: application/json' \
    -d '{
          "name": "SparkPi JAR job",
          "new_cluster": {
            "spark_version": "7.3.x-scala2.12",
            "node_type_id": "Standard_DS3_v2",
            "num_workers": 2
            },
         "libraries": [{"jar": "dbfs:/docs/sparkpi.jar"}],
         "spark_jar_task": {
            "main_class_name":"org.apache.spark.examples.SparkPi",
            "parameters": "10"
            }
    }' https://<databricks-instance>/api/2.0/jobs/create
    

    Detta returnerar en job-id som du sedan kan använda för att köra jobbet.

  5. Kör jobbet med run now :

    curl -n \
    -X POST -H 'Content-Type: application/json' \
    -d '{ "job_id": <job-id> }' https://<databricks-instance>/api/2.0/jobs/run-now
    
  6. Navigera till https://<databricks-instance>/#job/<job-id> och du kommer att kunna se jobbet som körs.

  7. Du kan också kontrol lera den från API: et med hjälp av den information som returnerades från föregående begäran.

    curl -n https://<databricks-instance>/api/2.0/jobs/runs/get?run_id=<run-id> | jq
    

    Vilket bör returnera något som liknar:

    {
      "job_id": 35,
      "run_id": 30,
      "number_in_job": 1,
      "original_attempt_run_id": 30,
      "state": {
        "life_cycle_state": "TERMINATED",
        "result_state": "SUCCESS",
        "state_message": ""
      },
      "task": {
        "spark_jar_task": {
          "jar_uri": "",
          "main_class_name": "org.apache.spark.examples.SparkPi",
          "parameters": [
            "10"
          ],
          "run_as_repl": true
        }
      },
      "cluster_spec": {
        "new_cluster": {
          "spark_version": "7.3.x-scala2.12",
          "node_type_id": "<node-type>",
          "enable_elastic_disk": false,
          "num_workers": 1
        },
        "libraries": [
          {
            "jar": "dbfs:/docs/sparkpi.jar"
          }
        ]
      },
      "cluster_instance": {
        "cluster_id": "0412-165350-type465",
        "spark_context_id": "5998195893958609953"
      },
      "start_time": 1523552029282,
      "setup_duration": 211000,
      "execution_duration": 33000,
      "cleanup_duration": 2000,
      "trigger": "ONE_TIME",
      "creator_user_name": "...",
      "run_name": "SparkPi JAR job",
      "run_page_url": "<databricks-instance>/?o=3901135158661429#job/35/run/1",
      "run_type": "JOB_RUN"
    }
    
  8. Du kan visa jobbets utdata på sidan körnings information för jobb.

    Executing command, time = 1523552263909.
    Pi is roughly 3.13973913973914
    

Exempel på att skapa kluster aktiverat för tabell åtkomst kontroll

Om du vill skapa ett kluster som är aktiverat för tabell åtkomst kontroll, anger du följande spark_conf egenskap i din begär ande text:

curl -X POST https://<databricks-instance>/api/2.0/clusters/create -d'
{
  "cluster_name": "my-cluster",
  "spark_version": "7.3.x-scala2.12",
  "node_type_id": "Standard_DS3_v2",
  "spark_conf": {
    "spark.databricks.acl.dfAclsEnabled":true,
    "spark.databricks.repl.allowedLanguages": "python,sql"
  },
  "num_workers": 1,
  "custom_tags":{
     "costcenter":"Tags",
     "applicationname":"Tags1"
  }
}'

Exempel på kluster logg leverans

Även om du kan se Spark-drivrutinen och utförar-loggarna i Spark-ANVÄNDARGRÄNSSNITTET kan Azure Databricks även leverera loggarna till DBFS-mål. Se följande exempel:

Skapa ett kluster med loggar som levereras till en DBFS-plats

Följande spiral kommando skapar ett kluster med namnet cluster_log_dbfs och begär Azure Databricks att skicka loggarna till dbfs:/logs med kluster-ID: t som sökvägar.

curl -n -X POST -H 'Content-Type: application/json' -d \
'{
  "cluster_name": "cluster_log_dbfs",
  "spark_version": "7.3.x-scala2.12",
  "node_type_id": "Standard_D3_v2",
  "num_workers": 1,
  "cluster_log_conf": {
    "dbfs": {
      "destination": "dbfs:/logs"
    }
  }
}' https://<databricks-instance>/api/2.0/clusters/create

Svaret ska innehålla klustrets ID:

{"cluster_id":"1111-223344-abc55"}

När klustret har skapats synkroniserar Azure Databricks loggfilerna till målet var 5: e minut. Den laddar upp driv rutins loggar till dbfs:/logs/1111-223344-abc55/driver och utförar loggar till dbfs:/logs/1111-223344-abc55/executor .

Kontrol lera leverans status för logg

Du kan hämta kluster information med logg leverans status via API:

curl -n -H 'Content-Type: application/json' -d \
'{
  "cluster_id": "1111-223344-abc55"
}' https://<databricks-instance>/api/2.0/clusters/get

Om den senaste logg överföringen har slutförts ska svaret bara innehålla tidsstämpeln för det senaste försöket:

{
  "cluster_log_status": {
    "last_attempted": 1479338561
  }
}

I händelse av fel visas fel meddelandet i svaret:

{
  "cluster_log_status": {
    "last_attempted": 1479338561,
    "last_exception": "Exception: Access Denied ..."
  }
}

Exempel på arbets ytor

Här följer några exempel på hur du använder arbets ytans API för att visa, hämta information om, skapa, ta bort, exportera och importera arbets ytans objekt.

Lista en bärbar dator eller en mapp

Följande spiral kommando visar en sökväg i arbets ytan.

curl -n -X GET -H 'Content-Type: application/json' -d \
'{
  "path": "/Users/user@example.com/"
}' https://<databricks-instance>/api/2.0/workspace/list

Svaret ska innehålla en lista med status:

{
  "objects": [
    {
     "object_type": "DIRECTORY",
     "path": "/Users/user@example.com/folder"
    },
    {
     "object_type": "NOTEBOOK",
     "language": "PYTHON",
     "path": "/Users/user@example.com/notebook1"
    },
    {
     "object_type": "NOTEBOOK",
     "language": "SCALA",
     "path": "/Users/user@example.com/notebook2"
    }
  ]
}

Om sökvägen är en antecknings bok innehåller svaret en matris som innehåller statusen för den inmatade antecknings boken.

Hämta information om en bärbar dator eller en mapp

Följande spiral-kommando hämtar status för en sökväg i arbets ytan.

curl -n  -X GET -H 'Content-Type: application/json' -d \
'{
  "path": "/Users/user@example.com/"
}' https://<databricks-instance>/api/2.0/workspace/get-status

Svaret ska innehålla status för ingångs Sök vägen:

{
  "object_type": "DIRECTORY",
  "path": "/Users/user@example.com"
}

Skapar en mapp

Följande spiral-kommando skapar en mapp. Den skapar mappen rekursivt som mkdir -p . Om mappen redan finns sker ingen och lyckas.

curl -n -X POST -H 'Content-Type: application/json' -d \
'{
  "path": "/Users/user@example.com/new/folder"
}' https://<databricks-instance>/api/2.0/workspace/mkdirs

Om begäran lyckas returneras en tom JSON-sträng.

Ta bort en antecknings bok eller mapp

Följande spiral kommando tar bort en antecknings bok eller mapp. Du kan aktivera recursive för att rekursivt ta bort en mapp som inte är tom.

curl -n -X POST -H 'Content-Type: application/json' -d \
'{
  "path": "/Users/user@example.com/new/folder",
  "recursive": "false"
}' https://<databricks-instance>/api/2.0/workspace/delete

Om begäran lyckas returneras en tom JSON-sträng.

Exportera en bärbar dator eller mapp

Följande spiral kommando exporterar en antecknings bok. Antecknings böcker kan exporteras i följande format: SOURCE , HTML , JUPYTER , DBC . En mapp kan bara exporteras som DBC .

curl -n  -X GET -H 'Content-Type: application/json' \
'{
  "path": "/Users/user@example.com/notebook",
  "format": "SOURCE"
}' https://<databricks-instance>/api/2.0/workspace/export

Svaret innehåller Base64-kodat antecknings boks innehåll.

{
  "content": "Ly8gRGF0YWJyaWNrcyBub3RlYm9vayBzb3VyY2UKcHJpbnQoImhlbGxvLCB3b3JsZCIpCgovLyBDT01NQU5EIC0tLS0tLS0tLS0KCg=="
}

Du kan också hämta den exporterade antecknings boken direkt.

curl -n -X GET "https://<databricks-instance>/api/2.0/workspace/export?format=SOURCE&direct_download=true&path=/Users/user@example.com/notebook"

Svaret är det exporterade antecknings bokens innehåll.

Importera en bärbar dator eller katalog

Följande spiral kommando importerar en antecknings bok i arbets ytan. Flera format ( SOURCE , HTML , JUPYTER , DBC ) stöds. Om format är SOURCE måste du ange language . contentParametern innehåller Base64-kodat Notebook-innehåll. Du kan aktivera overwrite för att skriva över den befintliga antecknings boken.

curl -n -X POST -H 'Content-Type: application/json' -d \
'{
  "path": "/Users/user@example.com/new-notebook",
  "format": "SOURCE",
  "language": "SCALA",
  "content": "Ly8gRGF0YWJyaWNrcyBub3RlYm9vayBzb3VyY2UKcHJpbnQoImhlbGxvLCB3b3JsZCIpCgovLyBDT01NQU5EIC0tLS0tLS0tLS0KCg==",
  "overwrite": "false"
}' https://<databricks-instance>/api/2.0/workspace/import

Om begäran lyckas returneras en tom JSON-sträng.

Du kan också importera en antecknings bok via flerdelade formulär post.

curl -n -X POST https://<databricks-instance>/api/2.0/workspace/import \
       -F path="/Users/user@example.com/new-notebook" -F format=SOURCE -F language=SCALA -F overwrite=true -F content=@notebook.scala